Home • Explore • Blog • CI
☰



postgresql
3rd chunk of `doc/src/sgml/ref/create_cast.sgml`
65d0f0d54a8073af509dd71feb639b1d125a806df0a8dd090000000100000fa2
 multiple possible interpretations.  A good
   rule of thumb is to make a cast implicitly invokable only for
   information-preserving transformations between types in the same
   general type category.  For example, the cast from <type>int2</type> to
   <type>int4</type> can reasonably be implicit, but the cast from
   <type>float8</type> to <type>int4</type> should probably be
   assignment-only.  Cross-type-category casts, such as <type>text</type>
   to <type>int4</type>, are best made explicit-only.
  </para>

  <note>
   <para>
    Sometimes it is necessary for usability or standards-compliance reasons
    to provide multiple implicit casts among a set of types, resulting in
    ambiguity that cannot be avoided as above.  The parser has a fallback
    heuristic based on <firstterm>type categories</firstterm> and <firstterm>preferred
    types</firstterm> that can help to provide desired behavior in such cases.  See
    <xref linkend="sql-createtype"/> for
    more information.
   </para>
  </note>

  <para>
   To be able to create a cast, you must own the source or the target data type
   and have <literal>USAGE</literal> privilege on the other type.  To create a
   binary-coercible cast, you must be superuser.  (This restriction is made
   because an erroneous binary-coercible cast conversion can easily crash the
   server.)
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

   <variablelist>
    <varlistentry>
     <term><replaceable>source_type</replaceable></term>

     <listitem>
      <para>
       The name of the source data type of the cast.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>target_type</replaceable></term>

     <listitem>
      <para>
       The name of the target data type of the cast.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal><replaceable>function_name</replaceable>[(<replaceable>argument_type</replaceable> [, ...])]</literal></term>

     <listitem>
      <para>
       The function used to perform the cast.  The function name can
       be schema-qualified.  If it is not, the function will be looked
       up in the schema search path.  The function's result data type must
       match the target type of the cast.   Its arguments are discussed below.
       If no argument list is specified, the function name must be unique in
       its schema.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>WITHOUT FUNCTION</literal></term>

     <listitem>
      <para>
       Indicates that the source type is binary-coercible to the target type,
       so no function is required to perform the cast.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>WITH INOUT</literal></term>

     <listitem>
      <para>
       Indicates that the cast is an I/O conversion cast, performed by
       invoking the output function of the source data type, and passing the
       resulting string to the input function of the target data type.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>AS ASSIGNMENT</literal></term>

     <listitem>
      <para>
       Indicates that the cast can be invoked implicitly in assignment
       contexts.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>AS IMPLICIT</literal></term>

     <listitem>
      <para>
       Indicates that the cast can be invoked implicitly in any context.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

  <para>
   Cast implementation functions can have one to three arguments.
   The first argument type must be identical to or binary-coercible from
   the cast's source type.  The second argument,
   if present, must be type <type>integer</type>; it receives the type
   modifier associated with the destination type, or <literal>-1</literal>
   if there is none.  The third argument,
Title: Creating Casts: Implicit vs. Explicit, Permissions, and Parameters
Summary
This section outlines considerations and requirements for creating casts in PostgreSQL. It reiterates the importance of conservative use of implicit casts, favoring them for information-preserving transformations within the same type category. When multiple implicit casts create unavoidable ambiguity, the parser uses type categories and preferred types as a fallback. To create a cast, ownership of the source or target type and USAGE privilege on the other type are required. Binary-coercible casts necessitate superuser privileges. The section then details the parameters involved in creating casts, including source and target types, the function used for conversion (or indication of binary-coercibility or I/O conversion), and the cast's invocation context (ASSIGNMENT or IMPLICIT).