- trigger and SPI interfaces.
Procedural Languages
- the definition of procedural languages.
- In the case of a function or trigger
- procedure defined in a procedural language, the database has
+
Postgres allows users to add new
+ programming languages to be available for writing functions and
+ procedures. These are called procedural
+ languages (PL). In the case of a function or trigger
+ procedure written in a procedural language, the database server has
no built-in knowledge about how to interpret the function's source
- text. Instead, the task is passed to
- a handler that knows the details of the language. The
- handler itself is a special programming language function
- compiled into a shared object
- and loaded on demand.
+ 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
+
Postgres and an existing implementation
+ of a programming language. The handler itself is a special
+ programming language function compiled into a shared object and
+ loaded on demand.
- Writing a handler for a new procedural language (PL)
- is outside the scope of this manual.
+ Writing a handler for a new procedural language is outside the
+ scope of this manual. Several procedural languages are available
+ in the
Postgres distribution.
- A procedural language is installed in the database in three steps.
- (For the languages supplied with the standard distribution, the
- shell script createlang can be used instead
- of carrying out the details manually.)
+ 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.
- Required">
+ required">
- The shared object for the language handler
- must be compiled and installed. By default the
- handler for PL/pgSQL is built and installed into the
- database library directory. If Tcl/Tk support is
- configured in, the handler for PL/Tcl is also built
- and installed in the same location.
+ 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 .
-
+
+
The handler must be declared with the command
+>
CREATE FUNCTION handler_function_name ()
RETURNS OPAQUE AS
- '<filename>path-to-shared-objecte>' LANGUAGE 'C';
- >
- The special return type of <acronym>OPAQUE> tells
+ '<replaceable>path-to-shared-objecte>' LANGUAGE 'C';
+>
+ The special return type of <type>OPAQUE> tells
the database that this function does not return one of
- the defined
SQL datatypes and is not directly usable
+ the defined
SQL data
types and is not directly usable
-
+
+
The PL must be declared with the command
-CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE 'language-name'
+>
+CREATE TRUSTED PROCEDURAL LANGUAGE 'language-name'
HANDLER handler_function_name
LANCOMPILER 'description';
- >
- The optional key
word TRUSTED> tells+>
+ The optional key word TRUSTED> tells
whether ordinary database users that have no superuser
privileges should be allowed to use this language to create functions
and trigger procedures. Since PL functions are
executed inside the database backend, the
TRUSTED flag should only be given for
- languages that don't allow access to database backends
+ 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.
+ In a default
Postgres installation, the
+ handler for the PL/pgSQL 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.
+
+
Example
-
+
+
The following command tells the database where to find the
shared object for the PL/pgSQL language's call handler function.
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
'/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
-
+
The command
CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
HANDLER plpgsql_call_handler
LANCOMPILER 'PL/pgSQL';
-
+
+ then defines that the previously declared call handler function
+ should be invoked for functions and trigger procedures where the
+ language attribute is '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
+
+
- then defines that the previously declared call handler
- function should be invoked for functions and trigger procedures
- where the language attribute is 'plpgsql'.
-
PL handler functions have a special call interface that is
different from regular C language functions. One of the arguments
multiple different PL functions having the same function name,
as long as the call arguments differ.
- Procedural languages defined in the template1
- database are automatically defined in all subsequently created
- databases. So the database administrator can decide which
- languages are available by default.
-
-
-
+
-
projects / postgresql.git / commitdiff