granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_type.sgml

   1 <!--
   2 doc/src/sgml/ref/create_type.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATETYPE">
   7  <refmeta>
   8   <refentrytitle>CREATE TYPE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>CREATE TYPE</refname>
  15   <refpurpose>define a new data type</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-createtype">
  19   <primary>CREATE TYPE</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE TYPE <replaceable class="parameter">name</replaceable> AS
  25     ( [ <replaceable class="PARAMETER">attribute_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ COLLATE <replaceable>collation</replaceable> ] [, ... ] ] )
  26
  27 CREATE TYPE <replaceable class="parameter">name</replaceable> AS ENUM
  28     ( [ '<replaceable class="parameter">label</replaceable>' [, ... ] ] )
  29
  30 CREATE TYPE <replaceable class="parameter">name</replaceable> AS RANGE (
  31     SUBTYPE = <replaceable class="parameter">subtype</replaceable>
  32     [ , SUBTYPE_OPCLASS = <replaceable class="parameter">subtype_operator_class</replaceable> ]
  33     [ , COLLATION = <replaceable class="parameter">collation</replaceable> ]
  34     [ , CANONICAL = <replaceable class="parameter">canonical_function</replaceable> ]
  35     [ , SUBTYPE_DIFF = <replaceable class="parameter">subtype_diff_function</replaceable> ]
  36 )
  37
  38 CREATE TYPE <replaceable class="parameter">name</replaceable> (
  39     INPUT = <replaceable class="parameter">input_function</replaceable>,
  40     OUTPUT = <replaceable class="parameter">output_function</replaceable>
  41     [ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
  42     [ , SEND = <replaceable class="parameter">send_function</replaceable> ]
  43     [ , TYPMOD_IN = <replaceable class="parameter">type_modifier_input_function</replaceable> ]
  44     [ , TYPMOD_OUT = <replaceable class="parameter">type_modifier_output_function</replaceable> ]
  45     [ , ANALYZE = <replaceable class="parameter">analyze_function</replaceable> ]
  46     [ , INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE } ]
  47     [ , PASSEDBYVALUE ]
  48     [ , ALIGNMENT = <replaceable class="parameter">alignment</replaceable> ]
  49     [ , STORAGE = <replaceable class="parameter">storage</replaceable> ]
  50     [ , LIKE = <replaceable class="parameter">like_type</replaceable> ]
  51     [ , CATEGORY = <replaceable class="parameter">category</replaceable> ]
  52     [ , PREFERRED = <replaceable class="parameter">preferred</replaceable> ]
  53     [ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
  54     [ , ELEMENT = <replaceable class="parameter">element</replaceable> ]
  55     [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
  56     [ , COLLATABLE = <replaceable class="parameter">collatable</replaceable> ]
  57 )
  58
  59 CREATE TYPE <replaceable class="parameter">name</replaceable>
  60 </synopsis>
  61  </refsynopsisdiv>
  62
  63  <refsect1>
  64   <title>Description</title>
  65
  66   <para>
  67    <command>CREATE TYPE</command> registers a new data type for use in
  68    the current database.  The user who defines a type becomes its
  69    owner.
  70   </para>
  71
  72   <para>
  73    If a schema name is given then the type is created in the specified
  74    schema.  Otherwise it is created in the current schema.  The type
  75    name must be distinct from the name of any existing type or domain
  76    in the same schema.  (Because tables have associated data types,
  77    the type name must also be distinct from the name of any existing
  78    table in the same schema.)
  79   </para>
  80
  81   <para>
  82    There are five forms of <command>CREATE TYPE</command>, as shown in the
  83    syntax synopsis above.  They respectively create a <firstterm>composite
  84    type</>, an <firstterm>enum type</>, a <firstterm>range type</>, a
  85    <firstterm>base type</>, or a <firstterm>shell type</>.  The first four
  86    of these are discussed in turn below.  A shell type is simply a placeholder
  87    for a type to be defined later; it is created by issuing <command>CREATE
  88    TYPE</command> with no parameters except for the type name.  Shell types
  89    are needed as forward references when creating range types and base types,
  90    as discussed in those sections.
  91   </para>
  92
  93   <refsect2>
  94    <title>Composite Types</title>
  95
  96   <para>
  97    The first form of <command>CREATE TYPE</command>
  98    creates a composite type.
  99    The composite type is specified by a list of attribute names and data types.
 100    An attribute's collation can be specified too, if its data type is
 101    collatable.  A composite type is essentially the same as the row type
 102    of a table, but using <command>CREATE TYPE</command> avoids the need to
 103    create an actual table when all that is wanted is to define a type.
 104    A stand-alone composite type is useful, for example, as the argument or
 105    return type of a function.
 106   </para>
 107
 108   <para>
 109    To be able to create a composite type, you must
 110    have <literal>USAGE</literal> privilege on all attribute types.
 111   </para>
 112   </refsect2>
 113
 114   <refsect2 id="SQL-CREATETYPE-enum">
 115    <title>Enumerated Types</title>
 116
 117    <para>
 118     The second form of <command>CREATE TYPE</command> creates an enumerated
 119     (enum) type, as described in <xref linkend="datatype-enum">.
 120     Enum types take a list of one or more quoted labels, each of which
 121     must be less than <symbol>NAMEDATALEN</symbol> bytes long (64 bytes in a
 122     standard <productname>PostgreSQL</productname> build).
 123    </para>
 124   </refsect2>
 125
 126   <refsect2 id="SQL-CREATETYPE-RANGE">
 127    <title>Range Types</title>
 128
 129    <para>
 130     The third form of <command>CREATE TYPE</command> creates a new
 131     range type, as described in <xref linkend="rangetypes">.
 132    </para>
 133
 134    <para>
 135     The range type's <replaceable class="parameter">subtype</replaceable> can
 136     be any type with an associated b-tree operator class (to determine the
 137     ordering of values for the range type).  Normally the subtype's default
 138     b-tree operator class is used to determine ordering; to use a non-default
 139     opclass, specify its name with <replaceable
 140     class="parameter">subtype_opclass</replaceable>.  If the subtype is
 141     collatable, and you want to use a non-default collation in the range's
 142     ordering, specify the desired collation with the <replaceable
 143     class="parameter">collation</replaceable> option.
 144    </para>
 145
 146    <para>
 147     The optional <replaceable class="parameter">canonical</replaceable>
 148     function must take one argument of the range type being defined, and
 149     return a value of the same type.  This is used to convert range values
 150     to a canonical form, when applicable.  See <xref
 151     linkend="rangetypes-defining"> for more information.  Creating a
 152     <replaceable class="parameter">canonical</replaceable> function
 153     is a bit tricky, since it must be defined before the range type can be
 154     declared.  To do this, you must first create a shell type, which is a
 155     placeholder type that has no properties except a name and an
 156     owner.  This is done by issuing the command <literal>CREATE TYPE
 157     <replaceable>name</></literal>, with no additional parameters.  Then
 158     the function can be declared using the shell type as argument and result,
 159     and finally the range type can be declared using the same name.  This
 160     automatically replaces the shell type entry with a valid range type.
 161    </para>
 162
 163    <para>
 164     The optional <replaceable class="parameter">subtype_diff</replaceable>
 165     function must take two values of the
 166     <replaceable class="parameter">subtype</replaceable> type as argument,
 167     and return a <type>double precision</type> value representing the
 168     difference between the two given values.  While this is optional,
 169     providing it allows much greater efficiency of GiST indexes on columns of
 170     the range type.  See <xref linkend="rangetypes-defining"> for more
 171     information.
 172    </para>
 173   </refsect2>
 174
 175   <refsect2>
 176    <title>Base Types</title>
 177
 178   <para>
 179    The fourth form of <command>CREATE TYPE</command> creates a new base type
 180    (scalar type).  To create a new base type, you must be a superuser.
 181    (This restriction is made because an erroneous type definition could
 182    confuse or even crash the server.)
 183   </para>
 184
 185   <para>
 186    The parameters can appear in any order, not only that
 187    illustrated above, and most are optional.  You must register
 188    two or more functions (using <command>CREATE FUNCTION</command>) before
 189    defining the type.  The support functions
 190    <replaceable class="parameter">input_function</replaceable> and
 191    <replaceable class="parameter">output_function</replaceable>
 192    are required, while the functions
 193    <replaceable class="parameter">receive_function</replaceable>,
 194    <replaceable class="parameter">send_function</replaceable>,
 195    <replaceable class="parameter">type_modifier_input_function</replaceable>,
 196    <replaceable class="parameter">type_modifier_output_function</replaceable> and
 197    <replaceable class="parameter">analyze_function</replaceable>
 198    are optional.  Generally these functions have to be coded in C
 199    or another low-level language.
 200   </para>
 201
 202   <para>
 203    The <replaceable class="parameter">input_function</replaceable>
 204    converts the type's external textual representation to the internal
 205    representation used by the operators and functions defined for the type.
 206    <replaceable class="parameter">output_function</replaceable>
 207    performs the reverse transformation.  The input function can be
 208    declared as taking one argument of type <type>cstring</type>,
 209    or as taking three arguments of types
 210    <type>cstring</type>, <type>oid</type>, <type>integer</type>.
 211    The first argument is the input text as a C string, the second
 212    argument is the type's own OID (except for array types, which instead
 213    receive their element type's OID),
 214    and the third is the <literal>typmod</> of the destination column, if known
 215    (-1 will be passed if not).
 216    The input function must return a value of the data type itself.
 217    Usually, an input function should be declared STRICT; if it is not,
 218    it will be called with a NULL first parameter when reading a NULL
 219    input value.  The function must still return NULL in this case, unless
 220    it raises an error.
 221    (This case is mainly meant to support domain input functions, which
 222    might need to reject NULL inputs.)
 223    The output function must be
 224    declared as taking one argument of the new data type.
 225    The output function must return type <type>cstring</type>.
 226    Output functions are not invoked for NULL values.
 227   </para>
 228
 229   <para>
 230    The optional <replaceable class="parameter">receive_function</replaceable>
 231    converts the type's external binary representation to the internal
 232    representation.  If this function is not supplied, the type cannot
 233    participate in binary input.  The binary representation should be
 234    chosen to be cheap to convert to internal form, while being reasonably
 235    portable.  (For example, the standard integer data types use network
 236    byte order as the external binary representation, while the internal
 237    representation is in the machine's native byte order.)  The receive
 238    function should perform adequate checking to ensure that the value is
 239    valid.
 240    The receive function can be declared as taking one argument of type
 241    <type>internal</type>, or as taking three arguments of types
 242    <type>internal</type>, <type>oid</type>, <type>integer</type>.
 243    The first argument is a pointer to a <type>StringInfo</type> buffer
 244    holding the received byte string; the optional arguments are the
 245    same as for the text input function.
 246    The receive function must return a value of the data type itself.
 247    Usually, a receive function should be declared STRICT; if it is not,
 248    it will be called with a NULL first parameter when reading a NULL
 249    input value.  The function must still return NULL in this case, unless
 250    it raises an error.
 251    (This case is mainly meant to support domain receive functions, which
 252    might need to reject NULL inputs.)
 253    Similarly, the optional
 254    <replaceable class="parameter">send_function</replaceable> converts
 255    from the internal representation to the external binary representation.
 256    If this function is not supplied, the type cannot participate in binary
 257    output.  The send function must be
 258    declared as taking one argument of the new data type.
 259    The send function must return type <type>bytea</type>.
 260    Send functions are not invoked for NULL values.
 261   </para>
 262
 263   <para>
 264    You should at this point be wondering how the input and output functions
 265    can be declared to have results or arguments of the new type, when they
 266    have to be created before the new type can be created.  The answer is that
 267    the type should first be defined as a <firstterm>shell type</>, which is a
 268    placeholder type that has no properties except a name and an owner.  This
 269    is done by issuing the command <literal>CREATE TYPE
 270    <replaceable>name</></literal>, with no additional parameters.  Then the
 271    I/O functions can be defined referencing the shell type.  Finally,
 272    <command>CREATE TYPE</> with a full definition replaces the shell entry
 273    with a complete, valid type definition, after which the new type can be
 274    used normally.
 275   </para>
 276
 277   <para>
 278    The optional
 279    <replaceable class="parameter">type_modifier_input_function</replaceable>
 280    and <replaceable class="parameter">type_modifier_output_function</replaceable>
 281    are needed if the type supports modifiers, that is optional constraints
 282    attached to a type declaration, such as <literal>char(5)</> or
 283    <literal>numeric(30,2)</>.  <productname>PostgreSQL</productname> allows
 284    user-defined types to take one or more simple constants or identifiers as
 285    modifiers.  However, this information must be capable of being packed into a
 286    single non-negative integer value for storage in the system catalogs.  The
 287    <replaceable class="parameter">type_modifier_input_function</replaceable>
 288    is passed the declared modifier(s) in the form of a <type>cstring</>
 289    array.  It must check the values for validity (throwing an error if they
 290    are wrong), and if they are correct, return a single non-negative
 291    <type>integer</> value that will be stored as the column <quote>typmod</>.
 292    Type modifiers will be rejected if the type does not have a
 293    <replaceable class="parameter">type_modifier_input_function</replaceable>.
 294    The <replaceable class="parameter">type_modifier_output_function</replaceable>
 295    converts the internal integer typmod value back to the correct form for
 296    user display.  It must return a <type>cstring</> value that is the exact
 297    string to append to the type name; for example <type>numeric</>'s
 298    function might return <literal>(30,2)</>.
 299    It is allowed to omit the
 300    <replaceable class="parameter">type_modifier_output_function</replaceable>,
 301    in which case the default display format is just the stored typmod integer
 302    value enclosed in parentheses.
 303   </para>
 304
 305   <para>
 306    The optional <replaceable class="parameter">analyze_function</replaceable>
 307    performs type-specific statistics collection for columns of the data type.
 308    By default, <command>ANALYZE</> will attempt to gather statistics using
 309    the type's <quote>equals</> and <quote>less-than</> operators, if there
 310    is a default b-tree operator class for the type.  For non-scalar types
 311    this behavior is likely to be unsuitable, so it can be overridden by
 312    specifying a custom analysis function.  The analysis function must be
 313    declared to take a single argument of type <type>internal</>, and return
 314    a <type>boolean</> result.  The detailed API for analysis functions appears
 315    in <filename>src/include/commands/vacuum.h</>.
 316   </para>
 317
 318   <para>
 319    While the details of the new type's internal representation are only
 320    known to the I/O functions and other functions you create to work with
 321    the type, there are several properties of the internal representation
 322    that must be declared to <productname>PostgreSQL</productname>.
 323    Foremost of these is
 324    <replaceable class="parameter">internallength</replaceable>.
 325    Base data types can be fixed-length, in which case
 326    <replaceable class="parameter">internallength</replaceable> is a
 327    positive integer, or variable  length, indicated by setting
 328    <replaceable class="parameter">internallength</replaceable>
 329    to <literal>VARIABLE</literal>.  (Internally, this is represented
 330    by setting <literal>typlen</> to -1.)  The internal representation of all
 331    variable-length types must start with a 4-byte integer giving the total
 332    length of this value of the type.
 333   </para>
 334
 335   <para>
 336    The optional flag <literal>PASSEDBYVALUE</literal> indicates that
 337    values of this data type are passed by value, rather than by
 338    reference.  You cannot pass by value types whose internal
 339    representation is larger than the size of the <type>Datum</> type
 340    (4 bytes on most machines, 8 bytes on a few).
 341   </para>
 342
 343   <para>
 344    The <replaceable class="parameter">alignment</replaceable> parameter
 345    specifies the storage alignment required for the data type.  The
 346    allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
 347    Note that variable-length types must have an alignment of at least
 348    4, since they necessarily contain an <type>int4</> as their first component.
 349   </para>
 350
 351   <para>
 352    The <replaceable class="parameter">storage</replaceable> parameter
 353    allows selection of storage strategies for variable-length data
 354    types.  (Only <literal>plain</literal> is allowed for fixed-length
 355    types.)  <literal>plain</literal> specifies that data of the type
 356    will always be stored in-line and not compressed.
 357    <literal>extended</literal> specifies that the system will first
 358    try to compress a long data value, and will move the value out of
 359    the main table row if it's still too long.
 360    <literal>external</literal> allows the value to be moved out of the
 361    main table, but the system will not try to compress it.
 362    <literal>main</literal> allows compression, but discourages moving
 363    the value out of the main table.  (Data items with this storage
 364    strategy might still be moved out of the main table if there is no
 365    other way to make a row fit, but they will be kept in the main
 366    table preferentially over <literal>extended</literal> and
 367    <literal>external</literal> items.)
 368   </para>
 369
 370   <para>
 371    The <replaceable class="parameter">like_type</replaceable> parameter
 372    provides an alternative method for specifying the basic representation
 373    properties of a data type: copy them from some existing type. The values of
 374    <replaceable class="parameter">internallength</replaceable>,
 375    <replaceable class="parameter">passedbyvalue</replaceable>,
 376    <replaceable class="parameter">alignment</replaceable>, and
 377    <replaceable class="parameter">storage</replaceable> are copied from the
 378    named type.  (It is possible, though usually undesirable, to override
 379    some of these values by specifying them along with the <literal>LIKE</>
 380    clause.)  Specifying representation this way is especially useful when
 381    the low-level implementation of the new type <quote>piggybacks</> on an
 382    existing type in some fashion.
 383   </para>
 384
 385   <para>
 386    The <replaceable class="parameter">category</replaceable> and
 387    <replaceable class="parameter">preferred</replaceable> parameters can be
 388    used to help control which implicit cast will be applied in ambiguous
 389    situations.  Each data type belongs to a category named by a single ASCII
 390    character, and each type is either <quote>preferred</> or not within its
 391    category.  The parser will prefer casting to preferred types (but only from
 392    other types within the same category) when this rule is helpful in
 393    resolving overloaded functions or operators.  For more details see <xref
 394    linkend="typeconv">.  For types that have no implicit casts to or from any
 395    other types, it is sufficient to leave these settings at the defaults.
 396    However, for a group of related types that have implicit casts, it is often
 397    helpful to mark them all as belonging to a category and select one or two
 398    of the <quote>most general</> types as being preferred within the category.
 399    The <replaceable class="parameter">category</replaceable> parameter is
 400    especially useful when adding a user-defined type to an existing built-in
 401    category, such as the numeric or string types.  However, it is also
 402    possible to create new entirely-user-defined type categories.  Select any
 403    ASCII character other than an upper-case letter to name such a category.
 404   </para>
 405
 406   <para>
 407    A default value can be specified, in case a user wants columns of the
 408    data type to default to something other than the null value.
 409    Specify the default with the <literal>DEFAULT</literal> key word.
 410    (Such a default can be overridden by an explicit <literal>DEFAULT</literal>
 411    clause attached to a particular column.)
 412   </para>
 413
 414   <para>
 415    To indicate that a type is an array, specify the type of the array
 416    elements using the <literal>ELEMENT</> key word.  For example, to
 417    define an array of 4-byte integers (<type>int4</type>), specify
 418    <literal>ELEMENT = int4</literal>. More details about array types
 419    appear below.
 420   </para>
 421
 422   <para>
 423    To indicate the delimiter to be used between values in the external
 424    representation of arrays of this type, <replaceable
 425    class="parameter">delimiter</replaceable> can be
 426    set to a specific character.  The default delimiter is the comma
 427    (<literal>,</literal>).  Note that the delimiter is associated
 428    with the array element type, not the array type itself.
 429   </para>
 430
 431   <para>
 432    If the optional Boolean
 433    parameter <replaceable class="parameter">collatable</replaceable>
 434    is true, column definitions and expressions of the type may carry
 435    collation information through use of
 436    the <literal>COLLATE</literal> clause.  It is up to the
 437    implementations of the functions operating on the type to actually
 438    make use of the collation information; this does not happen
 439    automatically merely by marking the type collatable.
 440   </para>
 441   </refsect2>
 442
 443   <refsect2>
 444    <title>Array Types</title>
 445
 446    <para>
 447     Whenever a user-defined type is created,
 448     <productname>PostgreSQL</productname> automatically creates an
 449     associated array type, whose name consists of the element type's
 450     name prepended with an underscore, and truncated if necessary to keep
 451     it less than <symbol>NAMEDATALEN</symbol> bytes long.  (If the name
 452     so generated collides with an existing type name, the process is
 453     repeated until a non-colliding name is found.)
 454     This implicitly-created array type is variable length and uses the
 455     built-in input and output functions <literal>array_in</> and
 456     <literal>array_out</>.  The array type tracks any changes in its
 457     element type's owner or schema, and is dropped if the element type is.
 458    </para>
 459
 460    <para>
 461     You might reasonably ask why there is an <option>ELEMENT</>
 462     option, if the system makes the correct array type automatically.
 463     The only case where it's useful to use <option>ELEMENT</> is when you are
 464     making a fixed-length type that happens to be internally an array of a number of
 465     identical things, and you want to allow these things to be accessed
 466     directly by subscripting, in addition to whatever operations you plan
 467     to provide for the type as a whole.  For example, type <type>point</>
 468     is represented as just two floating-point numbers, each can be accessed using
 469     <literal>point[0]</> and <literal>point[1]</>.
 470     Note that
 471     this facility only works for fixed-length types whose internal form
 472     is exactly a sequence of identical fixed-length fields.  A subscriptable
 473     variable-length type must have the generalized internal representation
 474     used by <literal>array_in</> and <literal>array_out</>.
 475     For historical reasons (i.e., this is clearly wrong but it's far too
 476     late to change it), subscripting of fixed-length array types starts from
 477     zero, rather than from one as for variable-length arrays.
 478    </para>
 479   </refsect2>
 480  </refsect1>
 481
 482  <refsect1>
 483   <title>Parameters</title>
 484
 485   <variablelist>
 486    <varlistentry>
 487     <term><replaceable class="parameter">name</replaceable></term>
 488     <listitem>
 489      <para>
 490       The name (optionally schema-qualified) of a type to be created.
 491      </para>
 492     </listitem>
 493    </varlistentry>
 494
 495    <varlistentry>
 496     <term><replaceable class="parameter">attribute_name</replaceable></term>
 497     <listitem>
 498      <para>
 499       The name of an attribute (column) for the composite type.
 500      </para>
 501     </listitem>
 502    </varlistentry>
 503
 504    <varlistentry>
 505     <term><replaceable class="parameter">data_type</replaceable></term>
 506     <listitem>
 507      <para>
 508       The name of an existing data type to become a column of the
 509       composite type.
 510      </para>
 511     </listitem>
 512    </varlistentry>
 513
 514    <varlistentry>
 515     <term><replaceable class="parameter">collation</replaceable></term>
 516     <listitem>
 517      <para>
 518       The name of an existing collation to be associated with a column of
 519       a composite type, or with a range type.
 520      </para>
 521     </listitem>
 522    </varlistentry>
 523
 524    <varlistentry>
 525     <term><replaceable class="parameter">label</replaceable></term>
 526     <listitem>
 527      <para>
 528       A string literal representing the textual label associated with
 529       one value of an enum type.
 530      </para>
 531     </listitem>
 532    </varlistentry>
 533
 534    <varlistentry>
 535     <term><replaceable class="parameter">subtype</replaceable></term>
 536     <listitem>
 537      <para>
 538       The name of the element type that the range type will represent ranges
 539       of.
 540      </para>
 541     </listitem>
 542    </varlistentry>
 543
 544    <varlistentry>
 545     <term><replaceable class="parameter">subtype_operator_class</replaceable></term>
 546     <listitem>
 547      <para>
 548       The name of a b-tree operator class for the subtype.
 549      </para>
 550     </listitem>
 551    </varlistentry>
 552
 553    <varlistentry>
 554     <term><replaceable class="parameter">canonical_function</replaceable></term>
 555     <listitem>
 556      <para>
 557       The name of the canonicalization function for the range type.
 558      </para>
 559     </listitem>
 560    </varlistentry>
 561
 562    <varlistentry>
 563     <term><replaceable class="parameter">subtype_diff_function</replaceable></term>
 564     <listitem>
 565      <para>
 566       The name of a difference function for the subtype.
 567      </para>
 568     </listitem>
 569    </varlistentry>
 570
 571    <varlistentry>
 572     <term><replaceable class="parameter">input_function</replaceable></term>
 573     <listitem>
 574      <para>
 575       The name of a function that converts data from the type's
 576       external textual form to its internal form.
 577      </para>
 578     </listitem>
 579    </varlistentry>
 580
 581    <varlistentry>
 582     <term><replaceable class="parameter">output_function</replaceable></term>
 583     <listitem>
 584      <para>
 585       The name of a function that converts data from the type's
 586       internal form to its external textual form.
 587      </para>
 588     </listitem>
 589    </varlistentry>
 590
 591    <varlistentry>
 592     <term><replaceable class="parameter">receive_function</replaceable></term>
 593     <listitem>
 594      <para>
 595       The name of a function that converts data from the type's
 596       external binary form to its internal form.
 597      </para>
 598     </listitem>
 599    </varlistentry>
 600
 601    <varlistentry>
 602     <term><replaceable class="parameter">send_function</replaceable></term>
 603     <listitem>
 604      <para>
 605       The name of a function that converts data from the type's
 606       internal form to its external binary form.
 607      </para>
 608     </listitem>
 609    </varlistentry>
 610
 611    <varlistentry>
 612     <term><replaceable class="parameter">type_modifier_input_function</replaceable></term>
 613     <listitem>
 614      <para>
 615       The name of a function that converts an array of modifier(s) for the type
 616       into internal form.
 617      </para>
 618     </listitem>
 619    </varlistentry>
 620
 621    <varlistentry>
 622     <term><replaceable class="parameter">type_modifier_output_function</replaceable></term>
 623     <listitem>
 624      <para>
 625       The name of a function that converts the internal form of the type's
 626       modifier(s) to external textual form.
 627      </para>
 628     </listitem>
 629    </varlistentry>
 630
 631    <varlistentry>
 632     <term><replaceable class="parameter">analyze_function</replaceable></term>
 633     <listitem>
 634      <para>
 635       The name of a function that performs statistical analysis for the
 636       data type.
 637      </para>
 638     </listitem>
 639    </varlistentry>
 640
 641    <varlistentry>
 642     <term><replaceable class="parameter">internallength</replaceable></term>
 643     <listitem>
 644      <para>
 645       A numeric constant that specifies the length in bytes of the new
 646       type's internal representation.  The default assumption is that
 647       it is variable-length.
 648      </para>
 649     </listitem>
 650    </varlistentry>
 651
 652    <varlistentry>
 653     <term><replaceable class="parameter">alignment</replaceable></term>
 654     <listitem>
 655      <para>
 656       The storage alignment requirement of the data type.  If specified,
 657       it must be <literal>char</literal>, <literal>int2</literal>,
 658       <literal>int4</literal>, or <literal>double</literal>; the
 659       default is <literal>int4</literal>.
 660      </para>
 661     </listitem>
 662    </varlistentry>
 663
 664    <varlistentry>
 665     <term><replaceable class="parameter">storage</replaceable></term>
 666     <listitem>
 667      <para>
 668       The storage strategy for the data type.  If specified, must be
 669       <literal>plain</literal>, <literal>external</literal>,
 670       <literal>extended</literal>, or <literal>main</literal>; the
 671       default is <literal>plain</literal>.
 672      </para>
 673     </listitem>
 674    </varlistentry>
 675
 676    <varlistentry>
 677     <term><replaceable class="parameter">like_type</replaceable></term>
 678     <listitem>
 679      <para>
 680       The name of an existing data type that the new type will have the
 681       same representation as.  The values of
 682       <replaceable class="parameter">internallength</replaceable>,
 683       <replaceable class="parameter">passedbyvalue</replaceable>,
 684       <replaceable class="parameter">alignment</replaceable>, and
 685       <replaceable class="parameter">storage</replaceable>
 686       are copied from that type, unless overridden by explicit
 687       specification elsewhere in this <command>CREATE TYPE</> command.
 688      </para>
 689     </listitem>
 690    </varlistentry>
 691
 692    <varlistentry>
 693     <term><replaceable class="parameter">category</replaceable></term>
 694     <listitem>
 695      <para>
 696       The category code (a single ASCII character) for this type.
 697       The default is <literal>'U'</> for <quote>user-defined type</>.
 698       Other standard category codes can be found in
 699       <xref linkend="catalog-typcategory-table">.  You may also choose
 700       other ASCII characters in order to create custom categories.
 701      </para>
 702     </listitem>
 703    </varlistentry>
 704
 705    <varlistentry>
 706     <term><replaceable class="parameter">preferred</replaceable></term>
 707     <listitem>
 708      <para>
 709       True if this type is a preferred type within its type category,
 710       else false.  The default is false.  Be very careful about creating
 711       a new preferred type within an existing type category, as this
 712       could cause surprising changes in behavior.
 713      </para>
 714     </listitem>
 715    </varlistentry>
 716
 717    <varlistentry>
 718     <term><replaceable class="parameter">default</replaceable></term>
 719     <listitem>
 720      <para>
 721       The default value for the data type.  If this is omitted, the
 722       default is null.
 723      </para>
 724     </listitem>
 725    </varlistentry>
 726
 727    <varlistentry>
 728     <term><replaceable class="parameter">element</replaceable></term>
 729     <listitem>
 730      <para>
 731       The type being created is an array; this specifies the type of
 732       the array elements.
 733      </para>
 734     </listitem>
 735    </varlistentry>
 736
 737    <varlistentry>
 738     <term><replaceable class="parameter">delimiter</replaceable></term>
 739     <listitem>
 740      <para>
 741       The delimiter character to be used between values in arrays made
 742       of this type.
 743      </para>
 744     </listitem>
 745    </varlistentry>
 746
 747    <varlistentry>
 748     <term><replaceable class="parameter">collatable</replaceable></term>
 749     <listitem>
 750      <para>
 751       True if this type's operations can use collation information.
 752       The default is false.
 753      </para>
 754     </listitem>
 755    </varlistentry>
 756   </variablelist>
 757  </refsect1>
 758
 759  <refsect1 id="SQL-CREATETYPE-notes">
 760   <title>Notes</title>
 761
 762   <para>
 763    Because there are no restrictions on use of a data type once it's been
 764    created, creating a base type or range type is tantamount to granting
 765    public execute permission on the functions mentioned in the type definition.
 766    This is usually
 767    not an issue for the sorts of functions that are useful in a type
 768    definition.  But you might want to think twice before designing a type
 769    in a way that would require <quote>secret</> information to be used
 770    while converting it to or from external form.
 771   </para>
 772
 773   <para>
 774    Before <productname>PostgreSQL</productname> version 8.3, the name of
 775    a generated array type was always exactly the element type's name with one
 776    underscore character (<literal>_</literal>) prepended.  (Type names were
 777    therefore restricted in length to one less character than other names.)
 778    While this is still usually the case, the array type name may vary from
 779    this in case of maximum-length names or collisions with user type names
 780    that begin with underscore.  Writing code that depends on this convention
 781    is therefore deprecated.  Instead, use
 782    <structname>pg_type</>.<structfield>typarray</> to locate the array type
 783    associated with a given type.
 784   </para>
 785
 786   <para>
 787    It may be advisable to avoid using type and table names that begin with
 788    underscore.  While the server will change generated array type names to
 789    avoid collisions with user-given names, there is still risk of confusion,
 790    particularly with old client software that may assume that type names
 791    beginning with underscores always represent arrays.
 792   </para>
 793
 794   <para>
 795    Before <productname>PostgreSQL</productname> version 8.2, the shell-type
 796    creation syntax
 797    <literal>CREATE TYPE <replaceable>name</></literal> did not exist.
 798    The way to create a new base type was to create its input function first.
 799    In this approach, <productname>PostgreSQL</productname> will first see
 800    the name of the new data type as the return type of the input function.
 801    The shell type is implicitly created in this situation, and then it
 802    can be referenced in the definitions of the remaining I/O functions.
 803    This approach still works, but is deprecated and might be disallowed in
 804    some future release.  Also, to avoid accidentally cluttering
 805    the catalogs with shell types as a result of simple typos in function
 806    definitions, a shell type will only be made this way when the input
 807    function is written in C.
 808   </para>
 809
 810   <para>
 811    In <productname>PostgreSQL</productname> versions before 7.3, it
 812    was customary to avoid creating a shell type at all, by replacing the
 813    functions' forward references to the type name with the placeholder
 814    pseudotype <type>opaque</>.  The <type>cstring</> arguments and
 815    results also had to be declared as <type>opaque</> before 7.3.  To
 816    support loading of old dump files, <command>CREATE TYPE</> will
 817    accept I/O functions declared using <type>opaque</>, but it will issue
 818    a notice and change the function declarations to use the correct
 819    types.
 820   </para>
 821
 822  </refsect1>
 823
 824  <refsect1>
 825   <title>Examples</title>
 826
 827   <para>
 828    This example creates a composite type and uses it in
 829    a function definition:
 830 <programlisting>
 831 CREATE TYPE compfoo AS (f1 int, f2 text);
 832
 833 CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$
 834     SELECT fooid, fooname FROM foo
 835 $$ LANGUAGE SQL;
 836 </programlisting>
 837   </para>
 838
 839   <para>
 840    This example creates an enumerated type and uses it in
 841    a table definition:
 842 <programlisting>
 843 CREATE TYPE bug_status AS ENUM ('new', 'open', 'closed');
 844
 845 CREATE TABLE bug (
 846     id serial,
 847     description text,
 848     status bug_status
 849 );
 850 </programlisting>
 851   </para>
 852
 853   <para>
 854    This example creates a range type:
 855 <programlisting>
 856 CREATE TYPE float8_range AS RANGE (subtype = float8, subtype_diff = float8mi);
 857 </programlisting>
 858   </para>
 859
 860   <para>
 861    This example creates the base data type <type>box</type> and then uses the
 862    type in a table definition:
 863 <programlisting>
 864 CREATE TYPE box;
 865
 866 CREATE FUNCTION my_box_in_function(cstring) RETURNS box AS ... ;
 867 CREATE FUNCTION my_box_out_function(box) RETURNS cstring AS ... ;
 868
 869 CREATE TYPE box (
 870     INTERNALLENGTH = 16,
 871     INPUT = my_box_in_function,
 872     OUTPUT = my_box_out_function
 873 );
 874
 875 CREATE TABLE myboxes (
 876     id integer,
 877     description box
 878 );
 879 </programlisting>
 880   </para>
 881
 882   <para>
 883    If the internal structure of <type>box</type> were an array of four
 884    <type>float4</> elements, we might instead use:
 885 <programlisting>
 886 CREATE TYPE box (
 887     INTERNALLENGTH = 16,
 888     INPUT = my_box_in_function,
 889     OUTPUT = my_box_out_function,
 890     ELEMENT = float4
 891 );
 892 </programlisting>
 893    which would allow a box value's component numbers to be accessed
 894    by subscripting.  Otherwise the type behaves the same as before.
 895   </para>
 896
 897   <para>
 898    This example creates a large object type and uses it in
 899    a table definition:
 900 <programlisting>
 901 CREATE TYPE bigobj (
 902     INPUT = lo_filein, OUTPUT = lo_fileout,
 903     INTERNALLENGTH = VARIABLE
 904 );
 905 CREATE TABLE big_objs (
 906     id integer,
 907     obj bigobj
 908 );
 909 </programlisting>
 910   </para>
 911
 912   <para>
 913    More examples, including suitable input and output functions, are
 914    in <xref linkend="xtypes">.
 915   </para>
 916  </refsect1>
 917
 918  <refsect1 id="SQL-CREATETYPE-compatibility">
 919   <title>Compatibility</title>
 920
 921   <para>
 922    The first form of the <command>CREATE TYPE</command> command, which
 923    creates a composite type, conforms to the <acronym>SQL</> standard.
 924    The other forms are <productname>PostgreSQL</productname>
 925    extensions.  The <command>CREATE TYPE</command> statement in
 926    the <acronym>SQL</> standard also defines other forms that are not
 927    implemented in <productname>PostgreSQL</>.
 928   </para>
 929
 930   <para>
 931    The ability to create a composite type with zero attributes is
 932    a <productname>PostgreSQL</productname>-specific deviation from the
 933    standard (analogous to the same case in <command>CREATE TABLE</command>).
 934   </para>
 935  </refsect1>
 936
 937  <refsect1 id="SQL-CREATETYPE-see-also">
 938   <title>See Also</title>
 939
 940   <simplelist type="inline">
 941    <member><xref linkend="sql-altertype"></member>
 942    <member><xref linkend="sql-createdomain"></member>
 943    <member><xref linkend="sql-createfunction"></member>
 944    <member><xref linkend="sql-droptype"></member>
 945   </simplelist>
 946  </refsect1>
 947
 948 </refentry>