← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/create_language.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/create_language.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.39 2005-01-04 00:39:53 tgl Exp $
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="SQL-CREATELANGUAGE">
 
7
 <refmeta>
 
8
  <refentrytitle id="sql-createlanguage-title">CREATE LANGUAGE</refentrytitle>
 
9
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
10
 </refmeta>
 
11
 
 
12
 <refnamediv>
 
13
  <refname>CREATE LANGUAGE</refname>
 
14
  <refpurpose>define a new procedural language</refpurpose>
 
15
 </refnamediv>
 
16
 
 
17
 <indexterm zone="sql-createlanguage">
 
18
  <primary>CREATE LANGUAGE</primary>
 
19
 </indexterm>
 
20
 
 
21
 <refsynopsisdiv>
 
22
<synopsis>
 
23
CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
 
24
    HANDLER <replaceable class="parameter">call_handler</replaceable> [ VALIDATOR <replaceable>valfunction</replaceable> ]
 
25
</synopsis>
 
26
 </refsynopsisdiv>
 
27
 
 
28
 <refsect1 id="sql-createlanguage-description">
 
29
  <title>Description</title>
 
30
 
 
31
  <para>
 
32
   Using <command>CREATE LANGUAGE</command>, a
 
33
   <productname>PostgreSQL</productname> user can register a new
 
34
   procedural language with a <productname>PostgreSQL</productname>
 
35
   database.  Subsequently, functions and trigger procedures can be
 
36
   defined in this new language.  The user must have the
 
37
   <productname>PostgreSQL</productname> superuser privilege to
 
38
   register a new language.
 
39
  </para>
 
40
 
 
41
  <para>
 
42
   <command>CREATE LANGUAGE</command> effectively associates the
 
43
   language name with a call handler that is responsible for executing
 
44
   functions written in the language.  Refer to <xref linkend="xplang">
 
45
   for more information about language call handlers.
 
46
  </para>
 
47
 
 
48
  <para>
 
49
   Note that procedural languages are local to individual databases.
 
50
   To make a language available in all databases by default, it should
 
51
   be installed into the <literal>template1</literal> database.
 
52
  </para>
 
53
 </refsect1>
 
54
 
 
55
 <refsect1 id="sql-createlanguage-parameters">
 
56
  <title>Parameters</title>
 
57
 
 
58
   <variablelist>
 
59
    <varlistentry>
 
60
     <term><literal>TRUSTED</literal></term>
 
61
 
 
62
     <listitem>
 
63
      <para>
 
64
       <literal>TRUSTED</literal> specifies that the call handler for
 
65
       the language is safe, that is, it does not offer an
 
66
       unprivileged user any functionality to bypass access
 
67
       restrictions. If this key word is omitted when registering the
 
68
       language, only users with the
 
69
       <productname>PostgreSQL</productname> superuser privilege can
 
70
       use this language to create new functions.
 
71
      </para>
 
72
     </listitem>
 
73
    </varlistentry>
 
74
 
 
75
    <varlistentry>
 
76
     <term><literal>PROCEDURAL</literal></term>
 
77
 
 
78
     <listitem>
 
79
      <para>
 
80
       This is a noise word.
 
81
      </para>
 
82
     </listitem>
 
83
    </varlistentry>
 
84
 
 
85
    <varlistentry>
 
86
     <term><replaceable class="parameter">name</replaceable></term>
 
87
 
 
88
     <listitem>
 
89
      <para>
 
90
       The name of the new procedural language.  The language name is
 
91
       case insensitive. The name must be unique among the languages
 
92
       in the database.
 
93
      </para>
 
94
 
 
95
      <para>
 
96
       For backward compatibility, the name may be enclosed by single
 
97
       quotes.
 
98
      </para>
 
99
     </listitem>
 
100
    </varlistentry>
 
101
 
 
102
    <varlistentry>
 
103
     <term><literal>HANDLER</literal> <replaceable class="parameter">call_handler</replaceable></term>
 
104
 
 
105
     <listitem>
 
106
      <para>
 
107
       <replaceable class="parameter">call_handler</replaceable> is
 
108
       the name of a previously registered function that will be
 
109
       called to execute the procedural language functions.  The call
 
110
       handler for a procedural language must be written in a compiled
 
111
       language such as C with version 1 call convention and
 
112
       registered with <productname>PostgreSQL</productname> as a
 
113
       function taking no arguments and returning the
 
114
       <type>language_handler</type> type, a placeholder type that is
 
115
       simply used to identify the function as a call handler.
 
116
      </para>
 
117
     </listitem>
 
118
    </varlistentry>
 
119
 
 
120
    <varlistentry>
 
121
     <term><literal>VALIDATOR</literal> <replaceable class="parameter">valfunction</replaceable></term>
 
122
 
 
123
     <listitem>
 
124
      <para>
 
125
       <replaceable class="parameter">valfunction</replaceable> is the
 
126
       name of a previously registered function that will be called
 
127
       when a new function in the language is created, to validate the
 
128
       new function.
 
129
       If no
 
130
       validator function is specified, then a new function will not
 
131
       be checked when it is created.
 
132
       The validator function must take one argument of
 
133
       type <type>oid</type>, which will be the OID of the
 
134
       to-be-created function, and will typically return <type>void</>.
 
135
      </para>
 
136
 
 
137
      <para>
 
138
       A validator function would typically inspect the function body
 
139
       for syntactical correctness, but it can also look at other
 
140
       properties of the function, for example if the language cannot
 
141
       handle certain argument types.  To signal an error, the
 
142
       validator function should use the <function>ereport()</function>
 
143
       function.  The return value of the function is ignored.
 
144
      </para>
 
145
     </listitem>
 
146
    </varlistentry>
 
147
   </variablelist>
 
148
 </refsect1>
 
149
 
 
150
 <refsect1 id="sql-createlanguage-notes">
 
151
  <title>Notes</title>
 
152
 
 
153
  <para>
 
154
   This command normally should not be executed directly by users.
 
155
   For the procedural languages supplied in the
 
156
   <productname>PostgreSQL</productname> distribution, the <xref
 
157
   linkend="app-createlang"> program should be used, which will also
 
158
   install the correct call handler.  (<command>createlang</command>
 
159
   will call <command>CREATE LANGUAGE</command> internally.)
 
160
  </para>
 
161
 
 
162
  <para>
 
163
   In <productname>PostgreSQL</productname> versions before 7.3, it was
 
164
   necessary to declare handler functions as returning the placeholder
 
165
   type <type>opaque</>, rather than <type>language_handler</>.
 
166
   To support loading 
 
167
   of old dump files, <command>CREATE LANGUAGE</> will accept a function
 
168
   declared as returning <type>opaque</>, but it will issue a notice and
 
169
   change the function's declared return type to <type>language_handler</>.
 
170
  </para>
 
171
 
 
172
  <para>
 
173
   Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new
 
174
   function.
 
175
  </para>
 
176
 
 
177
  <para>
 
178
   Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
 
179
   linkend="app-droplang"> program, to drop procedural languages.
 
180
  </para>
 
181
 
 
182
  <para>
 
183
   The system catalog <classname>pg_language</classname> (see <xref
 
184
   linkend="catalog-pg-language">) records information about the
 
185
   currently installed languages.  Also <command>createlang</command>
 
186
   has an option to list the installed languages.
 
187
  </para>
 
188
 
 
189
  <para>
 
190
   To be able to use a procedural language, a user must be granted the
 
191
   <literal>USAGE</literal> privilege.  The
 
192
   <command>createlang</command> program automatically grants
 
193
   permissions to everyone if the language is known to be trusted.
 
194
  </para>
 
195
 </refsect1>
 
196
 
 
197
 <refsect1 id="sql-createlanguage-examples">
 
198
  <title>Examples</title>
 
199
 
 
200
  <para>
 
201
   The following two commands executed in sequence will register a new
 
202
   procedural language and the associated call handler.
 
203
<programlisting>
 
204
CREATE FUNCTION plsample_call_handler() RETURNS language_handler
 
205
    AS '$libdir/plsample'
 
206
    LANGUAGE C;
 
207
CREATE LANGUAGE plsample
 
208
    HANDLER plsample_call_handler;
 
209
</programlisting>
 
210
  </para>
 
211
 </refsect1>
 
212
 
 
213
 <refsect1 id="sql-createlanguage-compat">
 
214
  <title>Compatibility</title>
 
215
 
 
216
  <para>
 
217
   <command>CREATE LANGUAGE</command> is a
 
218
   <productname>PostgreSQL</productname> extension.
 
219
  </para>
 
220
 </refsect1>
 
221
 
 
222
 <refsect1>
 
223
  <title>See Also</title>
 
224
 
 
225
  <simplelist type="inline">
 
226
   <member><xref linkend="sql-alterlanguage" endterm="sql-alterlanguage-title"></member>
 
227
   <member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
 
228
   <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
 
229
   <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
 
230
   <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
 
231
   <member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
 
232
   <member><xref linkend="app-droplang" endterm="app-droplang-title"></member>
 
233
  </simplelist>
 
234
 </refsect1>
 
235
</refentry>
 
236
 
 
237
<!-- Keep this comment at the end of the file
 
238
Local variables:
 
239
mode: sgml
 
240
sgml-omittag:nil
 
241
sgml-shorttag:t
 
242
sgml-minimize-attributes:nil
 
243
sgml-always-quote-attributes:t
 
244
sgml-indent-step:1
 
245
sgml-indent-data:t
 
246
sgml-parent-document:nil
 
247
sgml-default-dtd-file:"../reference.ced"
 
248
sgml-exposed-tags:nil
 
249
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
250
sgml-local-ecat-files:nil
 
251
End:
 
252
-->