Skip to content

PostgreSQL CONVERSION

    CREATE CONVERSION

    CREATE CONVERSION — define a new encoding conversion

    CREATE [ DEFAULT ] CONVERSION name
    FOR source_encoding TO dest_encoding FROM function_name

    CREATE CONVERSION defines a new conversion between two character set encodings.

    Conversions that are marked DEFAULT can be used for automatic encoding conversion between client and server. To support that usage, two conversions, from encoding A to B and from encoding B to A, must be defined.

    To be able to create a conversion, you must have EXECUTE privilege on the function and CREATE privilege on the destination schema.

    Parameters

    DEFAULT

    The DEFAULT clause indicates that this conversion is the default for this particular source to destination encoding. There should be only one default encoding in a schema for the encoding pair.

    name

    The name of the conversion. The conversion name can be schema-qualified. If it is not, the conversion is defined in the current schema. The conversion name must be unique within a schema.

    source_encoding

    The source encoding name.

    dest_encoding

    The destination encoding name.

    function_name

    The function used to perform the conversion. The function name can be schema-qualified. If it is not, the function will be looked up in the path.

    The function must have the following signature:

    conv_proc(
    integer,  -- destination encoding I
    cstring,  -- source string (null terminated C string)
    internal, -- destination (fill with a null terminated C string)
    integer   -- source string length
    ) RETURNS void;

    Neither the source nor the destination encoding can be SQL_ASCII, as the server’s behavior for cases involving the SQL_ASCII “encoding” is hard-wired.

    Use DROP CONVERSION to remove user-defined conversions.

    The privileges required to create a conversion might be changed in a future release.

    Examples

    To create a conversion from encoding UTF8 to LATIN1 using myfunc:

    CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;

    ALTER CONVERSION

    ALTER CONVERSION — change the definition of a conversion

    ALTER CONVERSION name RENAME TO new_name
    ALTER CONVERSION name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
    ALTER CONVERSION name SET SCHEMA new_schema

    ALTER CONVERSION changes the definition of a conversion.

    You must own the conversion to use ALTER CONVERSION. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the conversion’s schema. (These restrictions enforce that altering the owner doesn’t do anything you couldn’t do by dropping and recreating the conversion. However, a superuser can alter ownership of any conversion anyway.)

    Parameters

    name

    The name (optionally schema-qualified) of an existing conversion.

    new_name

    The new name of the conversion.

    new_owner

    The new owner of the conversion.

    new_schema

    The new schema for the conversion.

    Examples

    To rename the conversion iso_8859_1_to_utf8 to latin1_to_unicode:

    ALTER CONVERSION iso_8859_1_to_utf8 RENAME TO latin1_to_unicode;

    To change the owner of the conversion iso_8859_1_to_utf8 to joe:

    ALTER CONVERSION iso_8859_1_to_utf8 OWNER TO joe;

    DROP CONVERSION

    DROP CONVERSION — remove a conversion

    DROP CONVERSION [ IF EXISTS ] name [ CASCADE | RESTRICT ]

    DROP CONVERSION removes a previously defined conversion. To be able to drop a conversion, you must own the conversion.

    Parameters

    IF EXISTS

    Do not throw an error if the conversion does not exist. A notice is issued in this case.

    name

    The name of the conversion. The conversion name can be schema-qualified.

    CASCADE
    RESTRICT

    These key words do not have any effect, since there are no dependencies on conversions.

    Examples

    To drop the conversion named myname:

    DROP CONVERSION myname;