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 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 - 1.91
--- doc/src/sgml/ref/create_function.sgml 26 Feb 2010 23:58:55 -
***
*** 46,51
--- 46,55
CREATE FUNCTION defines a new function.
CREATE OR REPLACE FUNCTION will either create a
new function, or replace an existing definition.
+To be able to define a function, the user must have the
+USAGE privilege on the language.
+
+
***
*** 70,75
--- 74,87
+When 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).
+
+
+
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
+If a SET clause is attached to a function, then
+the effects of a 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
+SET command (without LOCAL) overrides the
+SET clause, much as it would do for a previous SET
+LOCAL command: the effects of such a command will persist after
+function exit, unless the current transaction is rolled back.
+
+
+
See and
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.
+
+
+It is often helpful to use dollar quoting (see ) 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.
+
+
***
*** 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.
+
+
+When repeated CREATE FUNCTION 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.
+
+
***
*** 479,501
!
! Notes
!
!
! Refer to for further information on writing
! functions.
!
!
! The full SQL type syntax is allowed for
! input arguments and return value. However, some details of the
! type specification (e.g., the precision field for
! type numeric) are the responsibility of the
! underlying function implementation and are silently swallowed
! (i.e., not recognized or
! enforced) by the CREATE FUNCTION command.
!
PostgreSQL allows function
--- 520,532
!
! Refer to for further information on writing
! functions.
!
!
! Overloading
PostgreSQL allows function
***
*** 529,578
function should be called.
!
! When repeated CREATE FUNCTION calls refer to
! the same object file, th
