CREATE LANGUAGE
SQL - Language Statements
CREATE LANGUAGE
Defines a new language for functions
1998-04-15
CREATE [TRUSTED] PROCEDURAL LANGUAGE 'langname'
HANDLER call_handler
LANCOMPILER 'comment'
1998-04-15
Inputs
TRUSTED
TRUSTED specifies that the call handler for
the language is safe; that is, it offers an unprivileged user
no functionality to get around 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
(like the 'C' language).
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.
call_handler
The argument for HANDLER is the name
of a previously
registered function that will be called to execute the PL
procedures.
comment
The LANCOMPILER argument is the
string that will be
inserted in the LANCOMPILER attribute
of the new
pg_language entry. At present,
PostgreSQL doesn't use
this attribute in any way.
1998-04-15
Outputs
CREATE
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.
1998-04-15
Description
Using CREATE LANGUAGE, a PostgreSQL user can register
a new language with PostgreSQL. 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.
1998-04-15
Writing PL handlers
The call handler for a procedural language must be written
in a compiler language such as 'C' and registered with
PostgreSQL as a function taking no arguments and returning
opaque type.
What does `opaque type' mean?
This prevents the call handler from being
called directly as a function from queries.
However, arguments must be supplied on the actual call when a
PL function or trigger
procedure in the language offered by the handler is to be
executed.
When called from the trigger manager, the only argument is
the object ID from the procedure's pg_proc
entry. All other
information from the trigger manager is found in the
global CurrentTriggerData pointer.
When called from the function manager, the arguments are
the object ID of the procedure's pg_proc
entry, the number
of arguments given to the PL function, the arguments in a
FmgrValues structure and a pointer
to a boolean where the
function tells the caller if the return value is the SQL
NULL value.
It's up to the call handler to fetch the
pg_proc entry and
to analyze the argument and return types of the called
procedure. The AS clause from the
CREATE FUNCTION of
the procedure will be found in the prosrc
attribute of the
pg_proc entry. This may be the
source text in the procedural
language itself (like for PL/Tcl), a pathname to a
file or anything else that tells the call handler what to
do in detail.
1998-04-15
Notes
Use
CREATE FUNCTION
to create a function.
Use
DROP LANGUAGE
to drop procedural languages.
Refer to the table pg_language
for further information:
Table = pg_language
+--------------------------+--------------------------+-------+
| Field | Type | Length|
+--------------------------+--------------------------+-------+
| lanname | name | 32 |
| lancompiler | text | var |
+--------------------------+--------------------------+-------+
lanname |lancompiler
--------+--------------
internal|n/a
lisp |/usr/ucb/liszt
C |/bin/cc
sql |postgres
Restrictions
Since the call handler for a procedural language must be
registered with PostgreSQL in the 'C' language, it inherits
all the restrictions of 'C' functions.
What are these restrictions?
Bugs
At present, the definitions for a procedural language cannot be
changed once they have been created.
Usage
This is a template for a PL handler written in 'C':
#include "executor/spi.h"
#include "commands/trigger.h"
#include "utils/elog.h"
#include "fmgr.h" /* for FmgrValues struct */
#include "access/heapam.h"
#include "utils/syscache.h"
#include "catalog/pg_proc.h"
#include "catalog/pg_type.h"
Datum
plsample_call_handler(
Oid prooid,
int pronargs,
FmgrValues *proargs,
bool *isNull)
{
Datum retval;
TriggerData *trigdata;
if (CurrentTriggerData == NULL) {
/*
* Called as a function
*/
retval = ...
} else {
/*
* Called as a trigger procedure
*/
trigdata = CurrentTriggerData;
CurrentTriggerData = NULL;
retval = ...
}
*isNull = false;
return retval;
}
Only a few thousand lines of code have to be added instead
of the dots to complete the PL call handler. See
CREATE FUNCTION
for information on how to compile
it into a loadable module
.
The following commands then register the sample procedural
language.
CREATE FUNCTION plsample_call_handler () RETURNS opaque
AS '/usr/local/pgsql/lib/plsample.so'
LANGUAGE 'C';
CREATE PROCEDURAL LANGUAGE 'plsample'
HANDLER plsample_call_handler
LANCOMPILER 'PL/Sample';
Compatibility
CREATE LANGUAGE is a PostgreSQL extension.
1998-04-15
SQL92
There is no CREATE LANGUAGE statement in SQL92.