CREATE LANGUAGE

CREATE LANGUAGE — Define a new procedural language

Synopsis

CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name

HANDLER call_handler [ INLINE inline_handler ] [ VALIDATOR valfunction ]

CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name

Description

CREATE LANGUAGE registers a new procedural language with the system. Subsequently, functions and stored procedures can be defined in this new language.

CREATE LANGUAGE essentially associates the language name with a handler function that is responsible for executing functions written in that language.

CREATE OR REPLACE LANGUAGE will create or replace an existing definition. If the language already exists, its parameters will be updated according to the command. However, the ownership and permission settings of the language will not be changed, and any existing functions written in the language are still assumed to be valid.

Superuser privileges are required to register a new language or change the parameters of an existing language. However, once a language is created, it is valid to assign its ownership to a non-superuser, who can then drop it, change its permissions, rename it, or assign it to a new owner. (However, do not assign ownership of the underlying C function to a non-superuser; this creates a privilege escalation path for that user.) The form of CREATE LANGUAGE that does not provide a handler function is obsolete. For backward compatibility with old dump files, it is interpreted as CREATE EXTENSION. This will work if the language is packaged as an extension with the same name, which is the traditional way to set up procedural languages.

Parameters

TRUSTED

TRUSTED specifies that the language does not grant users access to data they should not have. If this keyword is omitted when registering the language, only users with superuser privileges can use the language to create new functions.

PROCEDURAL

This is a noise word.

name

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

For backward compatibility, the name can be surrounded 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's functions. A procedural language's call handler must be written in a compiled language (such as C) and must use the version-1 calling convention. It must be registered in the system as a function that takes no arguments and returns the type language_handler. The language_handler type is a placeholder type used to identify the function as a call handler.

INLINE inline_handler

inline_handler is the name of a previously registered function that will be called to execute an anonymous code block (DO command) in the language. If no inline_handler function is specified, the language does not support anonymous code blocks.

The handler function must accept a single argument of type internal, which will be the internal representation of the DO command, and it typically returns void. The return value of the handler is ignored.

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, a new function will not be checked when created. The validator function must accept a single argument of type oid, which will be the OID of the function being created, and it typically returns void.

A validator function typically checks the syntactic correctness of the function body, but it can also examine other properties of the function, such as whether the language can handle specific parameter types. To report an error, the validator function should use the ereport() function. The return value of the validator function is ignored.

Notes

Use DROP LANGUAGE to drop a procedural language.

To create a function in a procedural language, the user must have USAGE privilege on the language. By default, USAGE is granted to PUBLIC (i.e., everyone) for trusted languages. This can be revoked if needed. Procedural languages are local to individual databases. However, a language can be installed in the template1 database, which will cause it to be automatically available in all subsequently created databases.

Examples

The minimal sequence to create a new procedural language is:

CREATE FUNCTION plsample_call_handler() RETURNS language_handler

AS '$libdir/plsample'

LANGUAGE C;

CREATE LANGUAGE plsample

HANDLER plsample_call_handler;

Typically this would be written in an extension's creation script, and users would do this to install the extension:

CREATE EXTENSION plsample;

See Also

ALTER LANGUAGE, CREATE FUNCTION, DROP LANGUAGE, GRANT, REVOKE