Skip to content

P
Postgres FD Implementation
Commit ab298522 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Move PL docs to programmer's guide, "storage" chapter to admin guide, 

clean up some things in the affected areas.
parent b1f528f8
Show whitespace changes
Inline Side-by-side
Showing with 97 additions and 153 deletions
doc/src/sgml/admin.sgml
View file @ ab298522
<!--
$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;
&regress;
&release;
......
doc/src/sgml/environ.sgml deleted 100644 → 0
View file @ b1f528f8
<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>
doc/src/sgml/filelist.sgml
View file @ ab298522
<!-- $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">
......
doc/src/sgml/manage-ag.sgml
View file @ ab298522
<!--
$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>
......
doc/src/sgml/manage.sgml
View file @ ab298522
<!--
$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">
......
doc/src/sgml/programmer.sgml
View file @ ab298522
<!--
$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;
]]>
......
doc/src/sgml/user.sgml
View file @ ab298522
<!--
$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 -->
......
doc/src/sgml/xplang.sgml
View file @ ab298522
<!--
$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>
then defines that the previously declared call handler
function should be invoked for functions and trigger procedures
where the language attribute is 'plpgsql'.
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>
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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment