diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/create_language.sgml | 103 | ||||
| -rw-r--r-- | doc/src/sgml/ref/createlang.sgml | 41 | ||||
| -rw-r--r-- | doc/src/sgml/xplang.sgml | 30 |
3 files changed, 101 insertions, 73 deletions
diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 9e895f2817b..29bcade195d 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.39 2005/01/04 00:39:53 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.40 2005/09/05 23:50:48 tgl Exp $ PostgreSQL documentation --> @@ -20,6 +20,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> +CREATE [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable> CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable> HANDLER <replaceable class="parameter">call_handler</replaceable> [ VALIDATOR <replaceable>valfunction</replaceable> ] </synopsis> @@ -46,9 +47,25 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</ </para> <para> - Note that procedural languages are local to individual databases. - To make a language available in all databases by default, it should - be installed into the <literal>template1</literal> database. + There are two forms of the <command>CREATE LANGUAGE</command> command. + In the first form, the user merely supplies the name of the desired + language, and the <productname>PostgreSQL</productname> server consults + an internal table to determine the correct parameters. In + the second form, the user supplies the language parameters along with + the language name. The second form must be used to create a language + that is not present in the internal table, but this form is considered + obsolescent. (It is expected that future releases of + <productname>PostgreSQL</productname> will replace the internal table + with a system catalog that can be extended to support additional + languages.) + </para> + + <para> + When the server finds an entry in its internal table for the given + language name, it will use the table data even if the given command + includes language parameters. This behavior simplifies loading of + old dump files, which are likely to contain out-of-date information + about language support functions. </para> </refsect1> @@ -145,52 +162,68 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</ </listitem> </varlistentry> </variablelist> + + <para> + The <literal>TRUSTED</> option and the support function name(s) are + ignored if the server has information about the specified language + name in its internal table. + </para> </refsect1> <refsect1 id="sql-createlanguage-notes"> <title>Notes</title> <para> - This command normally should not be executed directly by users. - For the procedural languages supplied in the - <productname>PostgreSQL</productname> distribution, the <xref - linkend="app-createlang"> program should be used, which will also - install the correct call handler. (<command>createlang</command> - will call <command>CREATE LANGUAGE</command> internally.) + The <xref linkend="app-createlang"> program is a simple wrapper around + the <command>CREATE LANGUAGE</> command. It eases + installation of procedural languages from the shell command line. </para> <para> - In <productname>PostgreSQL</productname> versions before 7.3, it was - necessary to declare handler functions as returning the placeholder - type <type>opaque</>, rather than <type>language_handler</>. - To support loading - of old dump files, <command>CREATE LANGUAGE</> will accept a function - declared as returning <type>opaque</>, but it will issue a notice and - change the function's declared return type to <type>language_handler</>. + Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref + linkend="app-droplang"> program, to drop procedural languages. </para> <para> - Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new - function. + The system catalog <classname>pg_language</classname> (see <xref + linkend="catalog-pg-language">) records information about the + currently installed languages. Also, <command>createlang</command> + has an option to list the installed languages. </para> <para> - Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref - linkend="app-droplang"> program, to drop procedural languages. + To create functions in a procedural language, a user must have the + <literal>USAGE</literal> privilege for the language. By default, + <literal>USAGE</> is granted to <literal>PUBLIC</> (i.e., everyone) + for trusted languages. This may be revoked if desired. </para> <para> - The system catalog <classname>pg_language</classname> (see <xref - linkend="catalog-pg-language">) records information about the - currently installed languages. Also <command>createlang</command> - has an option to list the installed languages. + Procedural languages are local to individual databases. + However, a language can be installed into the <literal>template1</literal> + database, which will cause it to be available automatically in + all subsequently-created databases. </para> <para> - To be able to use a procedural language, a user must be granted the - <literal>USAGE</literal> privilege. The - <command>createlang</command> program automatically grants - permissions to everyone if the language is known to be trusted. + The call handler function and the validator function (if any) + must already exist if the server does not have information about + the language in its internal table. But when there is an entry + in the internal table, the functions need not already exist; + they will be automatically defined if not present in the database. + (This can result in <command>CREATE LANGUAGE</> failing, if the + shared library that implements the language is not available in + the installation.) + </para> + + <para> + In <productname>PostgreSQL</productname> versions before 7.3, it was + necessary to declare handler functions as returning the placeholder + type <type>opaque</>, rather than <type>language_handler</>. + To support loading + of old dump files, <command>CREATE LANGUAGE</> will accept a function + declared as returning <type>opaque</>, but it will issue a notice and + change the function's declared return type to <type>language_handler</>. </para> </refsect1> @@ -198,8 +231,16 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</ <title>Examples</title> <para> - The following two commands executed in sequence will register a new - procedural language and the associated call handler. + The preferred way of creating any of the standard procedural languages + is just: +<programlisting> +CREATE LANGUAGE plpgsql; +</programlisting> + </para> + + <para> + For a language not known in the server's internal table, a sequence + such as this is needed: <programlisting> CREATE FUNCTION plsample_call_handler() RETURNS language_handler AS '$libdir/plsample' diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml index 9829d845b0e..f9f8dc1ea78 100644 --- a/doc/src/sgml/ref/createlang.sgml +++ b/doc/src/sgml/ref/createlang.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.35 2005/06/21 04:02:31 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.36 2005/09/05 23:50:48 tgl Exp $ PostgreSQL documentation --> @@ -42,13 +42,7 @@ PostgreSQL documentation programming language to a <productname>PostgreSQL</productname> database. <application>createlang</application> can handle all the languages supplied in the default <productname>PostgreSQL</> distribution, but - not languages provided by other parties. - </para> - <para> - Although backend programming languages can be added directly using - several <acronym>SQL</acronym> commands, it is recommended to use - <application>createlang</application> because it performs a number - of checks and is much easier to use. See + not languages provided by other parties. See <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"> for additional information. </para> @@ -66,8 +60,8 @@ PostgreSQL documentation <term><replaceable class="parameter">langname</replaceable></term> <listitem> <para> - Specifies the name of the procedural programming language to be - defined. + Specifies the name of the procedural programming language to be + defined. </para> </listitem> </varlistentry> @@ -77,7 +71,7 @@ PostgreSQL documentation <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></></term> <listitem> <para> - Specifies to which database the language should be added. + Specifies to which database the language should be added. The default is to use the database with the same name as the current system user. </para> @@ -104,17 +98,6 @@ PostgreSQL documentation </listitem> </varlistentry> - <varlistentry> - <term><option>-L <replaceable class="parameter">directory</replaceable></></term> - <listitem> - <para> - Specifies the directory in which the language interpreter is - to be found. The directory is normally found automatically; this - option is primarily for debugging purposes. - </para> - </listitem> - </varlistentry> - </variablelist> </para> @@ -128,10 +111,10 @@ PostgreSQL documentation <term><option>--host <replaceable class="parameter">host</replaceable></></term> <listitem> <para> - Specifies the host name of the machine on which the - server - is running. If the value begins with a slash, it is used - as the directory for the Unix domain socket. + Specifies the host name of the machine on which the + server + is running. If the value begins with a slash, it is used + as the directory for the Unix domain socket. </para> </listitem> </varlistentry> @@ -141,9 +124,9 @@ PostgreSQL documentation <term><option>--port <replaceable class="parameter">port</replaceable></></term> <listitem> <para> - Specifies the TCP port or local Unix domain socket file - extension on which the server - is listening for connections. + Specifies the TCP port or local Unix domain socket file + extension on which the server + is listening for connections. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 76842017a6a..7943138e623 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.28 2004/12/30 21:45:37 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.29 2005/09/05 23:50:48 tgl Exp $ --> <chapter id="xplang"> @@ -59,17 +59,19 @@ $PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.28 2004/12/30 21:45:37 tgl Exp $ </para> <para> - For the languages supplied with the standard distribution, the - program <xref linkend="app-createlang"> may be used to install the - language instead of carrying out the details by hand. For - example, to install the language + For the languages supplied with the standard distribution, it is + only necessary to execute <command>CREATE LANGUAGE</> + <replaceable>language_name</> to install the language into the + current database. Alternatively, the program <xref + linkend="app-createlang"> may be used to do this from the shell + command line. For example, to install the language <application>PL/pgSQL</application> into the database <literal>template1</>, use <programlisting> createlang plpgsql template1 </programlisting> The manual procedure described below is only recommended for - installing custom languages that <command>createlang</command> + installing custom languages that <command>CREATE LANGUAGE</command> does not know about. </para> @@ -80,9 +82,10 @@ createlang plpgsql template1 <para> A procedural language is installed in a database in four steps, - which must be carried out by a database superuser. The - <command>createlang</command> program automates all but <xref - linkend="xplang-install-cr1">. + which must be carried out by a database superuser. (For languages + known to <command>CREATE LANGUAGE</>, the second and third steps + can be omitted, because they will be carried out automatically + if needed.) </para> <step performance="required" id="xplang-install-cr1"> @@ -202,10 +205,11 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql In a default <productname>PostgreSQL</productname> installation, the handler for the <application>PL/pgSQL</application> language is built and installed into the <quote>library</quote> - directory. If <application>Tcl</> support is configured in, the handlers for - <application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same - location. Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built - and installed if Perl support is configured, and <application>PL/PythonU</> is + directory. If <application>Tcl</> support is configured in, the handlers + for <application>PL/Tcl</> and <application>PL/TclU</> are also built and + installed in the same location. Likewise, the <application>PL/Perl</> and + <application>PL/PerlU</> handlers are built and installed if Perl support + is configured, and the <application>PL/PythonU</> handler is installed if Python support is configured. </para> |