begriffs open source - ai-pg/blob - full-docs/txt/xplang-install.txt

   1
   2 40.1. Installing Procedural Languages #
   3
   4    A procedural language must be “installed” into each database where it
   5    is to be used. But procedural languages installed in the database
   6    template1 are automatically available in all subsequently created
   7    databases, since their entries in template1 will be copied by CREATE
   8    DATABASE. So the database administrator can decide which languages are
   9    available in which databases and can make some languages available by
  10    default if desired.
  11
  12    For the languages supplied with the standard distribution, it is only
  13    necessary to execute CREATE EXTENSION language_name to install the
  14    language into the current database. The manual procedure described
  15    below is only recommended for installing languages that have not been
  16    packaged as extensions.
  17
  18    Manual Procedural Language Installation
  19
  20    A procedural language is installed in a database in five steps, which
  21    must be carried out by a database superuser. In most cases the required
  22    SQL commands should be packaged as the installation script of an
  23    “extension”, so that CREATE EXTENSION can be used to execute them.
  24     1. The shared object for the language handler must be compiled and
  25        installed into an appropriate library directory. This works in the
  26        same way as building and installing modules with regular
  27        user-defined C functions does; see Section 36.10.5. Often, the
  28        language handler will depend on an external library that provides
  29        the actual programming language engine; if so, that must be
  30        installed as well.
  31     2. The handler must be declared with the command
  32 CREATE FUNCTION handler_function_name()
  33     RETURNS language_handler
  34     AS 'path-to-shared-object'
  35     LANGUAGE C;
  36
  37        The special return type of language_handler tells the database
  38        system that this function does not return one of the defined SQL
  39        data types and is not directly usable in SQL statements.
  40     3. Optionally, the language handler can provide an “inline” handler
  41        function that executes anonymous code blocks (DO commands) written
  42        in this language. If an inline handler function is provided by the
  43        language, declare it with a command like
  44 CREATE FUNCTION inline_function_name(internal)
  45     RETURNS void
  46     AS 'path-to-shared-object'
  47     LANGUAGE C;
  48
  49     4. Optionally, the language handler can provide a “validator” function
  50        that checks a function definition for correctness without actually
  51        executing it. The validator function is called by CREATE FUNCTION
  52        if it exists. If a validator function is provided by the language,
  53        declare it with a command like
  54 CREATE FUNCTION validator_function_name(oid)
  55     RETURNS void
  56     AS 'path-to-shared-object'
  57     LANGUAGE C STRICT;
  58
  59     5. Finally, the PL must be declared with the command
  60 CREATE [TRUSTED] LANGUAGE language_name
  61     HANDLER handler_function_name
  62     [INLINE inline_function_name]
  63     [VALIDATOR validator_function_name] ;
  64
  65        The optional key word TRUSTED specifies that the language does not
  66        grant access to data that the user would not otherwise have.
  67        Trusted languages are designed for ordinary database users (those
  68        without superuser privilege) and allows them to safely create
  69        functions and procedures. Since PL functions are executed inside
  70        the database server, the TRUSTED flag should only be given for
  71        languages that do not allow access to database server internals or
  72        the file system. The languages PL/pgSQL, PL/Tcl, and PL/Perl are
  73        considered trusted; the languages PL/TclU, PL/PerlU, and PL/PythonU
  74        are designed to provide unlimited functionality and should not be
  75        marked trusted.
  76
  77    Example 40.1 shows how the manual installation procedure would work
  78    with the language PL/Perl.
  79
  80    Example 40.1. Manual Installation of PL/Perl
  81
  82    The following command tells the database server where to find the
  83    shared object for the PL/Perl language's call handler function:
  84 CREATE FUNCTION plperl_call_handler() RETURNS language_handler AS
  85     '$libdir/plperl' LANGUAGE C;
  86
  87    PL/Perl has an inline handler function and a validator function, so we
  88    declare those too:
  89 CREATE FUNCTION plperl_inline_handler(internal) RETURNS void AS
  90     '$libdir/plperl' LANGUAGE C STRICT;
  91
  92 CREATE FUNCTION plperl_validator(oid) RETURNS void AS
  93     '$libdir/plperl' LANGUAGE C STRICT;
  94
  95    The command:
  96 CREATE TRUSTED LANGUAGE plperl
  97     HANDLER plperl_call_handler
  98     INLINE plperl_inline_handler
  99     VALIDATOR plperl_validator;
 100
 101    then defines that the previously declared functions should be invoked
 102    for functions and procedures where the language attribute is plperl.
 103
 104    In a default PostgreSQL installation, the handler for the PL/pgSQL
 105    language is built and installed into the “library” directory;
 106    furthermore, the PL/pgSQL language itself is installed in all
 107    databases. If Tcl support is configured in, the handlers for PL/Tcl and
 108    PL/TclU are built and installed in the library directory, but the
 109    language itself is not installed in any database by default. Likewise,
 110    the PL/Perl and PL/PerlU handlers are built and installed if Perl
 111    support is configured, and the PL/PythonU handler is installed if
 112    Python support is configured, but these languages are not installed by
 113    default.