aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
authorTom Lane <tgl@sss.pgh.pa.us>2010-02-23 22:51:43 +0000
committerTom Lane <tgl@sss.pgh.pa.us>2010-02-23 22:51:43 +0000
commit11b58470581f1c8cfad670c57ac3ffe77d1f0cdd (patch)
tree8fc7b3c2995b08720d6cd6ff48aa11dfec6187b2 /doc/src
parentc4fc082a5ac11c1206ed6707e3644914db36c6c3 (diff)
downloadpostgresql-11b58470581f1c8cfad670c57ac3ffe77d1f0cdd.tar.gz
postgresql-11b58470581f1c8cfad670c57ac3ffe77d1f0cdd.zip
Add an OR REPLACE option to CREATE LANGUAGE.
This operates in the same way as other CREATE OR REPLACE commands, ie, it replaces everything but the ownership and ACL lists of an existing entry, and requires the caller to have owner privileges for that entry. While modifying an existing language has some use in development scenarios, in typical usage all the "replaced" values come from pg_pltemplate so there will be no actual change in the language definition. The reason for adding this is mainly to allow programs to ensure that a language exists without triggering an error if it already does exist. This commit just adds and documents the new option. A followon patch will use it to clean up some unpleasant cases in pg_dump and pg_regress.
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/ref/create_language.sgml32
1 files changed, 24 insertions, 8 deletions
diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml
index 457af691832..3f52578634e 100644
--- a/doc/src/sgml/ref/create_language.sgml
+++ b/doc/src/sgml/ref/create_language.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.48 2009/12/19 01:49:02 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.49 2010/02/23 22:51:42 tgl Exp $
PostgreSQL documentation
-->
@@ -21,8 +21,8 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CREATE [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
-CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
+CREATE [ OR REPLACE ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
+CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
HANDLER <replaceable class="parameter">call_handler</replaceable> [ INLINE <replaceable class="parameter">inline_handler</replaceable> ] [ VALIDATOR <replaceable>valfunction</replaceable> ]
</synopsis>
</refsynopsisdiv>
@@ -31,8 +31,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
<title>Description</title>
<para>
- Using <command>CREATE LANGUAGE</command>, a
- <productname>PostgreSQL</productname> user can register a new
+ <command>CREATE LANGUAGE</command> registers a new
procedural language with a <productname>PostgreSQL</productname>
database. Subsequently, functions and trigger procedures can be
defined in this new language.
@@ -40,9 +39,9 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
<para>
<command>CREATE LANGUAGE</command> effectively associates the
- language name with a call handler that is responsible for executing
+ language name with handler function(s) that are responsible for executing
functions written in the language. Refer to <xref linkend="plhandler">
- for more information about language call handlers.
+ for more information about language handlers.
</para>
<para>
@@ -77,6 +76,23 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
The creator of a language becomes its owner and can later
drop it, rename it, or assign it to a new owner.
</para>
+
+ <para>
+ <command>CREATE OR REPLACE LANGUAGE</command> will either create a
+ new language, or replace an existing definition. If the language
+ already exists, its parameters are updated according to the values
+ specified or taken from <structname>pg_pltemplate</structname>,
+ but the language's ownership and permissions settings do not change,
+ and any existing functions written in the language are assumed to still
+ be valid. In addition to the normal privilege requirements for creating
+ a language, the user must be superuser or owner of the existing language.
+ The <literal>REPLACE</> case is mainly meant to be used to
+ ensure that the language exists. If the language has a
+ <structname>pg_pltemplate</structname> entry then <literal>REPLACE</>
+ will not actually change anything about an existing definition, except in
+ the unusual case where the <structname>pg_pltemplate</structname> entry
+ has been modified since the language was created.
+ </para>
</refsect1>
<refsect1 id="sql-createlanguage-parameters">
@@ -88,7 +104,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
<listitem>
<para>
- <literal>TRUSTED</literal> specifies that the call handler for
+ <literal>TRUSTED</literal> specifies that
the language is safe, that is, it does not offer an
unprivileged user any functionality to bypass access
restrictions. If this key word is omitted when registering the