diff options
Diffstat (limited to 'doc/src/sgml/html/sql-createlanguage.html')
| -rw-r--r-- | doc/src/sgml/html/sql-createlanguage.html | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/doc/src/sgml/html/sql-createlanguage.html b/doc/src/sgml/html/sql-createlanguage.html new file mode 100644 index 0000000..239a426 --- /dev/null +++ b/doc/src/sgml/html/sql-createlanguage.html @@ -0,0 +1,123 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE LANGUAGE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="sql-createindex.html" title="CREATE INDEX" /><link rel="next" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE LANGUAGE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createindex.html" title="CREATE INDEX">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW">Next</a></td></tr></table><hr></hr></div><div class="refentry" id="SQL-CREATELANGUAGE"><div class="titlepage"></div><a id="id-1.9.3.70.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE LANGUAGE</span></h2><p>CREATE LANGUAGE — define a new procedural language</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>name</code></em> + HANDLER <em class="replaceable"><code>call_handler</code></em> [ INLINE <em class="replaceable"><code>inline_handler</code></em> ] [ VALIDATOR <em class="replaceable"><code>valfunction</code></em> ] +CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <em class="replaceable"><code>name</code></em> +</pre></div><div class="refsect1" id="SQL-CREATELANGUAGE-DESCRIPTION"><h2>Description</h2><p> + <code class="command">CREATE LANGUAGE</code> registers a new + procedural language with a <span class="productname">PostgreSQL</span> + database. Subsequently, functions and procedures can be + defined in this new language. + </p><p> + <code class="command">CREATE LANGUAGE</code> effectively associates the + language name with handler function(s) that are responsible for executing + functions written in the language. Refer to <a class="xref" href="plhandler.html" title="Chapter 55. Writing a Procedural Language Handler">Chapter 55</a> + for more information about language handlers. + </p><p> + <code class="command">CREATE OR REPLACE LANGUAGE</code> will either create a + new language, or replace an existing definition. If the language + already exists, its parameters are updated according to the command, + but the language's ownership and permissions settings do not change, + and any existing functions written in the language are assumed to still + be valid. + </p><p> + One must have the + <span class="productname">PostgreSQL</span> superuser privilege to + register a new language or change an existing language's parameters. + However, once the language is created it is valid to assign ownership of + it to a non-superuser, who may then drop it, change its permissions, + rename it, or assign it to a new owner. (Do not, however, assign + ownership of the underlying C functions to a non-superuser; that would + create a privilege escalation path for that user.) + </p><p> + The form of <code class="command">CREATE LANGUAGE</code> that does not supply + any handler function is obsolete. For backwards compatibility with + old dump files, it is interpreted as <code class="command">CREATE EXTENSION</code>. + That will work if the language has been packaged into an extension of + the same name, which is the conventional way to set up procedural + languages. + </p></div><div class="refsect1" id="SQL-CREATELANGUAGE-PARAMETERS"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">TRUSTED</code></span></dt><dd><p><code class="literal">TRUSTED</code> specifies that the language does + not grant access to data that the user would not otherwise + have. If this key word is omitted + when registering the language, only users with the + <span class="productname">PostgreSQL</span> superuser privilege can + use this language to create new functions. + </p></dd><dt><span class="term"><code class="literal">PROCEDURAL</code></span></dt><dd><p> + This is a noise word. + </p></dd><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p> + The name of the new procedural language. + The name must be unique among the languages in the database. + </p><p> + For backward compatibility, the name can be enclosed by single + quotes. + </p></dd><dt><span class="term"><code class="literal">HANDLER</code> <em class="replaceable"><code>call_handler</code></em></span></dt><dd><p><em class="replaceable"><code>call_handler</code></em> is + the name of a previously registered function that will be + called to execute the procedural language's 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 <span class="productname">PostgreSQL</span> as a + function taking no arguments and returning the + <code class="type">language_handler</code> type, a placeholder type that is + simply used to identify the function as a call handler. + </p></dd><dt><span class="term"><code class="literal">INLINE</code> <em class="replaceable"><code>inline_handler</code></em></span></dt><dd><p><em class="replaceable"><code>inline_handler</code></em> is the + name of a previously registered function that will be called + to execute an anonymous code block + (<a class="xref" href="sql-do.html" title="DO"><span class="refentrytitle">DO</span></a> command) + in this language. + If no <em class="replaceable"><code>inline_handler</code></em> + function is specified, the language does not support anonymous code + blocks. + The handler function must take one argument of + type <code class="type">internal</code>, which will be the <code class="command">DO</code> command's + internal representation, and it will typically return + <code class="type">void</code>. The return value of the handler is ignored. + </p></dd><dt><span class="term"><code class="literal">VALIDATOR</code> <em class="replaceable"><code>valfunction</code></em></span></dt><dd><p><em class="replaceable"><code>valfunction</code></em> 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 <code class="type">oid</code>, which will be the OID of the + to-be-created function, and will typically return <code class="type">void</code>. + </p><p> + 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 <code class="function">ereport()</code> + function. The return value of the function is ignored. + </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATELANGUAGE-NOTES"><h2>Notes</h2><p> + Use <a class="xref" href="sql-droplanguage.html" title="DROP LANGUAGE"><span class="refentrytitle">DROP LANGUAGE</span></a> to drop procedural languages. + </p><p> + The system catalog <code class="classname">pg_language</code> (see <a class="xref" href="catalog-pg-language.html" title="51.29. pg_language">Section 51.29</a>) records information about the + currently installed languages. Also, the <span class="application">psql</span> + command <code class="command">\dL</code> lists the installed languages. + </p><p> + To create functions in a procedural language, a user must have the + <code class="literal">USAGE</code> privilege for the language. By default, + <code class="literal">USAGE</code> is granted to <code class="literal">PUBLIC</code> (i.e., everyone) + for trusted languages. This can be revoked if desired. + </p><p> + Procedural languages are local to individual databases. + However, a language can be installed into the <code class="literal">template1</code> + database, which will cause it to be available automatically in + all subsequently-created databases. + </p></div><div class="refsect1" id="SQL-CREATELANGUAGE-EXAMPLES"><h2>Examples</h2><p> + A minimal sequence for creating a new procedural language is: +</p><pre class="programlisting"> +CREATE FUNCTION plsample_call_handler() RETURNS language_handler + AS '$libdir/plsample' + LANGUAGE C; +CREATE LANGUAGE plsample + HANDLER plsample_call_handler; +</pre><p> + Typically that would be written in an extension's creation script, + and users would do this to install the extension: +</p><pre class="programlisting"> +CREATE EXTENSION plsample; +</pre></div><div class="refsect1" id="SQL-CREATELANGUAGE-COMPAT"><h2>Compatibility</h2><p> + <code class="command">CREATE LANGUAGE</code> is a + <span class="productname">PostgreSQL</span> extension. + </p></div><div class="refsect1" id="id-1.9.3.70.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterlanguage.html" title="ALTER LANGUAGE"><span class="refentrytitle">ALTER LANGUAGE</span></a>, <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>, <a class="xref" href="sql-droplanguage.html" title="DROP LANGUAGE"><span class="refentrytitle">DROP LANGUAGE</span></a>, <a class="xref" href="sql-grant.html" title="GRANT"><span class="refentrytitle">GRANT</span></a>, <a class="xref" href="sql-revoke.html" title="REVOKE"><span class="refentrytitle">REVOKE</span></a></span></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createindex.html" title="CREATE INDEX">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-creatematerializedview.html" title="CREATE MATERIALIZED VIEW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE INDEX </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE MATERIALIZED VIEW</td></tr></table></div></body></html>
\ No newline at end of file |