← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/xplang-install.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/xplang-install.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Installing Procedural Languages</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Procedural Languages"
 
16
HREF="xplang.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Procedural Languages"
 
19
HREF="xplang.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="PL/pgSQL - SQL Procedural Language"
 
22
HREF="plpgsql.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Procedural Languages"
 
57
HREF="xplang.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="Procedural Languages"
 
67
HREF="xplang.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 38. Procedural Languages</TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Procedural Languages"
 
81
HREF="xplang.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="PL/pgSQL - SQL Procedural Language"
 
90
HREF="plpgsql.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><DIV
 
100
CLASS="SECT1"
 
101
><H1
 
102
CLASS="SECT1"
 
103
><A
 
104
NAME="XPLANG-INSTALL"
 
105
>38.1. Installing Procedural Languages</A
 
106
></H1
 
107
><P
 
108
>    A procedural language must be <SPAN
 
109
CLASS="QUOTE"
 
110
>"installed"</SPAN
 
111
> into each
 
112
    database where it is to be used.  But procedural languages installed in
 
113
    the database <TT
 
114
CLASS="LITERAL"
 
115
>template1</TT
 
116
> are automatically available in all
 
117
    subsequently created databases, since their entries in
 
118
    <TT
 
119
CLASS="LITERAL"
 
120
>template1</TT
 
121
> will be copied by <TT
 
122
CLASS="COMMAND"
 
123
>CREATE DATABASE</TT
 
124
>.
 
125
    So the database administrator can
 
126
    decide which languages are available in which databases and can make
 
127
    some languages available by default if he chooses.
 
128
   </P
 
129
><P
 
130
>    For the languages supplied with the standard distribution, it is
 
131
    only necessary to execute <TT
 
132
CLASS="COMMAND"
 
133
>CREATE EXTENSION</TT
 
134
>
 
135
    <TT
 
136
CLASS="REPLACEABLE"
 
137
><I
 
138
>language_name</I
 
139
></TT
 
140
> to install the language into the
 
141
    current database.  Alternatively, the program <A
 
142
HREF="app-createlang.html"
 
143
><SPAN
 
144
CLASS="APPLICATION"
 
145
>createlang</SPAN
 
146
></A
 
147
> can be used to do this from the shell
 
148
    command line.  For example, to install the language
 
149
    <SPAN
 
150
CLASS="APPLICATION"
 
151
>PL/Perl</SPAN
 
152
> into the database
 
153
    <TT
 
154
CLASS="LITERAL"
 
155
>template1</TT
 
156
>, use:
 
157
</P><PRE
 
158
CLASS="PROGRAMLISTING"
 
159
>createlang plperl template1</PRE
 
160
><P>
 
161
    The manual procedure described below is only recommended for
 
162
    installing languages that have not been packaged as extensions.
 
163
   </P
 
164
><DIV
 
165
CLASS="PROCEDURE"
 
166
><P
 
167
><B
 
168
>     Manual Procedural Language Installation
 
169
    </B
 
170
></P
 
171
><P
 
172
>     A procedural language is installed in a database in five steps,
 
173
     which must be carried out by a database superuser.  In most cases
 
174
     the required SQL commands should be packaged as the installation script
 
175
     of an <SPAN
 
176
CLASS="QUOTE"
 
177
>"extension"</SPAN
 
178
>, so that <TT
 
179
CLASS="COMMAND"
 
180
>CREATE EXTENSION</TT
 
181
> can be
 
182
     used to execute them.
 
183
    </P
 
184
><OL
 
185
TYPE="1"
 
186
><LI
 
187
CLASS="STEP"
 
188
><A
 
189
NAME="XPLANG-INSTALL-CR1"
 
190
></A
 
191
><P
 
192
>      The shared object for the language handler must be compiled and
 
193
      installed into an appropriate library directory.  This works in the same
 
194
      way as building and installing modules with regular user-defined C
 
195
      functions does; see <A
 
196
HREF="xfunc-c.html#DFUNC"
 
197
>Section 35.9.6</A
 
198
>.  Often, the language
 
199
      handler will depend on an external library that provides the actual
 
200
      programming language engine; if so, that must be installed as well.
 
201
     </P
 
202
></LI
 
203
><LI
 
204
CLASS="STEP"
 
205
><A
 
206
NAME="XPLANG-INSTALL-CR2"
 
207
></A
 
208
><P
 
209
>      The handler must be declared with the command
 
210
</P><PRE
 
211
CLASS="SYNOPSIS"
 
212
>CREATE FUNCTION <TT
 
213
CLASS="REPLACEABLE"
 
214
><I
 
215
>handler_function_name</I
 
216
></TT
 
217
>()
 
218
    RETURNS language_handler
 
219
    AS '<TT
 
220
CLASS="REPLACEABLE"
 
221
><I
 
222
>path-to-shared-object</I
 
223
></TT
 
224
>'
 
225
    LANGUAGE C;</PRE
 
226
><P>
 
227
      The special return type of <TT
 
228
CLASS="TYPE"
 
229
>language_handler</TT
 
230
> tells
 
231
      the database system that this function does not return one of
 
232
      the defined <ACRONYM
 
233
CLASS="ACRONYM"
 
234
>SQL</ACRONYM
 
235
> data types and is not directly usable
 
236
      in <ACRONYM
 
237
CLASS="ACRONYM"
 
238
>SQL</ACRONYM
 
239
> statements.
 
240
     </P
 
241
></LI
 
242
><LI
 
243
CLASS="STEP"
 
244
><A
 
245
NAME="XPLANG-INSTALL-CR3"
 
246
></A
 
247
><P
 
248
>      Optionally, the language handler can provide an <SPAN
 
249
CLASS="QUOTE"
 
250
>"inline"</SPAN
 
251
>
 
252
      handler function that executes anonymous code blocks
 
253
      (<A
 
254
HREF="sql-do.html"
 
255
>DO</A
 
256
> commands)
 
257
      written in this language.  If an inline handler function
 
258
      is provided by the language, declare it with a command like
 
259
</P><PRE
 
260
CLASS="SYNOPSIS"
 
261
>CREATE FUNCTION <TT
 
262
CLASS="REPLACEABLE"
 
263
><I
 
264
>inline_function_name</I
 
265
></TT
 
266
>(internal)
 
267
    RETURNS void
 
268
    AS '<TT
 
269
CLASS="REPLACEABLE"
 
270
><I
 
271
>path-to-shared-object</I
 
272
></TT
 
273
>'
 
274
    LANGUAGE C;</PRE
 
275
><P>
 
276
     </P
 
277
></LI
 
278
><LI
 
279
CLASS="STEP"
 
280
><A
 
281
NAME="XPLANG-INSTALL-CR4"
 
282
></A
 
283
><P
 
284
>      Optionally, the language handler can provide a <SPAN
 
285
CLASS="QUOTE"
 
286
>"validator"</SPAN
 
287
>
 
288
      function that checks a function definition for correctness without
 
289
      actually executing it.  The validator function is called by
 
290
      <TT
 
291
CLASS="COMMAND"
 
292
>CREATE FUNCTION</TT
 
293
> if it exists.  If a validator function
 
294
      is provided by the language, declare it with a command like
 
295
</P><PRE
 
296
CLASS="SYNOPSIS"
 
297
>CREATE FUNCTION <TT
 
298
CLASS="REPLACEABLE"
 
299
><I
 
300
>validator_function_name</I
 
301
></TT
 
302
>(oid)
 
303
    RETURNS void
 
304
    AS '<TT
 
305
CLASS="REPLACEABLE"
 
306
><I
 
307
>path-to-shared-object</I
 
308
></TT
 
309
>'
 
310
    LANGUAGE C STRICT;</PRE
 
311
><P>
 
312
     </P
 
313
></LI
 
314
><LI
 
315
CLASS="STEP"
 
316
><A
 
317
NAME="XPLANG-INSTALL-CR5"
 
318
></A
 
319
><P
 
320
>      Finally, the PL must be declared with the command
 
321
</P><PRE
 
322
CLASS="SYNOPSIS"
 
323
>CREATE [<SPAN
 
324
CLASS="OPTIONAL"
 
325
>TRUSTED</SPAN
 
326
>] [<SPAN
 
327
CLASS="OPTIONAL"
 
328
>PROCEDURAL</SPAN
 
329
>] LANGUAGE <TT
 
330
CLASS="REPLACEABLE"
 
331
><I
 
332
>language-name</I
 
333
></TT
 
334
>
 
335
    HANDLER <TT
 
336
CLASS="REPLACEABLE"
 
337
><I
 
338
>handler_function_name</I
 
339
></TT
 
340
>
 
341
    [<SPAN
 
342
CLASS="OPTIONAL"
 
343
>INLINE <TT
 
344
CLASS="REPLACEABLE"
 
345
><I
 
346
>inline_function_name</I
 
347
></TT
 
348
></SPAN
 
349
>]
 
350
    [<SPAN
 
351
CLASS="OPTIONAL"
 
352
>VALIDATOR <TT
 
353
CLASS="REPLACEABLE"
 
354
><I
 
355
>validator_function_name</I
 
356
></TT
 
357
></SPAN
 
358
>] ;</PRE
 
359
><P>
 
360
      The optional key word <TT
 
361
CLASS="LITERAL"
 
362
>TRUSTED</TT
 
363
> specifies that
 
364
      the language does not grant access to data that the user would
 
365
      not otherwise have.  Trusted languages are designed for ordinary
 
366
      database users (those without superuser privilege) and allows them
 
367
      to safely create functions and trigger
 
368
      procedures. Since PL functions are executed inside the database
 
369
      server, the <TT
 
370
CLASS="LITERAL"
 
371
>TRUSTED</TT
 
372
> flag should only be given
 
373
      for languages that do not allow access to database server
 
374
      internals or the file system. The languages
 
375
      <SPAN
 
376
CLASS="APPLICATION"
 
377
>PL/pgSQL</SPAN
 
378
>,
 
379
      <SPAN
 
380
CLASS="APPLICATION"
 
381
>PL/Tcl</SPAN
 
382
>, and
 
383
      <SPAN
 
384
CLASS="APPLICATION"
 
385
>PL/Perl</SPAN
 
386
>
 
387
      are considered trusted; the languages
 
388
      <SPAN
 
389
CLASS="APPLICATION"
 
390
>PL/TclU</SPAN
 
391
>,
 
392
      <SPAN
 
393
CLASS="APPLICATION"
 
394
>PL/PerlU</SPAN
 
395
>, and
 
396
      <SPAN
 
397
CLASS="APPLICATION"
 
398
>PL/PythonU</SPAN
 
399
>
 
400
      are designed to provide unlimited functionality and should
 
401
      <SPAN
 
402
CLASS="emphasis"
 
403
><I
 
404
CLASS="EMPHASIS"
 
405
>not</I
 
406
></SPAN
 
407
> be marked trusted.
 
408
     </P
 
409
></LI
 
410
></OL
 
411
></DIV
 
412
><P
 
413
>    <A
 
414
HREF="xplang-install.html#XPLANG-INSTALL-EXAMPLE"
 
415
>Example 38-1</A
 
416
> shows how the manual
 
417
    installation procedure would work with the language
 
418
    <SPAN
 
419
CLASS="APPLICATION"
 
420
>PL/Perl</SPAN
 
421
>.
 
422
   </P
 
423
><DIV
 
424
CLASS="EXAMPLE"
 
425
><A
 
426
NAME="XPLANG-INSTALL-EXAMPLE"
 
427
></A
 
428
><P
 
429
><B
 
430
>Example 38-1. Manual Installation of <SPAN
 
431
CLASS="APPLICATION"
 
432
>PL/Perl</SPAN
 
433
></B
 
434
></P
 
435
><P
 
436
>      The following command tells the database server where to find the
 
437
      shared object for the <SPAN
 
438
CLASS="APPLICATION"
 
439
>PL/Perl</SPAN
 
440
> language's call
 
441
      handler function:
 
442
 
 
443
</P><PRE
 
444
CLASS="PROGRAMLISTING"
 
445
>CREATE FUNCTION plperl_call_handler() RETURNS language_handler AS
 
446
    '$libdir/plperl' LANGUAGE C;</PRE
 
447
><P>
 
448
     </P
 
449
><P
 
450
>      <SPAN
 
451
CLASS="APPLICATION"
 
452
>PL/Perl</SPAN
 
453
> has an inline handler function
 
454
      and a validator function, so we declare those too:
 
455
 
 
456
</P><PRE
 
457
CLASS="PROGRAMLISTING"
 
458
>CREATE FUNCTION plperl_inline_handler(internal) RETURNS void AS
 
459
    '$libdir/plperl' LANGUAGE C;
 
460
 
 
461
CREATE FUNCTION plperl_validator(oid) RETURNS void AS
 
462
    '$libdir/plperl' LANGUAGE C STRICT;</PRE
 
463
><P>
 
464
     </P
 
465
><P
 
466
>      The command:
 
467
</P><PRE
 
468
CLASS="PROGRAMLISTING"
 
469
>CREATE TRUSTED PROCEDURAL LANGUAGE plperl
 
470
    HANDLER plperl_call_handler
 
471
    INLINE plperl_inline_handler
 
472
    VALIDATOR plperl_validator;</PRE
 
473
><P>
 
474
      then defines that the previously declared functions
 
475
      should be invoked for functions and trigger procedures where the
 
476
      language attribute is <TT
 
477
CLASS="LITERAL"
 
478
>plperl</TT
 
479
>.
 
480
     </P
 
481
></DIV
 
482
><P
 
483
>    In a default <SPAN
 
484
CLASS="PRODUCTNAME"
 
485
>PostgreSQL</SPAN
 
486
> installation,
 
487
    the handler for the <SPAN
 
488
CLASS="APPLICATION"
 
489
>PL/pgSQL</SPAN
 
490
> language
 
491
    is built and installed into the <SPAN
 
492
CLASS="QUOTE"
 
493
>"library"</SPAN
 
494
>
 
495
    directory; furthermore, the <SPAN
 
496
CLASS="APPLICATION"
 
497
>PL/pgSQL</SPAN
 
498
> language
 
499
    itself is installed in all databases.
 
500
    If <SPAN
 
501
CLASS="APPLICATION"
 
502
>Tcl</SPAN
 
503
> support is configured in, the handlers for
 
504
    <SPAN
 
505
CLASS="APPLICATION"
 
506
>PL/Tcl</SPAN
 
507
> and <SPAN
 
508
CLASS="APPLICATION"
 
509
>PL/TclU</SPAN
 
510
> are built and installed
 
511
    in the library directory, but the language itself is not installed in any
 
512
    database by default.
 
513
    Likewise, the <SPAN
 
514
CLASS="APPLICATION"
 
515
>PL/Perl</SPAN
 
516
> and <SPAN
 
517
CLASS="APPLICATION"
 
518
>PL/PerlU</SPAN
 
519
>
 
520
    handlers are built and installed if Perl support is configured, and the
 
521
    <SPAN
 
522
CLASS="APPLICATION"
 
523
>PL/PythonU</SPAN
 
524
> handler is installed if Python support is
 
525
    configured, but these languages are not installed by default.
 
526
   </P
 
527
></DIV
 
528
><DIV
 
529
CLASS="NAVFOOTER"
 
530
><HR
 
531
ALIGN="LEFT"
 
532
WIDTH="100%"><TABLE
 
533
SUMMARY="Footer navigation table"
 
534
WIDTH="100%"
 
535
BORDER="0"
 
536
CELLPADDING="0"
 
537
CELLSPACING="0"
 
538
><TR
 
539
><TD
 
540
WIDTH="33%"
 
541
ALIGN="left"
 
542
VALIGN="top"
 
543
><A
 
544
HREF="xplang.html"
 
545
ACCESSKEY="P"
 
546
>Prev</A
 
547
></TD
 
548
><TD
 
549
WIDTH="34%"
 
550
ALIGN="center"
 
551
VALIGN="top"
 
552
><A
 
553
HREF="index.html"
 
554
ACCESSKEY="H"
 
555
>Home</A
 
556
></TD
 
557
><TD
 
558
WIDTH="33%"
 
559
ALIGN="right"
 
560
VALIGN="top"
 
561
><A
 
562
HREF="plpgsql.html"
 
563
ACCESSKEY="N"
 
564
>Next</A
 
565
></TD
 
566
></TR
 
567
><TR
 
568
><TD
 
569
WIDTH="33%"
 
570
ALIGN="left"
 
571
VALIGN="top"
 
572
>Procedural Languages</TD
 
573
><TD
 
574
WIDTH="34%"
 
575
ALIGN="center"
 
576
VALIGN="top"
 
577
><A
 
578
HREF="xplang.html"
 
579
ACCESSKEY="U"
 
580
>Up</A
 
581
></TD
 
582
><TD
 
583
WIDTH="33%"
 
584
ALIGN="right"
 
585
VALIGN="top"
 
586
><SPAN
 
587
CLASS="APPLICATION"
 
588
>PL/pgSQL</SPAN
 
589
> - <ACRONYM
 
590
CLASS="ACRONYM"
 
591
>SQL</ACRONYM
 
592
> Procedural Language</TD
 
593
></TR
 
594
></TABLE
 
595
></DIV
 
596
></BODY
 
597
></HTML
 
598
>
 
 
b'\\ No newline at end of file'