Thread: CREATE FUNCTION reference page's Notes section is getting out of hand
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? regards, tom lane
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 <bruce@momjian.us> 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>
Bruce Momjian wrote: > 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. > Applied. --------------------------------------------------------------------------- > -- > Bruce Momjian <bruce@momjian.us> 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. + [ text/x-diff is unsupported, treating like TEXT/PLAIN ] > 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 (pgsql-docs@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-docs -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com PG East: http://www.enterprisedb.com/community/nav-pg-east-2010.do