CREATE LANGUAGSQL)- Language Statements (2002-1CREATE LANGUAGE(l)
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
Page 1 (printed 3/24/03)
CREATE LANGUAGSQL)- Language Statements (2002-1CREATE LANGUAGE(l)
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(l)] command to
create a new function.
Page 2 (printed 3/24/03)
CREATE LANGUAGSQL)- Language Statements (2002-1CREATE LANGUAGE(l)
Use DROP LANGUAGE [drop_language(l)], 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
Page 3 (printed 3/24/03)
CREATE LANGUAGSQL)- Language Statements (2002-1CREATE LANGUAGE(l)createlang(1), CREATE FUNCTION [create_function(l)],
droplang(1), DROP LANGUAGE [drop_language(l)], GRANT
[grant(l)], REVOKE [revoke(l)], PostgreSQL Programmer's
Guide
Page 4 (printed 3/24/03)
