From 1f78ad262ef660088906a21af7e3adb6ab1318ff Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 9 Feb 2001 02:20:52 +0000 Subject: [PATCH] Restructure discussion of PL installation to emphasize createlang as the recommended install procedure, rather than mentioning it as an afterthought. --- doc/src/sgml/xplang.sgml | 83 +++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 43 deletions(-) diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 5c13526777..8e72b93189 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -1,5 +1,5 @@ @@ -15,7 +15,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 pete text. Instead, the task is passed to a special handler that knows the details of the language. The handler could either do all the work of parsing, syntax analysis, execution, etc. itself, or it - could serve as a glue between + could serve as glue between Postgres and an existing implementation of a programming language. The handler itself is a special programming language function compiled into a shared object and @@ -24,33 +24,52 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 pete Writing a handler for a new procedural language is outside the - scope of this manual. Several procedural languages are available - in the Postgres distribution. + scope of this manual, although some information is provided in + the CREATE LANGUAGE reference page. Several procedural languages are + available in the standard Postgres distribution. Installing Procedural Languages + + A procedural language must be installed into each + database where it is to be used. But procedural languages installed in + the template1 database are automatically available in all + subsequently created databases. So the database administrator can + decide which languages are available in which databases, and can make + some languages available by default if he chooses. + + + + For the languages supplied with the standard distribution, the + shell script createlang may be used instead + of carrying out the details by hand. For example, to install PL/pgSQL + into the template1 database, use + +createlang plpgsql template1 + + The manual procedure described below is only recommended for + installing custom languages that createlang + does not know about. + + - Procedural Language Installation + Manual Procedural Language Installation A procedural language is installed in the database in three - steps. A procedural language must be installed into each - database where it is to be used. Procedural languages defined in - the template1 database are automatically available in all - subsequently created databases. So the administrator can decide - which languages are available by default. + steps, which must be carried out by a database superuser. The shared object for the language handler must be compiled and - installed. This works in the same way as building and - installing modules with regular user-defined C functions does; - see . + installed into an appropriate library directory. This works in the same + way as building and installing modules with regular user-defined C + functions does; see . @@ -84,18 +103,21 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'TRUSTED flag should only be given for languages that do not allow access to database backends - internals or the filesystem. The languages PL/pgSQL and - PL/Tcl are known to be trusted. + internals or the filesystem. The languages PL/pgSQL, + PL/Tcl, and PL/Perl are known to be trusted; the language PL/TclU + should not be marked trusted. In a default Postgres installation, the - handler for the PL/pgSQL is built and installed into the + handler for the PL/pgSQL language is built and installed into the library directory. If Tcl/Tk support is configured - in, the handler for PL/Tcl is also built and installed in the same - location. + in, the handlers for PL/Tcl and PL/TclU are also built and installed in + the same location. Likewise, the PL/Perl handler is built and installed + if Perl support is configured. The createlang + script automates the two CREATE steps described above. @@ -128,31 +150,6 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql' - - For the languages supplied with the standard distribution, the - shell script createlang can be used instead - of carrying out the details manually. To install PL/pgSQL into - the template1 database, use - -createlang plpgsql template1 - - - - - PL handler functions have a special call interface that is - different from regular C language functions. One of the arguments - given to the handler is the object ID in the pg_proc - tables entry for the function that should be executed. - The handler examines various system catalogs to analyze the - functions call arguments and it's return data type. The source - text of the functions body is found in the prosrc attribute of - pg_proc. - Due to this, PL functions - can be overloaded like SQL language functions. There can be - multiple different PL functions having the same function name, - as long as the call arguments differ. - -