From ab298522247148417fe3d4165df6356b5b143755 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 4 Feb 2001 15:28:18 +0000 Subject: [PATCH] Move PL docs to programmer's guide, "storage" chapter to admin guide, clean up some things in the affected areas. --- doc/src/sgml/admin.sgml | 3 +- doc/src/sgml/environ.sgml | 62 --------------------- doc/src/sgml/filelist.sgml | 14 +++-- doc/src/sgml/manage-ag.sgml | 4 +- doc/src/sgml/manage.sgml | 18 +------ doc/src/sgml/programmer.sgml | 16 ++++-- doc/src/sgml/user.sgml | 7 +-- doc/src/sgml/xplang.sgml | 126 ++++++++++++++++++++++++------------------- 8 files changed, 97 insertions(+), 153 deletions(-) delete mode 100644 doc/src/sgml/environ.sgml diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index 51a78b3b30..f4ae0b182d 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,5 +1,5 @@ @@ -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; diff --git a/doc/src/sgml/environ.sgml b/doc/src/sgml/environ.sgml deleted file mode 100644 index dc5741a95d..0000000000 --- a/doc/src/sgml/environ.sgml +++ /dev/null @@ -1,62 +0,0 @@ - -Setting Up Your Environment - - - This section discusses how to set up - your own environment so that you can use frontend - applications. We assume Postgres has already been - successfully installed and started; refer to the Administrator's Guide -and the installation notes - for how to install Postgres. - - - -Postgres 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 psql). - For simplicity, - we will assume that Postgres has been installed in the - directory /usr/local/pgsql. Therefore, wherever - you see the directory /usr/local/pgsql you should - substitute the name of the directory where Postgres is - actually installed. - All Postgres commands are installed in the directory - /usr/local/pgsql/bin. Therefore, you should add - this directory to your shell command path. If you use - a variant of the Berkeley C shell, such as csh or tcsh, - you would add - -set path = ( /usr/local/pgsql/bin path ) - - in the .login file in your home directory. If you use - a variant of the Bourne shell, such as sh, ksh, or - bash, then you would add - -$ PATH=/usr/local/pgsql/bin:$PATH -$ export PATH - - to the .profile file in your home directory. - From now on, we will assume that you have added the - Postgres 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. - - - -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 PGHOST environment variable to the name -of the database server machine. The environment variable -PGPORT 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 postmaster, - you should immediately consult your site administrator to make sure that your -environment is properly set up. - - - diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index ae27be1999..f38c6b0cd2 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -1,4 +1,4 @@ - + @@ -8,6 +8,7 @@ + @@ -15,23 +16,16 @@ - - - - - - - @@ -51,6 +45,7 @@ + @@ -79,6 +74,9 @@ + + + diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml index 5ac9776eac..1cd500b3b0 100644 --- a/doc/src/sgml/manage-ag.sgml +++ b/doc/src/sgml/manage-ag.sgml @@ -1,5 +1,5 @@ @@ -174,7 +174,7 @@ CREATE DATABASE name WITH LOCATION = 'location' risk. To allow it, you must compile Postgres with the C preprocessor macro ALLOW_ABSOLUTE_DBPATHS defined. One way to do this is to run the compilation step like - this: gmake COPT=-DALLOW_ABSOLUTE_DBPATHS all. + this: gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all. diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml index 43e21b30ef..8c363d536e 100644 --- a/doc/src/sgml/manage.sgml +++ b/doc/src/sgml/manage.sgml @@ -1,5 +1,5 @@ @@ -256,22 +256,6 @@ mydb=> \q are denoted by "/* ... */". - -Database Privileges - - - - - - -Table Privileges - - -TBD - - - - diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index 81bbf42653..f4f3812fdd 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,5 +1,5 @@ @@ -28,7 +28,9 @@ PostgreSQL Programmer's Guide. operators, aggregates, and both query language and programming language functions. After a discussion of the PostgreSQL rule system, we discuss the - trigger and SPI interfaces. + trigger and SPI interfaces. The third part documents the + procedural languages available in the + PostgreSQL distribution. @@ -61,7 +63,6 @@ PostgreSQL Programmer's Guide. &xindex; &indexcost; &gist; - &xplang; @@ -76,6 +77,15 @@ Disable it until we put in some info. &spi; + + Procedural Languages + + &xplang; + &plsql; + &pltcl; + &plperl; + + diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index f0b3f4e5e3..7a4f8a3caa 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,5 +1,5 @@ @@ -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; diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index e83ee50469..5c13526777 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -1,26 +1,31 @@ Procedural Languages - Postgres supports - the definition of procedural languages. - In the case of a function or trigger - procedure defined in a procedural language, the database has + Postgres allows users to add new + programming languages to be available for writing functions and + procedures. These are called procedural + languages (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 glue between + Postgres 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. - 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 Postgres distribution. @@ -32,86 +37,107 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momj - A procedural language is installed in the database in three steps. - (For the languages supplied with the standard distribution, the - shell script createlang 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. - + - 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 . - + + The handler must be declared with the command - + CREATE FUNCTION handler_function_name () RETURNS OPAQUE AS - 'path-to-shared-object' LANGUAGE 'C'; - - The special return type of OPAQUE tells + 'path-to-shared-object' LANGUAGE 'C'; + + The special return type of OPAQUE tells the database that this function does not return one of - the defined SQL datatypes and is not directly usable + the defined SQL data types and is not directly usable in SQL statements. - + + The PL must be declared with the command - -CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE 'language-name' + +CREATE TRUSTED PROCEDURAL LANGUAGE 'language-name' HANDLER handler_function_name LANCOMPILER 'description'; - - The optional keyword TRUSTED tells + + The optional key word TRUSTED 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 TRUSTED 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. + + In a default Postgres installation, the + handler for the PL/pgSQL is built and installed into the + library directory. If Tcl/Tk support is configured + in, the handler for PL/Tcl is also built and installed in the same + location. + + Example - + + The following command tells the database where to find the shared object for the PL/pgSQL language's call handler function. - + CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS '/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C'; - + The command - + CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql' HANDLER plpgsql_call_handler LANCOMPILER 'PL/pgSQL'; - + + 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 createlang can be used instead + of carrying out the details manually. To install PL/pgSQL into + the template1 database, use + +createlang plpgsql template1 + + - - then defines that the previously declared call handler - function should be invoked for functions and trigger procedures - where the language attribute is 'plpgsql'. - 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. - - Procedural languages defined in the template1 - database are automatically defined in all subsequently created - databases. So the database administrator can decide which - languages are available by default. - - - + -