~ubuntu-branches/ubuntu/quantal/postgresql-9.1/quantal-proposed

« back to all changes in this revision

Viewing changes to doc/src/sgml/man7/CREATE_TYPE.7

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2011-12-02 14:39:18 UTC
  • mfrom: (12.1.1 sid)
  • Revision ID: package-import@ubuntu.com-20111202143918-1ftj0oo87w0y8m8d
* New upstream bug fix release:
  - Fix bugs in information_schema.referential_constraints view.
    This view was being insufficiently careful about matching the
    foreign-key constraint to the depended-on primary or unique key
    constraint. That could result in failure to show a foreign key
    constraint at all, or showing it multiple times, or claiming that
    it depends on a different constraint than the one it really does.
    Since the view definition is installed by initdb, merely upgrading
    will not fix the problem. If you need to fix this in an existing
    installation, you can (as a superuser) drop the information_schema
    schema then re-create it by sourcing
    "SHAREDIR/information_schema.sql". (Run pg_config --sharedir if
    you're uncertain where "SHAREDIR" is.) This must be repeated in
    each database to be fixed.
  - Make "contrib/citext"'s upgrade script fix collations of citext
    columns and indexes.
    Existing citext columns and indexes aren't correctly marked as
    being of a collatable data type during pg_upgrade from a pre-9.1
    server. That leads to operations on them failing with errors such
    as "could not determine which collation to use for string
    comparison". This change allows them to be fixed by the same script
    that upgrades the citext module into a proper 9.1 extension during
    CREATE EXTENSION citext FROM unpackaged.
    If you have a previously-upgraded database that is suffering from
    this problem, and you already ran the "CREATE EXTENSION" command,
    you can manually run (as superuser) the "UPDATE" commands found at
    the end of "SHAREDIR/extension/citext--unpackaged--1.0.sql". (Run
    pg_config --sharedir if you're uncertain where "SHAREDIR" is.)
  - Fix possible crash during "UPDATE" or "DELETE" that joins to the
    output of a scalar-returning function.
  - Fix incorrect replay of WAL records for GIN index updates.
  - Fix TOAST-related data corruption during CREATE TABLE dest AS
    SELECT - FROM src or INSERT INTO dest SELECT * FROM src.
  - Fix possible failures during hot standby startup.
  - Start hot standby faster when initial snapshot is incomplete.
  - Fix race condition during toast table access from stale syscache
    entries. The typical symptom was transient errors like "missing chunk
    number 0 for toast value NNNNN in pg_toast_2619", where the cited toast
    table would always belong to a system catalog.
  - Track dependencies of functions on items used in parameter default
    expressions. Previously, a referenced object could be dropped without
    having dropped or modified the function, leading to misbehavior when
    the function was used. Note that merely installing this update will not
    fix the missing dependency entries; to do that, you'd need to
    "CREATE OR REPLACE" each such function afterwards. If you have
    functions whose defaults depend on non-built-in objects, doing so
    is recommended.
  - Fix incorrect management of placeholder variables in nestloop joins.
    This bug is known to lead to "variable not found in subplan target
    list" planner errors, and could possibly result in wrong query
    output when outer joins are involved.
  - Fix window functions that sort by expressions involving aggregates.
  - Fix "MergeAppend child's targetlist doesn't match MergeAppend"
    planner errors.
  - Fix index matching for operators with both collatable and
    noncollatable inputs. In 9.1.0, an indexable operator that has a
    non-collatable left-hand input type and a collatable right-hand input
    type would not be recognized as matching the left-hand column's index.
    An example is the hstore ? text operator.
  - Allow inlining of set-returning SQL functions with multiple OUT
    parameters.
  - Don't trust deferred-unique indexes for join removal.
  - Make DatumGetInetP() unpack inet datums that have a 1-byte header,
    and add a new macro, DatumGetInetPP(), that does not.
  - Improve locale support in money type's input and output.
    Aside from not supporting all standard lc_monetary formatting
    options, the input and output functions were inconsistent, meaning
    there were locales in which dumped money values could not be
    re-read.
  - Don't let transform_null_equals affect CASE foo WHEN NULL ...
    constructs.  transform_null_equals is only supposed to affect foo =
    NULL expressions written directly by the user, not equality checks
    generated internally by this form of CASE.
  - Change foreign-key trigger creation order to better support
    self-referential foreign keys.
  - Fix IF EXISTS to work correctly in "DROP OPERATOR FAMILY".
  - Disallow dropping of an extension from within its own script.
  - Don't mark auto-generated types as extension members.
  - Cope with invalid pre-existing search_path settings during "CREATE
    EXTENSION".
  - Avoid floating-point underflow while tracking buffer allocation
    rate.
  - Prevent autovacuum transactions from running in serializable mode.
    Autovacuum formerly used the cluster-wide default transaction
    isolation level, but there is no need for it to use anything higher
    than READ COMMITTED, and using SERIALIZABLE could result in
    unnecessary delays for other processes.
  - Ensure walsender processes respond promptly to SIGTERM.
  - Exclude "postmaster.opts" from base backups.
  - Fix incorrect field alignment in ecpg's SQLDA area.
  - Preserve blank lines within commands in psql's command history.
    The former behavior could cause problems if an empty line was
    removed from within a string literal, for example.
  - Avoid platform-specific infinite loop in pg_dump.
  - Fix compression of plain-text output format in pg_dump.
    pg_dump has historically understood -Z with no -F switch to mean
    that it should emit a gzip-compressed version of its plain text
    output. Restore that behavior.
  - Fix pg_dump to dump user-defined casts between auto-generated
    types, such as table rowtypes.
  - Fix missed quoting of foreign server names in pg_dump.
  - Assorted fixes for pg_upgrade. Handle exclusion constraints correctly,
    avoid failures on Windows, don't complain about mismatched toast table
    names in 8.4 databases.
  - In PL/pgSQL, allow foreign tables to define row types.
  - Fix up conversions of PL/Perl functions' results.
    Restore the pre-9.1 behavior that PL/Perl functions returning void
    ignore the result value of their last Perl statement; 9.1.0 would
    throw an error if that statement returned a reference. Also, make
    sure it works to return a string value for a composite type, so
    long as the string meets the type's input format. In addition,
    throw errors for attempts to return Perl arrays or hashes when the
    function's declared result type is not an array or composite type,
    respectively. (Pre-9.1 versions rather uselessly returned strings
    like ARRAY(0x221a9a0) or HASH(0x221aa90) in such cases.)
  - Ensure PL/Perl strings are always correctly UTF8-encoded.
  - Use the preferred version of xsubpp to build PL/Perl, not
    necessarily the operating system's main copy.
  - Correctly propagate SQLSTATE in PL/Python exceptions.
  - Do not install PL/Python extension files for Python major versions
    other than the one built against.
  - Change all the "contrib" extension script files to report a useful
    error message if they are fed to psql. This should help teach people
    about the new method of using "CREATE EXTENSION" to load these files.
    In most cases, sourcing the scripts directly would fail anyway, but
    with harder-to-interpret messages.
  - Fix incorrect coding in "contrib/dict_int" and "contrib/dict_xsyn".
  - Remove "contrib/sepgsql" tests from the regular regression test
    mechanism. Since these tests require root privileges for setup, they're
    impractical to run automatically. Switch over to a manual approach
    instead, and provide a testing script to help with that.
  - Fix assorted errors in "contrib/unaccent"'s configuration file
    parsing.
  - Honor query cancel interrupts promptly in pgstatindex().
  - Revert unintentional enabling of WAL_DEBUG. Fortunately, as debugging
    tools go, this one is pretty cheap; but it's not intended to be enabled
    by default, so revert.
  - Ensure VPATH builds properly install all server header files.
  - Shorten file names reported in verbose error messages.
    Regular builds have always reported just the name of the C file
    containing the error message call, but VPATH builds formerly
    reported an absolute path name.
* debian/rules: Fix build failure for binary-indep-only builds.
  (Closes: #646079)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
'\" t
2
2
.\"     Title: CREATE TYPE
3
3
.\"    Author: The PostgreSQL Global Development Group
4
 
.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
5
 
.\"      Date: 2011-09-22
6
 
.\"    Manual: PostgreSQL 9.1.1 Documentation
7
 
.\"    Source: PostgreSQL 9.1.1
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 
5
.\"      Date: 2011-12-01
 
6
.\"    Manual: PostgreSQL 9.1.2 Documentation
 
7
.\"    Source: PostgreSQL 9.1.2
8
8
.\"  Language: English
9
9
.\"
10
 
.TH "CREATE TYPE" "7" "2011-09-22" "PostgreSQL 9.1.1" "PostgreSQL 9.1.1 Documentation"
 
10
.TH "CREATE TYPE" "7" "2011-12-01" "PostgreSQL 9.1.2" "PostgreSQL 9.1.2 Documentation"
 
11
.\" -----------------------------------------------------------------
 
12
.\" * Define some portability stuff
 
13
.\" -----------------------------------------------------------------
 
14
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
15
.\" http://bugs.debian.org/507673
 
16
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 
17
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
18
.ie \n(.g .ds Aq \(aq
 
19
.el       .ds Aq '
11
20
.\" -----------------------------------------------------------------
12
21
.\" * set default formatting
13
22
.\" -----------------------------------------------------------------
28
37
    ( [ \fIattribute_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [, \&.\&.\&. ] ] )
29
38
 
30
39
CREATE TYPE \fIname\fR AS ENUM
31
 
    ( [ \(aq\fIlabel\fR\(aq [, \&.\&.\&. ] ] )
 
40
    ( [ \*(Aq\fIlabel\fR\*(Aq [, \&.\&.\&. ] ] )
32
41
 
33
42
CREATE TYPE \fIname\fR (
34
43
    INPUT = \fIinput_function\fR,
64
73
.PP
65
74
The first form of
66
75
CREATE TYPE
67
 
creates a composite type\&. The composite type is specified by a list of attribute names and data types\&. An attribute\(aqs collation can be specified too, if its data type is collatable\&. A composite type is essentially the same as the row type of a table, but using
 
76
creates a composite type\&. The composite type is specified by a list of attribute names and data types\&. An attribute\*(Aqs collation can be specified too, if its data type is collatable\&. A composite type is essentially the same as the row type of a table, but using
68
77
CREATE TYPE
69
78
avoids the need to create an actual table when all that is wanted is to define a type\&. A stand\-alone composite type is useful, for example, as the argument or return type of a function\&.
70
79
.SS "Enumerated Types"
99
108
.PP
100
109
The
101
110
\fIinput_function\fR
102
 
converts the type\(aqs external textual representation to the internal representation used by the operators and functions defined for the type\&.
 
111
converts the type\*(Aqs external textual representation to the internal representation used by the operators and functions defined for the type\&.
103
112
\fIoutput_function\fR
104
113
performs the reverse transformation\&. The input function can be declared as taking one argument of type
105
114
cstring, or as taking three arguments of types
106
115
cstring,
107
116
oid,
108
 
integer\&. The first argument is the input text as a C string, the second argument is the type\(aqs own OID (except for array types, which instead receive their element type\(aqs OID), and the third is the
 
117
integer\&. The first argument is the input text as a C string, the second argument is the type\*(Aqs own OID (except for array types, which instead receive their element type\*(Aqs OID), and the third is the
109
118
typmod
110
119
of the destination column, if known (\-1 will be passed if not)\&. The input function must return a value of the data type itself\&. Usually, an input function should be declared STRICT; if it is not, it will be called with a NULL first parameter when reading a NULL input value\&. The function must still return NULL in this case, unless it raises an error\&. (This case is mainly meant to support domain input functions, which might need to reject NULL inputs\&.) The output function must be declared as taking one argument of the new data type\&. The output function must return type
111
120
cstring\&. Output functions are not invoked for NULL values\&.
112
121
.PP
113
122
The optional
114
123
\fIreceive_function\fR
115
 
converts the type\(aqs external binary representation to the internal representation\&. If this function is not supplied, the type cannot participate in binary input\&. The binary representation should be chosen to be cheap to convert to internal form, while being reasonably portable\&. (For example, the standard integer data types use network byte order as the external binary representation, while the internal representation is in the machine\(aqs native byte order\&.) The receive function should perform adequate checking to ensure that the value is valid\&. The receive function can be declared as taking one argument of type
 
124
converts the type\*(Aqs external binary representation to the internal representation\&. If this function is not supplied, the type cannot participate in binary input\&. The binary representation should be chosen to be cheap to convert to internal form, while being reasonably portable\&. (For example, the standard integer data types use network byte order as the external binary representation, while the internal representation is in the machine\*(Aqs native byte order\&.) The receive function should perform adequate checking to ensure that the value is valid\&. The receive function can be declared as taking one argument of type
116
125
internal, or as taking three arguments of types
117
126
internal,
118
127
oid,
151
160
converts the internal integer typmod value back to the correct form for user display\&. It must return a
152
161
cstring
153
162
value that is the exact string to append to the type name; for example
154
 
numeric\(aqs function might return
 
163
numeric\*(Aqs function might return
155
164
(30,2)\&. It is allowed to omit the
156
165
\fItype_modifier_output_function\fR, in which case the default display format is just the stored typmod integer value enclosed in parentheses\&.
157
166
.PP
159
168
\fIanalyze_function\fR
160
169
performs type\-specific statistics collection for columns of the data type\&. By default,
161
170
ANALYZE
162
 
will attempt to gather statistics using the type\(aqs
 
171
will attempt to gather statistics using the type\*(Aqs
163
172
\(lqequals\(rq
164
173
and
165
174
\(lqless\-than\(rq
169
178
result\&. The detailed API for analysis functions appears in
170
179
src/include/commands/vacuum\&.h\&.
171
180
.PP
172
 
While the details of the new type\(aqs internal representation are only known to the I/O functions and other functions you create to work with the type, there are several properties of the internal representation that must be declared to
 
181
While the details of the new type\*(Aqs internal representation are only known to the I/O functions and other functions you create to work with the type, there are several properties of the internal representation that must be declared to
173
182
PostgreSQL\&. Foremost of these is
174
183
\fIinternallength\fR\&. Base data types can be fixed\-length, in which case
175
184
\fIinternallength\fR
200
209
plain
201
210
specifies that data of the type will always be stored in\-line and not compressed\&.
202
211
extended
203
 
specifies that the system will first try to compress a long data value, and will move the value out of the main table row if it\(aqs still too long\&.
 
212
specifies that the system will first try to compress a long data value, and will move the value out of the main table row if it\*(Aqs still too long\&.
204
213
external
205
214
allows the value to be moved out of the main table, but the system will not try to compress it\&.
206
215
main
260
269
.PP
261
270
Whenever a user\-defined type is created,
262
271
PostgreSQL
263
 
automatically creates an associated array type, whose name consists of the base type\(aqs name prepended with an underscore, and truncated if necessary to keep it less than
 
272
automatically creates an associated array type, whose name consists of the base type\*(Aqs name prepended with an underscore, and truncated if necessary to keep it less than
264
273
NAMEDATALEN
265
274
bytes long\&. (If the name so generated collides with an existing type name, the process is repeated until a non\-colliding name is found\&.) This implicitly\-created array type is variable length and uses the built\-in input and output functions
266
275
array_in
267
276
and
268
 
array_out\&. The array type tracks any changes in its element type\(aqs owner or schema, and is dropped if the element type is\&.
 
277
array_out\&. The array type tracks any changes in its element type\*(Aqs owner or schema, and is dropped if the element type is\&.
269
278
.PP
270
279
You might reasonably ask why there is an
271
280
\fBELEMENT\fR
272
 
option, if the system makes the correct array type automatically\&. The only case where it\(aqs useful to use
 
281
option, if the system makes the correct array type automatically\&. The only case where it\*(Aqs useful to use
273
282
\fBELEMENT\fR
274
283
is when you are making a fixed\-length type that happens to be internally an array of a number of identical things, and you want to allow these things to be accessed directly by subscripting, in addition to whatever operations you plan to provide for the type as a whole\&. For example, type
275
284
point
279
288
point[1]\&. Note that this facility only works for fixed\-length types whose internal form is exactly a sequence of identical fixed\-length fields\&. A subscriptable variable\-length type must have the generalized internal representation used by
280
289
array_in
281
290
and
282
 
array_out\&. For historical reasons (i\&.e\&., this is clearly wrong but it\(aqs far too late to change it), subscripting of fixed\-length array types starts from zero, rather than from one as for variable\-length arrays\&.
 
291
array_out\&. For historical reasons (i\&.e\&., this is clearly wrong but it\*(Aqs far too late to change it), subscripting of fixed\-length array types starts from zero, rather than from one as for variable\-length arrays\&.
283
292
.SH "PARAMETERS"
284
293
.PP
285
294
\fIname\fR
304
313
.PP
305
314
\fIinput_function\fR
306
315
.RS 4
307
 
The name of a function that converts data from the type\(aqs external textual form to its internal form\&.
 
316
The name of a function that converts data from the type\*(Aqs external textual form to its internal form\&.
308
317
.RE
309
318
.PP
310
319
\fIoutput_function\fR
311
320
.RS 4
312
 
The name of a function that converts data from the type\(aqs internal form to its external textual form\&.
 
321
The name of a function that converts data from the type\*(Aqs internal form to its external textual form\&.
313
322
.RE
314
323
.PP
315
324
\fIreceive_function\fR
316
325
.RS 4
317
 
The name of a function that converts data from the type\(aqs external binary form to its internal form\&.
 
326
The name of a function that converts data from the type\*(Aqs external binary form to its internal form\&.
318
327
.RE
319
328
.PP
320
329
\fIsend_function\fR
321
330
.RS 4
322
 
The name of a function that converts data from the type\(aqs internal form to its external binary form\&.
 
331
The name of a function that converts data from the type\*(Aqs internal form to its external binary form\&.
323
332
.RE
324
333
.PP
325
334
\fItype_modifier_input_function\fR
329
338
.PP
330
339
\fItype_modifier_output_function\fR
331
340
.RS 4
332
 
The name of a function that converts the internal form of the type\(aqs modifier(s) to external textual form\&.
 
341
The name of a function that converts the internal form of the type\*(Aqs modifier(s) to external textual form\&.
333
342
.RE
334
343
.PP
335
344
\fIanalyze_function\fR
339
348
.PP
340
349
\fIinternallength\fR
341
350
.RS 4
342
 
A numeric constant that specifies the length in bytes of the new type\(aqs internal representation\&. The default assumption is that it is variable\-length\&.
 
351
A numeric constant that specifies the length in bytes of the new type\*(Aqs internal representation\&. The default assumption is that it is variable\-length\&.
343
352
.RE
344
353
.PP
345
354
\fIalignment\fR
377
386
\fIcategory\fR
378
387
.RS 4
379
388
The category code (a single ASCII character) for this type\&. The default is
380
 
\(aqU\(aq
 
389
\*(AqU\*(Aq
381
390
for
382
391
\(lquser\-defined type\(rq\&. Other standard category codes can be found in
383
392
Table\ \&45.49, \(lqtypcategory Codes\(rq\&. You may also choose other ASCII characters in order to create custom categories\&.
405
414
.PP
406
415
\fIcollatable\fR
407
416
.RS 4
408
 
True if this type\(aqs operations can use collation information\&. The default is false\&.
 
417
True if this type\*(Aqs operations can use collation information\&. The default is false\&.
409
418
.RE
410
419
.SH "NOTES"
411
420
.PP
412
 
Because there are no restrictions on use of a data type once it\(aqs been created, creating a base type is tantamount to granting public execute permission on the functions mentioned in the type definition\&. This is usually not an issue for the sorts of functions that are useful in a type definition\&. But you might want to think twice before designing a type in a way that would require
 
421
Because there are no restrictions on use of a data type once it\*(Aqs been created, creating a base type is tantamount to granting public execute permission on the functions mentioned in the type definition\&. This is usually not an issue for the sorts of functions that are useful in a type definition\&. But you might want to think twice before designing a type in a way that would require
413
422
\(lqsecret\(rq
414
423
information to be used while converting it to or from external form\&.
415
424
.PP
416
425
Before
417
426
PostgreSQL
418
 
version 8\&.3, the name of a generated array type was always exactly the element type\(aqs name with one underscore character (_) prepended\&. (Type names were therefore restricted in length to one less character than other names\&.) While this is still usually the case, the array type name may vary from this in case of maximum\-length names or collisions with user type names that begin with underscore\&. Writing code that depends on this convention is therefore deprecated\&. Instead, use
 
427
version 8\&.3, the name of a generated array type was always exactly the element type\*(Aqs name with one underscore character (_) prepended\&. (Type names were therefore restricted in length to one less character than other names\&.) While this is still usually the case, the array type name may vary from this in case of maximum\-length names or collisions with user type names that begin with underscore\&. Writing code that depends on this convention is therefore deprecated\&. Instead, use
419
428
pg_type\&.typarray
420
429
to locate the array type associated with a given type\&.
421
430
.PP
431
440
.PP
432
441
In
433
442
PostgreSQL
434
 
versions before 7\&.3, it was customary to avoid creating a shell type at all, by replacing the functions\(aq forward references to the type name with the placeholder pseudotype
 
443
versions before 7\&.3, it was customary to avoid creating a shell type at all, by replacing the functions\*(Aq forward references to the type name with the placeholder pseudotype
435
444
opaque\&. The
436
445
cstring
437
446
arguments and results also had to be declared as
464
473
.RS 4
465
474
.\}
466
475
.nf
467
 
CREATE TYPE bug_status AS ENUM (\(aqnew\(aq, \(aqopen\(aq, \(aqclosed\(aq);
 
476
CREATE TYPE bug_status AS ENUM (\*(Aqnew\*(Aq, \*(Aqopen\*(Aq, \*(Aqclosed\*(Aq);
468
477
 
469
478
CREATE TABLE bug (
470
479
    id serial,
525
534
.RE
526
535
.\}
527
536
.sp
528
 
which would allow a box value\(aqs component numbers to be accessed by subscripting\&. Otherwise the type behaves the same as before\&.
 
537
which would allow a box value\*(Aqs component numbers to be accessed by subscripting\&. Otherwise the type behaves the same as before\&.
529
538
.PP
530
539
This example creates a large object type and uses it in a table definition:
531
540
.sp