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

« back to all changes in this revision

Viewing changes to doc/src/sgml/man7/CREATE_FUNCTION.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 FUNCTION
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 FUNCTION" "7" "2011-09-22" "PostgreSQL 9.1.1" "PostgreSQL 9.1.1 Documentation"
 
10
.TH "CREATE FUNCTION" "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
.\" -----------------------------------------------------------------
36
45
    | COST \fIexecution_cost\fR
37
46
    | ROWS \fIresult_rows\fR
38
47
    | SET \fIconfiguration_parameter\fR { TO \fIvalue\fR | = \fIvalue\fR | FROM CURRENT }
39
 
    | AS \(aq\fIdefinition\fR\(aq
40
 
    | AS \(aq\fIobj_file\fR\(aq, \(aq\fIlink_symbol\fR\(aq
 
48
    | AS \*(Aq\fIdefinition\fR\*(Aq
 
49
    | AS \*(Aq\fIobj_file\fR\*(Aq, \*(Aq\fIlink_symbol\fR\*(Aq
41
50
  } \&.\&.\&.
42
51
    [ WITH ( \fIattribute\fR [, \&.\&.\&.] ) ]
43
52
.fi
109
118
.PP
110
119
\fIargtype\fR
111
120
.RS 4
112
 
The data type(s) of the function\(aqs arguments (optionally schema\-qualified), if any\&. The argument types can be base, composite, or domain types, or can reference the type of a table column\&.
 
121
The data type(s) of the function\*(Aqs arguments (optionally schema\-qualified), if any\&. The argument types can be base, composite, or domain types, or can reference the type of a table column\&.
113
122
.sp
114
123
Depending on the implementation language it might also be allowed to specify
115
124
\(lqpseudotypes\(rq
220
229
CALLED ON NULL INPUT, RETURNS NULL ON NULL INPUT, STRICT
221
230
.RS 4
222
231
CALLED ON NULL INPUT
223
 
(the default) indicates that the function will be called normally when some of its arguments are null\&. It is then the function author\(aqs responsibility to check for null values if necessary and respond appropriately\&.
 
232
(the default) indicates that the function will be called normally when some of its arguments are null\&. It is then the function author\*(Aqs responsibility to check for null values if necessary and respond appropriately\&.
224
233
.sp
225
234
RETURNS NULL ON NULL INPUT
226
235
or
257
266
SET
258
267
clause causes the specified configuration parameter to be set to the specified value when the function is entered, and then restored to its prior value when the function exits\&.
259
268
SET FROM CURRENT
260
 
saves the session\(aqs current value of the parameter as the value to be applied when the function is entered\&.
 
269
saves the session\*(Aqs current value of the parameter as the value to be applied when the function is entered\&.
261
270
.sp
262
271
If a
263
272
SET
264
273
clause is attached to a function, then the effects of a
265
274
SET LOCAL
266
 
command executed inside the function for the same variable are restricted to the function: the configuration parameter\(aqs prior value is still restored at function exit\&. However, an ordinary
 
275
command executed inside the function for the same variable are restricted to the function: the configuration parameter\*(Aqs prior value is still restored at function exit\&. However, an ordinary
267
276
SET
268
277
command (without
269
278
LOCAL) overrides the
295
304
\fIobj_file\fR
296
305
is the name of the file containing the dynamically loadable object, and
297
306
\fIlink_symbol\fR
298
 
is the function\(aqs link symbol, that is, the name of the function in the C language source code\&. If the link symbol is omitted, it is assumed to be the same as the name of the SQL function being defined\&.
 
307
is the function\*(Aqs link symbol, that is, the name of the function in the C language source code\&. If the link symbol is omitted, it is assumed to be the same as the name of the SQL function being defined\&.
299
308
.sp
300
309
When repeated
301
310
CREATE FUNCTION
318
327
.RS 4
319
328
isCachable
320
329
is an obsolete equivalent of
321
 
IMMUTABLE; it\(aqs still accepted for backwards\-compatibility reasons\&.
 
330
IMMUTABLE; it\*(Aqs still accepted for backwards\-compatibility reasons\&.
322
331
.RE
323
332
.sp
324
333
Attribute names are not case\-sensitive\&.
377
386
command\&.
378
387
.PP
379
388
When replacing an existing function with
380
 
CREATE OR REPLACE FUNCTION, there are restrictions on changing parameter names\&. You cannot change the name already assigned to any input parameter (although you can add names to parameters that had none before)\&. If there is more than one output parameter, you cannot change the names of the output parameters, because that would change the column names of the anonymous composite type that describes the function\(aqs result\&. These restrictions are made to ensure that existing calls of the function do not stop working when it is replaced\&.
 
389
CREATE OR REPLACE FUNCTION, there are restrictions on changing parameter names\&. You cannot change the name already assigned to any input parameter (although you can add names to parameters that had none before)\&. If there is more than one output parameter, you cannot change the names of the output parameters, because that would change the column names of the anonymous composite type that describes the function\*(Aqs result\&. These restrictions are made to ensure that existing calls of the function do not stop working when it is replaced\&.
381
390
.PP
382
391
If a function is declared
383
392
STRICT
396
405
.\}
397
406
.nf
398
407
CREATE FUNCTION add(integer, integer) RETURNS integer
399
 
    AS \(aqselect $1 + $2;\(aq
 
408
    AS \*(Aqselect $1 + $2;\*(Aq
400
409
    LANGUAGE SQL
401
410
    IMMUTABLE
402
411
    RETURNS NULL ON NULL INPUT;
429
438
.\}
430
439
.nf
431
440
CREATE FUNCTION dup(in int, out f1 int, out f2 text)
432
 
    AS $$ SELECT $1, CAST($1 AS text) || \(aq is text\(aq $$
 
441
    AS $$ SELECT $1, CAST($1 AS text) || \*(Aq is text\*(Aq $$
433
442
    LANGUAGE SQL;
434
443
 
435
444
SELECT * FROM dup(42);
447
456
CREATE TYPE dup_result AS (f1 int, f2 text);
448
457
 
449
458
CREATE FUNCTION dup(int) RETURNS dup_result
450
 
    AS $$ SELECT $1, CAST($1 AS text) || \(aq is text\(aq $$
 
459
    AS $$ SELECT $1, CAST($1 AS text) || \*(Aq is text\*(Aq $$
451
460
    LANGUAGE SQL;
452
461
 
453
462
SELECT * FROM dup(42);
465
474
.\}
466
475
.nf
467
476
CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text)
468
 
    AS $$ SELECT $1, CAST($1 AS text) || \(aq is text\(aq $$
 
477
    AS $$ SELECT $1, CAST($1 AS text) || \*(Aq is text\*(Aq $$
469
478
    LANGUAGE SQL;
470
479
 
471
480
SELECT * FROM dup(42);
506
515
END;
507
516
$$  LANGUAGE plpgsql
508
517
    SECURITY DEFINER
509
 
    \-\- Set a secure search_path: trusted schema(s), then \(aqpg_temp\(aq\&.
 
518
    \-\- Set a secure search_path: trusted schema(s), then \*(Aqpg_temp\*(Aq\&.
510
519
    SET search_path = admin, pg_temp;
511
520
.fi
512
521
.if n \{\