<!--

$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.39 2005/01/04 00:39:53 tgl Exp $

$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.40 2005/09/05 23:50:48 tgl Exp $

PostgreSQL documentation

-->

<refsynopsisdiv>

<synopsis>

CREATE [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>

CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>

HANDLER <replaceable class="parameter">call_handler</replaceable> [ VALIDATOR <replaceable>valfunction</replaceable> ]

</synopsis>

</para>

<para>

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 <literal>template1</literal> database.

There are two forms of the <command>CREATE LANGUAGE</command> command.

In the first form, the user merely supplies the name of the desired

language, and the <productname>PostgreSQL</productname> server consults

an internal table to determine the correct parameters. In

the second form, the user supplies the language parameters along with

the language name. The second form must be used to create a language

that is not present in the internal table, but this form is considered

obsolescent. (It is expected that future releases of

<productname>PostgreSQL</productname> will replace the internal table

with a system catalog that can be extended to support additional

languages.)

</para>

<para>

When the server finds an entry in its internal table for the given

language name, it will use the table data even if the given 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.

</para>

</refsect1>

</listitem>

</varlistentry>

</variablelist>

<para>

The <literal>TRUSTED</> option and the support function name(s) are

ignored if the server has information about the specified language

name in its internal table.

</para>

</refsect1>

<refsect1 id="sql-createlanguage-notes">

<title>Notes</title>

<para>

This command normally should not be executed directly by users.

For the procedural languages supplied in the

<productname>PostgreSQL</productname> distribution, the <xref

linkend="app-createlang"> program should be used, which will also

install the correct call handler. (<command>createlang</command>

will call <command>CREATE LANGUAGE</command> internally.)

The <xref linkend="app-createlang"> program is a simple wrapper around

the <command>CREATE LANGUAGE</> command. It eases

installation of procedural languages from the shell command line.

</para>

<para>

In <productname>PostgreSQL</productname> versions before 7.3, it was

necessary to declare handler functions as returning the placeholder

type <type>opaque</>, rather than <type>language_handler</>.

To support loading

of old dump files, <command>CREATE LANGUAGE</> will accept a function

declared as returning <type>opaque</>, but it will issue a notice and

change the function's declared return type to <type>language_handler</>.

Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref

linkend="app-droplang"> program, to drop procedural languages.

</para>

<para>

Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new

function.

The system catalog <classname>pg_language</classname> (see <xref

linkend="catalog-pg-language">) records information about the

currently installed languages. Also, <command>createlang</command>

has an option to list the installed languages.

</para>

<para>

Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref

linkend="app-droplang"> program, to drop procedural languages.

To create functions in a procedural language, a user must have the

<literal>USAGE</literal> privilege for the language. By default,

<literal>USAGE</> is granted to <literal>PUBLIC</> (i.e., everyone)

for trusted languages. This may be revoked if desired.

</para>

<para>

linkend="catalog-pg-language">) records information aboutthe

has an option to list the installed languages.

However, alanguage can be installed intothe <literal>template1</literal>

all subsequently-created databases.

</para>

<para>

To be able to use a procedural language, a user must be granted the

<literal>USAGE</literal> privilege. The

<command>createlang</command> program automatically grants

permissions to everyone if the language is known to be trusted.

The call handler function and the validator function (if any)

must already exist if the server does not have information about

the language in its internal table. But when there is an entry

in the internal table, the functions need not already exist;

they will be automatically defined if not present in the database.

(This can result in <command>CREATE LANGUAGE</> failing, if the

shared library that implements the language is not available in

the installation.)

</para>

<para>

In <productname>PostgreSQL</productname> versions before 7.3, it was

necessary to declare handler functions as returning the placeholder

type <type>opaque</>, rather than <type>language_handler</>.

To support loading

of old dump files, <command>CREATE LANGUAGE</> will accept a function

declared as returning <type>opaque</>, but it will issue a notice and

change the function's declared return type to <type>language_handler</>.

</para>

</refsect1>

<refsect1 id="sql-createlanguage-examples">

<title>Examples</title>

<para>

The following two commands executed in sequence will register a new

procedural language and the associated call handler.

The preferred way of creating any of the standard procedural languages

is just:

<programlisting>

CREATE LANGUAGE plpgsql;

</programlisting>

</para>

<para>

For a language not known in the server's internal table, a sequence

such as this is needed:

<programlisting>

CREATE FUNCTION plsample_call_handler() RETURNS language_handler

AS '$libdir/plsample'

<!--

$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.35 2005/06/21 04:02:31 tgl Exp $

$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.36 2005/09/05 23:50:48 tgl Exp $

PostgreSQL documentation

-->

programming language to a <productname>PostgreSQL</productname> database.

<application>createlang</application> can handle all the languages

supplied in the default <productname>PostgreSQL</> distribution, but

not languages provided by other parties.

</para>

<para>

Although backend programming languages can be added directly using

several <acronym>SQL</acronym> commands, it is recommended to use

<application>createlang</application> because it performs a number

of checks and is much easier to use. See

not languages provided by other parties. See

<xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">

for additional information.

</para>

<term><replaceable class="parameter">langname</replaceable></term>

<listitem>

<para>

Specifies the name of the procedural programming language to be

defined.

Specifies the name of the procedural programming language to be

defined.

</para>

</listitem>

</varlistentry>

<term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></></term>

<listitem>

<para>

Specifies to which database the language should be added.

Specifies to which database the language should be added.

The default is to use the database with the same name as the

current system user.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-L <replaceable class="parameter">directory</replaceable></></term>

<listitem>

<para>

Specifies the directory in which the language interpreter is

to be found. The directory is normally found automatically; this

option is primarily for debugging purposes.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<term><option>--host <replaceable class="parameter">host</replaceable></></term>

<listitem>

<para>

Specifies the host name of the machine on which the

server

is running. If the value begins with a slash, it is used

as the directory for the Unix domain socket.

Specifies the host name of the machine on which the

server

is running. If the value begins with a slash, it is used

as the directory for the Unix domain socket.

</para>

</listitem>

</varlistentry>

<term><option>--port <replaceable class="parameter">port</replaceable></></term>

<listitem>

<para>

Specifies the TCP port or local Unix domain socket file

extension on which the server

is listening for connections.

Specifies the TCP port or local Unix domain socket file

extension on which the server

is listening for connections.

</para>

</listitem>

</varlistentry>

<!--

$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.28 2004/12/30 21:45:37 tgl Exp $

$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.29 2005/09/05 23:50:48 tgl Exp $

-->

<chapter id="xplang">

</para>

<para>

For the languages supplied with the standard distribution, the

program <xref linkend="app-createlang"> may be used to install the

language instead of carrying out the details by hand. For

example, to install the language

For the languages supplied with the standard distribution, it is

only necessary to execute <command>CREATE LANGUAGE</>

<replaceable>language_name</> to install the language into the

current database. Alternatively, the program <xref

linkend="app-createlang"> may be used to do this from the shell

command line. For example, to install the language

<application>PL/pgSQL</application> into the database

<literal>template1</>, use

<programlisting>

createlang plpgsql template1

</programlisting>

The manual procedure described below is only recommended for

installing custom languages that <command>createlang</command>

installing custom languages that <command>CREATE LANGUAGE</command>

does not know about.

</para>

<para>

A procedural language is installed in a database in four steps,

which must be carried out by a database superuser. The

<command>createlang</command> program automates all but <xref

linkend="xplang-install-cr1">.

which must be carried out by a database superuser. (For languages

known to <command>CREATE LANGUAGE</>, the second and third steps

can be omitted, because they will be carried out automatically

if needed.)

</para>

<step performance="required" id="xplang-install-cr1">

In a default <productname>PostgreSQL</productname> installation,

the handler for the <application>PL/pgSQL</application> language

is built and installed into the <quote>library</quote>

directory. If <application>Tcl</> support is configured in, the handlers for

<application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same

location. Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built

and installed if Perl support is configured, and <application>PL/PythonU</> is

directory. If <application>Tcl</> support is configured in, the handlers

for <application>PL/Tcl</> and <application>PL/TclU</> are also built and

installed in the same location. Likewise, the <application>PL/Perl</> and

<application>PL/PerlU</> handlers are built and installed if Perl support

is configured, and the <application>PL/PythonU</> handler is

installed if Python support is configured.

</para>