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:
Tom Lane 2021-03-10 11:33:50 -05:00
parent fe2b5386b2
commit 9a4e4af420
3 changed files with 55 additions and 20 deletions

View File

@ -100,6 +100,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>
@ -578,12 +583,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">
@ -661,8 +660,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;'

View File

@ -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>

View File

@ -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>