Index for Section LANGUAGE

Alphabetical listing for C

Bottom of page

CREATE
NAME
  CREATE LANGUAGE - define a new procedural language

SYNOPSIS
  CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE langname
      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 Programmer's Guide for more information about
  language call handlers.

  Note that procedural languages are local to individual databases.  To make
  a language available in all databases by default, it should be installed
  into the template1 database.

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 keyword 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.

  langname
       The name of the new procedural language. The language name is case
       insensitive. A procedural language cannot override one of the built-in
       languages of PostgreSQL.

       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 elog() function. The return value of the function is ignored.

DIAGNOSTICS
  CREATE LANGUAGE

  This message is returned if the language is successfully created.

  ERROR:  PL handler function funcname() doesn't exist

  This error is returned if the function funcname() is not found.

NOTES
  This command normally should not be executed directly by users.  For the
  procedural languages supplied in the PostgreSQL distribution, the
  createlang(1) script should be used, which will also install the correct
  call handler. (createlang will call CREATE LANGUAGE internally.)

  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.

  Use the CREATE FUNCTION [create_function(5)] command to create a new
  function.

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

  The system catalog pg_language records information about the currently
  installed procedural languages.

	  Table "pg_language"
     Attribute	 |   Type    | Modifier
  ---------------+-----------+----------
   lanname	 | name	     |
   lanispl	 | boolean   |
   lanpltrusted	 | boolean   |
   lanplcallfoid | oid	     |
   lanvalidator	 | oid	     |
   lanacl	 | aclitem[] |

     lanname   | lanispl | lanpltrusted | lanplcallfoid | lanvalidator | lanacl
  -------------+---------+--------------+---------------+--------------+--------
   internal    | f	 | f		|	      0 |	  2246 |
   c	       | f	 | f		|	      0 |	  2247 |
   sql	       | f	 | t		|	      0 |	  2248 | {=U}

  At present, with the exception of the permissions, the definition of a
  procedural language cannot be changed once it has been created.

  To be able to use a procedural language, a user must be granted the USAGE
  privilege. The createlang program automatically grants permissions to
  everyone if the language is known to be trusted.

EXAMPLES
  The following two commands executed in sequence will register a new
  procedural language and the associated call handler.

  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.

HISTORY
  The CREATE LANGUAGE command first appeared in PostgreSQL 6.3.

SEE ALSO
  createlang(1), CREATE FUNCTION [create_function(5)], droplang(1), DROP
  LANGUAGE [drop_language(l)], GRANT [grant(l)], REVOKE [revoke(l)],
  PostgreSQL Programmer's Guide

Index for Section LANGUAGE

Alphabetical listing for C

Top of page