mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation to reflect that standard PLs are now extensions.

Browse Source 
Recommend use of CREATE EXTENSION rather than plain CREATE LANGUAGE
where relevant.  Encourage PL authors to provide extension wrappers
for their PLs.
This commit is contained in:
Tom Lane 2011-03-05 01:08:38 -05:00
parent 63b656b7bf
commit c2903fb3d2
8 changed files with 52 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/installation.sgml
View File

@ -2601,8 +2601,8 @@ cc-1020 cc: ERROR File = pqcomm.c, Line = 427
<para>
To build 64 bit binaries using MinGW, install the 64 bit tool set
from <ulink url="http://mingw-w64.sourceforge.net/"></ulink>, put its bin
directory in the <envar>PATH</envar>, and run
<command>configure</command> with the
directory in the <envar>PATH</envar>, and run
<command>configure</command> with the
<command>--host=x86_64-w64-mingw</command> option.
</para>

9
doc/src/sgml/plhandler.sgml
View File

@ -216,6 +216,15 @@ CREATE LANGUAGE plsample
should execute this code and return.
</para>
<para>
It's recommended that you wrap all these function declarations,
as well as the <command>CREATE LANGUAGE</> command itself, into
an <firstterm>extension</> so that a simple <command>CREATE EXTENSION</>
command is sufficient to install the language. See
<xref linkend="extend-extensions"> for information about writing
extensions.
</para>
<para>
The procedural languages included in the standard distribution
are good references when trying to write your own language handler.

10
doc/src/sgml/plperl.sgml
View File

@ -27,6 +27,7 @@
<para>
To install PL/Perl in a particular database, use
<literal>CREATE EXTENSION plperl</>, or from the shell command line use
<literal>createlang plperl <replaceable>dbname</></literal>.
</para>
@ -127,9 +128,9 @@ $$ LANGUAGE plperl;
<note>
<para>
Arguments will be converted from the database's encoding to UTF-8
for use inside plperl, and then converted from UTF-8 back to the
database encoding upon return.
Arguments will be converted from the database's encoding to UTF-8
for use inside plperl, and then converted from UTF-8 back to the
database encoding upon return.
</para>
</note>
@ -967,8 +968,7 @@ $$ LANGUAGE plperl;
mail. To handle these cases, PL/Perl can also be installed as an
<quote>untrusted</> language (usually called
<application>PL/PerlU</application><indexterm><primary>PL/PerlU</></indexterm>).
In this case the full Perl language is available. If the
<command>createlang</command> program is used to install the
In this case the full Perl language is available. When installing the
language, the language name <literal>plperlu</literal> will select
the untrusted PL/Perl variant.
</para>

1
doc/src/sgml/plpython.sgml
View File

@ -14,6 +14,7 @@
<para>
To install PL/Python in a particular database, use
<literal>CREATE EXTENSION plpythonu</>, or from the shell command line use
<literal>createlang plpythonu <replaceable>dbname</></literal> (but
see also <xref linkend="plpython-python23">).
</para>

1
doc/src/sgml/pltcl.sgml
View File

@ -66,6 +66,7 @@
directory if Tcl support is specified in the configuration step of
the installation procedure. To install <application>PL/Tcl</>
and/or <application>PL/TclU</> in a particular database, use the
<command>CREATE EXTENSION</> command or the
<command>createlang</command> program, for example
<literal>createlang pltcl <replaceable>dbname</></literal> or
<literal>createlang pltclu <replaceable>dbname</></literal>.

15
doc/src/sgml/ref/create_language.sgml
View File

@ -37,6 +37,21 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa
defined in this new language.
</para>
<note>
<para>
As of <productname>PostgreSQL</productname> 9.1, most procedural
languages have been made into <quote>extensions</>, and should
therefore be installed with <xref linkend="sql-createextension">
not <command>CREATE LANGUAGE</command>. Direct use of
<command>CREATE LANGUAGE</command> should now be confined to
extension installation scripts. If you have a <quote>bare</>
language in your database, perhaps as a result of an upgrade,
you can convert it to an extension using
<literal>CREATE EXTENSION <replaceable>langname</> FROM
unpackaged</literal>.
</para>
</note>
<para>
<command>CREATE LANGUAGE</command> effectively associates the
language name with handler function(s) that are responsible for executing

9
doc/src/sgml/ref/drop_language.sgml
View File

@ -33,6 +33,15 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] <replaceable class="PARAMETER">name</
previously registered procedural language. You must be a superuser
or the owner of the language to use <command>DROP LANGUAGE</>.
</para>
<note>
<para>
As of <productname>PostgreSQL</productname> 9.1, most procedural
languages have been made into <quote>extensions</>, and should
therefore be removed with <xref linkend="sql-dropextension">
not <command>DROP LANGUAGE</command>.
</para>
</note>
</refsect1>
<refsect1>

21
doc/src/sgml/xplang.sgml
View File

@ -54,7 +54,7 @@
<para>
For the languages supplied with the standard distribution, it is
only necessary to execute <command>CREATE LANGUAGE</>
only necessary to execute <command>CREATE EXTENSION</>
<replaceable>language_name</> to install the language into the
current database. Alternatively, the program <xref
linkend="app-createlang"> can be used to do this from the shell
@ -65,8 +65,7 @@
createlang plperl template1
</programlisting>
The manual procedure described below is only recommended for
installing custom languages that <command>CREATE LANGUAGE</command>
does not know about.
installing languages that have not been packaged as extensions.
</para>
<procedure>
@ -76,10 +75,10 @@ createlang plperl template1
<para>
A procedural language is installed in a database in five steps,
which must be carried out by a database superuser. (For languages
known to <command>CREATE LANGUAGE</>, the second through fourth steps
can be omitted, because they will be carried out automatically
if needed.)
which must be carried out by a database superuser. In most cases
the required SQL commands should be packaged as the installation script
of an <quote>extension</>, so that <command>CREATE EXTENSION</> can be
used to execute them.
</para>
<step performance="required" id="xplang-install-cr1">
@ -136,14 +135,14 @@ CREATE FUNCTION <replaceable>inline_function_name</replaceable>(internal)
CREATE FUNCTION <replaceable>validator_function_name</replaceable>(oid)
RETURNS void
AS '<replaceable>path-to-shared-object</replaceable>'
LANGUAGE C;
LANGUAGE C STRICT;
</synopsis>
</para>
</step>
<step performance="required" id="xplang-install-cr5">
<para>
The PL must be declared with the command
Finally, the PL must be declared with the command
<synopsis>
CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <replaceable>language-name</replaceable>
HANDLER <replaceable>handler_function_name</replaceable>
@ -154,7 +153,7 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
the language does not grant access to data that the user would
not otherwise have. Trusted languages are designed for ordinary
database users (those without superuser privilege) and allows them
to safely create of functions and trigger
to safely create functions and trigger
procedures. Since PL functions are executed inside the database
server, the <literal>TRUSTED</literal> flag should only be given
for languages that do not allow access to database server
@ -201,7 +200,7 @@ CREATE FUNCTION plperl_inline_handler(internal) RETURNS void AS
'$libdir/plperl' LANGUAGE C;
CREATE FUNCTION plperl_validator(oid) RETURNS void AS
'$libdir/plperl' LANGUAGE C;
'$libdir/plperl' LANGUAGE C STRICT;
</programlisting>
</para>