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>
privilege on the argument types and the return type.
</para>
<para>
Refer to <xref linkend="xfunc"/> for further information on writing
functions.
</para>
</refsect1>
<refsect1>
@ -578,12 +583,6 @@ CREATE [ OR REPLACE ] FUNCTION
</varlistentry>
</variablelist>
<para>
Refer to <xref linkend="xfunc"/> for further information on writing
functions.
</para>
</refsect1>
<refsect1 id="sql-createfunction-overloading">
@ -661,8 +660,7 @@ CREATE FUNCTION foo(int, int default 42) ...
<title>Examples</title>
<para>
Here are some trivial examples to help you get started. For more
information and examples, see <xref linkend="xfunc"/>.
Add two integers using a SQL function:
<programlisting>
CREATE FUNCTION add(integer, integer) RETURNS integer
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>
privilege on the argument types.
</para>
<para>
Refer to <xref linkend="xproc"/> for further information on writing
procedures.
</para>
</refsect1>
<refsect1>

View File

@ -81,21 +81,53 @@
</indexterm>
<para>
A procedure is a database object similar to a function. The difference is
that a procedure does not return a value, so there is no return type
declaration. 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. If the CALL command is not
part of an explicit transaction, a procedure in many server-side
languages can commit, rollback, and begin new transactions during
its execution, which is not possible in functions.
A procedure is a database object similar to a function.
The key differences are:
<itemizedlist>
<listitem>
<para>
Procedures are defined with the <xref linkend="sql-createprocedure"/>
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>
The explanations on how to define user-defined functions in the rest of
this chapter apply to procedures as well, except that
the <xref linkend="sql-createprocedure"/> command is used instead, there is
no return type, and some other features such as strictness don't apply.
The explanations in the following sections about how to define
user-defined functions apply to procedures as well, except for the
points made above.
</para>
<para>