1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2007-04-23 18:52:53 +02:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.75 2007/04/23 16:52:53 neilc Exp $
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<refentry id="SQL-CREATEFUNCTION">
|
|
|
|
<refmeta>
|
2001-11-18 21:35:02 +01:00
|
|
|
<refentrytitle id="SQL-CREATEFUNCTION-TITLE">CREATE FUNCTION</refentrytitle>
|
1999-06-14 09:37:05 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<refnamediv>
|
2001-05-19 11:01:10 +02:00
|
|
|
<refname>CREATE FUNCTION</refname>
|
2001-09-03 14:57:50 +02:00
|
|
|
<refpurpose>define a new function</refpurpose>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refnamediv>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-createfunction">
|
|
|
|
<primary>CREATE FUNCTION</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<refsynopsisdiv>
|
2001-05-19 11:01:10 +02:00
|
|
|
<synopsis>
|
2005-04-01 00:46:33 +02:00
|
|
|
CREATE [ OR REPLACE ] FUNCTION
|
|
|
|
<replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
|
|
|
|
[ RETURNS <replaceable class="parameter">rettype</replaceable> ]
|
2002-05-17 20:32:52 +02:00
|
|
|
{ LANGUAGE <replaceable class="parameter">langname</replaceable>
|
|
|
|
| IMMUTABLE | STABLE | VOLATILE
|
|
|
|
| CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
|
2004-06-25 09:05:34 +02:00
|
|
|
| [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
|
2007-01-22 02:35:23 +01:00
|
|
|
| COST <replaceable class="parameter">execution_cost</replaceable>
|
|
|
|
| ROWS <replaceable class="parameter">result_rows</replaceable>
|
2002-05-17 20:32:52 +02:00
|
|
|
| AS '<replaceable class="parameter">definition</replaceable>'
|
|
|
|
| AS '<replaceable class="parameter">obj_file</replaceable>', '<replaceable class="parameter">link_symbol</replaceable>'
|
|
|
|
} ...
|
2000-03-27 19:14:43 +02:00
|
|
|
[ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
|
2001-05-19 11:01:10 +02:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
1998-05-13 07:34:00 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<refsect1 id="sql-createfunction-description">
|
|
|
|
<title>Description</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<para>
|
|
|
|
<command>CREATE FUNCTION</command> defines a new function.
|
2002-05-17 20:32:52 +02:00
|
|
|
<command>CREATE OR REPLACE FUNCTION</command> will either create a
|
|
|
|
new function, or replace an existing definition.
|
|
|
|
</para>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
If a schema name is included, then the function is created in the
|
|
|
|
specified schema. Otherwise it is created in the current schema.
|
|
|
|
The name of the new function must not match any existing function
|
|
|
|
with the same argument types in the same schema. However,
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
functions of different argument types can share a name (this is
|
2003-04-22 12:08:08 +02:00
|
|
|
called <firstterm>overloading</>).
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2007-01-22 02:35:23 +01:00
|
|
|
To replace the current definition of an existing function, use
|
2003-04-22 12:08:08 +02:00
|
|
|
<command>CREATE OR REPLACE FUNCTION</command>. It is not possible
|
|
|
|
to change the name or argument types of a function this way (if you
|
2004-05-17 01:22:08 +02:00
|
|
|
tried, you would actually be creating a new, distinct function).
|
|
|
|
Also, <command>CREATE OR REPLACE FUNCTION</command> will not let
|
|
|
|
you change the return type of an existing function. To do that,
|
2005-04-01 00:46:33 +02:00
|
|
|
you must drop and recreate the function. (When using <literal>OUT</>
|
Wording cleanup for error messages. Also change can't -> cannot.
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 20:10:30 +01:00
|
|
|
parameters, that means you cannot change the names or types of any
|
2005-04-01 00:46:33 +02:00
|
|
|
<literal>OUT</> parameters except by dropping the function.)
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If you drop and then recreate a function, the new function is not
|
2005-01-04 01:39:53 +01:00
|
|
|
the same entity as the old; you will have to drop existing rules, views,
|
|
|
|
triggers, etc. that refer to the old function. Use
|
2003-04-22 12:08:08 +02:00
|
|
|
<command>CREATE OR REPLACE FUNCTION</command> to change a function
|
|
|
|
definition without breaking objects that refer to the function.
|
|
|
|
</para>
|
|
|
|
|
2002-05-17 20:32:52 +02:00
|
|
|
<para>
|
|
|
|
The user that creates the function becomes the owner of the function.
|
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<variablelist>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-09-16 06:16:08 +02:00
|
|
|
The name (optionally schema-qualified) of the function to create.
|
2001-05-19 11:01:10 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2005-04-01 00:46:33 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">argmode</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The mode of an argument: either <literal>IN</>, <literal>OUT</>,
|
|
|
|
or <literal>INOUT</>. If omitted, the default is <literal>IN</>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2004-06-25 09:05:34 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">argname</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of an argument. Some languages (currently only PL/pgSQL) let
|
|
|
|
you use the name in the function body. For other languages the
|
2005-04-01 00:46:33 +02:00
|
|
|
name of an input argument is just extra documentation. But the name
|
|
|
|
of an output argument is significant, since it defines the column
|
|
|
|
name in the result row type. (If you omit the name for an output
|
|
|
|
argument, the system will choose a default column name.)
|
2004-06-25 09:05:34 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">argtype</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-03-20 05:41:13 +01:00
|
|
|
The data type(s) of the function's arguments (optionally
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
schema-qualified), if any. The argument types can be base, composite,
|
|
|
|
or domain types, or can reference the type of a table column.
|
2003-03-20 05:41:13 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
Depending on the implementation language it might also be allowed
|
2003-04-22 12:08:08 +02:00
|
|
|
to specify <quote>pseudotypes</> such as <type>cstring</>.
|
|
|
|
Pseudotypes indicate that the actual argument type is either
|
2003-03-20 05:41:13 +01:00
|
|
|
incompletely specified, or outside the set of ordinary SQL data types.
|
2001-05-19 11:01:10 +02:00
|
|
|
</para>
|
2005-01-04 01:39:53 +01:00
|
|
|
<para>
|
|
|
|
The type of a column is referenced by writing
|
|
|
|
<literal><replaceable
|
|
|
|
class="parameter">tablename</replaceable>.<replaceable
|
|
|
|
class="parameter">columnname</replaceable>%TYPE</literal>.
|
|
|
|
Using this feature can sometimes help make a function independent of
|
|
|
|
changes to the definition of a table.
|
|
|
|
</para>
|
2001-05-19 11:01:10 +02:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">rettype</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-03-20 05:41:13 +01:00
|
|
|
The return data type (optionally schema-qualified). The return type
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
can be a base, composite, or domain type,
|
|
|
|
or can reference the type of a table column.
|
|
|
|
Depending on the implementation language it might also be allowed
|
2003-04-22 12:08:08 +02:00
|
|
|
to specify <quote>pseudotypes</> such as <type>cstring</>.
|
2006-11-03 08:17:36 +01:00
|
|
|
If the function is not supposed to return a value, specify
|
|
|
|
<type>void</> as the return type.
|
2005-01-04 01:39:53 +01:00
|
|
|
</para>
|
2005-04-01 00:46:33 +02:00
|
|
|
<para>
|
|
|
|
When there are <literal>OUT</> or <literal>INOUT</> parameters,
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
the <literal>RETURNS</> clause can be omitted. If present, it
|
2005-04-01 00:46:33 +02:00
|
|
|
must agree with the result type implied by the output parameters:
|
|
|
|
<literal>RECORD</> if there are multiple output parameters, or
|
|
|
|
the same type as the single output parameter.
|
|
|
|
</para>
|
2005-01-04 01:39:53 +01:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The <literal>SETOF</literal>
|
2001-05-19 11:01:10 +02:00
|
|
|
modifier indicates that the function will return a set of
|
2002-08-22 02:01:51 +02:00
|
|
|
items, rather than a single item.
|
2001-05-19 11:01:10 +02:00
|
|
|
</para>
|
2005-01-04 01:39:53 +01:00
|
|
|
<para>
|
|
|
|
The type of a column is referenced by writing
|
|
|
|
<literal><replaceable
|
|
|
|
class="parameter">tablename</replaceable>.<replaceable
|
|
|
|
class="parameter">columnname</replaceable>%TYPE</literal>.
|
|
|
|
</para>
|
2001-05-19 11:01:10 +02:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2002-05-17 20:32:52 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">langname</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of the language that the function is implemented in.
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
Can be <literal>SQL</literal>, <literal>C</literal>,
|
2002-05-17 20:32:52 +02:00
|
|
|
<literal>internal</literal>, or the name of a user-defined
|
2005-01-04 01:39:53 +01:00
|
|
|
procedural language. For backward compatibility,
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
the name can be enclosed by single quotes.
|
2002-05-17 20:32:52 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal>IMMUTABLE</literal></term>
|
|
|
|
<term><literal>STABLE</literal></term>
|
|
|
|
<term><literal>VOLATILE</literal></term>
|
2002-05-17 20:32:52 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2006-11-10 21:52:18 +01:00
|
|
|
These attributes inform the query optimizer about the behavior
|
|
|
|
of the function. At most one choice
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
can be specified. If none of these appear,
|
2002-05-17 20:32:52 +02:00
|
|
|
<literal>VOLATILE</literal> is the default assumption.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2006-11-10 21:52:18 +01:00
|
|
|
<literal>IMMUTABLE</literal> indicates that the function
|
|
|
|
cannot modify the database and always
|
2002-05-17 20:32:52 +02:00
|
|
|
returns the same result when given the same argument values; that
|
|
|
|
is, it does not do database lookups or otherwise use information not
|
2003-04-22 12:08:08 +02:00
|
|
|
directly present in its argument list. If this option is given,
|
2002-05-17 20:32:52 +02:00
|
|
|
any call of the function with all-constant arguments can be
|
|
|
|
immediately replaced with the function value.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2006-11-10 21:52:18 +01:00
|
|
|
<literal>STABLE</literal> indicates that the function
|
|
|
|
cannot modify the database,
|
|
|
|
and that within a single table scan it will consistently
|
2002-05-17 20:32:52 +02:00
|
|
|
return the same result for the same argument values, but that its
|
|
|
|
result could change across SQL statements. This is the appropriate
|
|
|
|
selection for functions whose results depend on database lookups,
|
|
|
|
parameter variables (such as the current time zone), etc. Also note
|
2003-04-22 12:08:08 +02:00
|
|
|
that the <function>current_timestamp</> family of functions qualify
|
2002-05-17 20:32:52 +02:00
|
|
|
as stable, since their values do not change within a transaction.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<literal>VOLATILE</literal> indicates that the function value can
|
|
|
|
change even within a single table scan, so no optimizations can be
|
|
|
|
made. Relatively few database functions are volatile in this sense;
|
|
|
|
some examples are <literal>random()</>, <literal>currval()</>,
|
2005-11-01 22:09:51 +01:00
|
|
|
<literal>timeofday()</>. But note that any function that has
|
|
|
|
side-effects must be classified volatile, even if its result is quite
|
|
|
|
predictable, to prevent calls from being optimized away; an example is
|
2002-05-17 20:32:52 +02:00
|
|
|
<literal>setval()</>.
|
|
|
|
</para>
|
2004-09-13 22:10:13 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
For additional details see <xref linkend="xfunc-volatility">.
|
|
|
|
</para>
|
2002-05-17 20:32:52 +02:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal>CALLED ON NULL INPUT</literal></term>
|
|
|
|
<term><literal>RETURNS NULL ON NULL INPUT</literal></term>
|
|
|
|
<term><literal>STRICT</literal></term>
|
2002-05-17 20:32:52 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<literal>CALLED ON NULL INPUT</literal> (the default) indicates
|
|
|
|
that the function will be called normally when some of its
|
|
|
|
arguments are null. It is then the function author's
|
2002-09-21 20:32:54 +02:00
|
|
|
responsibility to check for null values if necessary and respond
|
2002-05-17 20:32:52 +02:00
|
|
|
appropriately.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<literal>RETURNS NULL ON NULL INPUT</literal> or
|
|
|
|
<literal>STRICT</literal> indicates that the function always
|
2003-04-22 12:08:08 +02:00
|
|
|
returns null whenever any of its arguments are null. If this
|
2002-05-17 20:32:52 +02:00
|
|
|
parameter is specified, the function is not executed when there
|
2003-04-22 12:08:08 +02:00
|
|
|
are null arguments; instead a null result is assumed
|
2002-05-17 20:32:52 +02:00
|
|
|
automatically.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2002-05-18 15:48:01 +02:00
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
|
|
|
|
<term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>
|
2002-05-18 15:48:01 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<literal>SECURITY INVOKER</literal> indicates that the function
|
|
|
|
is to be executed with the privileges of the user that calls it.
|
|
|
|
That is the default. <literal>SECURITY DEFINER</literal>
|
|
|
|
specifies that the function is to be executed with the
|
|
|
|
privileges of the user that created it.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-11-01 22:09:51 +01:00
|
|
|
The key word <literal>EXTERNAL</literal> is allowed for SQL
|
|
|
|
conformance, but it is optional since, unlike in SQL, this feature
|
|
|
|
applies to all functions not only external ones.
|
2002-05-18 15:48:01 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2007-01-22 02:35:23 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">execution_cost</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A positive number giving the estimated execution cost for the function,
|
|
|
|
in units of <xref linkend="guc-cpu-operator-cost">. If the function
|
|
|
|
returns a set, this is the cost per returned row. If the cost is
|
|
|
|
not specified, 1 unit is assumed for C-language and internal functions,
|
|
|
|
and 100 units for functions in all other languages. Larger values
|
|
|
|
cause the planner to try to avoid evaluating the function more often
|
|
|
|
than necessary.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">result_rows</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A positive number giving the estimated number of rows that the planner
|
|
|
|
should expect the function to return. This is only allowed when the
|
|
|
|
function is declared to return a set. The default assumption is
|
|
|
|
1000 rows.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">definition</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-09-21 00:48:29 +02:00
|
|
|
A string constant defining the function; the meaning depends on the
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
language. It can be an internal function name, the path to an
|
2004-09-21 00:48:29 +02:00
|
|
|
object file, an SQL command, or text in a procedural language.
|
2001-05-19 11:01:10 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></literal></term>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This form of the <literal>AS</literal> clause is used for
|
2003-04-22 12:08:08 +02:00
|
|
|
dynamically loadable C language functions when the function name
|
2001-05-19 11:01:10 +02:00
|
|
|
in the C language source code is not the same as the name of
|
|
|
|
the SQL function. The string <replaceable
|
|
|
|
class="parameter">obj_file</replaceable> is the name of the
|
|
|
|
file containing the dynamically loadable object, and
|
|
|
|
<replaceable class="parameter">link_symbol</replaceable> is the
|
2003-04-22 12:08:08 +02:00
|
|
|
function's 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.
|
2001-05-19 11:01:10 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">attribute</replaceable></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-05-17 20:32:52 +02:00
|
|
|
The historical way to specify optional pieces of information
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
about the function. The following attributes can appear here:
|
2002-05-17 20:32:52 +02:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><literal>isStrict</></term>
|
2002-05-17 20:32:52 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2005-01-04 01:39:53 +01:00
|
|
|
Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>.
|
2002-05-17 20:32:52 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><literal>isCachable</></term>
|
2002-05-17 20:32:52 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<literal>isCachable</literal> is an obsolete equivalent of
|
2002-07-24 21:11:14 +02:00
|
|
|
<literal>IMMUTABLE</literal>; it's still accepted for
|
2002-05-17 20:32:52 +02:00
|
|
|
backwards-compatibility reasons.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
Attribute names are not case-sensitive.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
|
|
|
</variablelist>
|
2000-08-25 01:36:29 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
</refsect1>
|
2000-08-25 01:36:29 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<refsect1 id="sql-createfunction-notes">
|
|
|
|
<title>Notes</title>
|
2000-03-27 19:14:43 +02:00
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<para>
|
2003-03-25 17:15:44 +01:00
|
|
|
Refer to <xref linkend="xfunc"> for further information on writing
|
2003-04-22 12:08:08 +02:00
|
|
|
functions.
|
1999-06-14 09:37:05 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2000-03-27 19:14:43 +02:00
|
|
|
<para>
|
2001-05-19 11:01:10 +02:00
|
|
|
The full <acronym>SQL</acronym> type syntax is allowed for
|
2000-03-27 19:14:43 +02:00
|
|
|
input arguments and return value. However, some details of the
|
2000-10-05 21:48:34 +02:00
|
|
|
type specification (e.g., the precision field for
|
2003-04-22 12:08:08 +02:00
|
|
|
type <type>numeric</type>) are the responsibility of the
|
2000-03-27 19:14:43 +02:00
|
|
|
underlying function implementation and are silently swallowed
|
2000-08-25 01:36:29 +02:00
|
|
|
(i.e., not recognized or
|
2000-03-27 19:14:43 +02:00
|
|
|
enforced) by the <command>CREATE FUNCTION</command> command.
|
|
|
|
</para>
|
1999-05-20 04:57:15 +02:00
|
|
|
|
1999-07-22 17:09:15 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
<productname>PostgreSQL</productname> allows function
|
|
|
|
<firstterm>overloading</firstterm>; that is, the same name can be
|
|
|
|
used for several different functions so long as they have distinct
|
|
|
|
argument types. However, the C names of all functions must be
|
|
|
|
different, so you must give overloaded C functions different C
|
|
|
|
names (for example, use the argument types as part of the C
|
|
|
|
names).
|
1999-07-22 17:09:15 +02:00
|
|
|
</para>
|
|
|
|
|
2005-04-01 00:46:33 +02:00
|
|
|
<para>
|
|
|
|
Two functions are considered the same if they have the same names and
|
|
|
|
<emphasis>input</> argument types, ignoring any <literal>OUT</>
|
|
|
|
parameters. Thus for example these declarations conflict:
|
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION foo(int) ...
|
|
|
|
CREATE FUNCTION foo(int, out text) ...
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<para>
|
|
|
|
When repeated <command>CREATE FUNCTION</command> calls refer to
|
2007-01-22 02:35:23 +01:00
|
|
|
the same object file, the file is only loaded once per session.
|
|
|
|
To unload and
|
2001-05-19 11:01:10 +02:00
|
|
|
reload the file (perhaps during development), use the <xref
|
2001-11-18 21:35:02 +01:00
|
|
|
linkend="sql-load" endterm="sql-load-title"> command.
|
2001-05-19 11:01:10 +02:00
|
|
|
</para>
|
|
|
|
|
2001-10-02 23:39:36 +02:00
|
|
|
<para>
|
2004-05-17 01:22:08 +02:00
|
|
|
Use <xref linkend="sql-dropfunction"
|
|
|
|
endterm="sql-dropfunction-title"> to remove user-defined
|
|
|
|
functions.
|
2001-10-02 23:39:36 +02:00
|
|
|
</para>
|
|
|
|
|
2004-09-21 00:48:29 +02:00
|
|
|
<para>
|
|
|
|
It is often helpful to use dollar quoting (see <xref
|
|
|
|
linkend="sql-syntax-dollar-quoting">) to write the function definition
|
|
|
|
string, rather than the normal single quote syntax. Without dollar
|
|
|
|
quoting, any single quotes or backslashes in the function definition must
|
|
|
|
be escaped by doubling them.
|
|
|
|
</para>
|
2003-10-26 05:34:05 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
To be able to define a function, the user must have the
|
|
|
|
<literal>USAGE</literal> privilege on the language.
|
|
|
|
</para>
|
|
|
|
|
1998-12-29 03:24:47 +01:00
|
|
|
</refsect1>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
|
|
|
<refsect1 id="sql-createfunction-examples">
|
|
|
|
<title>Examples</title>
|
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
<para>
|
2005-04-01 00:46:33 +02:00
|
|
|
Here are some trivial examples to help you get started. For more
|
2003-04-22 12:08:08 +02:00
|
|
|
information and examples, see <xref linkend="xfunc">.
|
2001-05-19 11:01:10 +02:00
|
|
|
<programlisting>
|
2003-04-22 12:08:08 +02:00
|
|
|
CREATE FUNCTION add(integer, integer) RETURNS integer
|
2005-01-04 01:39:53 +01:00
|
|
|
AS 'select $1 + $2;'
|
2003-04-22 12:08:08 +02:00
|
|
|
LANGUAGE SQL
|
|
|
|
IMMUTABLE
|
|
|
|
RETURNS NULL ON NULL INPUT;
|
2004-07-12 01:23:43 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2004-10-01 04:00:44 +02:00
|
|
|
Increment an integer, making use of an argument name, in
|
|
|
|
<application>PL/pgSQL</application>:
|
2004-07-12 01:23:43 +02:00
|
|
|
<programlisting>
|
2005-01-04 01:39:53 +01:00
|
|
|
CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
|
2004-09-21 00:48:29 +02:00
|
|
|
BEGIN
|
|
|
|
RETURN i + 1;
|
2005-01-04 01:39:53 +01:00
|
|
|
END;
|
|
|
|
$$ LANGUAGE plpgsql;
|
2005-04-01 00:46:33 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Return a record containing multiple output parameters:
|
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION dup(in int, out f1 int, out f2 text)
|
|
|
|
AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
|
|
|
|
LANGUAGE SQL;
|
|
|
|
|
|
|
|
SELECT * FROM dup(42);
|
|
|
|
</programlisting>
|
|
|
|
You can do the same thing more verbosely with an explicitly named
|
|
|
|
composite type:
|
|
|
|
<programlisting>
|
|
|
|
CREATE TYPE dup_result AS (f1 int, f2 text);
|
|
|
|
|
|
|
|
CREATE FUNCTION dup(int) RETURNS dup_result
|
|
|
|
AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
|
|
|
|
LANGUAGE SQL;
|
|
|
|
|
|
|
|
SELECT * FROM dup(42);
|
2001-05-19 11:01:10 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
1999-06-14 09:37:05 +02:00
|
|
|
</refsect1>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
2007-04-20 04:37:38 +02:00
|
|
|
<refsect1 id="sql-createfunction-security">
|
|
|
|
<title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Because a <literal>SECURITY DEFINER</literal> function is executed
|
|
|
|
with the privileges of the user that created it, care is needed to
|
|
|
|
ensure that the function cannot be misused. For security,
|
|
|
|
<xref linkend="guc-search-path"> should be set to exclude any schemas
|
|
|
|
writable by untrusted users. This prevents
|
|
|
|
malicious users from creating objects that mask objects used by the
|
2007-04-23 18:52:53 +02:00
|
|
|
function. Particularly important in this regard is the
|
2007-04-20 04:37:38 +02:00
|
|
|
temporary-table schema, which is searched first by default, and
|
|
|
|
is normally writable by anyone. A secure arrangement can be had
|
|
|
|
by forcing the temporary schema to be searched last. To do this,
|
|
|
|
write <literal>pg_temp</> as the last entry in <varname>search_path</>.
|
|
|
|
This function illustrates safe usage:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION check_password(uname TEXT, pass TEXT)
|
|
|
|
RETURNS BOOLEAN AS $$
|
|
|
|
DECLARE passed BOOLEAN;
|
|
|
|
old_path TEXT;
|
|
|
|
BEGIN
|
|
|
|
-- Save old search_path; notice we must qualify current_setting
|
|
|
|
-- to ensure we invoke the right function
|
|
|
|
old_path := pg_catalog.current_setting('search_path');
|
|
|
|
|
|
|
|
-- Set a secure search_path: trusted schemas, then 'pg_temp'.
|
|
|
|
-- We set is_local = true so that the old value will be restored
|
|
|
|
-- in event of an error before we reach the function end.
|
|
|
|
PERFORM pg_catalog.set_config('search_path', 'admin, pg_temp', true);
|
|
|
|
|
|
|
|
-- Do whatever secure work we came for.
|
|
|
|
SELECT (pwd = $2) INTO passed
|
|
|
|
FROM pwds
|
|
|
|
WHERE username = $1;
|
|
|
|
|
|
|
|
-- Restore caller's search_path
|
|
|
|
PERFORM pg_catalog.set_config('search_path', old_path, true);
|
|
|
|
|
|
|
|
RETURN passed;
|
|
|
|
END;
|
|
|
|
$$ LANGUAGE plpgsql SECURITY DEFINER;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
</refsect1>
|
|
|
|
|
1998-05-13 07:34:00 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<refsect1 id="sql-createfunction-compat">
|
|
|
|
<title>Compatibility</title>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<para>
|
2005-11-01 22:09:51 +01:00
|
|
|
A <command>CREATE FUNCTION</command> command is defined in SQL:1999 and later.
|
2003-09-11 23:42:20 +02:00
|
|
|
The <productname>PostgreSQL</productname> version is similar but
|
2002-05-17 20:32:52 +02:00
|
|
|
not fully compatible. The attributes are not portable, neither are the
|
2001-05-19 11:01:10 +02:00
|
|
|
different available languages.
|
|
|
|
</para>
|
2005-04-01 00:46:33 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
For compatibility with some other database systems,
|
|
|
|
<replaceable class="parameter">argmode</replaceable> can be written
|
|
|
|
either before or after <replaceable class="parameter">argname</replaceable>.
|
|
|
|
But only the first way is standard-compliant.
|
|
|
|
</para>
|
2001-05-19 11:01:10 +02:00
|
|
|
</refsect1>
|
1998-09-16 16:43:12 +02:00
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
|
2005-01-04 01:39:53 +01:00
|
|
|
<refsect1>
|
2001-05-19 11:01:10 +02:00
|
|
|
<title>See Also</title>
|
|
|
|
|
2005-01-04 01:39:53 +01:00
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="sql-alterfunction" endterm="sql-alterfunction-title"></member>
|
|
|
|
<member><xref linkend="sql-dropfunction" endterm="sql-dropfunction-title"></member>
|
|
|
|
<member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
|
|
|
|
<member><xref linkend="sql-load" endterm="sql-load-title"></member>
|
|
|
|
<member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
|
|
|
|
<member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
|
|
|
|
</simplelist>
|
1998-05-13 07:34:00 +02:00
|
|
|
</refsect1>
|
2001-05-19 11:01:10 +02:00
|
|
|
|
1999-06-14 09:37:05 +02:00
|
|
|
</refentry>
|