Tom Lane wrote:
> I observe that the Notes section here
> http://developer.postgresql.org/pgdocs/postgres/sql-createfunction.html
> has turned into a disorganized laundry list of unrelated items,
> ranging from quite-subtle issues to barely-useful-even-to-novices
> advice (do we really need "Use DROP FUNCTION to remove user-defined
> functions" here? Especially given the See Also link later on?).
>
> I don't have an immediate proposal what to do about it, but it seems
> like it could use some effort. Any thoughts?
Yea, it is hard to read. What I did was to move some items up into
their proper sections, and add an "Overloading" heading. You can see
the results here:
http://momjian.us/tmp/pgsql/sql-createfunction.html
and a patch is attached.
--
Bruce Momjian <[email protected]> http://momjian.us
EnterpriseDB http://enterprisedb.com
PG East: http://www.enterprisedb.com/community/nav-pg-east-2010.do
+ If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/ref/create_function.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v
retrieving revision 1.91
diff -c -c -r1.91 create_function.sgml
*** doc/src/sgml/ref/create_function.sgml 25 Feb 2010 22:24:00 -0000 1.91
--- doc/src/sgml/ref/create_function.sgml 26 Feb 2010 23:58:55 -0000
***************
*** 46,51 ****
--- 46,55 ----
<command>CREATE FUNCTION</command> defines a new function.
<command>CREATE OR REPLACE FUNCTION</command> will either create a
new function, or replace an existing definition.
+ To be able to define a function, the user must have the
+ <literal>USAGE</literal> privilege on the language.
+ </para>
+
</para>
<para>
***************
*** 70,75 ****
--- 74,87 ----
</para>
<para>
+ When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
+ existing function, the ownership and permissions of the function
+ do not change. All other function properties are assigned the
+ values specified or implied in the command. You must own the function
+ to replace it (this includes being a member of the owning role).
+ </para>
+
+ <para>
If you drop and then recreate a function, the new function is not
the same entity as the old; you will have to drop existing rules, views,
triggers, etc. that refer to the old function. Use
***************
*** 401,406 ****
--- 413,430 ----
</para>
<para>
+ If a <literal>SET</> clause is attached to a function, then
+ the effects of a <command>SET LOCAL</> command executed inside the
+ function for the same variable are restricted to the function: the
+ configuration parameter's prior value is still restored at function exit.
+ However, an ordinary
+ <command>SET</> command (without <literal>LOCAL</>) overrides the
+ <literal>SET</> clause, much as it would do for a previous <command>SET
+ LOCAL</> command: the effects of such a command will persist after
+ function exit, unless the current transaction is rolled back.
+ </para>
+
+ <para>
See <xref linkend="sql-set" endterm="sql-set-title"> and
<xref linkend="runtime-config">
for more information about allowed parameter names and values.
***************
*** 417,422 ****
--- 441,455 ----
language. It can be an internal function name, the path to an
object file, an SQL command, or text in a procedural language.
</para>
+
+ <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>
+
</listitem>
</varlistentry>
***************
*** 436,441 ****
--- 469,482 ----
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.
</para>
+
+ <para>
+ When repeated <command>CREATE FUNCTION</command> calls refer to
+ the same object file, the file is only loaded once per session.
+ To unload and
+ reload the file (perhaps during development), start a new session.
+ </para>
+
</listitem>
</varlistentry>
***************
*** 479,501 ****
</refsect1>
! <refsect1 id="sql-createfunction-notes">
! <title>Notes</title>
!
! <para>
! Refer to <xref linkend="xfunc"> for further information on writing
! functions.
! </para>
! <para>
! The full <acronym>SQL</acronym> type syntax is allowed for
! input arguments and return value. However, some details of the
! type specification (e.g., the precision field for
! type <type>numeric</type>) are the responsibility of the
! underlying function implementation and are silently swallowed
! (i.e., not recognized or
! enforced) by the <command>CREATE FUNCTION</command> command.
! </para>
<para>
<productname>PostgreSQL</productname> allows function
--- 520,532 ----
</refsect1>
! <para>
! Refer to <xref linkend="xfunc"> for further information on writing
! functions.
! </para>
! <refsect1 id="sql-createfunction-overloading">
! <title>Overloading</title>
<para>
<productname>PostgreSQL</productname> allows function
***************
*** 529,578 ****
function should be called.
</para>
! <para>
! When repeated <command>CREATE FUNCTION</command> calls refer to
! the same object file, the file is only loaded once per session.
! To unload and
! reload the file (perhaps during development), start a new session.
! </para>
!
! <para>
! Use <xref linkend="sql-dropfunction"
! endterm="sql-dropfunction-title"> to remove user-defined
! functions.
! </para>
!
! <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>
!
! <para>
! If a <literal>SET</> clause is attached to a function, then
! the effects of a <command>SET LOCAL</> command executed inside the
! function for the same variable are restricted to the function: the
! configuration parameter's prior value is still restored at function exit.
! However, an ordinary
! <command>SET</> command (without <literal>LOCAL</>) overrides the
! <literal>SET</> clause, much as it would do for a previous <command>SET
! LOCAL</> command: the effects of such a command will persist after
! function exit, unless the current transaction is rolled back.
! </para>
! <para>
! To be able to define a function, the user must have the
! <literal>USAGE</literal> privilege on the language.
! </para>
<para>
! When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
! existing function, the ownership and permissions of the function
! do not change. All other function properties are assigned the
! values specified or implied in the command. You must own the function
! to replace it (this includes being a member of the owning role).
</para>
<para>
--- 560,578 ----
function should be called.
</para>
! </refsect1>
! <refsect1 id="sql-createfunction-notes">
! <title>Notes</title>
<para>
! The full <acronym>SQL</acronym> type syntax is allowed for
! input arguments and return value. However, some details of the
! type specification (e.g., the precision field for
! type <type>numeric</type>) are the responsibility of the
! underlying function implementation and are silently swallowed
! (i.e., not recognized or
! enforced) by the <command>CREATE FUNCTION</command> command.
</para>
<para>
--
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
