begriffs open source - ai-pg/blob - full-docs/txt/sql-createlanguage.txt

   1
   2 CREATE LANGUAGE
   3
   4    CREATE LANGUAGE — define a new procedural language
   5
   6 Synopsis
   7
   8 CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name
   9     HANDLER call_handler [ INLINE inline_handler ] [ VALIDATOR valfunction ]
  10 CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name
  11
  12 Description
  13
  14    CREATE LANGUAGE registers a new procedural language with a PostgreSQL
  15    database. Subsequently, functions and procedures can be defined in this
  16    new language.
  17
  18    CREATE LANGUAGE effectively associates the language name with handler
  19    function(s) that are responsible for executing functions written in the
  20    language. Refer to Chapter 57 for more information about language
  21    handlers.
  22
  23    CREATE OR REPLACE LANGUAGE will either create a new language, or
  24    replace an existing definition. If the language already exists, its
  25    parameters are updated according to the command, but the language's
  26    ownership and permissions settings do not change, and any existing
  27    functions written in the language are assumed to still be valid.
  28
  29    One must have the PostgreSQL superuser privilege to register a new
  30    language or change an existing language's parameters. However, once the
  31    language is created it is valid to assign ownership of it to a
  32    non-superuser, who may then drop it, change its permissions, rename it,
  33    or assign it to a new owner. (Do not, however, assign ownership of the
  34    underlying C functions to a non-superuser; that would create a
  35    privilege escalation path for that user.)
  36
  37    The form of CREATE LANGUAGE that does not supply any handler function
  38    is obsolete. For backwards compatibility with old dump files, it is
  39    interpreted as CREATE EXTENSION. That will work if the language has
  40    been packaged into an extension of the same name, which is the
  41    conventional way to set up procedural languages.
  42
  43 Parameters
  44
  45    TRUSTED
  46           TRUSTED specifies that the language does not grant access to
  47           data that the user would not otherwise have. If this key word is
  48           omitted when registering the language, only users with the
  49           PostgreSQL superuser privilege can use this language to create
  50           new functions.
  51
  52    PROCEDURAL
  53           This is a noise word.
  54
  55    name
  56           The name of the new procedural language. The name must be unique
  57           among the languages in the database.
  58
  59    HANDLER call_handler
  60           call_handler is the name of a previously registered function
  61           that will be called to execute the procedural language's
  62           functions. The call handler for a procedural language must be
  63           written in a compiled language such as C with version 1 call
  64           convention and registered with PostgreSQL as a function taking
  65           no arguments and returning the language_handler type, a
  66           placeholder type that is simply used to identify the function as
  67           a call handler.
  68
  69    INLINE inline_handler
  70           inline_handler is the name of a previously registered function
  71           that will be called to execute an anonymous code block (DO
  72           command) in this language. If no inline_handler function is
  73           specified, the language does not support anonymous code blocks.
  74           The handler function must take one argument of type internal,
  75           which will be the DO command's internal representation, and it
  76           will typically return void. The return value of the handler is
  77           ignored.
  78
  79    VALIDATOR valfunction
  80           valfunction is the name of a previously registered function that
  81           will be called when a new function in the language is created,
  82           to validate the new function. If no validator function is
  83           specified, then a new function will not be checked when it is
  84           created. The validator function must take one argument of type
  85           oid, which will be the OID of the to-be-created function, and
  86           will typically return void.
  87
  88           A validator function would typically inspect the function body
  89           for syntactical correctness, but it can also look at other
  90           properties of the function, for example if the language cannot
  91           handle certain argument types. To signal an error, the validator
  92           function should use the ereport() function. The return value of
  93           the function is ignored.
  94
  95 Notes
  96
  97    Use DROP LANGUAGE to drop procedural languages.
  98
  99    The system catalog pg_language (see Section 52.29) records information
 100    about the currently installed languages. Also, the psql command \dL
 101    lists the installed languages.
 102
 103    To create functions in a procedural language, a user must have the
 104    USAGE privilege for the language. By default, USAGE is granted to
 105    PUBLIC (i.e., everyone) for trusted languages. This can be revoked if
 106    desired.
 107
 108    Procedural languages are local to individual databases. However, a
 109    language can be installed into the template1 database, which will cause
 110    it to be available automatically in all subsequently-created databases.
 111
 112 Examples
 113
 114    A minimal sequence for creating a new procedural language is:
 115 CREATE FUNCTION plsample_call_handler() RETURNS language_handler
 116     AS '$libdir/plsample'
 117     LANGUAGE C;
 118 CREATE LANGUAGE plsample
 119     HANDLER plsample_call_handler;
 120
 121    Typically that would be written in an extension's creation script, and
 122    users would do this to install the extension:
 123 CREATE EXTENSION plsample;
 124
 125 Compatibility
 126
 127    CREATE LANGUAGE is a PostgreSQL extension.
 128
 129 See Also
 130
 131    ALTER LANGUAGE, CREATE FUNCTION, DROP LANGUAGE, GRANT, REVOKE