Index for Section LANGUAGE

Alphabetical listing for C

Bottom of page

CREATE
NAME
  CREATE LANGUAGE - define a new procedural language

SYNOPSIS
  CREATE [ PROCEDURAL ] LANGUAGE name
  CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name
      HANDLER call_handler [ VALIDATOR valfunction ]

DESCRIPTION
  Using CREATE LANGUAGE, a PostgreSQL user can register a new procedural
  language with a PostgreSQL database. Subsequently, functions and trigger
  procedures can be defined in this new language. The user must have the
  PostgreSQL superuser privilege to register a new language.

  CREATE LANGUAGE effectively associates the language name with a call
  handler that is responsible for executing functions written in the
  language. Refer to the documentation for more information about language
  call handlers.

  There are two forms of the CREATE LANGUAGE command.  In the first form, the
  user supplies just the name of the desired language, and the PostgreSQL
  server consults the pg_pltemplate system catalog to determine the correct
  parameters. In the second form, the user supplies the language parameters
  along with the language name.	 The second form can be used to create a
  language that is not defined in pg_pltemplate, but this approach is
  considered obsolescent.

  When the server finds an entry in the pg_pltemplate catalog for the given
  language name, it will use the catalog data even if the command includes
  language parameters. This behavior simplifies loading of old dump files,
  which are likely to contain out-of-date information about language support
  functions.

PARAMETERS
  TRUSTED
       TRUSTED specifies that the call handler for the language is safe, that
       is, it does not offer an unprivileged user any functionality to bypass
       access restrictions. If this key word is omitted when registering the
       language, only users with the PostgreSQL superuser privilege can use
       this language to create new functions.

  PROCEDURAL
       This is a noise word.

  name The name of the new procedural language. The language name is case
       insensitive. The name must be unique among the languages in the
       database.

       For backward compatibility, the name may be enclosed by single quotes.

  HANDLER call_handler
       call_handler is the name of a previously registered function that will
       be called to execute the procedural language functions. The call
       handler for a procedural language must be written in a compiled
       language such as C with version 1 call convention and registered with
       PostgreSQL as a function taking no arguments and returning the
       language_handler type, a placeholder type that is simply used to
       identify the function as a call handler.

  VALIDATOR valfunction
       valfunction is the name of a previously registered function that will
       be called when a new function in the language is created, to validate
       the new function.  If no validator function is specified, then a new
       function will not be checked when it is created.	 The validator
       function must take one argument of type oid, which will be the OID of
       the to-be-created function, and will typically return void.

       A validator function would typically inspect the function body for
       syntactical correctness, but it can also look at other properties of
       the function, for example if the language cannot handle certain
       argument types. To signal an error, the validator function should use
       the ereport() function. The return value of the function is ignored.

  The TRUSTED option and the support function name(s) are ignored if the
  server has an entry for the specified language name in pg_pltemplate.

NOTES
  The createlang(1) program is a simple wrapper around the CREATE LANGUAGE
  command. It eases installation of procedural languages from the shell
  command line.

  Use DROP LANGUAGE [drop_language(5)], or better yet the droplang(1)
  program, to drop procedural languages.

  The system catalog pg_language (see the documentation) records information
  about the currently installed languages. Also, createlang has an option to
  list the installed languages.

  To create functions in a procedural language, a user must have the USAGE
  privilege for the language. By default, USAGE is granted to PUBLIC (i.e.,
  everyone) for trusted languages. This may be revoked if desired.

  Procedural languages are local to individual databases.  However, a
  language can be installed into the template1 database, which will cause it
  to be available automatically in all subsequently-created databases.

  The call handler function and the validator function (if any) must already
  exist if the server does not have an entry for the language in
  pg_pltemplate. But when there is an entry, the functions need not already
  exist; they will be automatically defined if not present in the database.
  (This can result in CREATE LANGUAGE failing, if the shared library that
  implements the language is not available in the installation.)

  In PostgreSQL versions before 7.3, it was necessary to declare handler
  functions as returning the placeholder type opaque, rather than
  language_handler.  To support loading of old dump files, CREATE LANGUAGE
  will accept a function declared as returning opaque, but it will issue a
  notice and change the function's declared return type to language_handler.

EXAMPLES
  The preferred way of creating any of the standard procedural languages is
  just:

  CREATE LANGUAGE plpgsql;

  For a language not known in the pg_pltemplate catalog, a sequence such as
  this is needed:

  CREATE FUNCTION plsample_call_handler() RETURNS language_handler
      AS '$libdir/plsample'
      LANGUAGE C;
  CREATE LANGUAGE plsample
      HANDLER plsample_call_handler;

COMPATIBILITY
  CREATE LANGUAGE is a PostgreSQL extension.

SEE ALSO
  ALTER LANGUAGE [alter_language(5)], CREATE FUNCTION [create_function(l)],
  DROP LANGUAGE [drop_language(l)], GRANT [grant(l)], REVOKE [revoke(l)],
  createlang [createlang(1)], droplang [droplang(1)]

Index for Section LANGUAGE

Alphabetical listing for C

Top of page