mirror of
https://github.com/postgres/postgres.git
synced 2025-05-08 07:21:33 +03:00
55a7cf80a0
A DBA is allowed to create a language in his database if it's marked "tmpldbacreate" in pg_pltemplate. The factory default is that this is set for all standard trusted languages, but of course a superuser may adjust the settings. In service of this, add the long-foreseen owner column to pg_language; renaming, dropping, and altering owner of a PL now follow normal ownership rules instead of being superuser-only. Jeremy Drake, with some editorialization by Tom Lane.
286 lines
10 KiB
Plaintext
286 lines
10 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.44 2007/03/26 16:58:38 tgl Exp $
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="SQL-CREATELANGUAGE">
|
|
<refmeta>
|
|
<refentrytitle id="sql-createlanguage-title">CREATE LANGUAGE</refentrytitle>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>CREATE LANGUAGE</refname>
|
|
<refpurpose>define a new procedural language</refpurpose>
|
|
</refnamediv>
|
|
|
|
<indexterm zone="sql-createlanguage">
|
|
<primary>CREATE LANGUAGE</primary>
|
|
</indexterm>
|
|
|
|
<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>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="sql-createlanguage-description">
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Using <command>CREATE LANGUAGE</command>, a
|
|
<productname>PostgreSQL</productname> user can register a new
|
|
procedural language with a <productname>PostgreSQL</productname>
|
|
database. Subsequently, functions and trigger procedures can be
|
|
defined in this new language.
|
|
</para>
|
|
|
|
<para>
|
|
<command>CREATE LANGUAGE</command> effectively associates the
|
|
language name with a call handler that is responsible for executing
|
|
functions written in the language. Refer to <xref linkend="xplang">
|
|
for more information about language call handlers.
|
|
</para>
|
|
|
|
<para>
|
|
There are two forms of the <command>CREATE LANGUAGE</command> command.
|
|
In the first form, the user supplies just the name of the desired
|
|
language, and the <productname>PostgreSQL</productname> server consults
|
|
the <link linkend="catalog-pg-pltemplate"><structname>pg_pltemplate</structname></link>
|
|
system catalog to determine the correct parameters. In the second form,
|
|
the user supplies the language parameters along with the language name.
|
|
The second form can be used to create a language that is not defined in
|
|
<structname>pg_pltemplate</>, but this approach is considered obsolescent.
|
|
</para>
|
|
|
|
<para>
|
|
When the server finds an entry in the <structname>pg_pltemplate</> catalog
|
|
for the given language name, it will use the catalog data even if the
|
|
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>
|
|
|
|
<para>
|
|
Ordinarily, the user must have the
|
|
<productname>PostgreSQL</productname> superuser privilege to
|
|
register a new language. However, the owner of a database can register
|
|
a new language within that database if the language is listed in
|
|
the <structname>pg_pltemplate</structname> catalog and is marked
|
|
as allowed to be created by database owners (<structfield>tmpldbacreate</>
|
|
is true). The default is that trusted languages can be created
|
|
by database owners, but this can be adjusted by superusers by modifying
|
|
the contents of <structname>pg_pltemplate</structname>.
|
|
The creator of a language becomes its owner and can later
|
|
drop it, rename it, or assign it to a new owner.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="sql-createlanguage-parameters">
|
|
<title>Parameters</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>TRUSTED</literal></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
<literal>TRUSTED</literal> specifies that the call handler for
|
|
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
|
|
language, only users with the
|
|
<productname>PostgreSQL</productname> superuser privilege can
|
|
use this language to create new functions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>PROCEDURAL</literal></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
This is a noise word.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
The name of the new procedural language. The language name is
|
|
case insensitive. The name must be unique among the languages
|
|
in the database.
|
|
</para>
|
|
|
|
<para>
|
|
For backward compatibility, the name can be enclosed by single
|
|
quotes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>HANDLER</literal> <replaceable class="parameter">call_handler</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
<replaceable class="parameter">call_handler</replaceable> is
|
|
the name of a previously registered function that will be
|
|
called to execute the procedural language functions. The call
|
|
handler for a procedural language must be written in a compiled
|
|
language such as C with version 1 call convention and
|
|
registered with <productname>PostgreSQL</productname> as a
|
|
function taking no arguments and returning the
|
|
<type>language_handler</type> type, a placeholder type that is
|
|
simply used to identify the function as a call handler.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>VALIDATOR</literal> <replaceable class="parameter">valfunction</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
<replaceable class="parameter">valfunction</replaceable> is the
|
|
name of a previously registered function that will be called
|
|
when a new function in the language is created, to validate the
|
|
new function.
|
|
If no
|
|
validator function is specified, then a new function will not
|
|
be checked when it is created.
|
|
The validator function must take one argument of
|
|
type <type>oid</type>, which will be the OID of the
|
|
to-be-created function, and will typically return <type>void</>.
|
|
</para>
|
|
|
|
<para>
|
|
A validator function would typically inspect the function body
|
|
for syntactical correctness, but it can also look at other
|
|
properties of the function, for example if the language cannot
|
|
handle certain argument types. To signal an error, the
|
|
validator function should use the <function>ereport()</function>
|
|
function. The return value of the function is ignored.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The <literal>TRUSTED</> option and the support function name(s) are
|
|
ignored if the server has an entry for the specified language
|
|
name in <structname>pg_pltemplate</>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="sql-createlanguage-notes">
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
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 can 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 an entry for the language
|
|
in <structname>pg_pltemplate</>. But when there is an entry,
|
|
the functions need not already exist;
|
|
they will be automatically defined if not present in the database.
|
|
(This might 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>
|
|
|
|
<refsect1 id="sql-createlanguage-examples">
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
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 <structname>pg_pltemplate</> catalog, a
|
|
sequence such as this is needed:
|
|
<programlisting>
|
|
CREATE FUNCTION plsample_call_handler() RETURNS language_handler
|
|
AS '$libdir/plsample'
|
|
LANGUAGE C;
|
|
CREATE LANGUAGE plsample
|
|
HANDLER plsample_call_handler;
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="sql-createlanguage-compat">
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
<command>CREATE LANGUAGE</command> is a
|
|
<productname>PostgreSQL</productname> extension.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="sql-alterlanguage" endterm="sql-alterlanguage-title"></member>
|
|
<member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
|
|
<member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
|
|
<member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
|
|
<member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
|
|
<member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
|
|
<member><xref linkend="app-droplang" endterm="app-droplang-title"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|