| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.42 2006/09/16 00:30:17 momjian Exp $ |
| PostgreSQL documentation |
| --> |
| |
| <refentry id="SQL-CREATELANGUAGE"> |
| <refmeta> |
| <refentrytitle id="sql-createlanguage-title">CREATE LANGUAGE</refentrytitle> |
| <refmiscinfo>SQL - Language Statements</refmiscinfo> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>CREATE LANGUAGE</refname> |
| <refpurpose>define a new procedural language</refpurpose> |
| </refnamediv> |
| |
| <indexterm zone="sql-createlanguage"> |
| <primary>CREATE LANGUAGE</primary> |
| </indexterm> |
| |
| <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> |
| </refsynopsisdiv> |
| |
| <refsect1 id="sql-createlanguage-description"> |
| <title>Description</title> |
| |
| <para> |
| Using <command>CREATE LANGUAGE</command>, a |
| <productname>PostgreSQL</productname> user can register a new |
| procedural language with a <productname>PostgreSQL</productname> |
| database. Subsequently, functions and trigger procedures can be |
| defined in this new language. The user must have the |
| <productname>PostgreSQL</productname> superuser privilege to |
| register a new language. |
| </para> |
| |
| <para> |
| <command>CREATE LANGUAGE</command> effectively associates the |
| language name with a call handler that is responsible for executing |
| functions written in the language. Refer to <xref linkend="xplang"> |
| for more information about language call handlers. |
| </para> |
| |
| <para> |
| There are two forms of the <command>CREATE LANGUAGE</command> command. |
| In the first form, the user supplies just the name of the desired |
| language, and the <productname>PostgreSQL</productname> server consults |
| the <link linkend="catalog-pg-pltemplate"><structname>pg_pltemplate</structname></link> |
| system catalog to determine the correct parameters. In the second form, |
| the user supplies the language parameters along with the language name. |
| The second form can be used to create a language that is not defined in |
| <structname>pg_pltemplate</>, but this approach is considered obsolescent. |
| </para> |
| |
| <para> |
| When the server finds an entry in the <structname>pg_pltemplate</> catalog |
| for the given language name, it will use the catalog data even if the |
| 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> |
| |
| <refsect1 id="sql-createlanguage-parameters"> |
| <title>Parameters</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><literal>TRUSTED</literal></term> |
| |
| <listitem> |
| <para> |
| <literal>TRUSTED</literal> 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 key word is omitted when registering the |
| language, only users with the |
| <productname>PostgreSQL</productname> superuser privilege can |
| use this language to create new functions. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>PROCEDURAL</literal></term> |
| |
| <listitem> |
| <para> |
| This is a noise word. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><replaceable class="parameter">name</replaceable></term> |
| |
| <listitem> |
| <para> |
| The name of the new procedural language. The language name is |
| case insensitive. The name must be unique among the languages |
| in the database. |
| </para> |
| |
| <para> |
| For backward compatibility, the name may be enclosed by single |
| quotes. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>HANDLER</literal> <replaceable class="parameter">call_handler</replaceable></term> |
| |
| <listitem> |
| <para> |
| <replaceable class="parameter">call_handler</replaceable> 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 <productname>PostgreSQL</productname> as a |
| function taking no arguments and returning the |
| <type>language_handler</type> type, a placeholder type that is |
| simply used to identify the function as a call handler. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>VALIDATOR</literal> <replaceable class="parameter">valfunction</replaceable></term> |
| |
| <listitem> |
| <para> |
| <replaceable class="parameter">valfunction</replaceable> 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 <type>oid</type>, which will be the OID of the |
| to-be-created function, and will typically return <type>void</>. |
| </para> |
| |
| <para> |
| 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 <function>ereport()</function> |
| function. The return value of the function is ignored. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para> |
| The <literal>TRUSTED</> option and the support function name(s) are |
| ignored if the server has an entry for the specified language |
| name in <structname>pg_pltemplate</>. |
| </para> |
| </refsect1> |
| |
| <refsect1 id="sql-createlanguage-notes"> |
| <title>Notes</title> |
| |
| <para> |
| 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> |
| Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref |
| linkend="app-droplang"> program, to drop procedural languages. |
| </para> |
| |
| <para> |
| 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> |
| 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> |
| Procedural languages are local to individual databases. |
| However, a language can be installed into the <literal>template1</literal> |
| database, which will cause it to be available automatically in |
| all subsequently-created databases. |
| </para> |
| |
| <para> |
| The call handler function and the validator function (if any) |
| must already exist if the server does not have an entry for the language |
| in <structname>pg_pltemplate</>. But when there is an entry, |
| 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 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 <structname>pg_pltemplate</> catalog, a |
| sequence such as this is needed: |
| <programlisting> |
| CREATE FUNCTION plsample_call_handler() RETURNS language_handler |
| AS '$libdir/plsample' |
| LANGUAGE C; |
| CREATE LANGUAGE plsample |
| HANDLER plsample_call_handler; |
| </programlisting> |
| </para> |
| </refsect1> |
| |
| <refsect1 id="sql-createlanguage-compat"> |
| <title>Compatibility</title> |
| |
| <para> |
| <command>CREATE LANGUAGE</command> is a |
| <productname>PostgreSQL</productname> extension. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| |
| <simplelist type="inline"> |
| <member><xref linkend="sql-alterlanguage" endterm="sql-alterlanguage-title"></member> |
| <member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member> |
| <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member> |
| <member><xref linkend="sql-grant" endterm="sql-grant-title"></member> |
| <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member> |
| <member><xref linkend="app-createlang" endterm="app-createlang-title"></member> |
| <member><xref linkend="app-droplang" endterm="app-droplang-title"></member> |
| </simplelist> |
| </refsect1> |
| </refentry> |