From c2903fb3d2aeb0a7206945478ad28bc47bd6c6e8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 5 Mar 2011 01:08:38 -0500 Subject: [PATCH] Update documentation to reflect that standard PLs are now extensions. Recommend use of CREATE EXTENSION rather than plain CREATE LANGUAGE where relevant. Encourage PL authors to provide extension wrappers for their PLs. --- doc/src/sgml/installation.sgml | 4 ++-- doc/src/sgml/plhandler.sgml | 9 +++++++++ doc/src/sgml/plperl.sgml | 10 +++++----- doc/src/sgml/plpython.sgml | 1 + doc/src/sgml/pltcl.sgml | 1 + doc/src/sgml/ref/create_language.sgml | 15 +++++++++++++++ doc/src/sgml/ref/drop_language.sgml | 9 +++++++++ doc/src/sgml/xplang.sgml | 21 ++++++++++----------- 8 files changed, 52 insertions(+), 18 deletions(-) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 8400ce5d70..b2d6990f78 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -2601,8 +2601,8 @@ cc-1020 cc: ERROR File = pqcomm.c, Line = 427 To build 64 bit binaries using MinGW, install the 64 bit tool set from , put its bin - directory in the PATH, and run - configure with the + directory in the PATH, and run + configure with the --host=x86_64-w64-mingw option. diff --git a/doc/src/sgml/plhandler.sgml b/doc/src/sgml/plhandler.sgml index 6cddf002fb..20021bce65 100644 --- a/doc/src/sgml/plhandler.sgml +++ b/doc/src/sgml/plhandler.sgml @@ -216,6 +216,15 @@ CREATE LANGUAGE plsample should execute this code and return. + + It's recommended that you wrap all these function declarations, + as well as the CREATE LANGUAGE command itself, into + an extension so that a simple CREATE EXTENSION + command is sufficient to install the language. See + for information about writing + extensions. + + The procedural languages included in the standard distribution are good references when trying to write your own language handler. diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index a481accd86..16984aab63 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -27,6 +27,7 @@ To install PL/Perl in a particular database, use + CREATE EXTENSION plperl, or from the shell command line use createlang plperl dbname. @@ -127,9 +128,9 @@ $$ LANGUAGE plperl; - 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. @@ -967,8 +968,7 @@ $$ LANGUAGE plperl; mail. To handle these cases, PL/Perl can also be installed as an untrusted language (usually called PL/PerlUPL/PerlU). - In this case the full Perl language is available. If the - createlang program is used to install the + In this case the full Perl language is available. When installing the language, the language name plperlu will select the untrusted PL/Perl variant. diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml index a729fa3e17..0aa5159e2b 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -14,6 +14,7 @@ To install PL/Python in a particular database, use + CREATE EXTENSION plpythonu, or from the shell command line use createlang plpythonu dbname (but see also ). diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index 052a158fa9..4215f192ba 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -66,6 +66,7 @@ directory if Tcl support is specified in the configuration step of the installation procedure. To install PL/Tcl and/or PL/TclU in a particular database, use the + CREATE EXTENSION command or the createlang program, for example createlang pltcl dbname or createlang pltclu dbname. diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index c9cb95cae5..13c3baf993 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -37,6 +37,21 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE + not CREATE LANGUAGE. Direct use of + CREATE LANGUAGE should now be confined to + extension installation scripts. If you have a bare + language in your database, perhaps as a result of an upgrade, + you can convert it to an extension using + CREATE EXTENSION langname FROM + unpackaged. + + + CREATE LANGUAGE effectively associates the language name with handler function(s) that are responsible for executing diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index 6bf900e254..21c9e5aced 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -33,6 +33,15 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] nameDROP LANGUAGE. + + + + As of PostgreSQL 9.1, most procedural + languages have been made into extensions, and should + therefore be removed with + not DROP LANGUAGE. + + diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 0aef3bf4b3..68220bf633 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -54,7 +54,7 @@ For the languages supplied with the standard distribution, it is - only necessary to execute CREATE LANGUAGE + only necessary to execute CREATE EXTENSION language_name to install the language into the current database. Alternatively, the program can be used to do this from the shell @@ -65,8 +65,7 @@ createlang plperl template1 The manual procedure described below is only recommended for - installing custom languages that CREATE LANGUAGE - does not know about. + installing languages that have not been packaged as extensions. @@ -76,10 +75,10 @@ createlang plperl template1 A procedural language is installed in a database in five steps, - which must be carried out by a database superuser. (For languages - known to 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 extension, so that CREATE EXTENSION can be + used to execute them. @@ -136,14 +135,14 @@ CREATE FUNCTION inline_function_name(internal) CREATE FUNCTION validator_function_name(oid) RETURNS void AS 'path-to-shared-object' - LANGUAGE C; + LANGUAGE C STRICT; - The PL must be declared with the command + Finally, the PL must be declared with the command CREATE TRUSTED PROCEDURAL LANGUAGE language-name HANDLER handler_function_name @@ -154,7 +153,7 @@ CREATE TRUSTED PROCEDURAL LANGUAGE TRUSTED 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; -- 2.40.0