mirror of
https://github.com/postgres/postgres.git
synced 2025-07-30 11:03:19 +03:00
Move PL docs to programmer's guide, "storage" chapter to admin guide,
clean up some things in the affected areas.
This commit is contained in:
Peter Eisentraut
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.33 2001/02/04 15:28:18 petere Exp $
|
||||
-->
|
||||
|
||||
<book id="admin">
|
||||
@ -31,6 +31,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26
|
||||
&user-manag;
|
||||
&backup;
|
||||
&wal;
|
||||
&storage;
|
||||
&recovery;
|
||||
®ress;
|
||||
&release;
|
||||
|
||||
@ -1,62 +0,0 @@
|
||||
<Chapter Id="environ">
|
||||
<Title>Setting Up Your Environment</Title>
|
||||
|
||||
<Para>
|
||||
This section discusses how to set up
|
||||
your own environment so that you can use frontend
|
||||
applications. We assume <ProductName>Postgres</ProductName> has already been
|
||||
successfully installed and started; refer to the Administrator's Guide
|
||||
and the installation notes
|
||||
for how to install Postgres.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
<ProductName>Postgres</ProductName> is a client/server application. As a user,
|
||||
you only need access to the client portions of the installation (an example
|
||||
of a client application is the interactive monitor <Application>psql</Application>).
|
||||
For simplicity,
|
||||
we will assume that <ProductName>Postgres</ProductName> has been installed in the
|
||||
directory <FileName>/usr/local/pgsql</FileName>. Therefore, wherever
|
||||
you see the directory <FileName>/usr/local/pgsql</FileName> you should
|
||||
substitute the name of the directory where <ProductName>Postgres</ProductName> is
|
||||
actually installed.
|
||||
All <ProductName>Postgres</ProductName> commands are installed in the directory
|
||||
<FileName>/usr/local/pgsql/bin</FileName>. Therefore, you should add
|
||||
this directory to your shell command path. If you use
|
||||
a variant of the Berkeley C shell, such as <Application>csh</Application> or <Application>tcsh</Application>,
|
||||
you would add
|
||||
<ProgramListing>
|
||||
set path = ( /usr/local/pgsql/bin path )
|
||||
</ProgramListing>
|
||||
in the <FileName>.login</FileName> file in your home directory. If you use
|
||||
a variant of the Bourne shell, such as <Application>sh</Application>, <Application>ksh</Application>, or
|
||||
<Application>bash</Application>, then you would add
|
||||
<ProgramListing>
|
||||
$ PATH=/usr/local/pgsql/bin:$PATH
|
||||
$ export PATH
|
||||
</ProgramListing>
|
||||
to the <FileName>.profile</FileName> file in your home directory.
|
||||
From now on, we will assume that you have added the
|
||||
<ProductName>Postgres</ProductName> bin directory to your path. In addition, we
|
||||
will make frequent reference to "setting a shell
|
||||
variable" or "setting an environment variable" throughout
|
||||
this document. If you did not fully understand the
|
||||
last paragraph on modifying your search path, you
|
||||
should consult the Unix manual pages that describe your
|
||||
shell before going any further.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
If your site administrator has not set things up in the
|
||||
default way, you may have some more work to do. For example, if the database
|
||||
server machine is a remote machine, you
|
||||
will need to set the <Acronym>PGHOST</Acronym> environment variable to the name
|
||||
of the database server machine. The environment variable
|
||||
<Acronym>PGPORT</Acronym> may also have to be set. The bottom line is this: if
|
||||
you try to start an application program and it complains
|
||||
that it cannot connect to the <Application>postmaster</Application>,
|
||||
you should immediately consult your site administrator to make sure that your
|
||||
environment is properly set up.
|
||||
</Para>
|
||||
|
||||
</Chapter>
|
||||
@ -1,4 +1,4 @@
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.7 2001/02/03 19:03:26 petere Exp $ -->
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.8 2001/02/04 15:28:18 petere Exp $ -->
|
||||
|
||||
<!entity history SYSTEM "history.sgml">
|
||||
<!entity info SYSTEM "info.sgml">
|
||||
@ -8,6 +8,7 @@
|
||||
<!entity y2k SYSTEM "y2k.sgml">
|
||||
|
||||
<!-- tutorial -->
|
||||
<!entity advanced SYSTEM "advanced.sgml">
|
||||
<!entity arch SYSTEM "arch.sgml">
|
||||
<!entity intro SYSTEM "intro.sgml">
|
||||
<!entity query SYSTEM "query.sgml">
|
||||
@ -15,23 +16,16 @@
|
||||
<!entity start SYSTEM "start.sgml">
|
||||
|
||||
<!-- user's guide -->
|
||||
<!entity advanced SYSTEM "advanced.sgml">
|
||||
<!entity array SYSTEM "array.sgml">
|
||||
<!entity datatype SYSTEM "datatype.sgml">
|
||||
<!entity datetime SYSTEM "datetime.sgml">
|
||||
<!entity environ SYSTEM "environ.sgml">
|
||||
<!entity func SYSTEM "func.sgml">
|
||||
<!entity indices SYSTEM "indices.sgml">
|
||||
<!entity inherit SYSTEM "inherit.sgml">
|
||||
<!entity manage SYSTEM "manage.sgml">
|
||||
<!entity mvcc SYSTEM "mvcc.sgml">
|
||||
<!entity perform SYSTEM "perform.sgml">
|
||||
<!entity plperl SYSTEM "plperl.sgml">
|
||||
<!entity plsql SYSTEM "plsql.sgml">
|
||||
<!entity pltcl SYSTEM "pltcl.sgml">
|
||||
<!entity psql SYSTEM "psql.sgml">
|
||||
<!entity queries SYSTEM "queries.sgml">
|
||||
<!entity storage SYSTEM "storage.sgml">
|
||||
<!entity syntax SYSTEM "syntax.sgml">
|
||||
<!entity typeconv SYSTEM "typeconv.sgml">
|
||||
<!entity keywords SYSTEM "keywords.sgml">
|
||||
@ -51,6 +45,7 @@
|
||||
<!entity regress SYSTEM "regress.sgml">
|
||||
<!entity release SYSTEM "release.sgml">
|
||||
<!entity runtime SYSTEM "runtime.sgml">
|
||||
<!entity storage SYSTEM "storage.sgml">
|
||||
<!entity user-manag SYSTEM "user-manag.sgml">
|
||||
<!entity wal SYSTEM "wal.sgml">
|
||||
|
||||
@ -79,6 +74,9 @@
|
||||
<!entity xplang SYSTEM "xplang.sgml">
|
||||
<!entity xoper SYSTEM "xoper.sgml">
|
||||
<!entity xtypes SYSTEM "xtypes.sgml">
|
||||
<!entity plperl SYSTEM "plperl.sgml">
|
||||
<!entity plsql SYSTEM "plsql.sgml">
|
||||
<!entity pltcl SYSTEM "pltcl.sgml">
|
||||
|
||||
<!-- developer's guide -->
|
||||
<!entity arch-dev SYSTEM "arch-dev.sgml">
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.11 2000/09/29 20:21:34 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.12 2001/02/04 15:28:18 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="managing-databases">
|
||||
@ -174,7 +174,7 @@ CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
|
||||
risk. To allow it, you must compile <productname>Postgres</> with
|
||||
the C preprocessor macro <literal>ALLOW_ABSOLUTE_DBPATHS</>
|
||||
defined. One way to do this is to run the compilation step like
|
||||
this: <userinput>gmake COPT=-DALLOW_ABSOLUTE_DBPATHS all</>.
|
||||
this: <userinput>gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all</>.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.12 2000/10/08 19:44:01 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.13 2001/02/04 15:28:18 petere Exp $
|
||||
-->
|
||||
|
||||
<Chapter Id="manage">
|
||||
@ -256,22 +256,6 @@ mydb=> \q
|
||||
are denoted by "<literal>/* ... */</literal>".
|
||||
</Para>
|
||||
|
||||
<Sect2>
|
||||
<Title>Database Privileges</Title>
|
||||
|
||||
<Para>
|
||||
</para>
|
||||
</Sect2>
|
||||
|
||||
<Sect2>
|
||||
<Title>Table Privileges</Title>
|
||||
|
||||
<Para>
|
||||
TBD
|
||||
</Para>
|
||||
|
||||
</Sect2>
|
||||
|
||||
</Sect1>
|
||||
|
||||
<Sect1 id="db-destroy">
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.33 2001/02/03 19:03:27 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.34 2001/02/04 15:28:18 petere Exp $
|
||||
|
||||
PostgreSQL Programmer's Guide.
|
||||
-->
|
||||
@ -28,7 +28,9 @@ PostgreSQL Programmer's Guide.
|
||||
operators, aggregates, and both query language and programming
|
||||
language functions. After a discussion of the
|
||||
<productname>PostgreSQL</productname> rule system, we discuss the
|
||||
trigger and SPI interfaces.
|
||||
trigger and SPI interfaces. The third part documents the
|
||||
procedural languages available in the
|
||||
<productname>PostgreSQL</productname> distribution.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -61,7 +63,6 @@ PostgreSQL Programmer's Guide.
|
||||
&xindex;
|
||||
&indexcost;
|
||||
&gist;
|
||||
&xplang;
|
||||
|
||||
<!-- reference -->
|
||||
|
||||
@ -76,6 +77,15 @@ Disable it until we put in some info.
|
||||
&spi;
|
||||
</part>
|
||||
|
||||
<part id="programmer-pl">
|
||||
<title>Procedural Languages</title>
|
||||
|
||||
&xplang;
|
||||
&plsql;
|
||||
&pltcl;
|
||||
&plperl;
|
||||
</part>
|
||||
|
||||
<![%single-book;[
|
||||
&biblio;
|
||||
]]>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.28 2001/02/04 15:28:18 petere Exp $
|
||||
-->
|
||||
|
||||
<book id="user">
|
||||
@ -23,13 +23,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27
|
||||
&array;
|
||||
&indices;
|
||||
&inherit;
|
||||
&plsql;
|
||||
&pltcl;
|
||||
&plperl;
|
||||
&mvcc;
|
||||
&environ;
|
||||
&manage;
|
||||
&storage;
|
||||
&perform;
|
||||
|
||||
<!-- appendices -->
|
||||
|
||||
@ -1,26 +1,31 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="xplang">
|
||||
<title id="xplang-title">Procedural Languages</title>
|
||||
|
||||
<para>
|
||||
<productname>Postgres</productname> supports
|
||||
the definition of procedural languages.
|
||||
In the case of a function or trigger
|
||||
procedure defined in a procedural language, the database has
|
||||
<productname>Postgres</productname> allows users to add new
|
||||
programming languages to be available for writing functions and
|
||||
procedures. These are called <firstterm>procedural
|
||||
languages</firstterm> (PL). In the case of a function or trigger
|
||||
procedure written in a procedural language, the database server has
|
||||
no built-in knowledge about how to interpret the function's source
|
||||
text. Instead, the task is passed to
|
||||
a handler that knows the details of the language. The
|
||||
handler itself is a special programming language function
|
||||
compiled into a shared object
|
||||
and loaded on demand.
|
||||
text. Instead, the task is passed to a special handler that knows
|
||||
the details of the language. The handler could either do all the
|
||||
work of parsing, syntax analysis, execution, etc. itself, or it
|
||||
could serve as a <quote>glue</quote> between
|
||||
<productname>Postgres</productname> and an existing implementation
|
||||
of a programming language. The handler itself is a special
|
||||
programming language function compiled into a shared object and
|
||||
loaded on demand.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Writing a handler for a new procedural language (PL)
|
||||
is outside the scope of this manual.
|
||||
Writing a handler for a new procedural language is outside the
|
||||
scope of this manual. Several procedural languages are available
|
||||
in the <productname>Postgres</productname> distribution.
|
||||
</para>
|
||||
|
||||
<sect1 id="xplang-install">
|
||||
@ -32,86 +37,107 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momj
|
||||
</title>
|
||||
|
||||
<para>
|
||||
A procedural language is installed in the database in three steps.
|
||||
(For the languages supplied with the standard distribution, the
|
||||
shell script <filename>createlang</filename> can be used instead
|
||||
of carrying out the details manually.)
|
||||
A procedural language is installed in the database in three
|
||||
steps. A procedural language must be installed into each
|
||||
database where it is to be used. Procedural languages defined in
|
||||
the template1 database are automatically available in all
|
||||
subsequently created databases. So the administrator can decide
|
||||
which languages are available by default.
|
||||
</para>
|
||||
|
||||
<step performance="Required">
|
||||
<step performance="required">
|
||||
<para>
|
||||
The shared object for the language handler
|
||||
must be compiled and installed. By default the
|
||||
handler for PL/pgSQL is built and installed into the
|
||||
database library directory. If Tcl/Tk support is
|
||||
configured in, the handler for PL/Tcl is also built
|
||||
and installed in the same location.
|
||||
The shared object for the language handler must be compiled and
|
||||
installed. This works in the same way as building and
|
||||
installing modules with regular user-defined C functions does;
|
||||
see <xref linkend="dfunc">.
|
||||
</para>
|
||||
</step>
|
||||
<step performance="Required">
|
||||
|
||||
<step performance="required">
|
||||
<para>
|
||||
The handler must be declared with the command
|
||||
<programlisting>
|
||||
<synopsis>
|
||||
CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
|
||||
RETURNS OPAQUE AS
|
||||
'<filename>path-to-shared-object</filename>' LANGUAGE 'C';
|
||||
</programlisting>
|
||||
The special return type of <acronym>OPAQUE</acronym> tells
|
||||
'<replaceable>path-to-shared-object</replaceable>' LANGUAGE 'C';
|
||||
</synopsis>
|
||||
The special return type of <type>OPAQUE</type> tells
|
||||
the database that this function does not return one of
|
||||
the defined <acronym>SQL</acronym> datatypes and is not directly usable
|
||||
the defined <acronym>SQL</acronym> data types and is not directly usable
|
||||
in <acronym>SQL</acronym> statements.
|
||||
</para>
|
||||
</step>
|
||||
<step performance="Required">
|
||||
|
||||
<step performance="required">
|
||||
<para>
|
||||
The PL must be declared with the command
|
||||
<programlisting>
|
||||
CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE '<replaceable>language-name</replaceable>'
|
||||
<synopsis>
|
||||
CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE '<replaceable>language-name</replaceable>'
|
||||
HANDLER <replaceable>handler_function_name</replaceable>
|
||||
LANCOMPILER '<replaceable>description</replaceable>';
|
||||
</programlisting>
|
||||
The optional keyword <acronym>TRUSTED</acronym> tells
|
||||
</synopsis>
|
||||
The optional key word <token>TRUSTED</token> tells
|
||||
whether ordinary database users that have no superuser
|
||||
privileges should be allowed to use this language to create functions
|
||||
and trigger procedures. Since PL functions are
|
||||
executed inside the database backend, the <acronym>TRUSTED</acronym>
|
||||
flag should only be given for
|
||||
languages that don't allow access to database backends
|
||||
languages that do not allow access to database backends
|
||||
internals or the filesystem. The languages PL/pgSQL and
|
||||
PL/Tcl are known to be trusted.
|
||||
</para>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
<para>
|
||||
In a default <productname>Postgres</productname> installation, the
|
||||
handler for the PL/pgSQL is built and installed into the
|
||||
<quote>library</quote> directory. If Tcl/Tk support is configured
|
||||
in, the handler for PL/Tcl is also built and installed in the same
|
||||
location.
|
||||
</para>
|
||||
|
||||
<procedure>
|
||||
<title>Example</title>
|
||||
<step performance="Required">
|
||||
|
||||
<step performance="required">
|
||||
<para>
|
||||
The following command tells the database where to find the
|
||||
shared object for the PL/pgSQL language's call handler function.
|
||||
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
|
||||
'/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</step>
|
||||
|
||||
<step performance="Required">
|
||||
<para>
|
||||
The command
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
|
||||
HANDLER plpgsql_call_handler
|
||||
LANCOMPILER 'PL/pgSQL';
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
then defines that the previously declared call handler function
|
||||
should be invoked for functions and trigger procedures where the
|
||||
language attribute is 'plpgsql'.
|
||||
</para>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
<para>
|
||||
For the languages supplied with the standard distribution, the
|
||||
shell script <filename>createlang</filename> can be used instead
|
||||
of carrying out the details manually. To install PL/pgSQL into
|
||||
the template1 database, use
|
||||
<programlisting>
|
||||
createlang plpgsql template1
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
then defines that the previously declared call handler
|
||||
function should be invoked for functions and trigger procedures
|
||||
where the language attribute is 'plpgsql'.
|
||||
</para>
|
||||
<para>
|
||||
PL handler functions have a special call interface that is
|
||||
different from regular C language functions. One of the arguments
|
||||
@ -126,17 +152,9 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
|
||||
multiple different PL functions having the same function name,
|
||||
as long as the call arguments differ.
|
||||
</para>
|
||||
<para>
|
||||
Procedural languages defined in the <filename>template1</filename>
|
||||
database are automatically defined in all subsequently created
|
||||
databases. So the database administrator can decide which
|
||||
languages are available by default.
|
||||
</para>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- **** End of PL installation **** -->
|
||||
</chapter>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
||||
Reference in New Issue
Block a user