mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-05 00:47:19 +02:00
Doc: improve introductory information about procedures.
Clarify the discussion in "User-Defined Procedures", by laying out the key differences between functions and procedures in a bulleted list. Notably, this avoids burying the lede about procedures being able to do transaction control. Make the back-link in the CREATE FUNCTION reference page more prominent, and add one in CREATE PROCEDURE. Per gripe from Guyren Howe. Thanks to David Johnston for discussion. Discussion: https://postgr.es/m/BYAPR03MB4903C53A8BB7EFF5EA289674A6949@BYAPR03MB4903.namprd03.prod.outlook.com
This commit is contained in:
parent
ea42ccbced
commit
e0fcde7f74
@ -99,6 +99,11 @@ CREATE [ OR REPLACE ] FUNCTION
|
|||||||
To be able to create a function, you must have <literal>USAGE</literal>
|
To be able to create a function, you must have <literal>USAGE</literal>
|
||||||
privilege on the argument types and the return type.
|
privilege on the argument types and the return type.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Refer to <xref linkend="xfunc"/> for further information on writing
|
||||||
|
functions.
|
||||||
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
@ -564,12 +569,6 @@ CREATE [ OR REPLACE ] FUNCTION
|
|||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
||||||
<para>
|
|
||||||
Refer to <xref linkend="xfunc"/> for further information on writing
|
|
||||||
functions.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="sql-createfunction-overloading">
|
<refsect1 id="sql-createfunction-overloading">
|
||||||
@ -647,8 +646,7 @@ CREATE FUNCTION foo(int, int default 42) ...
|
|||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Here are some trivial examples to help you get started. For more
|
Add two integers using a SQL function:
|
||||||
information and examples, see <xref linkend="xfunc"/>.
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE FUNCTION add(integer, integer) RETURNS integer
|
CREATE FUNCTION add(integer, integer) RETURNS integer
|
||||||
AS 'select $1 + $2;'
|
AS 'select $1 + $2;'
|
||||||
|
@ -76,6 +76,11 @@ CREATE [ OR REPLACE ] PROCEDURE
|
|||||||
To be able to create a procedure, you must have <literal>USAGE</literal>
|
To be able to create a procedure, you must have <literal>USAGE</literal>
|
||||||
privilege on the argument types.
|
privilege on the argument types.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Refer to <xref linkend="xproc"/> for further information on writing
|
||||||
|
procedures.
|
||||||
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
@ -81,21 +81,53 @@
|
|||||||
</indexterm>
|
</indexterm>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
A procedure is a database object similar to a function. The difference is
|
A procedure is a database object similar to a function.
|
||||||
that a procedure does not return a value, so there is no return type
|
The key differences are:
|
||||||
declaration. While a function is called as part of a query or DML
|
|
||||||
command, a procedure is called in isolation using
|
<itemizedlist>
|
||||||
the <xref linkend="sql-call"/> command. If the CALL command is not
|
<listitem>
|
||||||
part of an explicit transaction, a procedure in many server-side
|
<para>
|
||||||
languages can commit, rollback, and begin new transactions during
|
Procedures are defined with the <xref linkend="sql-createprocedure"/>
|
||||||
its execution, which is not possible in functions.
|
command, not <command>CREATE FUNCTION</command>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Procedures do not return a function value; hence <command>CREATE
|
||||||
|
PROCEDURE</command> lacks a <literal>RETURNS</literal> clause.
|
||||||
|
However, procedures can instead return data to their callers via
|
||||||
|
output parameters.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
While a function is called as part of a query or DML command, a
|
||||||
|
procedure is called in isolation using
|
||||||
|
the <xref linkend="sql-call"/> command.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
A procedure can commit or roll back transactions during its
|
||||||
|
execution (then automatically beginning a new transaction), so long
|
||||||
|
as the invoking <command>CALL</command> command is not part of an
|
||||||
|
explicit transaction block. A function cannot do that.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Certain function attributes, such as strictness, don't apply to
|
||||||
|
procedures. Those attributes control how the function is
|
||||||
|
used in a query, which isn't relevant to procedures.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The explanations on how to define user-defined functions in the rest of
|
The explanations in the following sections about how to define
|
||||||
this chapter apply to procedures as well, except that
|
user-defined functions apply to procedures as well, except for the
|
||||||
the <xref linkend="sql-createprocedure"/> command is used instead, there is
|
points made above.
|
||||||
no return type, and some other features such as strictness don't apply.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
Loading…
Reference in New Issue
Block a user