mirror of
https://github.com/postgres/postgres.git
synced 2025-07-28 23:42:10 +03:00
Implement a preliminary 'template' facility for procedural languages,
as per my recent proposal. For now the template data is hard-wired in proclang.c --- this should be replaced later by a new shared system catalog, but we don't want to force initdb during 8.1 beta. This change lets us cleanly load existing dump files even if they contain outright wrong information about a PL's support functions, such as a wrong path to the shared library or a missing validator function. Also, we can revert the recent kluges to make pg_dump dump PL support functions that are stored in pg_catalog. While at it, I removed the code in pg_regress that replaced $libdir with a hardcoded path for temporary installations. This is no longer needed given our support for relocatable installations.
This commit is contained in:
Tom Lane
@ -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,18 +162,58 @@ 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>
|
||||
Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
|
||||
linkend="app-droplang"> program, to drop procedural languages.
|
||||
</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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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>
|
||||
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>
|
||||
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>
|
||||
@ -168,38 +225,22 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
|
||||
declared as returning <type>opaque</>, but it will issue a notice and
|
||||
change the function's declared return type to <type>language_handler</>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new
|
||||
function.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
|
||||
linkend="app-droplang"> program, to drop procedural languages.
|
||||
</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.
|
||||
</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.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="sql-createlanguage-examples">
|
||||
<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'
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user