database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-22 23:02:54 +03:00
Code

Clean up to ensure tag completion as required by the newest versions

Browse Source 
of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@michvhf.com>.
This commit is contained in:
Thomas G. Lockhart 1998-12-29 02:24:47 +00:00
parent 6d7735e7f0
commit a75f2d21a8
115 changed files with 10587 additions and 8000 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/src/sgml/about.sgml
View File

@ -4,15 +4,15 @@
<Para> <Para>
<ProductName>PostgreSQL</ProductName> is available without cost. This manual <ProductName>PostgreSQL</ProductName> is available without cost. This manual
describes version 6.4 of <ProductName>PostgreSQL</ProductName>. describes version 6.4 of <ProductName>PostgreSQL</ProductName>.
</Para>
<Para> <Para>
We will use <ProductName>Postgres</ProductName> We will use <ProductName>Postgres</ProductName>
to mean the version distributed as <ProductName>PostgreSQL</ProductName>. to mean the version distributed as <ProductName>PostgreSQL</ProductName>.
</Para>
<Para> <Para>
Check the Administrator's Guide for a list of currently supported machines. Check the Administrator's Guide for a list of currently supported machines.
In general, In general,
<ProductName>Postgres</ProductName> is portable to any Unix/Posix-compatible system <ProductName>Postgres</ProductName> is portable to any Unix/Posix-compatible system
with full libc library support. with full libc library support.
</Para>
</Sect1> </Sect1>

8
doc/src/sgml/advanced.sgml
View File

@ -66,6 +66,7 @@ SELECT name, altitude
|Mariposa | 1953 | |Mariposa | 1953 |
+----------+----------+ +----------+----------+
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
On the other hand, to find the names of all cities, On the other hand, to find the names of all cities,
@ -111,6 +112,7 @@ SELECT c.name, c.altitude
sub-values that can be accessed from the query sub-values that can be accessed from the query
language. For example, you can create attributes that language. For example, you can create attributes that
are arrays of base types. are arrays of base types.
</Para>
<Sect2> <Sect2>
<Title>Arrays</Title> <Title>Arrays</Title>
@ -210,7 +212,7 @@ SELECT SAL_EMP.schedule[1:2][1:1]
+-------------------+ +-------------------+
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect2>
</Sect1> </Sect1>
<Sect1> <Sect1>
@ -286,6 +288,7 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT.
|Mariposa | 1320 | |Mariposa | 1320 |
+---------+------------+ +---------+------------+
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
The default beginning of a time range is the earliest The default beginning of a time range is the earliest
@ -293,6 +296,7 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT.
the current time; thus, the above time range can be the current time; thus, the above time range can be
abbreviated as ``[,].'' abbreviated as ``[,].''
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>More Advanced Features</Title> <Title>More Advanced Features</Title>
@ -301,5 +305,7 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT.
<ProductName>Postgres</ProductName> has many features not touched upon in this <ProductName>Postgres</ProductName> has many features not touched upon in this
tutorial introduction, which has been oriented toward newer users of <Acronym>SQL</Acronym>. tutorial introduction, which has been oriented toward newer users of <Acronym>SQL</Acronym>.
These are discussed in more detail in both the User's and Programmer's Guides. These are discussed in more detail in both the User's and Programmer's Guides.
</Para>
</sect1>
</Chapter> </Chapter>

3
doc/src/sgml/arch-dev.sgml
View File

@ -30,6 +30,7 @@
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para>
<Para> <Para>
A single <Application>postmaster</Application> manages a given collection of A single <Application>postmaster</Application> manages a given collection of
@ -76,5 +77,5 @@
case, all files relating to a database should belong to case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser. this <ProductName>Postgres</ProductName> superuser.
</Para> </Para>
</sect1>
</Chapter> </Chapter>

4
doc/src/sgml/arch-pg.sgml
View File

@ -30,7 +30,7 @@
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
<Para> <Para>
A single <Application>postmaster</Application> manages a given collection of A single <Application>postmaster</Application> manages a given collection of
databases on a single host. Such a collection of databases on a single host. Such a collection of
@ -79,5 +79,5 @@ Furthermore, the <ProductName>Postgres</ProductName> superuser should
case, all files relating to a database should belong to case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser. this <ProductName>Postgres</ProductName> superuser.
</Para> </Para>
</sect1>
</Chapter> </Chapter>

5
doc/src/sgml/arch.sgml
View File

@ -12,6 +12,7 @@
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session per-user" client/server model. A <ProductName>Postgres</ProductName> session
consists of the following cooperating UNIX processes (programs): consists of the following cooperating UNIX processes (programs):
</Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
@ -53,6 +54,7 @@
<Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting <Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting
for requests, whereas frontend and backend processes for requests, whereas frontend and backend processes
come and go. come and go.
</Para>
<Para> <Para>
The <FileName>libpq</FileName> library allows a single The <FileName>libpq</FileName> library allows a single
@ -69,6 +71,7 @@
machine may not be accessible (or may only be accessed machine may not be accessible (or may only be accessed
using a different filename) on the database server using a different filename) on the database server
machine. machine.
</Para>
<Para> <Para>
You should also be aware that the <Application>postmaster</Application> and You should also be aware that the <Application>postmaster</Application> and
@ -81,5 +84,5 @@
case, all files relating to a database should belong to case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser. this <ProductName>Postgres</ProductName> superuser.
</Para> </Para>
</sect1>
</Chapter> </Chapter>

78
doc/src/sgml/bki.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.1 1998/08/15 06:49:33 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.2 1998/12/29 02:24:13 thomas Exp $
Transcribed from the original bki.man.5 documentation Transcribed from the original bki.man.5 documentation
- Thomas Lockhart 1998-08-03 - Thomas Lockhart 1998-08-03
@ -28,12 +28,14 @@ takes as input <productname>Postgres</productname> source files that double as
<application>genbki</application> <application>genbki</application>
input that builds tables and C header files that describe those input that builds tables and C header files that describe those
tables. tables.
</para>
<para> <para>
Related information may be found in documentation for Related information may be found in documentation for
<application>initdb</application>, <application>initdb</application>,
<application>createdb</application>, <application>createdb</application>,
and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>. and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>.
</para>
<sect1> <sect1>
<title><acronym>BKI</acronym> File Format</title> <title><acronym>BKI</acronym> File Format</title>
@ -44,6 +46,7 @@ description will be easier to understand if the <filename>global1.bki.source</fi
at hand as an example. (As explained above, this .source file isn't quite at hand as an example. (As explained above, this .source file isn't quite
a <acronym>BKI</acronym> file, but you'll be able to guess what the resulting <acronym>BKI</acronym> file would be a <acronym>BKI</acronym> file, but you'll be able to guess what the resulting <acronym>BKI</acronym> file would be
anyway). anyway).
</para>
<para> <para>
Commands are composed of a command name followed by space separated Commands are composed of a command name followed by space separated
@ -56,6 +59,7 @@ value. Otherwise, the characters following the <quote>$</quote> are
interpreted as the name of a macro causing the argument to be replaced interpreted as the name of a macro causing the argument to be replaced
with the macro's value. It is an error for this macro to be with the macro's value. It is an error for this macro to be
undefined. undefined.
</para>
<para> <para>
Macros are defined using Macros are defined using
@ -67,10 +71,13 @@ and are undefined using
undefine macro macro_name undefine macro macro_name
</programlisting> </programlisting>
and redefined using the same syntax as define. and redefined using the same syntax as define.
</para>
<para> <para>
Lists of general commands and macro commands Lists of general commands and macro commands
follow. follow.
</para>
</sect1>
<sect1> <sect1>
<title>General Commands</title> <title>General Commands</title>
@ -85,6 +92,9 @@ OPEN <replaceable class="parameter">classname</replaceable>
Open the class called Open the class called
<replaceable class="parameter">classname</replaceable> <replaceable class="parameter">classname</replaceable>
for further manipulation. for further manipulation.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -99,6 +109,9 @@ It is an error if
is not already opened. If no is not already opened. If no
<replaceable class="parameter">classname</replaceable> <replaceable class="parameter">classname</replaceable>
is given, then the currently open class is closed. is given, then the currently open class is closed.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -107,6 +120,9 @@ PRINT
<listitem> <listitem>
<para> <para>
Print the currently open class. Print the currently open class.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -123,6 +139,9 @@ for its OID. If
<replaceable class="parameter">oid_value</replaceable> <replaceable class="parameter">oid_value</replaceable>
is not <quote>0</quote>, then this value will be used as the instance's is not <quote>0</quote>, then this value will be used as the instance's
object identifier. Otherwise, it is an error. object identifier. Otherwise, it is an error.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -131,6 +150,9 @@ INSERT (<replaceable class="parameter">value1</replaceable> <replaceable class="
<listitem> <listitem>
<para> <para>
As above, but the system generates a unique object identifier. As above, but the system generates a unique object identifier.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -141,6 +163,9 @@ CREATE <replaceable class="parameter">classname</replaceable> (<replaceable clas
Create a class named Create a class named
<replaceable class="parameter">classname</replaceable> <replaceable class="parameter">classname</replaceable>
with the attributes given in parentheses. with the attributes given in parentheses.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -152,6 +177,9 @@ Open a class named
<replaceable class="parameter">classname</replaceable> <replaceable class="parameter">classname</replaceable>
for writing but do not record its existence in the system catalogs. for writing but do not record its existence in the system catalogs.
(This is primarily to aid in bootstrapping.) (This is primarily to aid in bootstrapping.)
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -161,6 +189,9 @@ DESTROY <replaceable class="parameter">classname</replaceable>
<para> <para>
Destroy the class named Destroy the class named
<replaceable class="parameter">classname</replaceable>. <replaceable class="parameter">classname</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -182,14 +213,18 @@ etc., and the operator collections to use are
<replaceable class="parameter">collection_1</replaceable>, <replaceable class="parameter">collection_1</replaceable>,
<replaceable class="parameter">collection_2</replaceable> <replaceable class="parameter">collection_2</replaceable>
etc., respectively. etc., respectively.
</para>
</listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<note> <note>
<para> <para>
This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04 This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04
</para>
</note> </note>
</sect1>
<sect1> <sect1>
<title>Macro Commands</title> <title>Macro Commands</title>
@ -211,6 +246,9 @@ computed from the execution
with the arguments with the arguments
<replaceable class="parameter">args</replaceable> <replaceable class="parameter">args</replaceable>
declared in a C-like manner. declared in a C-like manner.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -223,9 +261,13 @@ Define a macro named
which has its value which has its value
read from the file called read from the file called
<replaceable class="parameter">filename</replaceable>. <replaceable class="parameter">filename</replaceable>.
</para>
</listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</sect1>
<sect1> <sect1>
<title>Debugging Commands</title> <title>Debugging Commands</title>
@ -234,6 +276,7 @@ read from the file called
<note> <note>
<para> <para>
This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05 This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05
</para>
</note> </note>
<variablelist> <variablelist>
@ -244,6 +287,9 @@ r
<listitem> <listitem>
<para> <para>
Randomly print the open class. Randomly print the open class.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -252,6 +298,9 @@ m -1
<listitem> <listitem>
<para> <para>
Toggle display of time information. Toggle display of time information.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -260,6 +309,9 @@ m 0
<listitem> <listitem>
<para> <para>
Set retrievals to now. Set retrievals to now.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -268,6 +320,9 @@ m 1 Jan 1 01:00:00 1988
<listitem> <listitem>
<para> <para>
Set retrievals to snapshots of the specfied time. Set retrievals to snapshots of the specfied time.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -278,6 +333,9 @@ m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988
Set retrievals to ranges of the specified times. Set retrievals to ranges of the specified times.
Either time may be replaced with space Either time may be replaced with space
if an unbounded time range is desired. if an unbounded time range is desired.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -296,6 +354,9 @@ types
<replaceable class="parameter">type2</replaceable>, <replaceable class="parameter">type2</replaceable>,
etc. to the class etc. to the class
<replaceable class="parameter">classname</replaceable>. <replaceable class="parameter">classname</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -307,6 +368,9 @@ Rename the
<replaceable class="parameter">oldclassname</replaceable> <replaceable class="parameter">oldclassname</replaceable>
class to class to
<replaceable class="parameter">newclassname</replaceable>. <replaceable class="parameter">newclassname</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -323,9 +387,12 @@ attribute in the class named
<replaceable class="parameter">classname</replaceable> <replaceable class="parameter">classname</replaceable>
to to
<replaceable class="parameter">newattname</replaceable>. <replaceable class="parameter">newattname</replaceable>.
</para>
</listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</sect1>
<sect1> <sect1>
<title>Example</title> <title>Example</title>
@ -344,5 +411,6 @@ insert oid=421 (int_ops)
print print
close pg_opclass close pg_opclass
</programlisting> </programlisting>
</para>
</sect1>
</chapter> </chapter>

4
doc/src/sgml/compiler.sgml
View File

@ -17,6 +17,7 @@
Contributed by <ULink url="mailto:geek+@cmu.edu">Brian Gallew</ULink> Contributed by <ULink url="mailto:geek+@cmu.edu">Brian Gallew</ULink>
</Para> </Para>
</Note> </Note>
</para>
<Para> <Para>
Configuring gcc to use certain flags by default is a simple matter of Configuring gcc to use certain flags by default is a simple matter of
@ -28,6 +29,7 @@ sections, each of which is three lines long. The first line is
"*<Replaceable>section_name</Replaceable>:" (e.g. "*asm:"). "*<Replaceable>section_name</Replaceable>:" (e.g. "*asm:").
The second line is a list of flags, The second line is a list of flags,
and the third line is blank. and the third line is blank.
</para>
<Para> <Para>
The easiest change to make is to append The easiest change to make is to append
@ -64,10 +66,12 @@ box lying around, I'd have to make it look like this:
</ProgramListing> </ProgramListing>
This will always omit frame pointers, any will build 486-optimized This will always omit frame pointers, any will build 486-optimized
code unless -m386 is specified on the command line. code unless -m386 is specified on the command line.
</para>
<Para> <Para>
You can actually do quite a lot of customization with the specs file. You can actually do quite a lot of customization with the specs file.
Always remember, however, that these changes are global, and affect Always remember, however, that these changes are global, and affect
all users of the system. all users of the system.
</para>
</Chapter> </Chapter>

741
doc/src/sgml/config.sgml
View File

@ -1,21 +1,21 @@
<chapter id="config"> <chapter id="config">
<title id="install-config">Configuration Options</title> <title id="install-config">Configuration Options</title>
<sect1> <sect1>
<title>Parameters for Configuration (<application>configure</application>)</title> <title>Parameters for Configuration (<application>configure</application>)</title>
<para> <para>
The full set of parameters available in <application>configure</application> The full set of parameters available in <application>configure</application>
can be obtained by typing can be obtained by typing
<programlisting> <programlisting>
$ ./configure --help $ ./configure --help
</programlisting> </programlisting>
</para>
<para>
The following parameters may be of interest to installers:
<para> <programlisting>
The following parameters may be of interest to installers:
<programlisting>
Directory and file names: Directory and file names:
--prefix=PREFIX install architecture-independent files in PREFIX --prefix=PREFIX install architecture-independent files in PREFIX
[/usr/local/pgsql] [/usr/local/pgsql]
@ -47,143 +47,174 @@ Features and packages:
--enable-cassert enable assertion checks (debugging) --enable-cassert enable assertion checks (debugging)
--with-CC=<replaceable>compiler</replaceable> use specific C compiler --with-CC=<replaceable>compiler</replaceable> use specific C compiler
--with-CXX=<replaceable>compiler</replaceable> use specific C++ compiler --with-CXX=<replaceable>compiler</replaceable> use specific C++ compiler
</programlisting> </programlisting>
</para>
<para>
Some systems may have trouble building a specific feature of
<productname>Postgres</productname>. For example, systems with a damaged
C++ compiler may need to specify <option>--without-CXX</option> to encourage
the build procedure to ignore the <filename>libpq++</filename> construction.
</para>
</sect1>
<sect1>
<title>Parameters for Building (<application>make</application>)</title>
<para> <para>
Some systems may have trouble building a specific feature of Many installation-related parameters can be set in the building
<productname>Postgres</productname>. For example, systems with a damaged stage of <productname>Postgres</productname> installation.
C++ compiler may need to specify <option>--without-CXX</option> to encourage </para>
the build procedure to ignore the <filename>libpq++</filename> construction. <para>
In most cases, these parameters should be place in a file,
<filename>Makefile.custom</filename>, intended just for that purpose.
The default distribution does not contain this optional file, so you
will create it using a text editor of your choice. When upgrading installations,
you can simply copy your old Makefile.custom to the new installation before
doing the build.
<sect1> <synopsis>
<title>Parameters for Building (<application>make</application>)</title> make [ <replaceable>variable</replaceable>=<replaceable class="parameter">value</replaceable> [,...] ]
</synopsis>
</para>
<para>
A few of the many variables which can be specified are:
<para> <variablelist>
Many installation-related parameters can be set in the building <varlistentry>
stage of <productname>Postgres</productname> installation. <term>
<envar>POSTGRESDIR</envar>
</term>
<listitem>
<para>
Top of the installation tree.
</para>
</listitem>
</varlistentry>
<para> <varlistentry>
In most cases, these parameters should be place in a file, <term>
<filename>Makefile.custom</filename>, intended just for that purpose. <envar>BINDIR</envar>
The default distribution does not contain this optional file, so you </term>
will create it using a text editor of your choice. When upgrading installations, <listitem>
you can simply copy your old Makefile.custom to the new installation before <para>
doing the build. Location of applications and utilities.
</para>
</listitem>
</varlistentry>
<synopsis> <varlistentry>
make [ <replaceable>variable</replaceable>=<replaceable class="parameter">value</replaceable> [,...] ] <term>
</synopsis> <envar>LIBDIR</envar>
</term>
<listitem>
<para>
Location of object libraries, including shared libraries.
</para>
</listitem>
</varlistentry>
<para> <varlistentry>
A few of the many variables which can be specified are: <term>
<envar>HEADERDIR</envar>
</term>
<listitem>
<para>
Location of include files.
</para>
</listitem>
</varlistentry>
<variablelist> <varlistentry>
<varlistentry> <term>
<term> <envar>ODBCINST</envar>
<envar>POSTGRESDIR</envar> </term>
<listitem>
<para>
Location of installation-wide <application>psqlODBC</application>
(<acronym>ODBC</acronym>) configuration file.
</para>
</listitem>
</varlistentry>
<listitem> </variablelist>
<para> </para>
Top of the installation tree. <para>
There are other optional parameters which are not as commonly used.
Many of those listed below are appropriate when doing
<application>Postgres</application> server code development.
<varlistentry> <variablelist>
<term> <varlistentry>
<envar>BINDIR</envar> <term>
<envar>CFLAGS</envar>
</term>
<listitem>
<para>
Set flags for the C compiler.
Should be assigned with "+=" to retain relevant default parameters.
</para>
</listitem>
</varlistentry>
<listitem> <varlistentry>
<para> <term>
Location of applications and utilities. YFLAGS
</term>
<listitem>
<para>
Set flags for the yacc/bison parser. <option>-v</option> might be
used to help diagnose problems building a new parser.
Should be assigned with "+=" to retain relevant default parameters.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<envar>LIBDIR</envar> <envar>USE_TCL</envar>
</term>
<listitem>
<para>
Enable Tcl interface building.
</para>
</listitem>
</varlistentry>
<listitem> <varlistentry>
<para> <term>
Location of object libraries, including shared libraries. <envar>HSTYLE</envar>
</term>
<listitem>
<para>
DocBook <acronym>HTML</acronym> style sheets for building the
documentation from scratch.
Not used unless you are developing new documentation from the
DocBook-compatible <acronym>SGML</acronym> source documents in
<filename>doc/src/sgml/</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<envar>HEADERDIR</envar> <envar>PSTYLE</envar>
</term>
<listitem>
<para>
DocBook style sheets for building printed documentation from scratch.
Not used unless you are developing new documentation from the
DocBook-compatible <acronym>SGML</acronym> source documents in
<filename>doc/src/sgml/</filename>.
</para>
</listitem>
</varlistentry>
<listitem> </variablelist>
<para> </para>
Location of include files. <para>
Here is an example <filename>Makefile.custom</filename> for a
PentiumPro Linux system:
<varlistentry> <programlisting>
<term>
<envar>ODBCINST</envar>
<listitem>
<para>
Location of installation-wide <application>psqlODBC</application>
(<acronym>ODBC</acronym>) configuration file.
</variablelist>
<para>
There are other optional parameters which are not as commonly used.
Many of those listed below are appropriate when doing
<application>Postgres</application> server code development.
<variablelist>
<varlistentry>
<term>
<envar>CFLAGS</envar>
<listitem>
<para>
Set flags for the C compiler.
Should be assigned with "+=" to retain relevant default parameters.
<varlistentry>
<term>
YFLAGS
<listitem>
<para>
Set flags for the yacc/bison parser. <option>-v</option> might be
used to help diagnose problems building a new parser.
Should be assigned with "+=" to retain relevant default parameters.
<varlistentry>
<term>
<envar>USE_TCL</envar>
<listitem>
<para>
Enable Tcl interface building.
<varlistentry>
<term>
<envar>HSTYLE</envar>
<listitem>
<para>
DocBook <acronym>HTML</acronym> style sheets for building the
documentation from scratch.
Not used unless you are developing new documentation from the
DocBook-compatible <acronym>SGML</acronym> source documents in
<filename>doc/src/sgml/</filename>.
<varlistentry>
<term>
<envar>PSTYLE</envar>
<listitem>
<para>
DocBook style sheets for building printed documentation from scratch.
Not used unless you are developing new documentation from the
DocBook-compatible <acronym>SGML</acronym> source documents in
<filename>doc/src/sgml/</filename>.
</variablelist>
<para>
Here is an example <filename>Makefile.custom</filename> for a
PentiumPro Linux system:
<programlisting>
# Makefile.custom # Makefile.custom
# Thomas Lockhart 1998-03-01 # Thomas Lockhart 1998-03-01
@ -198,78 +229,79 @@ TK_LIB= -ltk
HSTYLE= /home/tgl/SGML/db118.d/docbook/html HSTYLE= /home/tgl/SGML/db118.d/docbook/html
PSTYLE= /home/tgl/SGML/db118.d/docbook/print PSTYLE= /home/tgl/SGML/db118.d/docbook/print
</programlisting> </programlisting>
</para>
</sect1>
<Sect1>
<Title>Locale Support</Title>
<Sect1> <Para>
<Title>Locale Support</Title> <Note>
<Para>
<Para> Written by Oleg Bartunov.
<Note> See <ULink url="http://www.sai.msu.su/~megera/postgres/">Oleg's web page</ULink>
<Para>
Written by Oleg Bartunov.
See <ULink url="http://www.sai.msu.su/~megera/postgres/">Oleg's web page</ULink>
for additional information on locale and Russian language support. for additional information on locale and Russian language support.
</Para> </Para>
</Note> </Note>
While doing a project for a company in Moscow, Russia, While doing a project for a company in Moscow, Russia,
I encountered the problem that postgresql had no I encountered the problem that postgresql had no
support of national alphabets. After looking for possible workarounds support of national alphabets. After looking for possible workarounds
I decided to develop support of locale myself. I decided to develop support of locale myself.
I'm not a C-programer but already had some experience with locale programming I'm not a C-programer but already had some experience with locale programming
when I work with perl when I work with perl
(debugging) and glimpse. After several days of digging through (debugging) and glimpse. After several days of digging through
the <ProductName>Postgres</ProductName> source tree I made very minor corections to the <ProductName>Postgres</ProductName> source tree I made very minor corections to
src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed! src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed!
I did support only for I did support only for
<envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>, <envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>,
but later <envar>LC_MONETARY</envar> was added by others. I got many but later <envar>LC_MONETARY</envar> was added by others. I got many
messages from people about this patch so I decided to send it to developers messages from people about this patch so I decided to send it to developers
and (to my surprise) it was and (to my surprise) it was
incorporated into the <productname>Postgres</productname> distribution. incorporated into the <productname>Postgres</productname> distribution.
</para>
<Para> <Para>
People often complain that locale doesn't work for them. People often complain that locale doesn't work for them.
There are several common mistakes: There are several common mistakes:
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
Didn't properly configure postgresql before compilation. Didn't properly configure postgresql before compilation.
You must run configure with --enable-locale option to enable locale support. You must run configure with --enable-locale option to enable locale support.
Didn't setup environment correctly when starting postmaster. Didn't setup environment correctly when starting postmaster.
You must define environment variables You must define environment variables
<envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar> <envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>
before running postmaster before running postmaster
because backend gets information about locale from environment. because backend gets information about locale from environment.
I use following shell script I use following shell script
(runpostgres): (runpostgres):
<ProgramListing> <ProgramListing>
#!/bin/sh #!/bin/sh
export LC_CTYPE=koi8-r export LC_CTYPE=koi8-r
export LC_COLLATE=koi8-r export LC_COLLATE=koi8-r
postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe'
</ProgramListing> </ProgramListing>
and run it from rc.local as and run it from rc.local as
<ProgramListing> <ProgramListing>
/bin/su - postgres -c "/home/postgres/runpostgres" /bin/su - postgres -c "/home/postgres/runpostgres"
</ProgramListing> </ProgramListing>
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
Broken locale support in OS (for example, locale support in libc Broken locale support in OS (for example, locale support in libc
under Linux several times has changed under Linux several times has changed
and this caused a lot of problems). Latest perl has also support of and this caused a lot of problems). Latest perl has also support of
locale and if locale is broken <command>perl -v</command> will locale and if locale is broken <command>perl -v</command> will
complain something like: complain something like:
<programlisting> <programlisting>
8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist
8:18[mira]:~/WWW/postgres>perl -v 8:18[mira]:~/WWW/postgres>perl -v
perl: warning: Setting locale failed. perl: warning: Setting locale failed.
@ -279,194 +311,215 @@ locale and if locale is broken <command>perl -v</command> will
LANG = (unset) LANG = (unset)
are supported and installed on your system. are supported and installed on your system.
perl: warning: Falling back to the standard locale ("C"). perl: warning: Falling back to the standard locale ("C").
</programlisting> </programlisting>
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
Wrong location of locale files! Wrong location of locale files!
Possible locations include: Possible locations include:
<filename>/usr/lib/locale</filename> <filename>/usr/lib/locale</filename>
(Linux, Solaris), <filename>/usr/share/locale</filename> (Linux), (Linux, Solaris), <filename>/usr/share/locale</filename> (Linux),
<filename>/usr/lib/nls/loc</filename> (DUX 4.0). <filename>/usr/lib/nls/loc</filename> (DUX 4.0).
Check <command>man locale</command> to find the correct location. Check <command>man locale</command> to find the correct location.
Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and
<filename>/usr/share/locale</filename> to be sure that <filename>/usr/share/locale</filename> to be sure that
the next libc will not break my locale. the next libc will not break my locale.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
<Sect2> <Sect2>
<Title>What are the Benefits?</Title> <Title>What are the Benefits?</Title>
<Para> <Para>
You can use ~* and order by operators for strings contain characters You can use ~* and order by operators for strings contain characters
from national alphabets. Non-english users from national alphabets. Non-english users
definitely need that. If you won't use locale stuff just undefine definitely need that. If you won't use locale stuff just undefine
the USE_LOCALE variable. the USE_LOCALE variable.
</para>
</sect2>
<Sect2> <Sect2>
<Title>What are the Drawbacks?</Title> <Title>What are the Drawbacks?</Title>
<Para> <Para>
There is one evident drawback of using locale - it's speed! There is one evident drawback of using locale - it's speed!
So, use locale only if you really need it. So, use locale only if you really need it.
</para>
</sect2>
</sect1>
<Sect1>
<Title>Kerberos Authentication</Title>
<Sect1> <Para>
<Title>Kerberos Authentication</Title> <productname>Kerberos</productname> is an industry-standard secure authentication
system suitable for distributed computing over a public network.
</para>
<Para> <sect2>
<productname>Kerberos</productname> is an industry-standard secure authentication <title>Availability</title>
system suitable for distributed computing over a public network.
<sect2> <para>
<title>Availability</title> The
<productname>Kerberos</productname>
authentication system is not distributed with <Productname>Postgres</Productname>. Versions of
<productname>Kerberos</productname>
are typically available as optional software from operating system
vendors. In addition, a source code distribution may be obtained through
<ulink url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink>.
</para>
<note>
<para>
You may wish to obtain the MIT version even if your
vendor provides a version, since some vendor ports have been
deliberately crippled or rendered non-interoperable with the MIT
version.
</para>
</note>
<para>
Users located outside the United States of America and
Canada are warned that distribution of the actual encryption code in
<productname>Kerberos</productname>
is restricted by U. S. Government export regulations.
</para>
<para>
Inquiries regarding your <productname>Kerberos</productname>
should be directed to your vendor or
<ulink url="info-kerberos@athena.mit.edu">MIT Project Athena</ulink>.
Note that <acronym>FAQL</acronym>s
(Frequently-Asked Questions Lists) are periodically posted to the
<ulink url="mailto:kerberos@ATHENA.MIT.EDU"><productname>Kerberos</productname> mailing list</ulink>
(send
<ulink url="mailto:kerberos-request@ATHENA.MIT.EDU">mail to subscribe</ulink>),
and
<ulink url="news:comp.protocols.kerberos">USENET news group</ulink>.
</para>
</sect2>
<para> <sect2>
The <title>Installation</title>
<productname>Kerberos</productname>
authentication system is not distributed with <Productname>Postgres</Productname>. Versions of
<productname>Kerberos</productname>
are typically available as optional software from operating system
vendors. In addition, a source code distribution may be obtained through
<ulink url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink>.
<note> <para>
<para> Installation of
You may wish to obtain the MIT version even if your <productname>Kerberos</productname>
vendor provides a version, since some vendor ports have been itself is covered in detail in the
deliberately crippled or rendered non-interoperable with the MIT <citetitle>Kerberos Installation Notes</citetitle> .
version. Make sure that the server key file (the <filename>srvtab</filename>
</note> or <filename>keytab</filename>)
Users located outside the United States of America and is somehow readable by the <productname>Postgres</productname> account.
Canada are warned that distribution of the actual encryption code in </para>
<productname>Kerberos</productname> <para>
is restricted by U. S. Government export regulations. <Productname>Postgres</Productname> and its clients can be compiled to use
either Version 4 or Version 5 of the MIT
<para> <productname>Kerberos</productname>
Inquiries regarding your <productname>Kerberos</productname> protocols by setting the
should be directed to your vendor or <envar>KRBVERS</envar>
<ulink url="info-kerberos@athena.mit.edu">MIT Project Athena</ulink>. variable in the file <filename>src/Makefile.global</filename> to the
Note that <acronym>FAQL</acronym>s appropriate value. You can also change the location where
(Frequently-Asked Questions Lists) are periodically posted to the
<ulink url="mailto:kerberos@ATHENA.MIT.EDU"><productname>Kerberos</productname> mailing list</ulink>
(send
<ulink url="mailto:kerberos-request@ATHENA.MIT.EDU">mail to subscribe</ulink>),
and
<ulink url="news:comp.protocols.kerberos">USENET news group</ulink>.
<sect2>
<title>Installation</title>
<para>
Installation of
<productname>Kerberos</productname>
itself is covered in detail in the
<citetitle>Kerberos Installation Notes</citetitle> .
Make sure that the server key file (the <filename>srvtab</filename>
or <filename>keytab</filename>)
is somehow readable by the <productname>Postgres</productname> account.
<para>
<Productname>Postgres</Productname> and its clients can be compiled to use
either Version 4 or Version 5 of the MIT
<productname>Kerberos</productname>
protocols by setting the
<envar>KRBVERS</envar>
variable in the file <filename>src/Makefile.global</filename> to the
appropriate value. You can also change the location where
<Productname>Postgres</Productname> <Productname>Postgres</Productname>
expects to find the associated libraries, header files and its own expects to find the associated libraries, header files and its own
server key file. server key file.
</para>
<para> <para>
After compilation is complete, <Productname>Postgres</Productname> After compilation is complete, <Productname>Postgres</Productname>
must be registered as a <productname>Kerberos</productname> must be registered as a <productname>Kerberos</productname>
service. See the service. See the
<citetitle>Kerberos Operations Notes</citetitle> <citetitle>Kerberos Operations Notes</citetitle>
and related manual pages for more details on registering services. and related manual pages for more details on registering services.
</para>
</sect2>
<sect2> <sect2>
<title>Operation</title> <title>Operation</title>
<para> <para>
After initial installation, <Productname>Postgres</Productname> After initial installation, <Productname>Postgres</Productname>
should operate in all ways as a normal should operate in all ways as a normal
<productname>Kerberos</productname> <productname>Kerberos</productname>
service. For details on the use of authentication, see the service. For details on the use of authentication, see the
<citetitle>PostgreSQL User's Guide</citetitle> reference sections <citetitle>PostgreSQL User's Guide</citetitle> reference sections
for <application>postmaster</application> for <application>postmaster</application>
and <application>psql</application>. and <application>psql</application>.
</para>
<para>
In the
<productname>Kerberos</productname>
Version 5 hooks, the following assumptions are made about user
and service naming:
<para> <itemizedlist>
In the <listitem>
<productname>Kerberos</productname> <para>
Version 5 hooks, the following assumptions are made about user User principal names (anames) are assumed to
and service naming: contain the actual Unix/<Productname>Postgres</Productname> user name
<itemizedlist>
<listitem>
<para>
User principal names (anames) are assumed to
contain the actual Unix/<Productname>Postgres</Productname> user name
in the first component. in the first component.
</para>
<listitem> </listitem>
<para> <listitem>
The <Productname>Postgres</Productname> service is assumed to be have two components, <para>
The <Productname>Postgres</Productname> service is assumed to be have two components,
the service name and a hostname, canonicalized as in Version 4 (i.e., with all domain the service name and a hostname, canonicalized as in Version 4 (i.e., with all domain
suffixes removed). suffixes removed).
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<para>
<table tocentry="1">
<title>Kerberos Parameter Examples</title>
<titleabbrev>Kerberos</titleabbrev>
<para> <tgroup cols="2">
<table tocentry="1"> <thead>
<title>Kerberos Parameter Examples</title> <row>
<titleabbrev>Kerberos</titleabbrev> <entry>
Parameter
<tgroup cols="2"> </entry>
<thead> <entry>
<row> Example
<entry> </entry>
Parameter </row>
</entry> </thead>
<entry> <tbody>
Example <row>
</entry> <entry>
user
<tbody> </entry>
<row> <entry>
<entry> frew@S2K.ORG
user </entry>
</entry> </row>
<entry> <row>
frew@S2K.ORG <entry>
</entry> user
</entry>
<row> <entry>
<entry> aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
user </entry>
</entry> </row>
<entry> <row>
aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG <entry>
</entry> host
</entry>
<row> <entry>
<entry> postgres_dbms/ucbvax@S2K.ORG
host </entry>
</entry> </row>
<entry> </tbody>
postgres_dbms/ucbvax@S2K.ORG </tgroup>
</entry> </table>
</tbody> </para>
</tgroup> <para>
</table> Support for Version 4 will disappear sometime after the production
release of Version 5 by MIT.
<para> </para>
Support for Version 4 will disappear sometime after the production </sect2>
release of Version 5 by MIT. </sect1>
</chapter>

25
doc/src/sgml/current.sgml
View File

@ -24,21 +24,28 @@ Here is a brief, incomplete summary:
Views and rules are now functional thanks to extensive new code in the Views and rules are now functional thanks to extensive new code in the
rewrite rules system from Jan Wieck. He also wrote a chapter on it rewrite rules system from Jan Wieck. He also wrote a chapter on it
for the <citetitle>Programmer's Guide</citetitle>. for the <citetitle>Programmer's Guide</citetitle>.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Jan also contributed a second procedural language, PL/pgSQL, to go with the Jan also contributed a second procedural language, PL/pgSQL, to go with the
original PL/pgTCL procedural language he contributed last release. original PL/pgTCL procedural language he contributed last release.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
We have optional multiple-byte character set support from Tatsuo Iishi We have optional multiple-byte character set support from Tatsuo Iishi
to complement our existing locale support. to complement our existing locale support.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Client/server communications has been cleaned up, with better support for Client/server communications has been cleaned up, with better support for
asynchronous messages and interrupts thanks to Tom Lane. asynchronous messages and interrupts thanks to Tom Lane.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
@ -48,6 +55,8 @@ with target columns. This uses a generic mechanism which supports
the type extensibility features of <productname>Postgres</productname>. the type extensibility features of <productname>Postgres</productname>.
There is a new chapter in the <citetitle>User's Guide</citetitle> There is a new chapter in the <citetitle>User's Guide</citetitle>
which covers this topic. which covers this topic.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
@ -58,20 +67,26 @@ type available on some platforms. See the chapter on data types
in the <citetitle>User's Guide</citetitle> for details. in the <citetitle>User's Guide</citetitle> for details.
A fourth type, <type>serial</type>, is now supported by the parser as an A fourth type, <type>serial</type>, is now supported by the parser as an
amalgam of the <type>int4</type> type, a sequence, and a unique index. amalgam of the <type>int4</type> type, a sequence, and a unique index.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Several more <acronym>SQL92</acronym>-compatible syntax features have been Several more <acronym>SQL92</acronym>-compatible syntax features have been
added, including <command>INSERT DEFAULT VALUES</command> added, including <command>INSERT DEFAULT VALUES</command>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
The automatic configuration and installation system has received some The automatic configuration and installation system has received some
attention, and should be more robust for more platforms than it has ever attention, and should be more robust for more platforms than it has ever
been. been.
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<sect2> <sect2>
<title>Migration to v6.4</title> <title>Migration to v6.4</title>
@ -81,8 +96,8 @@ A dump/restore using <application>pg_dump</application>
or <application>pg_dumpall</application> or <application>pg_dumpall</application>
is required for those wishing to migrate data from any is required for those wishing to migrate data from any
previous release of <productname>Postgres</productname>. previous release of <productname>Postgres</productname>.
</para>
</sect2>
<sect2> <sect2>
<title>Detailed Change List</title> <title>Detailed Change List</title>
@ -282,6 +297,6 @@ configure uses supplied install-sh if no install script found(Tom)
new Makefile.shlib for shared library configuration(Tom) new Makefile.shlib for shared library configuration(Tom)
</programlisting> </programlisting>
</Para> </Para>
</sect2>
</Sect1> </Sect1>

5
doc/src/sgml/dfunc.sgml
View File

@ -33,8 +33,10 @@ mechanism. On the other hand, the object file must be
postprocessed a bit before it can be loaded into <ProductName>Postgres</ProductName>. We postprocessed a bit before it can be loaded into <ProductName>Postgres</ProductName>. We
hope that the large increase in speed and reliability will hope that the large increase in speed and reliability will
make up for the slight decrease in convenience. make up for the slight decrease in convenience.
<Para> </para>
</Tip> </Tip>
</para>
<para>
You should expect to read (and reread, and re-reread) the You should expect to read (and reread, and re-reread) the
manual pages for the C compiler, cc(1), and the link manual pages for the C compiler, cc(1), and the link
editor, ld(1), if you have specific questions. In editor, ld(1), if you have specific questions. In
@ -120,6 +122,7 @@ The GNU C compiler usually does not provide the special
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
<Sect1> <Sect1>
<Title><Acronym>ULTRIX</Acronym></Title> <Title><Acronym>ULTRIX</Acronym></Title>

101
doc/src/sgml/docguide.sgml
View File

@ -1,9 +1,14 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.12 1998/12/18 16:17:29 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.13 1998/12/29 02:24:14 thomas Exp $
Documentation Guide Documentation Guide
Thomas Lockhart Thomas Lockhart
$Log: docguide.sgml,v $ $Log: docguide.sgml,v $
Revision 1.13 1998/12/29 02:24:14 thomas
Clean up to ensure tag completion as required by the newest versions
of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@michvhf.com>.
Revision 1.12 1998/12/18 16:17:29 thomas Revision 1.12 1998/12/18 16:17:29 thomas
Include more details on editing with Emacs. Include more details on editing with Emacs.
Remove mention of the old "migration" flat files. Remove mention of the old "migration" flat files.
@ -59,6 +64,7 @@ system, language, and interfaces.
It should be able to answer It should be able to answer
common questions and to allow a user to find those answers on his own common questions and to allow a user to find those answers on his own
without resorting to mailing list support. without resorting to mailing list support.
</para>
<sect1> <sect1>
<title>Documentation Roadmap</title> <title>Documentation Roadmap</title>
@ -81,6 +87,7 @@ Hardcopy, for in-depth reading and reference.
<acronym>man pages</acronym>, for quick reference. <acronym>man pages</acronym>, for quick reference.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para>
<para> <para>
<table tocentry="1"> <table tocentry="1">
@ -115,11 +122,14 @@ Description
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para>
<para> <para>
There are man pages available for installation, as well as a large number There are man pages available for installation, as well as a large number
of plain-text README-type files throughout the <productname>Postgres</productname> of plain-text README-type files throughout the <productname>Postgres</productname>
source tree. source tree.
</para>
</sect1>
<sect1> <sect1>
<title>The Documentation Project</title> <title>The Documentation Project</title>
@ -131,6 +141,7 @@ formats. These are available as part of the standard
<productname>Postgres</productname> installation. We discuss here <productname>Postgres</productname> installation. We discuss here
working with the documentation sources and generating documentation working with the documentation sources and generating documentation
packages. packages.
</para>
<para> <para>
The purpose of <productname>DocBook</productname> <acronym>SGML</acronym> The purpose of <productname>DocBook</productname> <acronym>SGML</acronym>
@ -141,6 +152,7 @@ have a document style define how that content is rendered into a
final form (e.g. using Norm Walsh's final form (e.g. using Norm Walsh's
<productname>Modular Style Sheets</productname>).</para> <productname>Modular Style Sheets</productname>).</para>
<para> <para>
See <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html"> See <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">
Introduction to DocBook</ulink> for a nice "quickstart" summary of Introduction to DocBook</ulink> for a nice "quickstart" summary of
@ -148,6 +160,7 @@ DocBook features.
<ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/"> DocBook Elements</ulink> <ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/"> DocBook Elements</ulink>
provides a powerful cross-reference for features of provides a powerful cross-reference for features of
<productname>DocBook</productname>. <productname>DocBook</productname>.
</para>
<para> <para>
This documentation set is constructed using several tools, including This documentation set is constructed using several tools, including
@ -155,6 +168,7 @@ James Clark's
<ulink url="http://www.jclark.com/jade/"> <productname>jade</productname></ulink> <ulink url="http://www.jclark.com/jade/"> <productname>jade</productname></ulink>
and Norm Walsh's and Norm Walsh's
<ulink url="http://www.berkshire.net/~norm/docbook/dsssl">Modular DocBook Stylesheets</ulink>. <ulink url="http://www.berkshire.net/~norm/docbook/dsssl">Modular DocBook Stylesheets</ulink>.
</para>
<para> <para>
Currently, hardcopy is produced by importing <firstterm>Rich Text Currently, hardcopy is produced by importing <firstterm>Rich Text
@ -163,6 +177,7 @@ Format</firstterm> (<acronym>RTF</acronym>) output from
<productname>ApplixWare</productname> for minor formatting fixups then <productname>ApplixWare</productname> for minor formatting fixups then
exporting as a Postscript file.</para> exporting as a Postscript file.</para>
<para> <para>
<ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/"> <ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/">
<productname>TeX</productname></ulink> is a supported format for <productname>TeX</productname></ulink> is a supported format for
@ -172,6 +187,8 @@ fixes before committing to hardcopy and generally inadequate table
support in the <productname>TeX</productname> support in the <productname>TeX</productname>
stylesheets.</para> stylesheets.</para>
</sect1>
<sect1> <sect1>
<title>Documentation Sources</title> <title>Documentation Sources</title>
@ -183,6 +200,7 @@ most new <productname>Postgres</productname> documentation will be written using
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink> <ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>). <firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>. Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
</para>
<para> <para>
The purpose of <acronym>SGML</acronym> is to allow an author to The purpose of <acronym>SGML</acronym> is to allow an author to
@ -190,6 +208,7 @@ specify the structure and content of a document (e.g. using the
<productname>DocBook</productname> <acronym>DTD</acronym>), and to <productname>DocBook</productname> <acronym>DTD</acronym>), and to
have the document style define how that content is rendered into a have the document style define how that content is rendered into a
final form (e.g. using Norm Walsh's stylesheets). final form (e.g. using Norm Walsh's stylesheets).
</para>
<para> <para>
Documentation has accumulated from several sources. As we integrate Documentation has accumulated from several sources. As we integrate
@ -198,6 +217,7 @@ the older versions will become obsolete and will be removed from the
distribution. However, this will not happen immediately, and will not distribution. However, this will not happen immediately, and will not
happen to all documents at the same time. To ease the transition, and happen to all documents at the same time. To ease the transition, and
to help guide developers and writers, we have defined a transition roadmap. to help guide developers and writers, we have defined a transition roadmap.
</para>
<para> <para>
Here is the documentation plan for v6.5: Here is the documentation plan for v6.5:
@ -206,30 +226,41 @@ Here is the documentation plan for v6.5:
<listitem> <listitem>
<para> <para>
Start compiling index information for the User's and Administrator's Guides. Start compiling index information for the User's and Administrator's Guides.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Write more sections for the User's Guide covering areas outside the reference pages. Write more sections for the User's Guide covering areas outside the reference pages.
This would include introductory information and suggestions for approaches to typical This would include introductory information and suggestions for approaches to typical
design problems. design problems.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Merge information in the existing man pages into the reference pages and User's Guide. Merge information in the existing man pages into the reference pages and User's Guide.
Condense the man pages down to reminder information, with references into the Condense the man pages down to reminder information, with references into the
primary doc set. primary doc set.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Convert the new sgml reference pages to new man pages, replacing the existing man pages. Convert the new sgml reference pages to new man pages, replacing the existing man pages.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Convert all source graphics to CGM format files for portability. Currently we mostly have Convert all source graphics to CGM format files for portability. Currently we mostly have
Applix Graphics sources from which we can generate .gif output. One graphic is only Applix Graphics sources from which we can generate .gif output. One graphic is only
available in .gif and .ps, and should be redrawn or removed. available in .gif and .ps, and should be redrawn or removed.
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<sect2> <sect2>
<title>Document Structure</title> <title>Document Structure</title>
@ -304,12 +335,14 @@ The Administrator's Guide. Include installation and release notes.
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
<!-- <!--
Disable for the hardcopy production release. Disable for the hardcopy production release.
Too much tabular info and not very helpful in hardcopy. Too much tabular info and not very helpful in hardcopy.
- thomas 1998-10-27 - thomas 1998-10-27
--> -->
</sect2>
<sect2> <sect2>
<title>Documentation Files</title> <title>Documentation Files</title>
@ -482,6 +515,8 @@ Status
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para>
</sect2>
<sect2> <sect2>
<title>Document Conversion</title> <title>Document Conversion</title>
@ -719,7 +754,8 @@ Status
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para>
</sect2>
<sect2> <sect2>
<title>Styles and Conventions</title> <title>Styles and Conventions</title>
@ -766,6 +802,7 @@ be included below.
</table> </table>
</para> </para>
--> -->
</sect2>
<sect2> <sect2>
<title>SGML Authoring Tools</title> <title>SGML Authoring Tools</title>
@ -774,12 +811,14 @@ be included below.
The current <acronym>Postgres</acronym> documentation set was written using The current <acronym>Postgres</acronym> documentation set was written using
a plain text editor (or emacs/psgml; see below) with the content marked up using a plain text editor (or emacs/psgml; see below) with the content marked up using
<acronym>SGML</acronym> DocBook tags. <acronym>SGML</acronym> DocBook tags.
</para>
<para> <para>
<acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer <acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer
from an oversupply of open-source authoring tools. The most common toolset is from an oversupply of open-source authoring tools. The most common toolset is
the emacs/xemacs editing package with the psgml feature extension. the emacs/xemacs editing package with the psgml feature extension.
On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation. On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
</para>
<sect3> <sect3>
<title>emacs/psgml</title> <title>emacs/psgml</title>
@ -789,6 +828,7 @@ On some systems (e.g. RedHat Linux) these tools are provided in a typical full i
an <acronym>SGML</acronym> <firstterm>major mode</firstterm>. When properly configured, an <acronym>SGML</acronym> <firstterm>major mode</firstterm>. When properly configured,
this will allow you to use <application>emacs</application> to insert tags and this will allow you to use <application>emacs</application> to insert tags and
check markup consistancy. check markup consistancy.
</para>
<para> <para>
Put the following in your <filename>~/.emacs</filename> environment file: Put the following in your <filename>~/.emacs</filename> environment file:
@ -832,13 +872,15 @@ sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog" sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil sgml-local-ecat-files:nil
End: End:
--<sgmltag> --</sgmltag>
</programlisting> </programlisting>
</para>
<para> <para>
The <productname>Postgres</productname> distribution includes a The <productname>Postgres</productname> distribution includes a
parsed DTD definitions file <filename>reference.ced</filename>. parsed DTD definitions file <filename>reference.ced</filename>.
You may find that You may find that
</para>
<para> <para>
When using <application>emacs</application>/psgml, a comfortable way of working with When using <application>emacs</application>/psgml, a comfortable way of working with
@ -853,6 +895,7 @@ a DocBook document by making the first line look like this:
This means that anything and everything that reads <acronym>SGML</acronym> will get it This means that anything and everything that reads <acronym>SGML</acronym> will get it
right, and I can verify the document with "nsgmls -s docguide.sgml". right, and I can verify the document with "nsgmls -s docguide.sgml".
</para>
</sect3> </sect3>
</sect2> </sect2>
@ -893,6 +936,7 @@ On many systems, these stylesheets will be found in packages installed in
<filename>/usr/share/lib/sgml/</filename>, <filename>/usr/share/lib/sgml/</filename>,
or or
<filename>/usr/local/lib/sgml/</filename>. <filename>/usr/local/lib/sgml/</filename>.
</para>
<para> <para>
<acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by <acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by
@ -926,6 +970,7 @@ The hardcopy Postscript documentation is generated by converting the
importing into <productname>ApplixWare-4.4.1</productname>. importing into <productname>ApplixWare-4.4.1</productname>.
After a little cleanup (see the following After a little cleanup (see the following
section) the output is "printed" to a postscript file. section) the output is "printed" to a postscript file.
</para>
<para> <para>
Some figures were redrawn to avoid having bitmap Some figures were redrawn to avoid having bitmap
@ -1066,6 +1111,7 @@ We understand that there are some other packaged distributions for
these tools. <productname>FreeBSD</productname> seems to have them these tools. <productname>FreeBSD</productname> seems to have them
available. Please report package status to the docs mailing list and available. Please report package status to the docs mailing list and
we will include that information here. we will include that information here.
</para>
<sect2> <sect2>
<title><acronym>RPM</acronym> installation on <title><acronym>RPM</acronym> installation on
@ -1086,6 +1132,7 @@ This is a brief run-through of the process of obtaining and
installing the software you'll need to edit DocBook source with Emacs installing the software you'll need to edit DocBook source with Emacs
and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym> and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym>
and <acronym>RTF</acronym>. and <acronym>RTF</acronym>.
</para>
<para> <para>
These instructions do not cover new <application>jade</application>/DocBook These instructions do not cover new <application>jade</application>/DocBook
@ -1093,6 +1140,7 @@ support in the
<ulink url="http://www.sgmltools.org/"><productname>sgml-tools</productname></ulink> <ulink url="http://www.sgmltools.org/"><productname>sgml-tools</productname></ulink>
package. The authors have not tried this package since it adopted DocBook, package. The authors have not tried this package since it adopted DocBook,
but it is almost certainly a good candidate for use. but it is almost certainly a good candidate for use.
</para>
<sect3><title>Prerequisites</title> <sect3><title>Prerequisites</title>
@ -1150,12 +1198,12 @@ Steve Pepper's Whirlwind Guide</ulink></para></listitem>
<listitem><para><ulink url="http://www.sil.org/sgml/publicSW.html"> <listitem><para><ulink url="http://www.sil.org/sgml/publicSW.html">
Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem> Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
</itemizedlist> </itemizedlist>
</para>
</sect3> </sect3>
<sect3> <sect3>
<title>Installing Jade</title> <title>Installing Jade</title>
<para>
<procedure> <procedure>
<title>Installing Jade</title> <title>Installing Jade</title>
@ -1164,6 +1212,8 @@ Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listi
<para> <para>
Read the installation instructions at the above listed Read the installation instructions at the above listed
URL. URL.
</para>
</step>
<step performance="required"> <step performance="required">
<para> <para>
@ -1173,6 +1223,7 @@ this will be something like
unzip -aU jade1_1.zip unzip -aU jade1_1.zip
</programlisting> </programlisting>
</para> </para>
</step>
<step performance="required"> <step performance="required">
<para><productname>Jade</productname> is not built using <para><productname>Jade</productname> is not built using
@ -1215,21 +1266,23 @@ doesn't need the above settings for the math library and the
<command>ranlib</command> command, leave them as they are in the <command>ranlib</command> command, leave them as they are in the
<filename>Makefile</filename>. <filename>Makefile</filename>.
</para> </para>
</step>
<step performance="required"> <step performance="required">
<para>Type <command>make</command> to build Jade and the various <para>Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para> <productname>SP</productname> tools.</para>
</step>
<step performance="required"> <step performance="required">
<para>Once the software is built, <command>make install</command> will <para>Once the software is built, <command>make install</command> will
do the obvious.</para> do the obvious.</para>
</step>
</procedure> </procedure>
</sect3>
<sect3> <sect3>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title> <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<para>
<procedure> <procedure>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title> <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
@ -1255,6 +1308,8 @@ the former, by giving it the single line of content:
<programlisting> <programlisting>
CATALOG /usr/local/share/sgml/CATALOG CATALOG /usr/local/share/sgml/CATALOG
</programlisting> </programlisting>
</para>
</step>
<step performance="required"> <step performance="required">
<para> <para>
@ -1274,6 +1329,8 @@ PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
</programlisting> </programlisting>
</para>
</step>
<step performance="required"> <step performance="required">
<para> <para>
@ -1296,12 +1353,13 @@ we've placed the <acronym>ISO</acronym> entity files in a subdirectory
named <filename>ISO</filename>. Again, proper catalog entries should named <filename>ISO</filename>. Again, proper catalog entries should
accompany the entity kit you fetch. accompany the entity kit you fetch.
</para> </para>
</step>
</procedure> </procedure>
</sect3>
<sect3> <sect3>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title> <title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<para>
<procedure> <procedure>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title> <title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
@ -1309,6 +1367,7 @@ accompany the entity kit you fetch.
<step performance="required"> <step performance="required">
<para>Read the installation instructions at the above listed <para>Read the installation instructions at the above listed
URL.</para> URL.</para>
</step>
<step performance="required"> <step performance="required">
<para>To install Norman's style sheets, simply unzip the distribution <para>To install Norman's style sheets, simply unzip the distribution
@ -1320,11 +1379,13 @@ The command will be something like
unzip -aU db119.zip unzip -aU db119.zip
</programlisting> </programlisting>
</para> </para>
</step>
<step performance="required"> <step performance="required">
<para>One way to test the installation is to build the <para>One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the <acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
<citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>. <citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>.
</para>
<substeps> <substeps>
@ -1336,9 +1397,12 @@ directory, <filename>doc/src/sgml</filename>, and say
<programlisting> <programlisting>
jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
</programlisting> </programlisting>
</para>
<para> <para>
<filename>book1.htm</filename> is the top level node of the output.. <filename>book1.htm</filename> is the top level node of the output..
</para>
</step>
<step performance="required"> <step performance="required">
<para> <para>
@ -1347,14 +1411,17 @@ into your favorite word processing system and printing, type:
<programlisting> <programlisting>
jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
</programlisting> </programlisting>
</para>
</step>
</substeps> </substeps>
</step>
</procedure> </procedure>
</sect3>
<sect3> <sect3>
<title>Installing <productname>PSGML</productname></title> <title>Installing <productname>PSGML</productname></title>
<para>
<procedure> <procedure>
<title>Installing <productname>PSGML</productname></title> <title>Installing <productname>PSGML</productname></title>
@ -1362,10 +1429,13 @@ jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgre
<step performance="required"> <step performance="required">
<para>Read the installation instructions at the above listed <para>Read the installation instructions at the above listed
URL.</para> URL.</para>
</step>
<step performance="required"> <step performance="required">
<para>Unpack the distribution file, run configure, make and make <para>Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place. install to put the byte-compiled files and info library in place.
</para>
</step>
<step performance="required" id="psgml-setup"> <step performance="required" id="psgml-setup">
<para> <para>
@ -1378,6 +1448,8 @@ file to make <productname>Emacs</productname> properly load
(cons "/usr/local/share/emacs/site-lisp/psgml" load-path)) (cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t) (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
</programlisting> </programlisting>
</para>
</step>
<step performance="optional"> <step performance="optional">
<para> <para>
@ -1388,7 +1460,7 @@ If you want to use <productname>PSGML</productname> when editing
(cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist)) (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
</programlisting> </programlisting>
</para> </para>
</step>
<step performance="optional"> <step performance="optional">
<para>There is one important thing to note with <para>There is one important thing to note with
@ -1397,18 +1469,23 @@ If you want to use <productname>PSGML</productname> when editing
<filename>/usr/local/lib/sgml</filename>. If, as in the examples in <filename>/usr/local/lib/sgml</filename>. If, as in the examples in
this chapter, you use <filename>/usr/local/share/sgml</filename>, you this chapter, you use <filename>/usr/local/share/sgml</filename>, you
have to compensate for this. have to compensate for this.
</para>
<substeps> <substeps>
<step performance="optional"> <step performance="optional">
<para> <para>
You can set the You can set the
<filename>SGML_CATALOG_FILES</filename> environment variable. <filename>SGML_CATALOG_FILES</filename> environment variable.
</para>
</step>
<step performance="optional"> <step performance="optional">
<para> <para>
You can You can
customize your <productname>PSGML</productname> installation (its customize your <productname>PSGML</productname> installation (its
manual tells you how). manual tells you how).
</para>
</step>
<step performance="optional"> <step performance="optional">
<para> <para>
@ -1416,10 +1493,13 @@ You can even edit the source file
<filename>psgml.el</filename> before compiling and installing <filename>psgml.el</filename> before compiling and installing
<productname>PSGML</productname>, changing the hard-coded paths to <productname>PSGML</productname>, changing the hard-coded paths to
match your own default.</para> match your own default.</para>
</step>
</substeps> </substeps>
</step>
</procedure> </procedure>
</sect3>
<sect3><title>Installing <productname>JadeTeX</productname></title> <sect3><title>Installing <productname>JadeTeX</productname></title>
@ -1503,6 +1583,7 @@ now supports <application>jade</application>
and <productname>DocBook</productname>. It may be the preferred toolset and <productname>DocBook</productname>. It may be the preferred toolset
for working with <acronym>SGML</acronym> but we have not had a chance to for working with <acronym>SGML</acronym> but we have not had a chance to
evaluate the new package. evaluate the new package.
</para>
<!-- <!--
@ -1570,7 +1651,7 @@ Run <productname>texhash</productname> to update the tex database.
</para></sect2></sect1> </para></sect2></sect1>
--> -->
</sect1>
</appendix> </appendix>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

75
doc/src/sgml/ecpg.sgml
View File

@ -37,7 +37,7 @@ Permission is granted to copy and use in the same way as you are allowed
to copy and use the rest of the <ProductName>PostgreSQL</ProductName>. to copy and use the rest of the <ProductName>PostgreSQL</ProductName>.
</Para> </Para>
</Note> </Note>
</para>
<Sect1> <Sect1>
<Title>Why Embedded <Acronym>SQL</Acronym>?</Title> <Title>Why Embedded <Acronym>SQL</Acronym>?</Title>
@ -48,6 +48,7 @@ queries. It takes care of all the tedious moving of information to and
from variables in your <Acronym>C</Acronym> program. from variables in your <Acronym>C</Acronym> program.
Many <Acronym>RDBMS</Acronym> packages Many <Acronym>RDBMS</Acronym> packages
support this embedded language. support this embedded language.
</Para>
<Para> There is an ANSI-standard describing how the embedded language should <Para> There is an ANSI-standard describing how the embedded language should
work. <Application>ecpg</Application> was designed to meet this standard work. <Application>ecpg</Application> was designed to meet this standard
@ -56,7 +57,8 @@ possible to port programs with embedded <Acronym>SQL</Acronym> written for
other <Acronym>RDBMS</Acronym> packages to other <Acronym>RDBMS</Acronym> packages to
<ProductName>Postgres</ProductName> and thus promoting the spirit of free <ProductName>Postgres</ProductName> and thus promoting the spirit of free
software. software.
</Para>
</sect1>
<Sect1> <Sect1>
<Title>The Concept</Title> <Title>The Concept</Title>
@ -67,6 +69,7 @@ For declaring variables that can be used in
<Acronym>SQL</Acronym> statements you need to <Acronym>SQL</Acronym> statements you need to
put them in a special declare section. put them in a special declare section.
You use a special syntax for the <Acronym>SQL</Acronym> queries. You use a special syntax for the <Acronym>SQL</Acronym> queries.
</Para>
<Para> <Para>
Before compiling you run the file through Before compiling you run the file through
@ -77,6 +80,7 @@ calls with the variables used as arguments. Both variables that are used
as input to the <Acronym>SQL</Acronym> statements and variables that will as input to the <Acronym>SQL</Acronym> statements and variables that will
contain the contain the
result are passed. result are passed.
</Para>
<Para> <Para>
Then you compile and at link time you link with a special library that Then you compile and at link time you link with a special library that
@ -85,6 +89,7 @@ single function) fetches the information from the arguments, performs
the <Acronym>SQL</Acronym> query using the ordinary interface the <Acronym>SQL</Acronym> query using the ordinary interface
(<FileName>libpq</FileName>) and puts back (<FileName>libpq</FileName>) and puts back
the result in the arguments dedicated for output. the result in the arguments dedicated for output.
</Para>
<Para> <Para>
Then you run your program and when the control arrives to Then you run your program and when the control arrives to
@ -92,24 +97,27 @@ the <Acronym>SQL</Acronym>
statement the <Acronym>SQL</Acronym> statement is performed against statement the <Acronym>SQL</Acronym> statement is performed against
the database and you the database and you
can continue with the result. can continue with the result.
</Para>
</sect1>
<Sect1> <Sect1>
<Title>How To Use <Application>egpc</Application></Title> <Title>How To Use <Application>egpc</Application></Title>
<Para> <Para>
This section describes how to use the <Application>egpc</Application> tool. This section describes how to use the <Application>egpc</Application> tool.
</Para>
<Sect2> <Sect2>
<Title>Preprocessor <Title>Preprocessor</title>
<Para> <Para>
The preprocessor is called <Application>ecpg</Application>. The preprocessor is called <Application>ecpg</Application>.
After installation it resides in After installation it resides in
the <ProductName>Postgres</ProductName> <FileName>bin/</FileName> directory. the <ProductName>Postgres</ProductName> <FileName>bin/</FileName> directory.
</Para>
</sect2>
<Sect2> <Sect2>
<Title>Library <Title>Library</title>
<Para> <Para>
The <Application>ecpg</Application> library is called The <Application>ecpg</Application> library is called
@ -118,6 +126,7 @@ The <Application>ecpg</Application> library is called
uses the <FileName>libpq</FileName> library for communication to the uses the <FileName>libpq</FileName> library for communication to the
<ProductName>Postgres</ProductName> server so you will <ProductName>Postgres</ProductName> server so you will
have to link your program with <Parameter>-lecpg -lpq</Parameter>. have to link your program with <Parameter>-lecpg -lpq</Parameter>.
</Para>
<Para> <Para>
The library has some methods that are "hidden" but that could prove very The library has some methods that are "hidden" but that could prove very
@ -130,6 +139,7 @@ useful sometime.
turns on debug logging if called with the first argument non-zero. turns on debug logging if called with the first argument non-zero.
Debug logging is done on <replaceable class="parameter">stream</replaceable>. Debug logging is done on <replaceable class="parameter">stream</replaceable>.
Most <Acronym>SQL</Acronym> statement logs its arguments and result. Most <Acronym>SQL</Acronym> statement logs its arguments and result.
</Para>
<Para> <Para>
The most important one (<Function>ECPGdo</Function>) The most important one (<Function>ECPGdo</Function>)
@ -152,9 +162,11 @@ This method returns TRUE if we are connected to a database and FALSE if not.
</Para> </Para>
</ListItem> </ListItem>
</itemizedlist> </itemizedlist>
</Para>
</sect2>
<Sect2> <Sect2>
<Title>Error handling <Title>Error handling</title>
<Para> <Para>
To be able to detect errors from the <ProductName>Postgres</ProductName> To be able to detect errors from the <ProductName>Postgres</ProductName>
@ -173,6 +185,7 @@ struct sqlca {
} sqlerrm; } sqlerrm;
} sqlca; } sqlca;
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
If an error occured in the last <Acronym>SQL</Acronym> statement If an error occured in the last <Acronym>SQL</Acronym> statement
@ -182,12 +195,14 @@ will be non-zero. If <Parameter>sqlca.sqlcode</Parameter> is less that 0
some kind of serious error, like the database definition does not match some kind of serious error, like the database definition does not match
the query given. If it is bigger than 0 then this is a normal error like the query given. If it is bigger than 0 then this is a normal error like
the table did not contain the requested row. the table did not contain the requested row.
</Para>
<Para> <Para>
sqlca.sqlerrm.sqlerrmc will contain a string that describes the error. sqlca.sqlerrm.sqlerrmc will contain a string that describes the error.
The string ends with <Quote>line 23.</Quote> where the line is the line number The string ends with <Quote>line 23.</Quote> where the line is the line number
in the source file (actually the file generated by the preprocessor but in the source file (actually the file generated by the preprocessor but
I hope I can fix this to be the line number in the input file.) I hope I can fix this to be the line number in the input file.)
</Para>
<Para> <Para>
List of errors that can occur: List of errors that can occur:
@ -394,8 +409,9 @@ The connect to the database did not work.
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para>
</Sect2> </Sect2>
</sect1>
<Sect1> <Sect1>
<Title>Limitations</Title> <Title>Limitations</Title>
@ -415,6 +431,7 @@ application in a so called single tasking way. Instead of starting one
client process per application process both the database part and the client process per application process both the database part and the
application part is run in the same process. In later versions of oracle application part is run in the same process. In later versions of oracle
this is no longer supported. this is no longer supported.
</Para>
<Para> <Para>
This would require a total redesign of the <ProductName>Postgres</ProductName> access model and This would require a total redesign of the <ProductName>Postgres</ProductName> access model and
@ -423,6 +440,8 @@ that effort can not justify the performance gained.
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para>
</sect1>
<Sect1> <Sect1>
<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title> <Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title>
@ -431,6 +450,8 @@ that effort can not justify the performance gained.
To be written by someone who knows the different To be written by someone who knows the different
<Acronym>RDBMS</Acronym> packages and who <Acronym>RDBMS</Acronym> packages and who
actually does port something... actually does port something...
</Para>
</sect1>
<Sect1> <Sect1>
<Title>Installation</Title> <Title>Installation</Title>
@ -440,6 +461,8 @@ Since version 0.5 <Application>ecpg</Application> is distributed
together with <ProductName>Postgres</ProductName>. So you together with <ProductName>Postgres</ProductName>. So you
should get your precompiler, libraries and header files compiled and should get your precompiler, libraries and header files compiled and
installed by default as a part of your installation. installed by default as a part of your installation.
</Para>
</sect1>
<Sect1> <Sect1>
<Title>For the Developer</Title> <Title>For the Developer</Title>
@ -454,6 +477,7 @@ on How to use it should be enough for all normal questions.
So, read this before looking at the internals of the So, read this before looking at the internals of the
<Application>ecpg</Application>. If <Application>ecpg</Application>. If
you are not interested in how it really works, skip this section. you are not interested in how it really works, skip this section.
</Para>
<Sect2> <Sect2>
<Title>ToDo List</Title> <Title>ToDo List</Title>
@ -499,7 +523,7 @@ to_date et al.
<ListItem> <ListItem>
<Para> <Para>
Records or structures have to be defined in the declare section. Records or structures have to be defined in the declare section.
</Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
@ -513,31 +537,43 @@ The following statements are not implemented thus far:
<Term> exec sql type</Term> <Term> exec sql type</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para>
</listitem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term> exec sql prepare</Term> <Term> exec sql prepare</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para>
</listitem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term> exec sql allocate</Term> <Term> exec sql allocate</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para>
</listitem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term> exec sql free</Term> <Term> exec sql free</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para>
</listitem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term> exec sql whenever sqlwarning</Term> <Term> exec sql whenever sqlwarning</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para>
</listitem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
<Term> SQLSTATE</Term> <Term> SQLSTATE</Term>
<ListItem> <ListItem>
<Para> <Para>
</Para>
</listitem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para> </Para>
@ -571,6 +607,7 @@ To set up a database you need a few scripts with table definitions and
other configuration parameters. If you have these scripts for an old other configuration parameters. If you have these scripts for an old
database you would like to just apply them to get a database you would like to just apply them to get a
<ProductName>Postgres</ProductName> database that works in the same way. <ProductName>Postgres</ProductName> database that works in the same way.
</Para>
<Para> <Para>
To set up a database you need a few scripts with table definitions and To set up a database you need a few scripts with table definitions and
@ -582,6 +619,8 @@ than could be realised in a script.
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para>
</sect2>
<Sect2> <Sect2>
<Title>The Preprocessor</Title> <Title>The Preprocessor</Title>
@ -589,11 +628,13 @@ than could be realised in a script.
<Para> <Para>
First four lines are written to the output. Two comments and two include First four lines are written to the output. Two comments and two include
lines necessary for the interface to the library. lines necessary for the interface to the library.
</Para>
<Para> <Para>
Then the preprocessor works in one pass only reading the input file and Then the preprocessor works in one pass only reading the input file and
writing to the output as it goes along. Normally it just echoes writing to the output as it goes along. Normally it just echoes
everything to the output without looking at it further. everything to the output without looking at it further.
</Para>
<Para> <Para>
When it comes to an <Command>EXEC SQL</Command> statements it interviens and When it comes to an <Command>EXEC SQL</Command> statements it interviens and
@ -616,10 +657,12 @@ exec sql end declare section;
In the section only variable declarations are allowed. Every variable In the section only variable declarations are allowed. Every variable
declare within this section is also entered in a list of variables declare within this section is also entered in a list of variables
indexed on their name together with the corresponding type. indexed on their name together with the corresponding type.
</Para>
<Para> <Para>
The declaration is echoed to the file to make the variable a normal The declaration is echoed to the file to make the variable a normal
C-variable also. C-variable also.
</Para>
<Para> <Para>
The special types VARCHAR and VARCHAR2 are converted into a named struct The special types VARCHAR and VARCHAR2 are converted into a named struct
@ -720,6 +763,7 @@ Other <Acronym>SQL</Acronym> statements are other statements that start with
<Command>exec sql</Command> and ends with <Command>;</Command>. <Command>exec sql</Command> and ends with <Command>;</Command>.
Everything inbetween is treated Everything inbetween is treated
as an <Acronym>SQL</Acronym> statement and parsed for variable substitution. as an <Acronym>SQL</Acronym> statement and parsed for variable substitution.
</Para>
<Para> <Para>
Variable substitution occur when a symbol starts with a colon Variable substitution occur when a symbol starts with a colon
@ -730,6 +774,7 @@ whether or not the <Acronym>SQL</Acronym> statements knows it to be
a variable for input or a variable for input or
output the pointers to the variables are written to the output to allow output the pointers to the variables are written to the output to allow
for access by the function. for access by the function.
</Para>
<Para> <Para>
For every variable that is part of the <Acronym>SQL</Acronym> request For every variable that is part of the <Acronym>SQL</Acronym> request
@ -742,6 +787,7 @@ the function gets another five arguments:
<Member>Number of elements in the array (for array fetches)</Member> <Member>Number of elements in the array (for array fetches)</Member>
<Member>The offset to the next element in the array (for array fetches)</Member> <Member>The offset to the next element in the array (for array fetches)</Member>
</SimpleList> </SimpleList>
</Para>
<Para> <Para>
Since the array fetches are not implemented yet the two last arguments Since the array fetches are not implemented yet the two last arguments
@ -750,7 +796,7 @@ are not really important. They could perhaps have been left out.
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para>
</Sect2> </Sect2>
<Sect2> <Sect2>
@ -786,6 +832,8 @@ is translated into:
</ProgramListing> </ProgramListing>
(the indentation in this manual is added for readability and not (the indentation in this manual is added for readability and not
something that the preprocessor can do.) something that the preprocessor can do.)
</Para>
</sect2>
<Sect2> <Sect2>
<Title>The Library</Title> <Title>The Library</Title>
@ -796,6 +844,7 @@ function. It takes a variable amount of arguments. Hopefully we wont run
into machines with limits on the amount of variables that can be into machines with limits on the amount of variables that can be
accepted by a varchar function. This could easily add up to 50 or so accepted by a varchar function. This could easily add up to 50 or so
arguments. arguments.
</Para>
<Para> <Para>
The arguments are: The arguments are:
@ -861,14 +910,18 @@ An enum telling that there are no more variables.
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para>
<Para> <Para>
All the <Acronym>SQL</Acronym> statements are performed in one transaction All the <Acronym>SQL</Acronym> statements are performed in one transaction
unless you issue unless you issue
a commit transaction. This works so that the first transaction or the a commit transaction. This works so that the first transaction or the
first after a commit or rollback always begins a transaction. first after a commit or rollback always begins a transaction.
</Para>
<Para> <Para>
To be completed: entries describing the other entries. To be completed: entries describing the other entries.
</Para>
</sect2>
</sect1>
</Chapter> </Chapter>

2
doc/src/sgml/extend.sgml
View File

@ -243,8 +243,10 @@ interchangably.
and will be described in depth (in the section and will be described in depth (in the section
on interfacing types and operators to indices) on interfacing types and operators to indices)
after we have discussed basic extensions. after we have discussed basic extensions.
</para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para> </Para>
</sect1>
</Chapter> </Chapter>

4
doc/src/sgml/func.sgml
View File

@ -63,6 +63,7 @@ available through operators and may be documented as operators only.
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
</sect1>
<sect1> <sect1>
<title>String Functions</title> <title>String Functions</title>
@ -230,6 +231,7 @@ Some are used internally to implement the SQL92 string functions listed above.
<para> <para>
Most functions explicitly defined for text will work for char() and varchar() arguments. Most functions explicitly defined for text will work for char() and varchar() arguments.
</para> </para>
</sect1>
<sect1> <sect1>
<title>Date/Time Functions</title> <title>Date/Time Functions</title>
@ -345,6 +347,7 @@ as well as the more specialized quantities
to return day of week and `epoch' to return seconds since 1970 (for <Type>datetime</Type>) to return day of week and `epoch' to return seconds since 1970 (for <Type>datetime</Type>)
or 'epoch' to return total elapsed seconds (for <Type>timespan</Type>). or 'epoch' to return total elapsed seconds (for <Type>timespan</Type>).
</Para> </Para>
</sect1>
<sect1> <sect1>
<title>Geometric Functions</title> <title>Geometric Functions</title>
@ -623,6 +626,7 @@ support functions.
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
</sect1>
<sect1> <sect1>
<title id="cidr-funcs">IP V4 Functions</title> <title id="cidr-funcs">IP V4 Functions</title>

37
doc/src/sgml/geqo.sgml
View File

@ -1,8 +1,13 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/geqo.sgml,v 1.4 1998/08/15 06:55:05 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/geqo.sgml,v 1.5 1998/12/29 02:24:15 thomas Exp $
Genetic Optimizer Genetic Optimizer
$Log: geqo.sgml,v $ $Log: geqo.sgml,v $
Revision 1.5 1998/12/29 02:24:15 thomas
Clean up to ensure tag completion as required by the newest versions
of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@michvhf.com>.
Revision 1.4 1998/08/15 06:55:05 thomas Revision 1.4 1998/08/15 06:55:05 thomas
Change Id field in chapter tag to change html output file name. Change Id field in chapter tag to change html output file name.
@ -43,6 +48,7 @@ Written by <ULink url="utesch@aut.tu-freiberg.de">Martin Utesch</ULink>
for the Institute of Automatic Control at the University of Mining and Technology in Freiberg, Germany. for the Institute of Automatic Control at the University of Mining and Technology in Freiberg, Germany.
</Para> </Para>
</Note> </Note>
</para>
<Sect1> <Sect1>
<Title>Query Handling as a Complex Optimization Problem</Title> <Title>Query Handling as a Complex Optimization Problem</Title>
@ -55,6 +61,7 @@ optimization effort is caused by the support of a variety of <FirstTerm>join met
(e.g., nested loop, index scan, merge join in <ProductName>Postgres</ProductName>) to (e.g., nested loop, index scan, merge join in <ProductName>Postgres</ProductName>) to
process individual <Command>join</Command>s and a diversity of <FirstTerm>indices</FirstTerm> (e.g., r-tree, process individual <Command>join</Command>s and a diversity of <FirstTerm>indices</FirstTerm> (e.g., r-tree,
b-tree, hash in <ProductName>Postgres</ProductName>) as access paths for relations. b-tree, hash in <ProductName>Postgres</ProductName>) as access paths for relations.
</para>
<Para> <Para>
The current <ProductName>Postgres</ProductName> optimizer implementation performs a <FirstTerm>near- The current <ProductName>Postgres</ProductName> optimizer implementation performs a <FirstTerm>near-
@ -62,6 +69,7 @@ exhaustive search</FirstTerm> over the space of alternative strategies. This que
optimization technique is inadequate to support database application optimization technique is inadequate to support database application
domains that involve the need for extensive queries, such as artificial domains that involve the need for extensive queries, such as artificial
intelligence. intelligence.
</para>
<Para> <Para>
The Institute of Automatic Control at the University of Mining and The Institute of Automatic Control at the University of Mining and
@ -70,15 +78,18 @@ folks wanted to take the <ProductName>Postgres</ProductName> DBMS as the backend
support knowledge based system for the maintenance of an electrical support knowledge based system for the maintenance of an electrical
power grid. The DBMS needed to handle large <Command>join</Command> queries for the power grid. The DBMS needed to handle large <Command>join</Command> queries for the
inference machine of the knowledge based system. inference machine of the knowledge based system.
</para>
<Para> <Para>
Performance difficulties within exploring the space of possible query Performance difficulties within exploring the space of possible query
plans arose the demand for a new optimization technique being developed. plans arose the demand for a new optimization technique being developed.
</para>
<Para> <Para>
In the following we propose the implementation of a <FirstTerm>Genetic Algorithm</FirstTerm> In the following we propose the implementation of a <FirstTerm>Genetic Algorithm</FirstTerm>
as an option for the database query optimization problem. as an option for the database query optimization problem.
</para>
</sect1>
<Sect1> <Sect1>
<Title>Genetic Algorithms (<Acronym>GA</Acronym>)</Title> <Title>Genetic Algorithms (<Acronym>GA</Acronym>)</Title>
@ -89,6 +100,7 @@ determined, randomized search. The set of possible solutions for the
optimization problem is considered as a <FirstTerm>population</FirstTerm> of <FirstTerm>individuals</FirstTerm>. optimization problem is considered as a <FirstTerm>population</FirstTerm> of <FirstTerm>individuals</FirstTerm>.
The degree of adaption of an individual to its environment is specified The degree of adaption of an individual to its environment is specified
by its <FirstTerm>fitness</FirstTerm>. by its <FirstTerm>fitness</FirstTerm>.
</para>
<Para> <Para>
The coordinates of an individual in the search space are represented The coordinates of an individual in the search space are represented
@ -96,11 +108,13 @@ by <FirstTerm>chromosomes</FirstTerm>, in essence a set of character strings. A
subsection of a chromosome which encodes the value of a single parameter subsection of a chromosome which encodes the value of a single parameter
being optimized. Typical encodings for a gene could be <FirstTerm>binary</FirstTerm> or being optimized. Typical encodings for a gene could be <FirstTerm>binary</FirstTerm> or
<FirstTerm>integer</FirstTerm>. <FirstTerm>integer</FirstTerm>.
</para>
<Para> <Para>
Through simulation of the evolutionary operations <FirstTerm>recombination</FirstTerm>, Through simulation of the evolutionary operations <FirstTerm>recombination</FirstTerm>,
<FirstTerm>mutation</FirstTerm>, and <FirstTerm>selection</FirstTerm> new generations of search points are found <FirstTerm>mutation</FirstTerm>, and <FirstTerm>selection</FirstTerm> new generations of search points are found
that show a higher average fitness than their ancestors. that show a higher average fitness than their ancestors.
</para>
<Para> <Para>
According to the "comp.ai.genetic" <Acronym>FAQ</Acronym> it cannot be stressed too According to the "comp.ai.genetic" <Acronym>FAQ</Acronym> it cannot be stressed too
@ -137,6 +151,8 @@ P''(t) generation of descendants at a time t
| | t := t + 1 | | | t := t + 1 |
+===+=====================================+ +===+=====================================+
</ProgramListing> </ProgramListing>
</para>
</sect1>
<Sect1> <Sect1>
<Title>Genetic Query Optimization (<Acronym>GEQO</Acronym>) in Postgres</Title> <Title>Genetic Query Optimization (<Acronym>GEQO</Acronym>) in Postgres</Title>
@ -156,10 +172,12 @@ E. g., the query tree
is encoded by the integer string '4-1-3-2', is encoded by the integer string '4-1-3-2',
which means, first join relation '4' and '1', then '3', and which means, first join relation '4' and '1', then '3', and
then '2', where 1, 2, 3, 4 are relids in <ProductName>Postgres</ProductName>. then '2', where 1, 2, 3, 4 are relids in <ProductName>Postgres</ProductName>.
</para>
<Para> <Para>
Parts of the <Acronym>GEQO</Acronym> module are adapted from D. Whitley's Genitor Parts of the <Acronym>GEQO</Acronym> module are adapted from D. Whitley's Genitor
algorithm. algorithm.
</para>
<Para> <Para>
Specific characteristics of the <Acronym>GEQO</Acronym> implementation in <ProductName>Postgres</ProductName> Specific characteristics of the <Acronym>GEQO</Acronym> implementation in <ProductName>Postgres</ProductName>
@ -189,6 +207,7 @@ Mutation as genetic operator is deprecated so that no repair
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
<Para> <Para>
The <Acronym>GEQO</Acronym> module gives the following benefits to the <ProductName>Postgres</ProductName> DBMS The <Acronym>GEQO</Acronym> module gives the following benefits to the <ProductName>Postgres</ProductName> DBMS
@ -209,6 +228,7 @@ Improved cost size approximation of query plans since no longer
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
</Sect1> </Sect1>
@ -231,6 +251,8 @@ Debugging showed that it get stucked in a loop of routine
<Function>OrderedElemPop</Function>, file <FileName>backend/utils/mmgr/oset.c</FileName>. <Function>OrderedElemPop</Function>, file <FileName>backend/utils/mmgr/oset.c</FileName>.
The same problems arise with long queries when using the normal The same problems arise with long queries when using the normal
<ProductName>Postgres</ProductName> query optimization algorithm. <ProductName>Postgres</ProductName> query optimization algorithm.
</para>
</sect3>
<Sect3> <Sect3>
<Title>Improve genetic algorithm parameter settings</Title> <Title>Improve genetic algorithm parameter settings</Title>
@ -252,6 +274,8 @@ Computing time
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
</sect3>
<Sect3> <Sect3>
<Title>Find better solution for integer overflow</Title> <Title>Find better solution for integer overflow</Title>
@ -263,6 +287,8 @@ the present hack for MAXINT overflow is to set the <ProductName>Postgres</Produc
value of <StructField>rel->size</StructField> to its logarithm. value of <StructField>rel->size</StructField> to its logarithm.
Modifications of <StructName>Rel</StructName> in <FileName>backend/nodes/relation.h</FileName> will Modifications of <StructName>Rel</StructName> in <FileName>backend/nodes/relation.h</FileName> will
surely have severe impacts on the whole <ProductName>Postgres</ProductName> implementation. surely have severe impacts on the whole <ProductName>Postgres</ProductName> implementation.
</para>
</sect3>
<Sect3> <Sect3>
<Title>Find solution for exhausted memory</Title> <Title>Find solution for exhausted memory</Title>
@ -275,7 +301,9 @@ Maybe I forgot something to be freed correctly, but I dunno what.
Of course the <StructName>rel</StructName> data structure of the <Command>join</Command> keeps growing and Of course the <StructName>rel</StructName> data structure of the <Command>join</Command> keeps growing and
growing the more relations are packed into it. growing the more relations are packed into it.
Suggestions are welcome :-( Suggestions are welcome :-(
</para>
</sect3>
</sect2>
<Sect2> <Sect2>
<Title>Further Improvements</Title> <Title>Further Improvements</Title>
@ -283,6 +311,7 @@ Suggestions are welcome :-(
<Para> <Para>
Enable bushy query tree processing within <ProductName>Postgres</ProductName>; Enable bushy query tree processing within <ProductName>Postgres</ProductName>;
that may improve the quality of query plans. that may improve the quality of query plans.
</para>
<BIBLIOGRAPHY Id="geqo-biblio"> <BIBLIOGRAPHY Id="geqo-biblio">
<TITLE> <TITLE>
@ -365,4 +394,6 @@ The Benjamin/Cummings Pub., Inc.
</BIBLIOENTRY> </BIBLIOENTRY>
</BIBLIOGRAPHY> </BIBLIOGRAPHY>
</sect2>
</sect1>
</Chapter> </Chapter>

22
doc/src/sgml/gist.sgml
View File

@ -19,7 +19,7 @@ with more on different indexing and sorting schemes at
And there is more interesting reading at the Berkely database site at And there is more interesting reading at the Berkely database site at
<ULink url="http://epoch.cs.berkeley.edu:8000/">http://epoch.cs.berkeley.edu:8000/</ULink>. <ULink url="http://epoch.cs.berkeley.edu:8000/">http://epoch.cs.berkeley.edu:8000/</ULink>.
</para>
<Para> <Para>
<Note> <Note>
@ -32,12 +32,12 @@ on GiST. Hopefully we will learn more in the future and update this information.
- thomas 1998-03-01 - thomas 1998-03-01
</Para> </Para>
</Note> </Note>
</para>
<Para> <Para>
Well, I can't say I quite understand what's going on, but at least Well, I can't say I quite understand what's going on, but at least
I (almost) succeeded in porting GiST examples to linux. The GiST access I (almost) succeeded in porting GiST examples to linux. The GiST access
method is already in the postgres tree (<FileName>src/backend/access/gist</FileName>). method is already in the postgres tree (<FileName>src/backend/access/gist</FileName>).
</para>
<Para> <Para>
<ULink url="ftp://s2k-ftp.cs.berkeley.edu/pub/gist/pggist/pggist.tgz">Examples at Berkeley</ULink> <ULink url="ftp://s2k-ftp.cs.berkeley.edu/pub/gist/pggist/pggist.tgz">Examples at Berkeley</ULink>
come with an overview of the methods and demonstrate spatial index come with an overview of the methods and demonstrate spatial index
@ -56,7 +56,7 @@ ERROR: cannot open pix
(PostgreSQL 6.3 Sun Feb 1 14:57:30 EST 1998) (PostgreSQL 6.3 Sun Feb 1 14:57:30 EST 1998)
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
I could not get sense of this error message; it appears to be something I could not get sense of this error message; it appears to be something
we'd rather ask the developers about (see also Note 4 below). What I we'd rather ask the developers about (see also Note 4 below). What I
@ -64,28 +64,28 @@ would suggest here is that someone of you linux guys (linux==gcc?) fetch the
original sources quoted above and apply my patch (see attachment) and original sources quoted above and apply my patch (see attachment) and
tell us what you feel about it. Looks cool to me, but I would not like tell us what you feel about it. Looks cool to me, but I would not like
to hold it up while there are so many competent people around. to hold it up while there are so many competent people around.
</para>
<Para> <Para>
A few notes on the sources: A few notes on the sources:
</para>
<Para> <Para>
1. I failed to make use of the original (HPUX) Makefile and rearranged 1. I failed to make use of the original (HPUX) Makefile and rearranged
the Makefile from the ancient postgres95 tutorial to do the job. I tried the Makefile from the ancient postgres95 tutorial to do the job. I tried
to keep it generic, but I am a very poor makefile writer -- just did to keep it generic, but I am a very poor makefile writer -- just did
some monkey work. Sorry about that, but I guess it is now a little some monkey work. Sorry about that, but I guess it is now a little
more portable that the original makefile. more portable that the original makefile.
</para>
<Para> <Para>
2. I built the example sources right under pgsql/src (just extracted the 2. I built the example sources right under pgsql/src (just extracted the
tar file there). The aforementioned Makefile assumes it is one level tar file there). The aforementioned Makefile assumes it is one level
below pgsql/src (in our case, in pgsql/src/pggist). below pgsql/src (in our case, in pgsql/src/pggist).
</para>
<Para> <Para>
3. The changes I made to the *.c files were all about #include's, 3. The changes I made to the *.c files were all about #include's,
function prototypes and typecasting. Other than that, I just threw function prototypes and typecasting. Other than that, I just threw
away a bunch of unused vars and added a couple parentheses to please away a bunch of unused vars and added a couple parentheses to please
gcc. I hope I did not screw up too much :) gcc. I hope I did not screw up too much :)
</para>
<Para> <Para>
4. There is a comment in polyproc.sql: 4. There is a comment in polyproc.sql:
@ -98,11 +98,11 @@ A few notes on the sources:
<ProductName>Postgres</ProductName> versions <ProductName>Postgres</ProductName> versions
back and tried the query. My system went nuts and I had to shoot down back and tried the query. My system went nuts and I had to shoot down
the postmaster in about ten minutes. the postmaster in about ten minutes.
</para>
<Para> <Para>
I will continue to look into GiST for a while, but I would also I will continue to look into GiST for a while, but I would also
appreciate appreciate
more examples of R-tree usage. more examples of R-tree usage.
</para>
</Chapter> </Chapter>

5
doc/src/sgml/history.sgml
View File

@ -170,6 +170,7 @@ At the same time, the version numbering
was reset to start at 6.0, was reset to start at 6.0,
putting the numbers back into the sequence originally begun by putting the numbers back into the sequence originally begun by
the <ProductName>Postgres</ProductName> Project. the <ProductName>Postgres</ProductName> Project.
</Para>
<Para> <Para>
The emphasis on development for the v1.0.x releases of The emphasis on development for the v1.0.x releases of
@ -180,9 +181,11 @@ the emphasis has shifted from
identifying and understanding existing problems in the backend identifying and understanding existing problems in the backend
to augmenting features and capabilities, although to augmenting features and capabilities, although
work continues in all areas. work continues in all areas.
</Para>
<Para> <Para>
Major enhancements include: Major enhancements include:
</Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
@ -203,6 +206,7 @@ type casting, and binary and hexadecimal integer input.
Built-in types have been improved, including new wide-range date/time types Built-in types have been improved, including new wide-range date/time types
and additional geometric type support. and additional geometric type support.
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
@ -211,7 +215,6 @@ and backend startup time has decreased 80% since v6.0 was released.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</Para>
</Sect2> </Sect2>
</sect1> </sect1>

2
doc/src/sgml/info.sgml
View File

@ -3,6 +3,7 @@
<Para> <Para>
This manual set is organized into several parts: This manual set is organized into several parts:
</Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
@ -69,6 +70,7 @@ Currently included in the <citetitle>User's Guide</citetitle>.
<Para> <Para>
In addition to this manual set, there are other resources to help you with In addition to this manual set, there are other resources to help you with
<ProductName>Postgres</ProductName> installation and use: <ProductName>Postgres</ProductName> installation and use:
</Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>

1
doc/src/sgml/inherit.sgml
View File

@ -51,6 +51,7 @@ SELECT name, altitude
|Mariposa | 1953 | |Mariposa | 1953 |
+----------+----------+ +----------+----------+
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
On the other hand, to find the names of all cities, On the other hand, to find the names of all cities,

299
doc/src/sgml/install.sgml
View File

@ -44,7 +44,7 @@ The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possi
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
</para>
<Para> <Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell. Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands Except where noted, they will probably work on most systems. Commands
@ -74,14 +74,14 @@ http://www.postgresql.org/docs/admin/install.htm</ulink>.
In general, most Unix-compatible In general, most Unix-compatible
platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>. platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>.
</para>
<para> <para>
Although the minimum required memory for running <ProductName>Postgres</ProductName> Although the minimum required memory for running <ProductName>Postgres</ProductName>
is as little as 8MB, there are noticable improvements in runtimes for the regression is as little as 8MB, there are noticable improvements in runtimes for the regression
tests when expanding memory up to 96MB on a relatively fast dual-processor system tests when expanding memory up to 96MB on a relatively fast dual-processor system
running X-Windows. running X-Windows.
The rule is you can never have too much memory. The rule is you can never have too much memory.
</para>
<Para> <Para>
Check that you have sufficient disk space. You will need about Check that you have sufficient disk space. You will need about
30 Mbytes for <filename>/usr/src/pgsql</filename>, 30 Mbytes for <filename>/usr/src/pgsql</filename>,
@ -107,13 +107,12 @@ about 5 Mbytes for <filename>/usr/local/pgsql</filename>
<programlisting> <programlisting>
$ df -k $ df -k
</programlisting> </programlisting>
</para>
</Sect1> </Sect1>
<Sect1> <Sect1>
<Title>Installation Procedure</Title> <Title>Installation Procedure</Title>
<Para>
<Procedure> <Procedure>
<Title><ProductName>Postgres</ProductName> Installation</Title> <Title><ProductName>Postgres</ProductName> Installation</Title>
@ -151,19 +150,20 @@ Read any last minute information and platform specific porting
<Para> <Para>
Create the <ProductName>Postgres</ProductName> superuser account Create the <ProductName>Postgres</ProductName> superuser account
(<literal>postgres</literal> is commonly used) if it does not already exist. (<literal>postgres</literal> is commonly used) if it does not already exist.
</para>
<para> <para>
The owner of the Postgres files can be any unprivileged user account. The owner of the Postgres files can be any unprivileged user account.
It <emphasis>must not</emphasis> be <literal>root</literal>, <literal>bin</literal>, It <emphasis>must not</emphasis> be <literal>root</literal>, <literal>bin</literal>,
or any other account with special access rights, as that would create a security risk. or any other account with special access rights, as that would create a security risk.
</para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the
remaining steps in the installation will happen in this account. remaining steps in the installation will happen in this account.
</para>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Ftp file Ftp file
@ -244,12 +244,13 @@ If you are upgrading an existing system then back up your database.
in the HACKERS mailing list. Full releases always require a dump/reload in the HACKERS mailing list. Full releases always require a dump/reload
from previous releases. It is therefore a bad idea to skip this from previous releases. It is therefore a bad idea to skip this
step. step.
</para>
<tip> <tip>
<para> <para>
Do not use the <application>pg_dumpall</application> Do not use the <application>pg_dumpall</application>
script from v6.0 or everything script from v6.0 or everything
will be owned by the <ProductName>Postgres</ProductName> super user. will be owned by the <ProductName>Postgres</ProductName> super user.
</para>
</tip> </tip>
<para> <para>
@ -258,7 +259,7 @@ To dump your fairly recent post-v6.0 database installation, type
<programlisting> <programlisting>
$ pg_dumpall -z > db.out $ pg_dumpall -z > db.out
</programlisting> </programlisting>
</para>
<para> <para>
To use the latest <application>pg_dumpall</application> script on your To use the latest <application>pg_dumpall</application> script on your
existing older database before upgrading <productname>Postgres</productname>, existing older database before upgrading <productname>Postgres</productname>,
@ -341,6 +342,7 @@ Linux system I can type
$ /etc/rc.d/init.d/postgres.init stop $ /etc/rc.d/init.d/postgres.init stop
</programlisting> </programlisting>
to halt <productname>Postgres</productname>. to halt <productname>Postgres</productname>.
</para>
</tip> </tip>
</Para> </Para>
</Step> </Step>
@ -379,12 +381,14 @@ $ exit
<Para> <Para>
Make new source and install directories. The actual paths can be Make new source and install directories. The actual paths can be
different for your installation but you must be consistant throughout this procedure. different for your installation but you must be consistant throughout this procedure.
</para>
<note> <note>
<para> <para>
There are two places in this installation procedure where you will have an opportunity There are two places in this installation procedure where you will have an opportunity
to specify installation locations for programs, libraries, documentation, and other files. to specify installation locations for programs, libraries, documentation, and other files.
Usually it is sufficient to specify these at the <command>make install</command> stage Usually it is sufficient to specify these at the <command>make install</command> stage
of installation. of installation.
</para>
</note> </note>
<para> <para>
@ -443,10 +447,11 @@ If your system is not automatically recognized by configure and you have to do t
send email to send email to
<ulink url="mailto:scrappy@hub.org">scrappy@hub.org</ulink> with the output of the program <ulink url="mailto:scrappy@hub.org">scrappy@hub.org</ulink> with the output of the program
<application>./config.guess</application>. Indicate what the template file should be. <application>./config.guess</application>. Indicate what the template file should be.
</para>
</note> </note>
</Para> </Para>
</step>
<Step Performance="optional"> <Step Performance="optional">
<Para> <Para>
Choose configuration options. Check <xref linkend="config" endterm="install-config"> Choose configuration options. Check <xref linkend="config" endterm="install-config">
@ -488,7 +493,7 @@ extra options specified.
present.) present.)
</ProgramListing> </ProgramListing>
</Para> </Para>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Here is the configure script used on a Sparc Solaris 2.5 system Here is the configure script used on a Sparc Solaris 2.5 system
@ -505,13 +510,14 @@ $ ./configure --prefix=/opt/postgres \
<para> <para>
Of course, you may type these three lines all Of course, you may type these three lines all
on the same line. on the same line.
</para>
</tip> </tip>
</Para> </Para>
</Step> </Step>
</substeps> </substeps>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Install the <application>man</application> and Install the <application>man</application> and
@ -521,11 +527,12 @@ Install the <application>man</application> and
$ cd /usr/src/pgsql/doc $ cd /usr/src/pgsql/doc
$ gmake install $ gmake install
</ProgramListing> </ProgramListing>
</para>
<para> <para>
The documentation is also available in Postscript format. Look for files The documentation is also available in Postscript format. Look for files
ending with <filename>.ps.gz</filename> in the same directory. ending with <filename>.ps.gz</filename> in the same directory.
</para>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Compile the program. Type Compile the program. Type
@ -553,8 +560,9 @@ All of PostgreSQL is successfully made. Ready to install.
You will probably find a number of warning You will probably find a number of warning
messages in make.log. Unless you have problems later on, these messages in make.log. Unless you have problems later on, these
messages may be safely ignored. messages may be safely ignored.
</para>
</note> </note>
</para>
<Para> <Para>
If the compiler fails with a message stating that If the compiler fails with a message stating that
the <application>flex</application> command the <application>flex</application> command
@ -603,7 +611,7 @@ At this point, or earlier if you wish,
<Para> <Para>
If necessary, tell your system how to find the new shared libraries. You can If necessary, tell your system how to find the new shared libraries. You can
do <emphasis>one</emphasis> of the following, preferably the first: do <emphasis>one</emphasis> of the following, preferably the first:
</para>
<SubSteps> <SubSteps>
<Step Performance="optional"> <Step Performance="optional">
<Para> <Para>
@ -629,6 +637,7 @@ to the file. Then run command <Command>/sbin/ldconfig</Command>.
<ProgramListing> <ProgramListing>
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</ProgramListing> </ProgramListing>
</para>
</Step> </Step>
</SubSteps> </SubSteps>
@ -648,93 +657,94 @@ pg_id: can't load library 'libpq.so'
</Para> </Para>
</Step> </Step>
<Step Performance="optional"> <Step Performance="optional">
<Para> <Para>
If you used the <option>--with-perl</option> option to configure, check If you used the <option>--with-perl</option> option to configure, check
the install log to see whether the Perl module was actually installed. the install log to see whether the Perl module was actually installed.
If you've followed our advice to make the Postgres files be owned by If you've followed our advice to make the Postgres files be owned by
an unprivileged userid, then the Perl module won't have been installed, an unprivileged userid, then the Perl module won't have been installed,
for lack of write privileges on the Perl library directories. You can for lack of write privileges on the Perl library directories. You can
complete its installation, either now or later, by becoming the user that complete its installation, either now or later, by becoming the user that
does own the Perl library (often root) (via <command>su</command>) and doing does own the Perl library (often root) (via <command>su</command>) and doing
<ProgramListing> <ProgramListing>
$ cd /usr/src/pgsql/src/interfaces/perl5 $ cd /usr/src/pgsql/src/interfaces/perl5
$ gmake install $ gmake install
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
If it has not already been done, then prepare account <literal>postgres</literal> If it has not already been done, then prepare account <literal>postgres</literal>
for using <ProductName>Postgres</ProductName>. for using <ProductName>Postgres</ProductName>.
Any account that will use <ProductName>Postgres</ProductName> must Any account that will use <ProductName>Postgres</ProductName> must
be similarly prepared. be similarly prepared.
</para>
<para> <para>
There are several ways to influence the runtime environment of the There are several ways to influence the runtime environment of the
<ProductName>Postgres</ProductName> <ProductName>Postgres</ProductName>
server. Refer to the <citetitle>Administrator's Guide</citetitle> server. Refer to the <citetitle>Administrator's Guide</citetitle>
for more information. for more information.
<note>
<note> <para>
<para> The following instructions are for a
The following instructions are for a
bash/sh shell. Adapt accordingly for other shells. bash/sh shell. Adapt accordingly for other shells.
</note> </para>
</note>
</Para>
</Para> <substeps>
<substeps> <Step Performance="required">
<Para>
<Step Performance="required">
<Para>
Add the following lines to your login environment: Add the following lines to your login environment:
shell, <filename>~/.bash_profile</filename>: shell, <filename>~/.bash_profile</filename>:
<ProgramListing> <ProgramListing>
PATH=$PATH:/usr/local/pgsql/bin PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man MANPATH=$MANPATH:/usr/local/pgsql/man
PGLIB=/usr/local/pgsql/lib PGLIB=/usr/local/pgsql/lib
PGDATA=/usr/local/pgsql/data PGDATA=/usr/local/pgsql/data
export PATH MANPATH PGLIB PGDATA export PATH MANPATH PGLIB PGDATA
</ProgramListing> </ProgramListing>
</Para> </Para>
</step>
<Step Performance="required"> <Step Performance="required">
<para> <para>
Several regression tests could failed if the user's locale collation Several regression tests could failed if the user's locale collation
scheme is different from that of standard C locale. scheme is different from that of standard C locale.
</para>
<para> <para>
If you configure and compile <ProductName>Postgres</ProductName> If you configure and compile <ProductName>Postgres</ProductName>
with the <option>--enable-locale</option> option then with the <option>--enable-locale</option> option then
set locale environment to C (or unset all LC_* variables) set locale environment to C (or unset all LC_* variables)
by putting these additional lines to your login environment by putting these additional lines to your login environment
before starting postmaster: before starting postmaster:
<ProgramListing> <ProgramListing>
LC_COLLATE=C LC_COLLATE=C
LC_CTYPE=C LC_CTYPE=C
LC_COLLATE=C LC_COLLATE=C
export LC_COLLATE LC_CTYPE LC_COLLATE export LC_COLLATE LC_CTYPE LC_COLLATE
</ProgramListing> </ProgramListing>
<ProgramListing> <ProgramListing>
</ProgramListing> </ProgramListing>
</para>
</step>
<Step Performance="required">
<Step Performance="required"> <Para>
<Para>
Make sure that you have defined these variables before continuing Make sure that you have defined these variables before continuing
with the remaining steps. The easiest way to do this is to type: with the remaining steps. The easiest way to do this is to type:
<ProgramListing> <ProgramListing>
$ source ~/.bash_profile $ source ~/.bash_profile
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
</substeps> </substeps>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
@ -768,7 +778,7 @@ $ initdb
<para> <para>
Briefly test that the backend will start and run by running it from Briefly test that the backend will start and run by running it from
the command line. the command line.
</para>
<substeps> <substeps>
<Step Performance="required"> <Step Performance="required">
@ -787,55 +797,60 @@ Create a database by typing
<ProgramListing> <ProgramListing>
$ createdb $ createdb
</ProgramListing> </ProgramListing>
</para>
</step>
<Step Performance="required"> <Step Performance="required">
<para> <para>
Connect to the new database: Connect to the new database:
<ProgramListing> <ProgramListing>
$ psql $ psql
</ProgramListing> </ProgramListing>
</para>
</step>
<Step Performance="required"> <Step Performance="required">
<para> <para>
And run a sample query: And run a sample query:
<ProgramListing> <ProgramListing>
postgres=> SELECT datetime 'now'; postgres=> SELECT datetime 'now';
</ProgramListing> </ProgramListing>
</para>
</step>
<Step Performance="required"> <Step Performance="required">
<para> <para>
Exit <application>psql</application>: Exit <application>psql</application>:
<ProgramListing> <ProgramListing>
postgres=> \q postgres=> \q
</ProgramListing> </ProgramListing>
</para>
</step>
<Step Performance="required"> <Step Performance="required">
<para> <para>
Remove the test database (unless you will want to use it later for other tests): Remove the test database (unless you will want to use it later for other tests):
<ProgramListing> <ProgramListing>
$ destroydb $ destroydb
</ProgramListing> </ProgramListing>
</para>
</step>
</substeps> </substeps>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Run postmaster in the background from your <ProductName>Postgres</ProductName> Run postmaster in the background from your <ProductName>Postgres</ProductName>
superuser account (typically account <literal>postgres</literal>). superuser account (typically account <literal>postgres</literal>).
<emphasis>Do not run <application>postmaster</application> <emphasis>Do not run <application>postmaster</application>
from the root account!</emphasis> from the root account!</emphasis>
</para>
<Para> <Para>
Usually, you will want to modify Usually, you will want to modify
your computer so that it will automatically start postmaster whenever your computer so that it will automatically start postmaster whenever
it boots. It is not required; the <ProductName>Postgres</ProductName> it boots. It is not required; the <ProductName>Postgres</ProductName>
server can server can
be run successfully from non-privileged accounts without root intervention. be run successfully from non-privileged accounts without root intervention.
</para>
<para> <para>
Here are some suggestions on how to do this, contributed by various Here are some suggestions on how to do this, contributed by various
users. users.
</para>
<para> <para>
Whatever you do, postmaster must be run by Whatever you do, postmaster must be run by
the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?) the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
@ -856,7 +871,8 @@ start the <application>postmaster</application> and send it to the background:
$ cd $ cd
$ nohup postmaster > regress.log 2>&1 & $ nohup postmaster > regress.log 2>&1 &
</ProgramListing> </ProgramListing>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
@ -864,6 +880,8 @@ Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
<programlisting> <programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting> </programlisting>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
@ -885,6 +903,8 @@ In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
enough to keep parsing beyond end-of-line if there is an enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under expression unfinished. The exec saves one layer of shell under
the postmaster process so the parent is init. the postmaster process so the parent is init.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
@ -892,6 +912,8 @@ In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
which is based on the example in <filename>contrib/linux/</filename>. which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from Then make a softlink to this file from
<filename>/etc/rc.d/rc5.d/S98postgres.init</filename>. <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
@ -907,6 +929,8 @@ pg:2345:respawn:/bin/su - postgres -c
(The author of this example says this example will revive the (The author of this example says this example will revive the
postmaster if it dies, but he doesn't know if there are other side postmaster if it dies, but he doesn't know if there are other side
effects.) effects.)
</para>
</listitem>
</itemizedlist> </itemizedlist>
@ -967,6 +991,7 @@ For example,
For a i686/Linux-ELF platform, no tests failed since this is the For a i686/Linux-ELF platform, no tests failed since this is the
v6.4 regression testing reference platform. v6.4 regression testing reference platform.
</Para> </Para>
</listitem>
<listitem> <listitem>
<Para> <Para>
@ -976,8 +1001,10 @@ For example,
floating point numbers. select_views produces massively different output, floating point numbers. select_views produces massively different output,
but the differences are due to minor floating point differences. but the differences are due to minor floating point differences.
</Para> </Para>
</itemizedlist> </listitem>
</itemizedlist>
</para>
<Para> <Para>
Even if a test result clearly indicates a real failure, it may be a Even if a test result clearly indicates a real failure, it may be a
localized problem that will not affect you. An example is that the localized problem that will not affect you. An example is that the
@ -1009,13 +1036,13 @@ $ gmake clean
</Step> </Step>
</substeps> </substeps>
</step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
If you haven't already done so, this would be a good time to modify If you haven't already done so, this would be a good time to modify
your computer to do regular maintainence. The following should be your computer to do regular maintainence. The following should be
done at regular intervals: done at regular intervals:
</para>
<procedure> <procedure>
<title>Minimal Backup Procedure</title> <title>Minimal Backup Procedure</title>
@ -1023,13 +1050,15 @@ $ gmake clean
<para> <para>
Run the <acronym>SQL</acronym> command <command>VACUUM</command>. Run the <acronym>SQL</acronym> command <command>VACUUM</command>.
This will clean up your database. This will clean up your database.
</para>
</step>
<step performance="required"> <step performance="required">
<para> <para>
Back up your system. (You should probably keep the last few Back up your system. (You should probably keep the last few
backups on hand.) Preferably, no one else should be using the backups on hand.) Preferably, no one else should be using the
system at the time. system at the time.
</para>
</step>
</procedure> </procedure>
<para> <para>
@ -1100,7 +1129,7 @@ simply type
$ cd /usr/local/pgsql/doc $ cd /usr/local/pgsql/doc
$ gunzip user.ps.tz | lpr $ gunzip user.ps.tz | lpr
</programlisting> </programlisting>
</para>
<para> <para>
Here is how Here is how
you might do it if you have Ghostscript on your system and are you might do it if you have Ghostscript on your system and are
@ -1114,7 +1143,7 @@ $ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps $ gzip user.ps
$ lpr -l -s -r manpage.hp $ lpr -l -s -r manpage.hp
</programlisting> </programlisting>
</para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
@ -1132,14 +1161,20 @@ $ lpr -l -s -r manpage.hp
<listitem> <listitem>
<para> <para>
The version of <ProductName>Postgres</ProductName> (v6.4, 6.3.2, beta 981014, etc.). The version of <ProductName>Postgres</ProductName> (v6.4, 6.3.2, beta 981014, etc.).
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Your operating system (i.e. RedHat v5.1 Linux v2.0.34). Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Your hardware (SPARC, i486, etc.). Your hardware (SPARC, i486, etc.).
</para>
</listitem>
<listitem> <listitem>
<para> <para>
@ -1148,6 +1183,8 @@ Did you compile, install and run the regression tests cleanly?
applied, changes you made, etc.), what tests failed, etc. applied, changes you made, etc.), what tests failed, etc.
It is normal to get many warning when you compile. You do It is normal to get many warning when you compile. You do
not need to report these. not need to report these.
</para>
</listitem>
</itemizedlist> </itemizedlist>
@ -1161,6 +1198,7 @@ Did you compile, install and run the regression tests cleanly?
</Para> </Para>
</Step> </Step>
</Procedure> </Procedure>
</sect1>
<Sect1> <Sect1>
<Title>Playing with <ProductName>Postgres</ProductName></Title> <Title>Playing with <ProductName>Postgres</ProductName></Title>
@ -1282,41 +1320,42 @@ the source distribution. For some ports, the notes below may be out of date.
</Para> </Para>
</Note> </Note>
<Sect2> <Sect2>
<Title>Ultrix4.x</Title> <Title>Ultrix4.x</Title>
<para> <para>
<note> <note>
<para> <para>
There have been no recent reports of Ultrix usage with <productname>Postgres</productname>. There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
</note> </para>
</note>
<para> </para>
<para>
You need to install the libdl-1.1 package since Ultrix 4.x doesn't You need to install the libdl-1.1 package since Ultrix 4.x doesn't
have a dynamic loader. It's available in have a dynamic loader. It's available in
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
</Para> </Para>
</Sect2> </Sect2>
<Sect2> <Sect2>
<Title>Linux</Title> <Title>Linux</Title>
<Sect3> <Sect3>
<Sect3Info> <Sect3Info>
<Author> <Author>
<FirstName>Thomas G.</FirstName> <FirstName>Thomas G.</FirstName>
<SurName>Lockhart</SurName> <SurName>Lockhart</SurName>
</Author> </Author>
<Date>1998-02-19</Date> <Date>1998-02-19</Date>
</Sect3Info> </Sect3Info>
<Title>Linux ELF</Title> <Title>Linux ELF</Title>
<Para> <Para>
The regression test reference machine is The regression test reference machine is
a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686. a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
The linux-elf port installs cleanly. See the Linux FAQ for more details. The linux-elf port installs cleanly. See the Linux FAQ for more details.
</Para> </Para>
</Sect3> </Sect3>
<Sect3> <Sect3>
<Sect3Info> <Sect3Info>
@ -1353,7 +1392,7 @@ The linux-elf port installs cleanly. See the Linux FAQ for more details.
a product so contact him for information. He has also indicated that a product so contact him for information. He has also indicated that
binary releases of <ProductName>Postgres</ProductName> for NEXTSTEP will be made available to binary releases of <ProductName>Postgres</ProductName> for NEXTSTEP will be made available to
the general public. Contact Info@RnA.nl for information. the general public. Contact Info@RnA.nl for information.
</para>
<Para> <Para>
We have no recent reports of successful NeXT installations (as of v6.2.1). We have no recent reports of successful NeXT installations (as of v6.2.1).
However, the client-side libraries should work even However, the client-side libraries should work even

1
doc/src/sgml/intro.sgml
View File

@ -65,6 +65,7 @@ are not as well suited to supporting the traditional relational database languag
So, although <ProductName>Postgres</ProductName> has some object-oriented features, So, although <ProductName>Postgres</ProductName> has some object-oriented features,
it is firmly in the relational database world. In fact, some commercial databases it is firmly in the relational database world. In fact, some commercial databases
have recently incorporated features pioneered by <ProductName>Postgres</ProductName>. have recently incorporated features pioneered by <ProductName>Postgres</ProductName>.
</Para>
</Sect1> </Sect1>

117
doc/src/sgml/jdbc.sgml
View File

@ -7,24 +7,26 @@
<para> <para>
Written by <ulink url="peter@retep.org.uk">Peter T. Mount</ulink>, the Written by <ulink url="peter@retep.org.uk">Peter T. Mount</ulink>, the
author of the <acronym>JDBC</acronym> driver. author of the <acronym>JDBC</acronym> driver.
</para>
</note> </note>
</para>
<para> <para>
<acronym>JDBC</acronym> is a core <acronym>API</acronym> of Java 1.1 and later. <acronym>JDBC</acronym> is a core <acronym>API</acronym> of Java 1.1 and later.
It provides a standard set of It provides a standard set of
interfaces to <acronym>SQL</acronym>-compliant databases. interfaces to <acronym>SQL</acronym>-compliant databases.
</para>
<para> <para>
<application>Postgres</application> provides <application>Postgres</application> provides
a type 4 <acronym>JDBC</acronym> Driver. Type 4 indicates that the driver a type 4 <acronym>JDBC</acronym> Driver. Type 4 indicates that the driver
is written in Pure Java, and communicates in the database's own network is written in Pure Java, and communicates in the database's own network
protocol. Because of this, the driver is platform independent. Once compiled, protocol. Because of this, the driver is platform independent. Once compiled,
the driver can be used on any platform. the driver can be used on any platform.
</para>
<sect1> <sect1>
<title>Building the <acronym>JDBC</acronym> Interface</title> <title>Building the <acronym>JDBC</acronym> Interface</title>
<para>
<sect2> <sect2>
<title>Compiling the Driver</title> <title>Compiling the Driver</title>
@ -36,6 +38,7 @@ source tree. To compile simply change directory to that directory, and type:
<programlisting> <programlisting>
% make % make
</programlisting> </programlisting>
</para>
<para> <para>
Upon completion, you will find the archive <filename>postgresql.jar</filename> Upon completion, you will find the archive <filename>postgresql.jar</filename>
@ -50,7 +53,10 @@ as the driver uses some dynamic
loading techniques for performance reasons, loading techniques for performance reasons,
and <application>javac</application> cannot cope. and <application>javac</application> cannot cope.
The <filename>Makefile</filename> will generate the jar archive. The <filename>Makefile</filename> will generate the jar archive.
</para>
</note> </note>
</para>
</sect2>
<sect2> <sect2>
<title>Installing the Driver</title> <title>Installing the Driver</title>
@ -58,22 +64,29 @@ The <filename>Makefile</filename> will generate the jar archive.
<para> <para>
To use the driver, the jar archive postgresql.jar needs to be included in To use the driver, the jar archive postgresql.jar needs to be included in
the CLASSPATH. the CLASSPATH.
</para>
<para> <para>
Example: Example:
</para>
<para> <para>
I have an application that uses the <acronym>JDBC</acronym> driver to access a large database I have an application that uses the <acronym>JDBC</acronym> driver to access a large database
containing astronomical objects. I have the application and the jdbc driver containing astronomical objects. I have the application and the jdbc driver
installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6. installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6.
</para>
<para> <para>
To run the application, I would use: To run the application, I would use:
</para>
<para> <para>
export CLASSPATH = \ export CLASSPATH = \
/usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:. /usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
java uk.org.retep.finder.Main java uk.org.retep.finder.Main
</para>
<para> <para>
Loading the driver is covered later on in this chapter. Loading the driver is covered later on in this chapter.
<para> </para>
</sect2>
</sect1>
<sect1> <sect1>
<title>Preparing the Database for <acronym>JDBC</acronym></title> <title>Preparing the Database for <acronym>JDBC</acronym></title>
@ -81,22 +94,26 @@ Loading the driver is covered later on in this chapter.
<para> <para>
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
must be running with the -i flag. must be running with the -i flag.
</para>
<para> <para>
Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA Also, the <filename>pg_hba.conf</filename> file must be configured. It's located in the PGDATA
directory. In a default installation, this file permits access only by UNIX directory. In a default installation, this file permits access only by UNIX
domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
to add something like: to add something like:
</para>
<para> <para>
host all 127.0.0.1 255.255.255.255 password host all 127.0.0.1 255.255.255.255 password
</para>
<para> <para>
Here access to all databases are possible from the local machine Here access to all databases are possible from the local machine
with <acronym>JDBC</acronym>. with <acronym>JDBC</acronym>.
</para>
<para> <para>
The <acronym>JDBC</acronym> Driver supports trust, ident, The <acronym>JDBC</acronym> Driver supports trust, ident,
password and crypt authentication methods. password and crypt authentication methods.
</para>
<para> </sect1>
<sect1> <sect1>
<title>Using the Driver</title> <title>Using the Driver</title>
@ -106,10 +123,12 @@ This section is not intended as a complete guide to
<acronym>JDBC</acronym> programming, but <acronym>JDBC</acronym> programming, but
should help to get you started. For more information refer to the standard should help to get you started. For more information refer to the standard
<acronym>JDBC</acronym> <acronym>API</acronym> documentation. <acronym>JDBC</acronym> <acronym>API</acronym> documentation.
</para>
<para> <para>
Also, take a look at the examples included with the source. The basic Also, take a look at the examples included with the source. The basic
example is used here. example is used here.
<para> </para>
</sect1>
<sect1> <sect1>
<title>Importing <acronym>JDBC</acronym></title> <title>Importing <acronym>JDBC</acronym></title>
@ -126,7 +145,10 @@ import java.sql.*;
<para> <para>
Do not import the postgresql package. If you do, your source will not Do not import the postgresql package. If you do, your source will not
compile, as javac will get confused. compile, as javac will get confused.
</para>
</important> </important>
</para>
</sect1>
<sect1> <sect1>
<title>Loading the Driver</title> <title>Loading the Driver</title>
@ -134,6 +156,7 @@ compile, as javac will get confused.
<para> <para>
Before you can connect to a database, you need to load the driver. There Before you can connect to a database, you need to load the driver. There
are two methods available, and it depends on your code to the best one to use. are two methods available, and it depends on your code to the best one to use.
</para>
<para> <para>
In the first method, your code implicitly loads the driver using the In the first method, your code implicitly loads the driver using the
@ -145,36 +168,43 @@ Class.forName(<literal>postgresql.Driver</literal>);
This will load the driver, and while loading, the driver will automatically This will load the driver, and while loading, the driver will automatically
register itself with <acronym>JDBC</acronym>. register itself with <acronym>JDBC</acronym>.
</para>
<para> <para>
Note: The <function>forName()</function> method Note: The <function>forName()</function> method
can throw a ClassNotFoundException, so you will can throw a ClassNotFoundException, so you will
need to catch it if the driver is not available. need to catch it if the driver is not available.
</para>
<para> <para>
This is the most common method to use, but restricts your code to use just This is the most common method to use, but restricts your code to use just
<application>Postgres</application>. <application>Postgres</application>.
If your code may access another database in the future, and you If your code may access another database in the future, and you
don't use our extensions, then the second method is advisable. don't use our extensions, then the second method is advisable.
</para>
<para> <para>
The second method passes the driver as a parameter to the JVM as it starts, The second method passes the driver as a parameter to the JVM as it starts,
using the -D argument. using the -D argument.
</para>
<para> <para>
Example: Example:
<programlisting> <programlisting>
% java -Djdbc.drivers=postgresql.Driver example.ImageViewer % java -Djdbc.drivers=postgresql.Driver example.ImageViewer
</programlisting> </programlisting>
</para>
<para> <para>
In this example, the JVM will attempt to load the driver as part of it's In this example, the JVM will attempt to load the driver as part of it's
initialisation. Once done, the ImageViewer is started. initialisation. Once done, the ImageViewer is started.
</para>
<para> <para>
Now, this method is the better one to use because it allows your code to Now, this method is the better one to use because it allows your code to
be used with other databases, without recompiling the code. The only thing be used with other databases, without recompiling the code. The only thing
that would also change is the URL, which is covered next. that would also change is the URL, which is covered next.
</para>
<para> <para>
One last thing. When your code then tries to open a Connection, and you get One last thing. When your code then tries to open a Connection, and you get
@ -182,6 +212,8 @@ a <literal>No driver available</literal> SQLException being thrown,
this is probably this is probably
caused by the driver not being in the classpath, or the value in the parameter caused by the driver not being in the classpath, or the value in the parameter
not being correct. not being correct.
</para>
</sect1>
<sect1> <sect1>
<title>Connecting to the Database</title> <title>Connecting to the Database</title>
@ -196,14 +228,21 @@ forms:
<listitem> <listitem>
<para> <para>
jdbc:postgresql:<replaceable class="parameter">database</replaceable> jdbc:postgresql:<replaceable class="parameter">database</replaceable>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable> jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
</para>
</listitem>
<listitem> <listitem>
<para> <para>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable> jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
</para>
</listitem>
</itemizedlist> </itemizedlist>
where: where:
@ -212,37 +251,49 @@ where:
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">host</replaceable> <replaceable class="parameter">host</replaceable>
</term>
<listitem> <listitem>
<para> <para>
The hostname of the server. Defaults to "localhost". The hostname of the server. Defaults to "localhost".
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">port</replaceable> <replaceable class="parameter">port</replaceable>
</term>
<listitem> <listitem>
<para> <para>
The port number the server is listening on. Defaults to the Postgres The port number the server is listening on. Defaults to the Postgres
standard port number (5432). standard port number (5432).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">database</replaceable> <replaceable class="parameter">database</replaceable>
</term>
<listitem> <listitem>
<para> <para>
The database name. The database name.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
<para> <para>
To connect, you need to get a Connection instance from To connect, you need to get a Connection instance from
<acronym>JDBC</acronym>. To do this, <acronym>JDBC</acronym>. To do this,
you would use the DriverManager.getConnection() method: you would use the DriverManager.getConnection() method:
</para>
<para> <para>
Connection db = DriverManager.getConnection(url,user,pwd); Connection db = DriverManager.getConnection(url,user,pwd);
<para> </para>
</sect1>
<sect1> <sect1>
<title>Issuing a Query and Processing the Result</title> <title>Issuing a Query and Processing the Result</title>
@ -252,7 +303,7 @@ Any time you want to issue SQL statements to the database, you require a
Statement instance. Once you have a Statement, you can use the executeQuery() Statement instance. Once you have a Statement, you can use the executeQuery()
method to issue a query. This will return a ResultSet instance, which contains method to issue a query. This will return a ResultSet instance, which contains
the entire result. the entire result.
<para> </para>
<sect2> <sect2>
<title>Using the Statement Interface</title> <title>Using the Statement Interface</title>
@ -266,19 +317,26 @@ The following must be considered when using the Statement interface:
You can use a Statement instance as many times as you want. You could You can use a Statement instance as many times as you want. You could
create one as soon as you open the connection, and use it for the connections create one as soon as you open the connection, and use it for the connections
lifetime. You have to remember that only one ResultSet can exist per Statement. lifetime. You have to remember that only one ResultSet can exist per Statement.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
If you need to perform a query while processing a ResultSet, you can If you need to perform a query while processing a ResultSet, you can
simply create and use another Statement. simply create and use another Statement.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
If you are using Threads, and several are using the database, you must If you are using Threads, and several are using the database, you must
use a separate Statement for each thread. Refer to the sections covering use a separate Statement for each thread. Refer to the sections covering
Threads and Servlets later in this document if you are thinking of using them, Threads and Servlets later in this document if you are thinking of using them,
as it covers some important points. as it covers some important points.
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
</sect2>
<sect2> <sect2>
<title>Using the ResultSet Interface</title> <title>Using the ResultSet Interface</title>
@ -291,22 +349,31 @@ The following must be considered when using the ResultSet interface:
<para> <para>
Before reading any values, you must call <function>next()</function>. This returns true if Before reading any values, you must call <function>next()</function>. This returns true if
there is a result, but more importantly, it prepares the row for processing. there is a result, but more importantly, it prepares the row for processing.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest
to stick to this rule, although at the current time, the <application>Postgres</application> driver to stick to this rule, although at the current time, the <application>Postgres</application> driver
will allow you to access a field as many times as you want. will allow you to access a field as many times as you want.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
You must close a ResultSet by calling <function>close()</function> once you have finished with it. You must close a ResultSet by calling <function>close()</function> once you have finished with it.
</para>
</listitem>
<listitem> <listitem>
<para> <para>
Once you request another query with the Statement used to create a Once you request another query with the Statement used to create a
ResultSet, the currently open instance is closed. ResultSet, the currently open instance is closed.
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<para> <para>
An example is as follows: An example is as follows:
@ -321,7 +388,9 @@ while(rs.next()) {
rs.close(); rs.close();
st.close(); st.close();
</programlisting> </programlisting>
</para>
</sect2>
</sect1>
<sect1> <sect1>
<title>Performing Updates</title> <title>Performing Updates</title>
@ -333,7 +402,8 @@ result), you simply use the executeUpdate() method:
<programlisting> <programlisting>
st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>); st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
</programlisting> </programlisting>
</para>
</sect1>
<sect1> <sect1>
<title>Closing the Connection</title> <title>Closing the Connection</title>
@ -344,6 +414,8 @@ To close the database connection, simply call the close() method to the Connecti
<programlisting> <programlisting>
db.close(); db.close();
</programlisting> </programlisting>
</para>
</sect1>
<sect1> <sect1>
<title>Using Large Objects</title> <title>Using Large Objects</title>
@ -353,6 +425,7 @@ In <application>Postgres</application>,
large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
the database that cannot be stored in a normal SQL table. They are stored as a the database that cannot be stored in a normal SQL table. They are stored as a
Table/Index pair, and are refered to from your own tables, by an OID value. Table/Index pair, and are refered to from your own tables, by an OID value.
</para>
<para> <para>
Now, there are you methods of using Large Objects. The first is the Now, there are you methods of using Large Objects. The first is the
@ -360,11 +433,13 @@ standard <acronym>JDBC</acronym> way, and is documented here. The other, uses ou
to the api, which presents the libpq large object <acronym>API</acronym> to Java, providing even to the api, which presents the libpq large object <acronym>API</acronym> to Java, providing even
better access to large objects than the standard. Internally, the driver uses better access to large objects than the standard. Internally, the driver uses
the extension to provide large object support. the extension to provide large object support.
</para>
<para> <para>
In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream() In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
method in ResultSet, and setBinaryStream() method in PreparedStatement. These method in ResultSet, and setBinaryStream() method in PreparedStatement. These
methods make the large object appear as a Java stream, allowing you to use the methods make the large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the object. java.io package, and others, to manipulate the object.
</para>
<para> <para>
For example, suppose For example, suppose
@ -374,6 +449,7 @@ containing that image:
<programlisting> <programlisting>
create table images (imgname name,imgoid oid); create table images (imgname name,imgoid oid);
</programlisting> </programlisting>
</para>
<para> <para>
To insert an image, you would use: To insert an image, you would use:
@ -388,11 +464,13 @@ ps.executeUpdate();
ps.close(); ps.close();
fis.close(); fis.close();
</programlisting> </programlisting>
</para>
<para> <para>
Now in this example, setBinaryStream transfers a set number of bytes from a Now in this example, setBinaryStream transfers a set number of bytes from a
stream into a large object, and stores the OID into the field holding a stream into a large object, and stores the OID into the field holding a
reference to it. reference to it.
</para>
<para> <para>
Retrieving an image is even easier (I'm using PreparedStatement here, but Retrieving an image is even easier (I'm using PreparedStatement here, but
@ -412,13 +490,15 @@ if(rs!=null) {
} }
ps.close(); ps.close();
</programlisting> </programlisting>
</para>
<para> <para>
Now here you can see where the Large Object is retrieved as an InputStream. Now here you can see where the Large Object is retrieved as an InputStream.
You'll also notice that we close the stream before processing the next row in You'll also notice that we close the stream before processing the next row in
the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any
InputStream returned is closed when ResultSet.next() or ResultSet.close() is called. InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
</para>
</sect1>
<sect1> <sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title> <title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>
@ -428,6 +508,7 @@ InputStream returned is closed when ResultSet.next() or ResultSet.close() is cal
You can add your own functions You can add your own functions
to the backend, which can then be called from queries, or even add your own to the backend, which can then be called from queries, or even add your own
data types. data types.
</para>
<para> <para>
Now, as these are facilities unique to us, we support them from Java, with Now, as these are facilities unique to us, we support them from Java, with
a set of extension <acronym>API</acronym>'s. Some features within a set of extension <acronym>API</acronym>'s. Some features within
@ -2511,6 +2592,8 @@ for each Connection.
It's up to you, and your applications requirements. It's up to you, and your applications requirements.
</programlisting> </programlisting>
</para>
</sect1>
<sect1> <sect1>
<title>Further Reading</title> <title>Further Reading</title>
@ -2522,10 +2605,12 @@ Documentation (supplied with Sun's <acronym>JDK</acronym>),
and the <acronym>JDBC</acronym> Specification. and the <acronym>JDBC</acronym> Specification.
Both are available on Both are available on
<ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>. <ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>.
</para>
<para> <para>
<ulink url="http://www.retep.org.uk">My own web site</ulink> <ulink url="http://www.retep.org.uk">My own web site</ulink>
contains updated information not included in this contains updated information not included in this
document, and also includes precompiled drivers for v6.4, and earlier. document, and also includes precompiled drivers for v6.4, and earlier.
</para>
</sect1>
</chapter> </chapter>

12
doc/src/sgml/keys.sgml
View File

@ -1,8 +1,13 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/keys.sgml,v 1.2 1998/08/17 16:18:13 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/keys.sgml,v 1.3 1998/12/29 02:24:16 thomas Exp $
Indices and Keys Indices and Keys
$Log: keys.sgml,v $ $Log: keys.sgml,v $
Revision 1.3 1998/12/29 02:24:16 thomas
Clean up to ensure tag completion as required by the newest versions
of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@michvhf.com>.
Revision 1.2 1998/08/17 16:18:13 thomas Revision 1.2 1998/08/17 16:18:13 thomas
Small sentence cleanups. Add tags for acronyms and products. Small sentence cleanups. Add tags for acronyms and products.
@ -110,6 +115,8 @@ Should not allow NULLs.
</Para> </Para>
</ListItem> </ListItem>
</itemizedlist> </itemizedlist>
</para>
</listitem>
<ListItem> <ListItem>
<Para> <Para>
@ -131,7 +138,10 @@ NULLs are acceptable.
</Para> </Para>
</ListItem> </ListItem>
</itemizedlist> </itemizedlist>
</para>
</listitem>
</itemizedlist> </itemizedlist>
</para>
<Para> <Para>
As for why no non-unique keys are defined explicitly in standard <acronym>SQL</acronym> syntax? As for why no non-unique keys are defined explicitly in standard <acronym>SQL</acronym> syntax?

3
doc/src/sgml/legal.sgml
View File

@ -5,6 +5,7 @@
<ProductName>PostgreSQL</ProductName> is copyright (C) 1996-8 <ProductName>PostgreSQL</ProductName> is copyright (C) 1996-8
by the PostgreSQL Global Development Group, by the PostgreSQL Global Development Group,
and is distributed under the terms of the Berkeley license. and is distributed under the terms of the Berkeley license.
</Para>
<Para> <Para>
<ProductName>Postgres95</ProductName> is copyright (C) 1994-5 <ProductName>Postgres95</ProductName> is copyright (C) 1994-5
@ -38,3 +39,5 @@ Equipment Corp. PA-RISC and HP-UX are trademarks of
Hewlett-Packard Co. OSF/1 is a trademark of the Open Hewlett-Packard Co. OSF/1 is a trademark of the Open
Software Foundation. Software Foundation.
</Para> </Para>
</Sect1>

7
doc/src/sgml/libpgtcl.sgml
View File

@ -281,6 +281,7 @@ Handles start with the prefix "pgsql".
</TITLE> </TITLE>
<PARA><FUNCTION>pg_connect</FUNCTION> opens a connection to the <PARA><FUNCTION>pg_connect</FUNCTION> opens a connection to the
<ProductName>Postgres</ProductName> backend. <ProductName>Postgres</ProductName> backend.
</Para>
<para> <para>
Two syntaxes are available. In the older one, each possible option Two syntaxes are available. In the older one, each possible option
@ -421,8 +422,10 @@ None.
The result is a list describing the possible connection options and their The result is a list describing the possible connection options and their
current default values. current default values.
Each entry in the list is a sublist of the format: Each entry in the list is a sublist of the format:
</Para>
<para> <para>
{optname label dispchar dispsize value} {optname label dispchar dispsize value}
</Para>
<Para> <Para>
where the optname is usable as an option in where the optname is usable as an option in
<FUNCTION>pg_connect -conninfo</FUNCTION>. <FUNCTION>pg_connect -conninfo</FUNCTION>.
@ -540,6 +543,7 @@ to obtain the results of the query.
Query result handles start with the connection handle and add a period Query result handles start with the connection handle and add a period
and a result number. and a result number.
</Para>
<PARA> <PARA>
Note that lack of a Tcl error is not proof that the query succeeded! Note that lack of a Tcl error is not proof that the query succeeded!
@ -548,6 +552,7 @@ as a query result with failure status, not by generating a Tcl error
in pg_exec. in pg_exec.
</PARA> </PARA>
</REFSECT1> </REFSECT1>
</refentry>
<REFENTRY ID="PGTCL-PGRESULT"> <REFENTRY ID="PGTCL-PGRESULT">
<REFMETA> <REFMETA>
@ -765,6 +770,7 @@ The result depends on the selected option, as described above.
<PARA> <PARA>
<FUNCTION>pg_result</FUNCTION> returns information about a query result <FUNCTION>pg_result</FUNCTION> returns information about a query result
created by a prior <FUNCTION>pg_exec</FUNCTION>. created by a prior <FUNCTION>pg_exec</FUNCTION>.
</Para>
<para> <para>
You can keep a query result around for as long as you need it, but when You can keep a query result around for as long as you need it, but when
@ -1012,6 +1018,7 @@ The command string is executed from the Tcl idle loop. That is the normal
idle state of an application written with Tk. In non-Tk Tcl shells, you can idle state of an application written with Tk. In non-Tk Tcl shells, you can
execute <FUNCTION>update</FUNCTION> or <FUNCTION>vwait</FUNCTION> to cause execute <FUNCTION>update</FUNCTION> or <FUNCTION>vwait</FUNCTION> to cause
the idle loop to be entered. the idle loop to be entered.
</Para>
<para> <para>
You should not invoke the SQL statements LISTEN or UNLISTEN directly when You should not invoke the SQL statements LISTEN or UNLISTEN directly when

23
doc/src/sgml/libpq.sgml
View File

@ -24,6 +24,7 @@ following directories:
../src/test/examples ../src/test/examples
../src/bin/psql ../src/bin/psql
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
Frontend programs which use <FileName>libpq</FileName> must include the Frontend programs which use <FileName>libpq</FileName> must include the
@ -317,6 +318,7 @@ char *PQoptions(PGconn *conn)
<synopsis> <synopsis>
ConnStatusType *PQstatus(PGconn *conn) ConnStatusType *PQstatus(PGconn *conn)
</synopsis> </synopsis>
</Para>
<Para> <Para>
A failed connection attempt is signaled by status CONNECTION_BAD. A failed connection attempt is signaled by status CONNECTION_BAD.
@ -324,6 +326,7 @@ Ordinarily, an OK status will remain so until PQfinish, but a
communications failure might result in the status changing to communications failure might result in the status changing to
CONNECTION_BAD prematurely. In that case the application could CONNECTION_BAD prematurely. In that case the application could
try to recover by calling PQreset. try to recover by calling PQreset.
</Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
@ -334,11 +337,13 @@ try to recover by calling PQreset.
<synopsis> <synopsis>
char *PQerrorMessage(PGconn* conn); char *PQerrorMessage(PGconn* conn);
</synopsis> </synopsis>
</Para>
<Para> <Para>
Nearly all libpq functions will set PQerrorMessage if they fail. Nearly all libpq functions will set PQerrorMessage if they fail.
Note that by libpq convention, a non-empty PQerrorMessage will Note that by libpq convention, a non-empty PQerrorMessage will
include a trailing newline. include a trailing newline.
</Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
@ -499,9 +504,11 @@ char *PQfname(PGresult *res,
int PQfnumber(PGresult *res, int PQfnumber(PGresult *res,
char* field_name); char* field_name);
</synopsis> </synopsis>
</Para>
<Para> <Para>
-1 is returned if the given name does not match any field. -1 is returned if the given name does not match any field.
</Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
@ -752,7 +759,6 @@ as with a PGresult returned by libpq itself.
The PQexec function is adequate for submitting queries in simple synchronous The PQexec function is adequate for submitting queries in simple synchronous
applications. It has a couple of major deficiencies however: applications. It has a couple of major deficiencies however:
<Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
@ -783,7 +789,6 @@ Applications that do not like these limitations can instead use the
underlying functions that PQexec is built from: PQsendQuery and underlying functions that PQexec is built from: PQsendQuery and
PQgetResult. PQgetResult.
<Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
@ -837,7 +842,6 @@ still cause the frontend to block until the backend completes the
next SQL command. This can be avoided by proper use of three more next SQL command. This can be avoided by proper use of three more
functions: functions:
<Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
@ -908,10 +912,12 @@ to read the input. It can then call PQisBusy, followed by PQgetResult
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below). An example is given messages (see "Asynchronous Notification", below). An example is given
in the sample programs section. in the sample programs section.
</Para>
<Para> <Para>
A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
a query that is still being processed by the backend. a query that is still being processed by the backend.
</Para>
<Para> <Para>
<ItemizedList> <ItemizedList>
@ -941,6 +947,7 @@ int PQrequestCancel(PGconn *conn);
<Para> <Para>
Note that if the current query is part of a transaction, cancellation Note that if the current query is part of a transaction, cancellation
will abort the whole transaction. will abort the whole transaction.
</Para>
<Para> <Para>
PQrequestCancel can safely be invoked from a signal handler. So, it is PQrequestCancel can safely be invoked from a signal handler. So, it is
@ -950,6 +957,7 @@ PQrequestCancel from a SIGINT signal handler, thus allowing interactive
cancellation of queries that it issues through PQexec. Note that cancellation of queries that it issues through PQexec. Note that
PQrequestCancel will have no effect if the connection is not currently open PQrequestCancel will have no effect if the connection is not currently open
or the backend is not currently processing a query. or the backend is not currently processing a query.
</Para>
</Sect1> </Sect1>
@ -961,7 +969,6 @@ or the backend is not currently processing a query.
function calls to the backend. This is a trapdoor into system internals and function calls to the backend. This is a trapdoor into system internals and
can be a potential security hole. Most users will not need this feature. can be a potential security hole. Most users will not need this feature.
<Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
@ -1023,13 +1030,13 @@ passed from the notifier to the listener. Thus, typically, any actual data
that needs to be communicated is transferred through a database relation. that needs to be communicated is transferred through a database relation.
Commonly the condition name is the same as the associated relation, but it is Commonly the condition name is the same as the associated relation, but it is
not necessary for there to be any associated relation. not necessary for there to be any associated relation.
</Para>
<Para> <Para>
<FileName>libpq</FileName> applications submit LISTEN and UNLISTEN <FileName>libpq</FileName> applications submit LISTEN and UNLISTEN
commands as ordinary SQL queries. Subsequently, arrival of NOTIFY commands as ordinary SQL queries. Subsequently, arrival of NOTIFY
messages can be detected by calling PQnotifies(). messages can be detected by calling PQnotifies().
<Para>
<ItemizedList> <ItemizedList>
<ListItem> <ListItem>
<Para> <Para>
@ -1062,6 +1069,7 @@ typedef struct pgNotify
<Para> <Para>
The second sample program gives an example of the use The second sample program gives an example of the use
of asynchronous notification. of asynchronous notification.
</Para>
<Para> <Para>
PQnotifies() does not actually read backend data; it just returns messages PQnotifies() does not actually read backend data; it just returns messages
@ -1216,6 +1224,7 @@ specified directly.
<synopsis> <synopsis>
int PQendcopy(PGconn *conn); int PQendcopy(PGconn *conn);
</synopsis> </synopsis>
</Para>
<Para> <Para>
As an example: As an example:
@ -1318,10 +1327,12 @@ defaultNoticeProcessor(void * arg, const char * message)
fprintf(stderr, "%s", message); fprintf(stderr, "%s", message);
} }
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
To use a special notice processor, call <function>PQsetNoticeProcessor</function> just after To use a special notice processor, call <function>PQsetNoticeProcessor</function> just after
creation of a new PGconn object. creation of a new PGconn object.
</Para>
</Sect1> </Sect1>
@ -1951,7 +1962,7 @@ main()
} }
</ProgramListing> </ProgramListing>
<Para> </Para>
</Sect2> </Sect2>
</Sect1> </Sect1>

1
doc/src/sgml/lobj.sgml
View File

@ -200,6 +200,7 @@ int lo_close(PGconn *conn, int fd)
lo_open. On success, <Acronym>lo_close</Acronym> returns zero. On error, lo_open. On success, <Acronym>lo_close</Acronym> returns zero. On error,
the return value is negative. the return value is negative.
</Para> </Para>
</sect2>
</Sect1> </Sect1>
<Sect1> <Sect1>

9
doc/src/sgml/manage.sgml
View File

@ -82,6 +82,7 @@ It is possible to create a database in a location other than the default
location for the installation. Remember that all database access actually location for the installation. Remember that all database access actually
occurs through the database backend, so that any location specified must occurs through the database backend, so that any location specified must
be accessible by the backend. be accessible by the backend.
</Para>
<Para> <Para>
Alternate database locations are created and referenced by an environment variable Alternate database locations are created and referenced by an environment variable
@ -94,6 +95,7 @@ Any valid environment variable name may be used to reference an alternate locati
although using variable names with a prefix of <quote>PGDATA</quote> is recommended although using variable names with a prefix of <quote>PGDATA</quote> is recommended
to avoid confusion to avoid confusion
and conflict with other variables. and conflict with other variables.
</Para>
<Note> <Note>
<Para> <Para>
@ -112,10 +114,12 @@ The administrator's guide discusses how to enable this feature.
For security and integrity reasons, For security and integrity reasons,
any path or environment variable specified has some any path or environment variable specified has some
additional path fields appended. additional path fields appended.
</Para>
<Para> <Para>
Alternate database locations must be prepared by running Alternate database locations must be prepared by running
<Application>initlocation</Application>. <Application>initlocation</Application>.
</Para>
<Para> <Para>
To create a data storage area using the environment variable To create a data storage area using the environment variable
@ -128,9 +132,10 @@ Then, from the command line, type
Creating Postgres database system directory /alt/postgres/data Creating Postgres database system directory /alt/postgres/data
Creating Postgres database system directory /alt/postgres/data/base Creating Postgres database system directory /alt/postgres/data/base
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
To create a database in the alternate storage area <envar>PGDATA2<envar> To create a database in the alternate storage area <envar>PGDATA2</envar>
from the command line, use the following command: from the command line, use the following command:
<ProgramListing> <ProgramListing>
% createdb -D PGDATA2 mydb % createdb -D PGDATA2 mydb
@ -161,6 +166,7 @@ the following:
ERROR: Unable to create database directory /alt/postgres/data/base/mydb ERROR: Unable to create database directory /alt/postgres/data/base/mydb
createdb: database creation failed on mydb. createdb: database creation failed on mydb.
</ProgramListing> </ProgramListing>
</Para>
</Sect1> </Sect1>
@ -260,6 +266,7 @@ mydb=> \q
<Title>Database Privileges</Title> <Title>Database Privileges</Title>
<Para> <Para>
</para>
</Sect2> </Sect2>
<Sect2> <Sect2>

11
doc/src/sgml/notation.sgml
View File

@ -11,6 +11,7 @@ Since it is possible to install more than one set of
databases on a single host, this term more precisely denotes any databases on a single host, this term more precisely denotes any
particular set of installed particular set of installed
<Productname>Postgres</Productname> binaries and databases. <Productname>Postgres</Productname> binaries and databases.
</para>
<para> <para>
The The
@ -27,6 +28,7 @@ Note that the <Productname>Postgres</Productname> superuser is
the same as the Unix superuser (which will be referred to as <firstterm>root</firstterm>). the same as the Unix superuser (which will be referred to as <firstterm>root</firstterm>).
The superuser should have a non-zero user identifier (<firstterm>UID</firstterm>) The superuser should have a non-zero user identifier (<firstterm>UID</firstterm>)
for security reasons. for security reasons.
</para>
<para> <para>
The The
@ -37,6 +39,7 @@ enforce a security policy for a site. The DBA can add new users by
the method described below the method described below
and maintain a set of template databases for use by and maintain a set of template databases for use by
<application>createdb</application>. <application>createdb</application>.
</para>
<para> <para>
The <application>postmaster</application> The <application>postmaster</application>
@ -48,6 +51,7 @@ backend processes. The <application>postmaster</application>
can take several command-line arguments to tune its behavior. can take several command-line arguments to tune its behavior.
However, supplying arguments is necessary only if you intend to run multiple However, supplying arguments is necessary only if you intend to run multiple
sites or a non-default site. sites or a non-default site.
</para>
<para> <para>
The <Productname>Postgres</Productname> backend The <Productname>Postgres</Productname> backend
@ -58,6 +62,8 @@ directly from the user shell by the
doing this bypasses the shared buffer pool and lock table associated doing this bypasses the shared buffer pool and lock table associated
with a postmaster/site, therefore this is not recommended in a multiuser with a postmaster/site, therefore this is not recommended in a multiuser
site. site.
</para>
</sect1>
<sect1> <sect1>
<title>Notation</title> <title>Notation</title>
@ -66,6 +72,7 @@ site.
<quote>...</quote> or <filename>/usr/local/pgsql/</filename> <quote>...</quote> or <filename>/usr/local/pgsql/</filename>
at the front of a file name is used to represent the at the front of a file name is used to represent the
path to the <Productname>Postgres</Productname> superuser's home directory. path to the <Productname>Postgres</Productname> superuser's home directory.
</para>
<para> <para>
In a command synopsis, brackets In a command synopsis, brackets
@ -73,10 +80,12 @@ In a command synopsis, brackets
Anything in braces Anything in braces
(<quote>{</quote> and <quote>}</quote>) and containing vertical bars (<quote>|</quote>) (<quote>{</quote> and <quote>}</quote>) and containing vertical bars (<quote>|</quote>)
indicates that you must choose one. indicates that you must choose one.
</para>
<para> <para>
In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean
expressions. <quote>|</quote> is the boolean operator OR. expressions. <quote>|</quote> is the boolean operator OR.
</para>
<para> <para>
Examples will show commands executed from various accounts and programs. Examples will show commands executed from various accounts and programs.
@ -87,6 +96,7 @@ executed from an unprivileged user's account will be preceeded with
<quote>$</quote>. <quote>$</quote>.
<acronym>SQL</acronym> commands will be preceeded with <quote>=&gt;</quote> <acronym>SQL</acronym> commands will be preceeded with <quote>=&gt;</quote>
or will have no leading prompt, depending on the context. or will have no leading prompt, depending on the context.
</para>
<note> <note>
<para> <para>
@ -94,6 +104,7 @@ At the time of writing (<Productname>Postgres</Productname> v6.4) the notation f
flagging commands is not universally consistant throughout the documentation set. flagging commands is not universally consistant throughout the documentation set.
Please report problems to Please report problems to
<ulink url="mailto:docs@postgresql.org">the Documentation Mailing List</ulink>. <ulink url="mailto:docs@postgresql.org">the Documentation Mailing List</ulink>.
</para>
</note> </note>
</sect1> </sect1>

307
doc/src/sgml/odbc.sgml
View File

File diff suppressed because it is too large Load Diff

125
doc/src/sgml/oper.sgml
View File

@ -15,6 +15,7 @@ These operators are declared in the system catalog
pg_operator. Every entry in pg_operator includes pg_operator. Every entry in pg_operator includes
the name of the procedure that implements the operator and the the name of the procedure that implements the operator and the
class <Acronym>OIDs</Acronym> of the input and output types. class <Acronym>OIDs</Acronym> of the input and output types.
</Para>
<Para> <Para>
To view all variations of the <Quote>||</Quote> string concatenation operator, To view all variations of the <Quote>||</Quote> string concatenation operator,
@ -45,11 +46,12 @@ as:
<ProgramListing> <ProgramListing>
select * from emp where int4lt(salary, 40000); select * from emp where int4lt(salary, 40000);
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
<Application>psql</Application> <Application>psql</Application>
has a command (<Command>\dd</Command>) to show these operators. has a command (<Command>\dd</Command>) to show these operators.
</Para>
<sect1> <sect1>
<title>Lexical Precedence</title> <title>Lexical Precedence</title>
@ -70,180 +72,255 @@ Operator Ordering (decreasing precedence)
<row> <row>
<entry> <entry>
Element Element
</entry>
<entry> <entry>
Precedence Precedence
</entry>
<entry> <entry>
Description Description
</entry>
</row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry> <entry>
UNION UNION
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
SQL select construct SQL select construct
</entry>
</row>
<row> <row>
<entry> <entry>
:: ::
</entry>
<entry> <entry>
</entry>
<entry> <entry>
<productname>Postgres</productname> typecasting <productname>Postgres</productname> typecasting
</entry>
</row>
<row> <row>
<entry> <entry>
[ ] [ ]
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
array delimiters array delimiters
</entry>
</row>
<row> <row>
<entry> <entry>
. .
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
table/column delimiter table/column delimiter
</entry>
</row>
<row> <row>
<entry> <entry>
- -
</entry>
<entry> <entry>
right right
</entry>
<entry> <entry>
unary minus unary minus
</entry>
</row>
<row> <row>
<entry> <entry>
; ;
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
statement termination, logarithm statement termination, logarithm
</entry>
</row>
<row> <row>
<entry> <entry>
: :
</entry>
<entry> <entry>
right right
</entry>
<entry> <entry>
exponentiation exponentiation
</entry>
</row>
<row> <row>
<entry> <entry>
| |
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
start of interval start of interval
</entry>
</row>
<row> <row>
<entry> <entry>
* / * /
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
multiplication, division multiplication, division
</entry>
</row>
<row> <row>
<entry> <entry>
+ - + -
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
addition, subtraction addition, subtraction
</entry>
</row>
<row> <row>
<entry> <entry>
IS IS
</entry>
<entry> <entry>
</entry>
<entry> <entry>
test for TRUE, FALSE, NULL test for TRUE, FALSE, NULL
</entry>
</row>
<row> <row>
<entry> <entry>
ISNULL ISNULL
</entry>
<entry> <entry>
</entry>
<entry> <entry>
test for NULL test for NULL
</entry>
</row>
<row> <row>
<entry> <entry>
NOTNULL NOTNULL
</entry>
<entry> <entry>
</entry>
<entry> <entry>
test for NOT NULL test for NOT NULL
</entry>
</row>
<row> <row>
<entry> <entry>
(all other operators) (all other operators)
</entry>
<entry> <entry>
</entry>
<entry> <entry>
native and user-defined native and user-defined
</entry>
</row>
<row> <row>
<entry> <entry>
IN IN
</entry>
<entry> <entry>
</entry>
<entry> <entry>
set membership set membership
</entry>
</row>
<row> <row>
<entry> <entry>
BETWEEN BETWEEN
</entry>
<entry> <entry>
</entry>
<entry> <entry>
containment containment
</entry>
</row>
<row> <row>
<entry> <entry>
LIKE LIKE
</entry>
<entry> <entry>
</entry>
<entry> <entry>
string pattern matching string pattern matching
</entry>
</row>
<row> <row>
<entry> <entry>
&lt; &gt; &lt; &gt;
</entry>
<entry> <entry>
</entry>
<entry> <entry>
boolean inequality boolean inequality
</entry>
</row>
<row> <row>
<entry> <entry>
= =
</entry>
<entry> <entry>
right right
</entry>
<entry> <entry>
equality equality
</entry>
</row>
<row> <row>
<entry> <entry>
NOT NOT
</entry>
<entry> <entry>
right right
</entry>
<entry> <entry>
negation negation
</entry>
</row>
<row> <row>
<entry> <entry>
AND AND
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
logical intersection logical intersection
</entry>
</row>
<row> <row>
<entry> <entry>
OR OR
</entry>
<entry> <entry>
left left
</entry>
<entry> <entry>
logical union logical union
</entry>
</row>
</tbody> </tbody>
</tgroup>
</table> </table>
</para>
</sect1>
<sect1> <sect1>
<title>General Operators</title> <title>General Operators</title>
@ -251,7 +328,7 @@ logical union
<para> <para>
The operators listed here are defined for a number of native data types, The operators listed here are defined for a number of native data types,
ranging from numeric types to data/time types. ranging from numeric types to data/time types.
</para>
<Para> <Para>
<TABLE TOCENTRY="1"> <TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Operators</TITLE> <TITLE><ProductName>Postgres</ProductName> Operators</TITLE>
@ -339,6 +416,7 @@ ranging from numeric types to data/time types.
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
</sect1>
<sect1> <sect1>
<title id="math-opers">Numerical Operators</title> <title id="math-opers">Numerical Operators</title>
@ -430,6 +508,7 @@ ranging from numeric types to data/time types.
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
</sect1>
<sect1> <sect1>
<title>Geometric Operators</title> <title>Geometric Operators</title>
@ -571,6 +650,7 @@ ranging from numeric types to data/time types.
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
</sect1>
<sect1> <sect1>
<title>Time Interval Operators</title> <title>Time Interval Operators</title>
@ -651,6 +731,7 @@ are several operators for this type.
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<title id="cidr-opers">IP V4 Operators</title> <title id="cidr-opers">IP V4 Operators</title>

41
doc/src/sgml/page.sgml
View File

@ -11,6 +11,7 @@ A description of the database file default page format.
<para> <para>
This section provides an overview of the page format used by <productname>Postgres</productname> This section provides an overview of the page format used by <productname>Postgres</productname>
classes. User-defined access methods need not use this page format. classes. User-defined access methods need not use this page format.
</para>
<para> <para>
In the following explanation, a In the following explanation, a
@ -18,6 +19,7 @@ In the following explanation, a
is assumed to contain 8 bits. In addition, the term is assumed to contain 8 bits. In addition, the term
<firstterm>item</firstterm> <firstterm>item</firstterm>
refers to data which is stored in <productname>Postgres</productname> classes. refers to data which is stored in <productname>Postgres</productname> classes.
</para>
<sect1> <sect1>
<title>Page Structure</title> <title>Page Structure</title>
@ -41,50 +43,73 @@ Description
</entry> </entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry> <entry>
itemPointerData itemPointerData
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
filler filler
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
itemData... itemData...
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
Unallocated Space Unallocated Space
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
ItemContinuationData ItemContinuationData
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
Special Space Special Space
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
``ItemData 2'' ``ItemData 2''
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
``ItemData 1'' ``ItemData 1''
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
ItemIdData ItemIdData
</entry> </entry>
</row>
<row> <row>
<entry> <entry>
PageHeaderData PageHeaderData
</entry> </entry>
</row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para>
<!-- <!--
.\" Running .\" Running
@ -121,6 +146,7 @@ the page. Page size is stored in each page because frames in the
buffer pool may be subdivided into equal sized pages on a frame by buffer pool may be subdivided into equal sized pages on a frame by
frame basis within a class. The internal fragmentation information is frame basis within a class. The internal fragmentation information is
used to aid in determining when page reorganization should occur. used to aid in determining when page reorganization should occur.
</para>
<para> <para>
Following the page header are item identifiers Following the page header are item identifiers
@ -134,6 +160,7 @@ created by <productname>Postgres</productname> consists of a frame number and an
identifier. An item identifier contains a byte-offset to the start of identifier. An item identifier contains a byte-offset to the start of
an item, its length in bytes, and a set of attribute bits which affect an item, its length in bytes, and a set of attribute bits which affect
its interpretation. its interpretation.
</para>
<para> <para>
The items themselves are stored in space allocated backwards from The items themselves are stored in space allocated backwards from
@ -148,6 +175,8 @@ This structure contains
itemPointerData itemPointerData
which points to the next piece and the piece itself. The last piece which points to the next piece and the piece itself. The last piece
is handled normally. is handled normally.
</para>
</sect1>
<sect1> <sect1>
<title>Files</title> <title>Files</title>
@ -161,6 +190,9 @@ is handled normally.
<listitem> <listitem>
<para> <para>
Location of shared (global) database files. Location of shared (global) database files.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
@ -169,8 +201,13 @@ Location of shared (global) database files.
<listitem> <listitem>
<para> <para>
Location of local database files. Location of local database files.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</sect1>
<sect1> <sect1>
<title>Bugs</title> <title>Bugs</title>
@ -178,9 +215,11 @@ Location of local database files.
<para> <para>
The page format may change in the future to provide more efficient The page format may change in the future to provide more efficient
access to large objects. access to large objects.
</para>
<para> <para>
This section contains insufficient detail to be of any assistance in This section contains insufficient detail to be of any assistance in
writing a new access method. writing a new access method.
</para>
</sect1>
</chapter> </chapter>

206
doc/src/sgml/pg_options.sgml
View File

@ -17,7 +17,7 @@
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink> Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
</Para> </Para>
</Note> </Note>
</para>
<Para> <Para>
The optional file <filename>data/pg_options</filename> contains runtime The optional file <filename>data/pg_options</filename> contains runtime
options used by the backend to control trace messages and other backend options used by the backend to control trace messages and other backend
@ -32,7 +32,7 @@ parameters which can be used by the backend to control its behaviour.
New options and parameters must be defined in New options and parameters must be defined in
<filename>backend/utils/misc/trace.c</filename> and <filename>backend/utils/misc/trace.c</filename> and
<filename>backend/include/utils/trace.h</filename>. <filename>backend/include/utils/trace.h</filename>.
</para>
<Para> <Para>
For example suppose we want to add conditional trace messages and a tunable For example suppose we want to add conditional trace messages and a tunable
numeric parameter to the code in file <filename>foo.c</filename>. numeric parameter to the code in file <filename>foo.c</filename>.
@ -78,7 +78,7 @@ foo_function(int x, int y)
} }
} }
</programlisting> </programlisting>
</para>
<para> <para>
Existing files using private trace flags can be changed by simply adding Existing files using private trace flags can be changed by simply adding
the following code: the following code:
@ -88,7 +88,7 @@ the following code:
/* int my_own_flag = 0; -- removed */ /* int my_own_flag = 0; -- removed */
#define my_own_flag pg_options[OPT_MY_OWN_FLAG] #define my_own_flag pg_options[OPT_MY_OWN_FLAG]
</programlisting> </programlisting>
</para>
<para> <para>
All pg_options are initialized to zero at backend startup. If we need a All pg_options are initialized to zero at backend startup. If we need a
different default value we must add some initialization code at the beginning different default value we must add some initialization code at the beginning
@ -103,14 +103,14 @@ Now we can set the foo_param and enable foo trace by writing values into the
foo=1 foo=1
fooparam=17 fooparam=17
</programlisting> </programlisting>
</para>
<para> <para>
The new options will be read by all new backends when they are started. The new options will be read by all new backends when they are started.
To make effective the changes for all running backends we need to send a To make effective the changes for all running backends we need to send a
SIGHUP to the postmaster. The signal will be automatically sent to all the SIGHUP to the postmaster. The signal will be automatically sent to all the
backends. We can also activate the changes only for a specific backend by backends. We can also activate the changes only for a specific backend by
sending the SIGHUP directly to it. sending the SIGHUP directly to it.
</para>
<para> <para>
pg_options can also be specified with the <option>-T</option> switch of pg_options can also be specified with the <option>-T</option> switch of
<productname>Postgres</productname>: <productname>Postgres</productname>:
@ -118,7 +118,7 @@ pg_options can also be specified with the <option>-T</option> switch of
<programlisting> <programlisting>
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-" postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
</programlisting> </programlisting>
</para>
<Para> <Para>
The functions used for printing errors and debug messages can now make use The functions used for printing errors and debug messages can now make use
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
@ -135,13 +135,13 @@ or stderr are prefixed by a timestamp containing also the backend pid:
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done 980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
980127.19:52:14.466 [29286] Async_NotifyHandler done 980127.19:52:14.466 [29286] Async_NotifyHandler done
</programlisting> </programlisting>
</para>
<para> <para>
This format improves readability of the logs and allows people to understand This format improves readability of the logs and allows people to understand
exactly which backend is doing what and at which time. It also makes exactly which backend is doing what and at which time. It also makes
easier to write simple awk or perl scripts which monitor the log to easier to write simple awk or perl scripts which monitor the log to
detect database errors or problem, or to compute transaction time statistics. detect database errors or problem, or to compute transaction time statistics.
</para>
<para> <para>
Messages printed to syslog use the log facility LOG_LOCAL0. Messages printed to syslog use the log facility LOG_LOCAL0.
The use of syslog can be controlled with the syslog pg_option. The use of syslog can be controlled with the syslog pg_option.
@ -207,313 +207,421 @@ The options currently defined in
<varlistentry> <varlistentry>
<term> <term>
all all
</term>
<listitem> <listitem>
<para> <para>
Global trace flag. Allowed values are: Global trace flag. Allowed values are:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
0 0
</term>
<listitem> <listitem>
<para> <para>
Trace messages enabled individually Trace messages enabled individually
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
1 1
</term>
<listitem> <listitem>
<para> <para>
Enable all trace messages Enable all trace messages
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-1 -1
</term>
<listitem> <listitem>
<para> <para>
Disable all trace messages Disable all trace messages
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
verbose verbose
</term>
<listitem> <listitem>
<para> <para>
Verbosity flag. Allowed values are: Verbosity flag. Allowed values are:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
0 0
</term>
<listitem> <listitem>
<para> <para>
No messages. This is the default. No messages. This is the default.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
1 1
</term>
<listitem> <listitem>
<para> <para>
Print information messages. Print information messages.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
2 2
</term>
<listitem> <listitem>
<para> <para>
Print more information messages. Print more information messages.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
query query
</term>
<listitem> <listitem>
<para> <para>
Query trace flag. Allowed values are: Query trace flag. Allowed values are:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
0 0
</term>
<listitem> <listitem>
<para> <para>
Don't print query. Don't print query.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
1 1
</term>
<listitem> <listitem>
<para> <para>
Print a condensed query in one line. Print a condensed query in one line.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
4 4
</term>
<listitem> <listitem>
<para> <para>
Print the full query. Print the full query.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
plan plan
</term>
<listitem> <listitem>
<para> <para>
Print query plan. Print query plan.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
parse parse
</term>
<listitem> <listitem>
<para> <para>
Print parser output. Print parser output.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
rewritten rewritten
</term>
<listitem> <listitem>
<para> <para>
Print rewritten query. Print rewritten query.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
parserstats parserstats
</term>
<listitem> <listitem>
<para> <para>
Print parser statistics. Print parser statistics.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
plannerstats plannerstats
</term>
<listitem> <listitem>
<para> <para>
Print planner statistics. Print planner statistics.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
executorstats executorstats
</term>
<listitem> <listitem>
<para> <para>
Print executor statistics. Print executor statistics.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
shortlocks shortlocks
</term>
<listitem> <listitem>
<para> <para>
Currently unused but needed to enable features in the future. Currently unused but needed to enable features in the future.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
locks locks
</term>
<listitem> <listitem>
<para> <para>
Trace locks. Trace locks.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
userlocks userlocks
</term>
<listitem> <listitem>
<para> <para>
Trace user locks. Trace user locks.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
spinlocks spinlocks
</term>
<listitem> <listitem>
<para> <para>
Trace spin locks. Trace spin locks.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
notify notify
</term>
<listitem> <listitem>
<para> <para>
Trace notify functions. Trace notify functions.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
malloc malloc
</term>
<listitem> <listitem>
<para> <para>
Currently unused. Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
palloc palloc
</term>
<listitem> <listitem>
<para> <para>
Currently unused. Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
lock_debug_oidmin lock_debug_oidmin
</term>
<listitem> <listitem>
<para> <para>
Minimum relation oid traced by locks. Minimum relation oid traced by locks.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
lock_debug_relid lock_debug_relid
</term>
<listitem> <listitem>
<para> <para>
oid, if not zero, of relation traced by locks. oid, if not zero, of relation traced by locks.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
lock_read_priority lock_read_priority
</term>
<listitem> <listitem>
<para> <para>
Currently unused. Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
deadlock_timeout deadlock_timeout
</term>
<listitem> <listitem>
<para> <para>
Deadlock check timer. Deadlock check timer.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
syslog syslog
</term>
<listitem> <listitem>
<para> <para>
syslog flag. Allowed values are: syslog flag. Allowed values are:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
0 0
</term>
<listitem> <listitem>
<para> <para>
Messages to stdout/stderr. Messages to stdout/stderr.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
1 1
</term>
<listitem> <listitem>
<para> <para>
Messages to stdout/stderr and syslog. Messages to stdout/stderr and syslog.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
2 2
</term>
<listitem> <listitem>
<para> <para>
Messages only to syslog. Messages only to syslog.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
hostlookup hostlookup
</term>
<listitem> <listitem>
<para> <para>
Enable hostname lookup in ps_status. Enable hostname lookup in ps_status.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
showportnumber showportnumber
</term>
<listitem> <listitem>
<para> <para>
Show port number in ps_status. Show port number in ps_status.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
notifyunlock notifyunlock
</term>
<listitem> <listitem>
<para> <para>
Unlock of pg_listener after notify. Unlock of pg_listener after notify.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
notifyhack notifyhack
</term>
<listitem> <listitem>
<para> <para>
Remove duplicate tuples from pg_listener. Remove duplicate tuples from pg_listener.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>

8
doc/src/sgml/ports.sgml
View File

@ -8,6 +8,7 @@ compiled and tested <ProductName>Postgres</ProductName> on a
number of platforms. Check number of platforms. Check
<ulink url="http://www.postgresql.org/docs/admin/ports.htm">the web site</ulink> <ulink url="http://www.postgresql.org/docs/admin/ports.htm">the web site</ulink>
for the latest information. for the latest information.
</para>
<Sect1> <Sect1>
<Title>Currently Supported Platforms</Title> <Title>Currently Supported Platforms</Title>
@ -226,11 +227,11 @@ At the time of publication, the following platforms have been tested:
</TBODY> </TBODY>
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</para>
<para> <para>
Platforms listed for v6.3.x should also work with v6.4, but we did not receive Platforms listed for v6.3.x should also work with v6.4, but we did not receive
confirmation of such at the time this list was compiled. confirmation of such at the time this list was compiled.
</para>
<note> <note>
<para> <para>
For <productname>Windows NT</productname>, For <productname>Windows NT</productname>,
@ -240,7 +241,9 @@ accomplished. Check
for up to date information. You may also want to for up to date information. You may also want to
look for possible patches on the look for possible patches on the
<ulink url="http://postgresql.org">Postgres web site</ulink>. <ulink url="http://postgresql.org">Postgres web site</ulink>.
</para>
</note> </note>
</sect1>
<Sect1> <Sect1>
<Title>Unsupported Platforms</Title> <Title>Unsupported Platforms</Title>
@ -309,6 +312,7 @@ Others listed here do not provide sufficient library support for an attempt.
</TBODY> </TBODY>
</TGROUP> </TGROUP>
</TABLE> </TABLE>
</para>
<Para> <Para>
Note that Windows ports of the frontend are apparently possible Note that Windows ports of the frontend are apparently possible

59
doc/src/sgml/protocol.sgml
View File

@ -15,6 +15,7 @@ Written by <ULink url="mailto:phil@river-bank.demon.co.uk">Phil Thompson</ULink>
Updates for protocol 2.0 by <ULink url="mailto:tgl@sss.pgh.pa.us">Tom Lane</ULink>. Updates for protocol 2.0 by <ULink url="mailto:tgl@sss.pgh.pa.us">Tom Lane</ULink>.
</Para> </Para>
</Note> </Note>
</para>
<Para> <Para>
<ProductName>Postgres</ProductName> uses a message-based protocol for communication between frontends <ProductName>Postgres</ProductName> uses a message-based protocol for communication between frontends
@ -23,15 +24,18 @@ and backends. The protocol is implemented over <Acronym>TCP/IP</Acronym> and al
This was done in such This was done in such
a way as to still allow connections from earlier versions of frontends, but a way as to still allow connections from earlier versions of frontends, but
this document does not cover the protocol used by those earlier versions. this document does not cover the protocol used by those earlier versions.
</para>
<Para> <Para>
This document describes version 2.0 of the protocol, implemented in This document describes version 2.0 of the protocol, implemented in
<ProductName>Postgres</ProductName> v6.4 and later. <ProductName>Postgres</ProductName> v6.4 and later.
</para>
<Para> <Para>
Higher level features built on this protocol (for example, how <FileName>libpq</FileName> passes Higher level features built on this protocol (for example, how <FileName>libpq</FileName> passes
certain environment variables after the connection is established) certain environment variables after the connection is established)
are covered elsewhere. are covered elsewhere.
</para>
<Sect1> <Sect1>
<Title>Overview</Title> <Title>Overview</Title>
@ -40,6 +44,7 @@ are covered elsewhere.
The three major components are the frontend (running on the client) and the The three major components are the frontend (running on the client) and the
postmaster and backend (running on the server). The postmaster and backend postmaster and backend (running on the server). The postmaster and backend
have different roles but may be implemented by the same executable. have different roles but may be implemented by the same executable.
</para>
<Para> <Para>
A frontend sends a startup packet to the postmaster. This includes the names A frontend sends a startup packet to the postmaster. This includes the names
@ -47,6 +52,7 @@ of the user and the database the user wants to connect to. The postmaster then
uses this, and the information in the pg_hba.conf(5) file to determine what uses this, and the information in the pg_hba.conf(5) file to determine what
further authentication information it requires the frontend to send (if any) further authentication information it requires the frontend to send (if any)
and responds to the frontend accordingly. and responds to the frontend accordingly.
</para>
<Para> <Para>
The frontend then sends any required authentication information. Once the The frontend then sends any required authentication information. Once the
@ -54,6 +60,7 @@ postmaster validates this it responds to the frontend that it is authenticated
and hands over the connection to a backend. The backend then sends a message and hands over the connection to a backend. The backend then sends a message
indicating successful startup (normal case) or failure (for example, an indicating successful startup (normal case) or failure (for example, an
invalid database name). invalid database name).
</para>
<Para> <Para>
Subsequent communications are query and result packets exchanged between the Subsequent communications are query and result packets exchanged between the
@ -61,16 +68,20 @@ frontend and the backend. The postmaster takes no further part in ordinary
query/result communication. (However, the postmaster is involved when the query/result communication. (However, the postmaster is involved when the
frontend wishes to cancel a query currently being executed by its backend. frontend wishes to cancel a query currently being executed by its backend.
Further details about that appear below.) Further details about that appear below.)
</para>
<Para> <Para>
When the frontend wishes to disconnect it sends an appropriate packet and When the frontend wishes to disconnect it sends an appropriate packet and
closes the connection without waiting for a response for the backend. closes the connection without waiting for a response for the backend.
</para>
<Para> <Para>
Packets are sent as a data stream. The first byte determines what should be Packets are sent as a data stream. The first byte determines what should be
expected in the rest of the packet. The exception is packets sent from a expected in the rest of the packet. The exception is packets sent from a
frontend to the postmaster, which comprise a packet length then the packet frontend to the postmaster, which comprise a packet length then the packet
itself. The difference is historical. itself. The difference is historical.
</para>
</sect1>
<Sect1> <Sect1>
<Title>Protocol</Title> <Title>Protocol</Title>
@ -81,6 +92,7 @@ flows depending on the state of the connection:
startup, query, function call, and termination. startup, query, function call, and termination.
There are also special provisions for notification responses and command There are also special provisions for notification responses and command
cancellation, which can occur at any time after the startup phase. cancellation, which can occur at any time after the startup phase.
</para>
<Sect2> <Sect2>
@ -88,12 +100,14 @@ cancellation, which can occur at any time after the startup phase.
<Para> <Para>
Startup is divided into an authentication phase and a backend startup phase. Startup is divided into an authentication phase and a backend startup phase.
</para>
<Para> <Para>
Initially, the frontend sends a StartupPacket. The postmaster uses this info Initially, the frontend sends a StartupPacket. The postmaster uses this info
and the contents of the pg_hba.conf(5) file to determine what authentication and the contents of the pg_hba.conf(5) file to determine what authentication
method the frontend must use. The postmaster then responds with one of the method the frontend must use. The postmaster then responds with one of the
following messages: following messages:
</para>
<Para> <Para>
<VariableList> <VariableList>
@ -176,6 +190,7 @@ following messages:
<Para> <Para>
If the frontend does not support the authentication method requested by the If the frontend does not support the authentication method requested by the
postmaster, then it should immediately close the connection. postmaster, then it should immediately close the connection.
</para>
<Para> <Para>
After sending AuthenticationOk, the postmaster attempts to launch a backend After sending AuthenticationOk, the postmaster attempts to launch a backend
@ -184,7 +199,6 @@ during startup, the frontend must wait for the backend to acknowledge
successful startup. The frontend should send no messages at this point. successful startup. The frontend should send no messages at this point.
The possible messages from the backend during this phase are: The possible messages from the backend during this phase are:
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term> <Term>
@ -244,7 +258,8 @@ reasonable to consider ReadyForQuery as starting a query cycle (and then
BackendKeyData indicates successful conclusion of the startup phase), BackendKeyData indicates successful conclusion of the startup phase),
or to consider ReadyForQuery as ending the startup phase and each subsequent or to consider ReadyForQuery as ending the startup phase and each subsequent
query cycle. query cycle.
</para>
</sect2>
<Sect2> <Sect2>
<Title>Query</Title> <Title>Query</Title>
@ -255,11 +270,11 @@ backend. The backend then sends one or more response messages depending
on the contents of the query command string, and finally a ReadyForQuery on the contents of the query command string, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely response message. ReadyForQuery informs the frontend that it may safely
send a new query or function call. send a new query or function call.
</para>
<Para> <Para>
The possible response messages from the backend are: The possible response messages from the backend are:
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term> <Term>
@ -390,6 +405,7 @@ The possible response messages from the backend are:
<Para> <Para>
A frontend must be prepared to accept ErrorResponse and NoticeResponse A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message. messages whenever it is expecting any other type of message.
</para>
<Para> <Para>
Actually, it is possible for NoticeResponse to arrive even when the frontend Actually, it is possible for NoticeResponse to arrive even when the frontend
@ -398,11 +414,13 @@ is not expecting any kind of message, that is, the backend is nominally idle.
In that case it will send a NoticeResponse before closing the connection.) In that case it will send a NoticeResponse before closing the connection.)
It is recommended that the frontend check for such asynchronous notices just It is recommended that the frontend check for such asynchronous notices just
before issuing any new command. before issuing any new command.
</para>
<Para> <Para>
Also, if the frontend issues any listen(l) commands then it must be prepared Also, if the frontend issues any listen(l) commands then it must be prepared
to accept NotificationResponse messages at any time; see below. to accept NotificationResponse messages at any time; see below.
</para>
</sect2>
<Sect2> <Sect2>
<Title>Function Call</Title> <Title>Function Call</Title>
@ -413,11 +431,11 @@ message to the backend. The backend then sends one or more response messages
depending on the results of the function call, and finally a ReadyForQuery depending on the results of the function call, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely send response message. ReadyForQuery informs the frontend that it may safely send
a new query or function call. a new query or function call.
</para>
<Para> <Para>
The possible response messages from the backend are: The possible response messages from the backend are:
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term> <Term>
@ -482,7 +500,8 @@ A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message. Also, messages whenever it is expecting any other type of message. Also,
if it issues any listen(l) commands then it must be prepared to accept if it issues any listen(l) commands then it must be prepared to accept
NotificationResponse messages at any time; see below. NotificationResponse messages at any time; see below.
</para>
</sect2>
<Sect2> <Sect2>
<Title>Notification Responses</Title> <Title>Notification Responses</Title>
@ -491,6 +510,7 @@ NotificationResponse messages at any time; see below.
If a frontend issues a listen(l) command, then the backend will send a If a frontend issues a listen(l) command, then the backend will send a
NotificationResponse message (not to be confused with NoticeResponse!) NotificationResponse message (not to be confused with NoticeResponse!)
whenever a notify(l) command is executed for the same notification name. whenever a notify(l) command is executed for the same notification name.
</para>
<Para> <Para>
Notification responses are permitted at any point in the protocol (after Notification responses are permitted at any point in the protocol (after
@ -499,7 +519,6 @@ must be prepared to recognize a NotificationResponse message whenever it is
expecting any message. Indeed, it should be able to handle expecting any message. Indeed, it should be able to handle
NotificationResponse messages even when it is not engaged in a query. NotificationResponse messages even when it is not engaged in a query.
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term> <Term>
@ -521,7 +540,8 @@ It may be worth pointing out that the names used in listen and notify
commands need not have anything to do with names of relations (tables) commands need not have anything to do with names of relations (tables)
in the SQL database. Notification names are simply arbitrarily chosen in the SQL database. Notification names are simply arbitrarily chosen
condition names. condition names.
</para>
</sect2>
<Sect2> <Sect2>
<Title>Cancelling Requests in Progress</Title> <Title>Cancelling Requests in Progress</Title>
@ -534,6 +554,7 @@ we don't want to have the backend constantly checking for new input from
the frontend during query processing. Cancel requests should be relatively the frontend during query processing. Cancel requests should be relatively
infrequent, so we make them slightly cumbersome in order to avoid a penalty infrequent, so we make them slightly cumbersome in order to avoid a penalty
in the normal case. in the normal case.
</para>
<Para> <Para>
To issue a cancel request, the frontend opens a new connection to the To issue a cancel request, the frontend opens a new connection to the
@ -541,18 +562,21 @@ postmaster and sends a CancelRequest message, rather than the StartupPacket
message that would ordinarily be sent across a new connection. The postmaster message that would ordinarily be sent across a new connection. The postmaster
will process this request and then close the connection. For security will process this request and then close the connection. For security
reasons, no direct reply is made to the cancel request message. reasons, no direct reply is made to the cancel request message.
</para>
<Para> <Para>
A CancelRequest message will be ignored unless it contains the same key data A CancelRequest message will be ignored unless it contains the same key data
(PID and secret key) passed to the frontend during connection startup. If the (PID and secret key) passed to the frontend during connection startup. If the
request matches the PID and secret key for a currently executing backend, the request matches the PID and secret key for a currently executing backend, the
postmaster signals the backend to abort processing of the current query. postmaster signals the backend to abort processing of the current query.
</para>
<Para> <Para>
The cancellation signal may or may not have any effect --- for example, if it The cancellation signal may or may not have any effect --- for example, if it
arrives after the backend has finished processing the query, then it will have arrives after the backend has finished processing the query, then it will have
no effect. If the cancellation is effective, it results in the current no effect. If the cancellation is effective, it results in the current
command being terminated early with an error message. command being terminated early with an error message.
</para>
<Para> <Para>
The upshot of all this is that for reasons of both security and efficiency, The upshot of all this is that for reasons of both security and efficiency,
@ -561,6 +585,7 @@ It must continue to wait for the backend to respond to the query. Issuing a
cancel simply improves the odds that the current query will finish soon, cancel simply improves the odds that the current query will finish soon,
and improves the odds that it will fail with an error message instead of and improves the odds that it will fail with an error message instead of
succeeding. succeeding.
</para>
<Para> <Para>
Since the cancel request is sent to the postmaster and not across the Since the cancel request is sent to the postmaster and not across the
@ -571,7 +596,8 @@ multiple-process applications. It also introduces a security risk, in that
unauthorized persons might try to cancel queries. The security risk is unauthorized persons might try to cancel queries. The security risk is
addressed by requiring a dynamically generated secret key to be supplied addressed by requiring a dynamically generated secret key to be supplied
in cancel requests. in cancel requests.
</para>
</sect2>
<Sect2> <Sect2>
<Title>Termination</Title> <Title>Termination</Title>
@ -580,6 +606,7 @@ in cancel requests.
The normal, graceful termination procedure is that the frontend sends a The normal, graceful termination procedure is that the frontend sends a
Terminate message and immediately closes the connection. On receipt of the Terminate message and immediately closes the connection. On receipt of the
message, the backend immediately closes the connection and terminates. message, the backend immediately closes the connection and terminates.
</para>
<Para> <Para>
An ungraceful termination may occur due to software failure (i.e., core dump) An ungraceful termination may occur due to software failure (i.e., core dump)
@ -587,7 +614,9 @@ at either end. If either frontend or backend sees an unexpected closure of
the connection, it should clean up and terminate. The frontend has the option the connection, it should clean up and terminate. The frontend has the option
of launching a new backend by recontacting the postmaster, if it doesn't want of launching a new backend by recontacting the postmaster, if it doesn't want
to terminate itself. to terminate itself.
</para>
</sect2>
</sect1>
<Sect1> <Sect1>
<Title>Message Data Types</Title> <Title>Message Data Types</Title>
@ -595,7 +624,6 @@ to terminate itself.
<Para> <Para>
This section describes the base data types used in messages. This section describes the base data types used in messages.
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term> <Term>
@ -655,6 +683,7 @@ Is 8193 bytes the largest allowed size?
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Message Formats</Title> <Title>Message Formats</Title>
@ -662,8 +691,7 @@ Is 8193 bytes the largest allowed size?
<Para> <Para>
This section describes the detailed format of each message. Each can be sent This section describes the detailed format of each message. Each can be sent
by either a frontend (F), a postmaster/backend (B), or both (F & B). by either a frontend (F), a postmaster/backend (B), or both (F & B).
</para>
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
@ -1402,9 +1430,8 @@ FunctionCall (F)
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
<Para>
</Para> </Para>
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
<VarListEntry> <VarListEntry>
@ -1871,6 +1898,6 @@ UnencryptedPasswordPacket (F)
</ListItem> </ListItem>
</VarListEntry> </VarListEntry>
</VariableList> </VariableList>
</Para>
</sect1>
</Chapter> </Chapter>

4
doc/src/sgml/psql.sgml
View File

@ -26,6 +26,7 @@ To affect the paging behavior of your <Command>psql</Command> output,
set or unset your PAGER environment variable. I always have to set mine set or unset your PAGER environment variable. I always have to set mine
before it will pause. And of course you have to do this before before it will pause. And of course you have to do this before
starting the program. starting the program.
</para>
<Para> <Para>
In csh/tcsh or other C shells: In csh/tcsh or other C shells:
@ -39,5 +40,6 @@ while in sh/bash or other Bourne shells:
<ProgramListing> <ProgramListing>
unset PAGER unset PAGER
</ProgramListing> </ProgramListing>
</para>
</sect1>
</Chapter> </Chapter>

17
doc/src/sgml/query-ug.sgml
View File

@ -54,6 +54,7 @@ identifier</FirstTerm> (<Acronym>OID</Acronym>)
single <FileName>postmaster</FileName> process constitutes an installation single <FileName>postmaster</FileName> process constitutes an installation
or site. or site.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Creating a New Class</Title> <Title>Creating a New Class</Title>
@ -71,12 +72,14 @@ CREATE TABLE weather (
date date date date
); );
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
Note that keywords are case-insensitive and identifiers Note that keywords are case-insensitive and identifiers
are usually case-insensitive. are usually case-insensitive.
<Acronym>Postgres</Acronym> allows <Acronym>SQL92</Acronym> <FirstTerm>delimited identifiers</FirstTerm> <Acronym>Postgres</Acronym> allows <Acronym>SQL92</Acronym> <FirstTerm>delimited identifiers</FirstTerm>
(identifiers surrounded by double-quotes) to include mixed-case and spaces, tabs, etc. (identifiers surrounded by double-quotes) to include mixed-case and spaces, tabs, etc.
</para>
<Para> <Para>
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual
@ -95,6 +98,7 @@ a rich set of geometric types. As we will
classes have properties that are extensions of the classes have properties that are extensions of the
relational model. relational model.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Populating a Class with Instances</Title> <Title>Populating a Class with Instances</Title>
@ -107,6 +111,7 @@ a rich set of geometric types. As we will
INSERT INTO weather INSERT INTO weather
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994') VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
You can also use the <Command>copy</Command> command to perform load large You can also use the <Command>copy</Command> command to perform load large
@ -121,6 +126,8 @@ COPY INTO weather FROM '/home/user/weather.txt'
where the path name for the source file must be available to the backend server where the path name for the source file must be available to the backend server
machine, not just the client. machine, not just the client.
</para>
</sect1>
<Sect1> <Sect1>
<Title>Querying a Class</Title> <Title>Querying a Class</Title>
@ -153,6 +160,7 @@ SELECT * FROM WEATHER;
<ProgramListing> <ProgramListing>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather; SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
Arbitrary Boolean operators Arbitrary Boolean operators
@ -183,6 +191,7 @@ SELECT DISTINCT city
ORDER BY city; ORDER BY city;
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Redirecting SELECT Queries</Title> <Title>Redirecting SELECT Queries</Title>
@ -192,6 +201,7 @@ SELECT DISTINCT city
<ProgramListing> <ProgramListing>
SELECT * INTO TABLE temp FROM weather; SELECT * INTO TABLE temp FROM weather;
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
This forms an implicit <Command>create</Command> command, creating a new This forms an implicit <Command>create</Command> command, creating a new
@ -200,6 +210,7 @@ SELECT * INTO TABLE temp FROM weather;
then, of course, perform any operations on the resulting then, of course, perform any operations on the resulting
class that we can perform on other classes. class that we can perform on other classes.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Joins Between Classes</Title> <Title>Joins Between Classes</Title>
@ -258,6 +269,7 @@ The semantics of such a join are
the <Command>select distinct</Command> statement. the <Command>select distinct</Command> statement.
</Para> </Para>
</Note> </Note>
</para>
<Para> <Para>
In this case, both W1 and W2 are surrogates for an In this case, both W1 and W2 are surrogates for an
@ -267,6 +279,7 @@ The semantics of such a join are
A query can contain an arbitrary number of A query can contain an arbitrary number of
class names and surrogates. class names and surrogates.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Updates</Title> <Title>Updates</Title>
@ -283,6 +296,7 @@ UPDATE weather
WHERE date > '11/28/1994'; WHERE date > '11/28/1994';
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Deletions</Title> <Title>Deletions</Title>
@ -304,6 +318,7 @@ DELETE FROM classname;
empty. The system will not request confirmation before empty. The system will not request confirmation before
doing this. doing this.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Using Aggregate Functions</Title> <Title>Using Aggregate Functions</Title>
@ -344,5 +359,5 @@ SELECT city, max(temp_lo)
GROUP BY city; GROUP BY city;
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect1>
</Chapter> </Chapter>

16
doc/src/sgml/query.sgml
View File

@ -60,6 +60,7 @@ has a variety of <Literal>\d</Literal> commands for showing system information.
Consult these commands for more details; Consult these commands for more details;
for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt. for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Concepts</Title> <Title>Concepts</Title>
@ -81,6 +82,7 @@ for a listing, type <Literal>\?</Literal> at the <Application>psql</Application>
single <Application>postmaster</Application> process constitutes an installation single <Application>postmaster</Application> process constitutes an installation
or site. or site.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Creating a New Class</Title> <Title>Creating a New Class</Title>
@ -98,6 +100,7 @@ CREATE TABLE weather (
date date date date
); );
</ProgramListing> </ProgramListing>
</para>
<Para> <Para>
Note that both keywords and identifiers are case-insensitive; identifiers can become Note that both keywords and identifiers are case-insensitive; identifiers can become
@ -118,6 +121,7 @@ a rich set of geometric types. As we will
classes have properties that are extensions of the classes have properties that are extensions of the
relational model. relational model.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Populating a Class with Instances</Title> <Title>Populating a Class with Instances</Title>
@ -130,11 +134,13 @@ a rich set of geometric types. As we will
INSERT INTO weather INSERT INTO weather
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994') VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
You can also use the <Command>copy</Command> command to perform load large You can also use the <Command>copy</Command> command to perform load large
amounts of data from flat (<Acronym>ASCII</Acronym>) files. amounts of data from flat (<Acronym>ASCII</Acronym>) files.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Querying a Class</Title> <Title>Querying a Class</Title>
@ -167,6 +173,7 @@ SELECT * FROM WEATHER;
<ProgramListing> <ProgramListing>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather; SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
Arbitrary Boolean operators Arbitrary Boolean operators
@ -197,6 +204,7 @@ SELECT DISTINCT city
ORDER BY city; ORDER BY city;
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Redirecting SELECT Queries</Title> <Title>Redirecting SELECT Queries</Title>
@ -206,6 +214,7 @@ SELECT DISTINCT city
<ProgramListing> <ProgramListing>
SELECT * INTO TABLE temp FROM weather; SELECT * INTO TABLE temp FROM weather;
</ProgramListing> </ProgramListing>
</Para>
<Para> <Para>
This forms an implicit <Command>create</Command> command, creating a new This forms an implicit <Command>create</Command> command, creating a new
@ -214,6 +223,7 @@ SELECT * INTO TABLE temp FROM weather;
then, of course, perform any operations on the resulting then, of course, perform any operations on the resulting
class that we can perform on other classes. class that we can perform on other classes.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Joins Between Classes</Title> <Title>Joins Between Classes</Title>
@ -272,6 +282,7 @@ The semantics of such a join are
the <Command>select distinct</Command> statement. the <Command>select distinct</Command> statement.
</Para> </Para>
</Note> </Note>
</para>
<Para> <Para>
In this case, both W1 and W2 are surrogates for an In this case, both W1 and W2 are surrogates for an
@ -281,6 +292,7 @@ The semantics of such a join are
A query can contain an arbitrary number of A query can contain an arbitrary number of
class names and surrogates. class names and surrogates.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Updates</Title> <Title>Updates</Title>
@ -297,6 +309,7 @@ UPDATE weather
WHERE date > '11/28/1994'; WHERE date > '11/28/1994';
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Deletions</Title> <Title>Deletions</Title>
@ -318,6 +331,7 @@ DELETE FROM classname;
empty. The system will not request confirmation before empty. The system will not request confirmation before
doing this. doing this.
</Para> </Para>
</sect1>
<Sect1> <Sect1>
<Title>Using Aggregate Functions</Title> <Title>Using Aggregate Functions</Title>
@ -358,5 +372,5 @@ SELECT city, max(temp_lo)
GROUP BY city; GROUP BY city;
</ProgramListing> </ProgramListing>
</Para> </Para>
</sect1>
</Chapter> </Chapter>

20
doc/src/sgml/ref/abort.sgml
View File

@ -12,6 +12,7 @@ ABORT
<REFPURPOSE> <REFPURPOSE>
Aborts the current transaction Aborts the current transaction
</REFPURPOSE> </REFPURPOSE>
</REFNAMEDIV>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-27</DATE> <DATE>1998-09-27</DATE>
@ -29,6 +30,7 @@ Inputs
</TITLE> </TITLE>
<PARA> <PARA>
None. None.
</para>
</REFSECT2> </REFSECT2>
@ -49,7 +51,9 @@ Outputs
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if successful. Message returned if successful.
</para>
</listitem>
</VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
NOTICE: UserAbortTransactionBlock and not in in-progress state NOTICE: UserAbortTransactionBlock and not in in-progress state
@ -58,10 +62,11 @@ ABORT
<LISTITEM> <LISTITEM>
<PARA> <PARA>
If there is not any transaction currently in progress. If there is not any transaction currently in progress.
</para>
</listitem>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -78,7 +83,7 @@ Description
This command is identical This command is identical
in behavior to the <acronym>SQL92</acronym> command <command>ROLLBACK</command>, in behavior to the <acronym>SQL92</acronym> command <command>ROLLBACK</command>,
and is present only for historical reasons. and is present only for historical reasons.
</para>
<REFSECT2 ID="R2-SQL-ABORT-3"> <REFSECT2 ID="R2-SQL-ABORT-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-27</DATE> <DATE>1998-09-27</DATE>
@ -89,7 +94,8 @@ Notes
<para> <para>
Use the <command>COMMIT</command> statement to successfully Use the <command>COMMIT</command> statement to successfully
terminate a transaction. terminate a transaction.
</para>
</refsect2>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-ABORT-2"> <REFSECT1 ID="R1-SQL-ABORT-2">
@ -102,6 +108,7 @@ Usage
-- --
ABORT WORK; ABORT WORK;
</ProgramListing> </ProgramListing>
</para>
</REFSECT1> </REFSECT1>
@ -109,7 +116,6 @@ ABORT WORK;
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-ABORT-4"> <REFSECT2 ID="R2-SQL-ABORT-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -123,5 +129,7 @@ This command is a <productname>Postgres</productname> extension present
for historical reasons. <command>ROLLBACK</command> is the <acronym>SQL92</acronym> for historical reasons. <command>ROLLBACK</command> is the <acronym>SQL92</acronym>
equivalent command. equivalent command.
</PARA> </PARA>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

30
doc/src/sgml/ref/alter_table.sgml
View File

@ -12,6 +12,7 @@ ALTER TABLE
<REFPURPOSE> <REFPURPOSE>
Modifies table properties Modifies table properties
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -89,7 +90,7 @@ Inputs
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-ALTERTABLE-2"> <REFSECT2 ID="R2-SQL-ALTERTABLE-2">
@ -131,9 +132,11 @@ Outputs
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if table or column is not available. Message returned if table or column is not available.
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -153,6 +156,7 @@ Description
the affected table. Thus, the table or column will the affected table. Thus, the table or column will
remain of the same type and size after this command is remain of the same type and size after this command is
executed. executed.
</para>
<PARA> <PARA>
You must own the table in order to change its schema. You must own the table in order to change its schema.
</PARA> </PARA>
@ -166,18 +170,19 @@ Notes
</TITLE> </TITLE>
<PARA> <PARA>
The keyword COLUMN is noise and can be omitted. The keyword COLUMN is noise and can be omitted.
</para>
<PARA> <PARA>
<Quote>[*]</Quote> following a name of a table indicates that statement <Quote>[*]</Quote> following a name of a table indicates that statement
should be run over that table and all tables below it in the should be run over that table and all tables below it in the
inheritance hierarchy. inheritance hierarchy.
The <citetitle>PostgreSQL User's Guide</citetitle> has further The <citetitle>PostgreSQL User's Guide</citetitle> has further
information on inheritance. information on inheritance.
</para>
<PARA> <PARA>
Refer to CREATE TABLE for a further description Refer to CREATE TABLE for a further description
of valid arguments. of valid arguments.
</para>
</REFSECT2> </REFSECT2>
</REFSECT1> </REFSECT1>
@ -190,18 +195,21 @@ Usage
<ProgramListing> <ProgramListing>
ALTER TABLE distributors ADD COLUMN address VARCHAR(30); ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
</ProgramListing> </ProgramListing>
</para>
<PARA> <PARA>
To rename an existing column: To rename an existing column:
<ProgramListing> <ProgramListing>
ALTER TABLE distributors RENAME COLUMN address TO city; ALTER TABLE distributors RENAME COLUMN address TO city;
</ProgramListing> </ProgramListing>
</para>
<PARA> <PARA>
To rename an existing table: To rename an existing table:
<ProgramListing> <ProgramListing>
ALTER TABLE distributors RENAME TO suppliers; ALTER TABLE distributors RENAME TO suppliers;
</ProgramListing> </ProgramListing>
</para>
</REFSECT1> </REFSECT1>
@ -220,11 +228,13 @@ SQL92
<PARA> <PARA>
<command>ALTER TABLE/RENAME</command> <command>ALTER TABLE/RENAME</command>
is a <productname>Postgres</productname> language extension. is a <productname>Postgres</productname> language extension.
</para>
<PARA> <PARA>
SQL92 specifies some additional capabilities for <command>ALTER TABLE</command> SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
statement which are not yet directly supported by statement which are not yet directly supported by
<ProductName>Postgres</ProductName>: <ProductName>Postgres</ProductName>:
</para>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
@ -247,6 +257,7 @@ ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [ COLUMN ]
the new definition. If any constraints on this column already the new definition. If any constraints on this column already
exist, they will be retained using a boolean AND with the new exist, they will be retained using a boolean AND with the new
constraint. constraint.
</para>
<PARA> <PARA>
Currently, to set new default constraints on an existing column Currently, to set new default constraints on an existing column
@ -284,6 +295,7 @@ ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
constraints can be destroyed. constraints can be destroyed.
If CASCADE is specified, Any constraints that are dependent on If CASCADE is specified, Any constraints that are dependent on
this constraint are also dropped. this constraint are also dropped.
</para>
<PARA> <PARA>
Currently, to remove a default value or constraints on an Currently, to remove a default value or constraints on an
@ -295,6 +307,9 @@ DROP TABLE distributors;
CREATE TABLE distributors AS SELECT * FROM temp; CREATE TABLE distributors AS SELECT * FROM temp;
DROP TABLE temp; DROP TABLE temp;
</ProgramListing> </ProgramListing>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -310,6 +325,7 @@ ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
objects can be destroyed. objects can be destroyed.
If CASCADE is specified, all objects that are dependent on If CASCADE is specified, all objects that are dependent on
this column are also dropped. this column are also dropped.
</para>
<PARA> <PARA>
Currently, to remove an existing column the table must be Currently, to remove an existing column the table must be
@ -326,5 +342,9 @@ INSERT INTO distributors SELECT * FROM temp;
DROP TABLE temp; DROP TABLE temp;
</ProgramListing> </ProgramListing>
</PARA> </PARA>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

7
doc/src/sgml/ref/alter_user.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Modifies user account information Modifies user account information
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>
@ -112,8 +113,11 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable>
<PARA> <PARA>
Error message returned if the user specified doesn't Error message returned if the user specified doesn't
exist. exist.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -223,6 +227,7 @@ ALTER USER miriam IN GROUP sales, payroll;
The standard leaves The standard leaves
the definition of users to the implementation. the definition of users to the implementation.
</PARA> </PARA>
</refsect2>
</refsect1> </refsect1>
</REFENTRY> </REFENTRY>

14
doc/src/sgml/ref/begin.sgml
View File

@ -13,7 +13,7 @@
Begins a transaction Begins a transaction
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>
@ -31,6 +31,7 @@ BEGIN [ WORK | TRANSACTION ]
</TITLE> </TITLE>
<PARA> <PARA>
None None
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-BEGINWORK-2"> <REFSECT2 ID="R2-SQL-BEGINWORK-2">
@ -60,9 +61,12 @@ BEGIN [ WORK | TRANSACTION ]
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This indicates that a transaction was already in progress. This indicates that a transaction was already in progress.
The current transaction is not affected. The current transaction is not affected.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -109,6 +113,7 @@ The current transaction is not affected.
to terminate a transaction. to terminate a transaction.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-BEGINWORK-2"> <REFSECT1 ID="R1-SQL-BEGINWORK-2">
<TITLE> <TITLE>
@ -119,6 +124,7 @@ The current transaction is not affected.
<ProgramListing> <ProgramListing>
BEGIN WORK; BEGIN WORK;
</ProgramListing> </ProgramListing>
</para>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-BEGINWORK-3"> <REFSECT1 ID="R1-SQL-BEGINWORK-3">
@ -128,7 +134,7 @@ BEGIN WORK;
<PARA> <PARA>
<command>BEGIN</command> <command>BEGIN</command>
is a <productname>Postgres</productname> language extension. is a <productname>Postgres</productname> language extension.
</para>
<REFSECT2 ID="R2-SQL-BEGINWORK-4"> <REFSECT2 ID="R2-SQL-BEGINWORK-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>

9
doc/src/sgml/ref/close.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Close a cursor Close a cursor
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>
@ -41,6 +41,7 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CLOSE-2"> <REFSECT2 ID="R2-SQL-CLOSE-2">
@ -71,9 +72,11 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
This warning is given if This warning is given if
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> is not <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> is not
declared or has already been closed. declared or has already been closed.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

13
doc/src/sgml/ref/cluster.sgml
View File

@ -12,13 +12,13 @@
<REFPURPOSE> <REFPURPOSE>
Gives storage clustering advice to the backend Gives storage clustering advice to the backend
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CLUSTER-1"> <REFSECT2 ID="R2-SQL-CLUSTER-1">
@ -103,7 +103,7 @@ CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE C
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -139,7 +139,7 @@ to cluster the class specified
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA>
<para> <para>
The table is actually copied to a temporary table in index The table is actually copied to a temporary table in index
order, then renamed back to the original name. For this order, then renamed back to the original name. For this
@ -192,7 +192,8 @@ SELECT ... INTO TABLE <replaceable class="parameter">temp</replaceable> FROM ...
fast because most of the heap data has already been fast because most of the heap data has already been
ordered, and the existing index is used. ordered, and the existing index is used.
</para> </para>
</refsect2>
</refsect1>
<REFSECT1 ID="R1-SQL-CLUSTER-2"> <REFSECT1 ID="R1-SQL-CLUSTER-2">
<TITLE> <TITLE>
@ -202,7 +203,7 @@ SELECT ... INTO TABLE <replaceable class="parameter">temp</replaceable> FROM ...
Cluster the employees relation on the basis of its salary attribute Cluster the employees relation on the basis of its salary attribute
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CLUSTER emp_ind ON emp CLUSTER emp_ind ON emp
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>

13
doc/src/sgml/ref/commit.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Commits the current transaction Commits the current transaction
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
@ -30,8 +30,8 @@ COMMIT [ WORK | TRANSACTION ]
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
None None
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-COMMIT-2"> <REFSECT2 ID="R2-SQL-COMMIT-2">
@ -60,9 +60,12 @@ Message returned if the transaction is successfully committed.
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
If there is no transaction in progress. If there is no transaction in progress.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

33
doc/src/sgml/ref/copy.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Copies data between files and tables Copies data between files and tables
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>
@ -106,6 +107,7 @@ Specifies that output goes to a pipe or terminal.
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-COPY-2"> <REFSECT2 ID="R2-SQL-COPY-2">
@ -135,8 +137,11 @@ Specifies that output goes to a pipe or terminal.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The copy failed for the reason stated in the error message. The copy failed for the reason stated in the error message.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -147,19 +152,18 @@ Specifies that output goes to a pipe or terminal.
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <para>
<command>COPY</command> moves data between <command>COPY</command> moves data between
<productname>Postgres</productname> tables and <productname>Postgres</productname> tables and
standard Unix files. standard Unix files.
<para> <command>COPY</command> instructs
<command>COPY</command> instructs
the <productname>Postgres</productname> backend the <productname>Postgres</productname> backend
to directly read from or write to a file. The file must be directly visible to to directly read from or write to a file. The file must be directly visible to
the backend and the name must be specified from the viewpoint of the backend. the backend and the name must be specified from the viewpoint of the backend.
If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
the backend. the backend.
</para>
<REFSECT2 ID="R2-SQL-COPY-3"> <REFSECT2 ID="R2-SQL-COPY-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-08</DATE> <DATE>1998-09-08</DATE>
@ -189,16 +193,17 @@ the backend.
</para> </para>
<para> <para>
The keyword phrase USING DELIMITERS specifies a single character The keyword phrase USING DELIMITERS specifies a single character
to be used for all delimiters between columns. If multiple characters to be used for all delimiters between columns. If multiple characters
are specified in the delimiter string, only the first character is are specified in the delimiter string, only the first character is
used. used.
<tip> <tip>
<para> <para>
Do not confuse <command>COPY</command> with the Do not confuse <command>COPY</command> with the
<application>psql</application> instruction <command>\copy</command>. <application>psql</application> instruction <command>\copy</command>.
</tip> </para>
</tip>
</para>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>

113
doc/src/sgml/ref/create_aggregate.sgml
View File

@ -13,6 +13,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a new aggregate function Defines a new aggregate function
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE> <DATE>1998-09-09</DATE>
@ -152,7 +153,7 @@ The initial value for the second transition function argument.
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2"> <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2">
@ -172,8 +173,11 @@ The initial value for the second transition function argument.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if the command completes successfully. Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -184,80 +188,80 @@ The initial value for the second transition function argument.
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<para> <para>
<command>CREATE AGGREGATE</command> <command>CREATE AGGREGATE</command>
allows a user or programmer to extend <productname>Postgres</productname> allows a user or programmer to extend <productname>Postgres</productname>
functionality by defining new aggregate functions. Some aggregate functions functionality by defining new aggregate functions. Some aggregate functions
for base types such as <function>min(int4)</function> for base types such as <function>min(int4)</function>
and <function>avg(float8)</function> are already provided in the base and <function>avg(float8)</function> are already provided in the base
distribution. If one defines new types or needs an aggregate function not distribution. If one defines new types or needs an aggregate function not
already provided then <command>CREATE AGGREGATE</command> already provided then <command>CREATE AGGREGATE</command>
can be used to provide the desired features. can be used to provide the desired features.
</para>
<PARA> <PARA>
An aggregate function can require up to three functions, two An aggregate function can require up to three functions, two
state transition functions, state transition functions,
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>: and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
<programlisting> <programlisting>
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1 <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2 <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2
</programlisting> </programlisting>
and a final calculation function, and a final calculation function,
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>: <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>:
<programlisting> <programlisting>
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value
</programlisting> </programlisting>
</para>
<para> <para>
<productname>Postgres</productname> creates up to two temporary variables <productname>Postgres</productname> creates up to two temporary variables
(referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE> (referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>) and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>)
to hold intermediate results used as arguments to the transition functions. to hold intermediate results used as arguments to the transition functions.
</para>
<para> <para>
These transition functions are required to have the following properties: These transition functions are required to have the following properties:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
The arguments to The arguments to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
must be must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
of type of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and and
<REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE>
of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>. of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>.
The return value must be of type The return value must be of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and will be used as the first argument in the next call to and will be used as the first argument in the next call to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>. <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The argument and return value of The argument and return value of
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
must be must be
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
of type of type
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>. <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The arguments to the final-calculation-function The arguments to the final-calculation-function
must be must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and and
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
and its return value must and its return value must
be a <productname>Postgres</productname> be a <productname>Postgres</productname>
base type (not necessarily base type (not necessarily
<REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
which had been specified for BASETYPE). which had been specified for BASETYPE).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -304,38 +308,39 @@ which had been specified for BASETYPE).
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2"> <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2">
<TITLE> <TITLE>
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
Refer to the chapter on aggregate functions Refer to the chapter on aggregate functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle> in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
on aggregate functions for on aggregate functions for
complete examples of usage. complete examples of usage.
</para>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-3"> <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-3">
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4"> <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-09</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
<command>CREATE AGGREGATE</command> <command>CREATE AGGREGATE</command>
is a <productname>Postgres</productname> language extension. is a <productname>Postgres</productname> language extension.
There is no <command>CREATE AGGREGATE</command> in SQL92. There is no <command>CREATE AGGREGATE</command> in SQL92.
</PARA> </PARA>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

29
doc/src/sgml/ref/create_database.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Creates a new database Creates a new database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -55,6 +56,7 @@ CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ WITH LOCATIO
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-2"> <REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
@ -90,14 +92,17 @@ CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ WITH LOCATIO
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ERROR: Unable to create database directory <replaceable class="parameter">directory</replaceable> <ReturnValue>ERROR: Unable to create database directory <replaceable class="parameter">directory</replaceable>
</ReturnValue> </ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
There was a problem with creating the required directory; this operation will There was a problem with creating the required directory; this operation will
need permissions for the <literal>postgres</literal> user on the specified location. need permissions for the <literal>postgres</literal> user on the specified location.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -128,6 +133,7 @@ need permissions for the <literal>postgres</literal> user on the specified locat
Use <command>DROP DATABASE</command> to remove a database. Use <command>DROP DATABASE</command> to remove a database.
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEDATABASE-2"> <REFSECT1 ID="R1-SQL-CREATEDATABASE-2">
<TITLE> <TITLE>
@ -137,18 +143,18 @@ need permissions for the <literal>postgres</literal> user on the specified locat
To create a new database: To create a new database:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput> <prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
</ProgramListing> </ProgramListing>
<PARA> <PARA>
To create a new database in an alternate area <filename>~/private_db</filename>: To create a new database in an alternate area <filename>~/private_db</filename>:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
<prompt>$</prompt> <userinput>mkdir private_db</userinput> <prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput> <prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput> <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
<prompt>$</prompt> <userinput>psql olly</userinput> <prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to the POSTGRESQL interactive sql monitor: <computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \? for help on slash commands type \? for help on slash commands
@ -156,7 +162,7 @@ need permissions for the <literal>postgres</literal> user on the specified locat
type \g or terminate with semicolon to execute query type \g or terminate with semicolon to execute query
You are currently connected to the database: template1 You are currently connected to the database: template1
<prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput> <prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
<computeroutput>CREATEDB</computeroutput> <computeroutput>CREATEDB</computeroutput>
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -190,7 +196,6 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-4"> <REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
<REFSECT2INFO> <REFSECT2INFO>

36
doc/src/sgml/ref/create_function.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a new function Defines a new function
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE> <DATE>1998-09-09</DATE>
@ -90,6 +90,7 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-2"> <REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
@ -109,7 +110,11 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This is returned if the command completes successfully. This is returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -122,8 +127,8 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
</TITLE> </TITLE>
<PARA> <PARA>
<command>CREATE FUNCTION</command> allows a <command>CREATE FUNCTION</command> allows a
<productname>Postgres</productname> user <productname>Postgres</productname> user
to register a function to register a function
with a database. Subsequently, this user is treated as the with a database. Subsequently, this user is treated as the
owner of the function. owner of the function.
</PARA> </PARA>
@ -145,6 +150,7 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
to drop user-defined functions. to drop user-defined functions.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEFUNCTION-2"> <REFSECT1 ID="R1-SQL-CREATEFUNCTION-2">
<TITLE> <TITLE>
@ -154,17 +160,17 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
To create a simple SQL function: To create a simple SQL function:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE FUNCTION one() RETURNS int4 CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT' AS 'SELECT 1 AS RESULT'
LANGUAGE 'sql'; LANGUAGE 'sql';
SELECT one() AS answer; SELECT one() AS answer;
<computeroutput> <computeroutput>
answer answer
------ ------
1 1
</computeroutput> </computeroutput>
</ProgramListing> </ProgramListing>
<para> <para>
To create a C function, calling a routine from a user-created To create a C function, calling a routine from a user-created
@ -173,18 +179,18 @@ answer
is correct. It is intended for use in a CHECK contraint. is correct. It is intended for use in a CHECK contraint.
</para> </para>
<programlisting> <programlisting>
<userinput> <userinput>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c'; AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
CREATE TABLE product CREATE TABLE product
( (
id char(8) PRIMARY KEY, id char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}') eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
REFERENCES brandname(ean_prefix), REFERENCES brandname(ean_prefix),
eancode char(6) CHECK (eancode ~ '[0-9]{6}'), eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode)) CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput> );</userinput>
</programlisting> </programlisting>
</REFSECT1> </REFSECT1>

29
doc/src/sgml/ref/create_index.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Constructs a secondary index Constructs a secondary index
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE> <DATE>1998-09-09</DATE>
@ -153,7 +154,7 @@ SELECT am.amname AS acc_name,
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEINDEX-2"> <REFSECT2 ID="R2-SQL-CREATEINDEX-2">
@ -184,9 +185,11 @@ SELECT am.amname AS acc_name,
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This error occurs if it is impossible to create the index. This error occurs if it is impossible to create the index.
</para>
</VARIABLELIST> </listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -200,15 +203,16 @@ SELECT am.amname AS acc_name,
<PARA> <PARA>
<command>CREATE INDEX</command> constructs an index <command>CREATE INDEX</command> constructs an index
<replaceable class="parameter">index_name</replaceable>. <replaceable class="parameter">index_name</replaceable>.
on the specified on the specified
<replaceable class="parameter">table</replaceable>. <replaceable class="parameter">table</replaceable>.
<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</tip>
<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</para>
</tip>
</para>
<para> <para>
In the first syntax shown above, the key fields for the In the first syntax shown above, the key fields for the
index are specified as column names; a column may also have index are specified as column names; a column may also have
@ -247,6 +251,7 @@ But inappropriate use will result in slower performance.
to remove an index. to remove an index.
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEINDEX-2"> <REFSECT1 ID="R1-SQL-CREATEINDEX-2">
<TITLE> <TITLE>

15
doc/src/sgml/ref/create_language.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a new language for functions Defines a new language for functions
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE> <DATE>1998-09-09</DATE>
@ -93,6 +93,7 @@ superuser privilege can use
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
@ -125,7 +126,11 @@ superuser privilege can use
This error is returned if the function This error is returned if the function
<replaceable class="parameter">funcname</replaceable>() <replaceable class="parameter">funcname</replaceable>()
is not found. is not found.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -206,6 +211,7 @@ Subsequently, functions and
file or anything else that tells the call handler what to file or anything else that tells the call handler what to
do in detail. do in detail.
</para> </para>
</refsect2>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-4"> <REFSECT2 ID="R2-SQL-CREATELANGUAGE-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -320,19 +326,20 @@ sql |postgres
of the dots to complete the PL call handler. of the dots to complete the PL call handler.
See <command>CREATE FUNCTION</command> for information on how to compile See <command>CREATE FUNCTION</command> for information on how to compile
it into a loadable module it into a loadable module
.</para> .</para>
<para> <para>
The following commands then register the sample procedural The following commands then register the sample procedural
language: language:
<programlisting> <programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS opaque CREATE FUNCTION plsample_call_handler () RETURNS opaque
AS '/usr/local/pgsql/lib/plsample.so' AS '/usr/local/pgsql/lib/plsample.so'
LANGUAGE 'C'; LANGUAGE 'C';
CREATE PROCEDURAL LANGUAGE 'plsample' CREATE PROCEDURAL LANGUAGE 'plsample'
HANDLER plsample_call_handler HANDLER plsample_call_handler
LANCOMPILER 'PL/Sample'; LANCOMPILER 'PL/Sample';
</programlisting> </programlisting>
</para>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-7"> <REFSECT1 ID="R1-SQL-CREATELANGUAGE-7">

72
doc/src/sgml/ref/create_operator.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a new user operator Defines a new user operator
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE> <DATE>1998-09-09</DATE>
@ -163,8 +163,11 @@ Operator to use for sorting.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if the operator is successfully created. Message returned if the operator is successfully created.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -176,24 +179,24 @@ Operator to use for sorting.
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
<command>CREATE OPERATOR</command> defines a new operator, <command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>. <replaceable class="parameter">name</replaceable>.
The user who defines an operator becomes its owner. The user who defines an operator becomes its owner.
</para> </para>
<para> <para>
The operator <replaceable class="parameter">name</replaceable> The operator <replaceable class="parameter">name</replaceable>
is a sequence of up to thirty two (32) characters in any combination is a sequence of up to thirty two (32) characters in any combination
from the following: from the following:
<literallayout> <literallayout>
+ - * / &lt; &gt; = ~ ! @ # % ^ & | ` ? $ : + - * / &lt; &gt; = ~ ! @ # % ^ & | ` ? $ :
</literallayout> </literallayout>
<note> <note>
<para> <para>
No alphabetic characters are allowed in an operator name. No alphabetic characters are allowed in an operator name.
This enables <productname>Postgres</productname> to parse SQL input This enables <productname>Postgres</productname> to parse SQL input
into tokens without requiring spaces between each token. into tokens without requiring spaces between each token.
</note> </para>
</note>
</para> </para>
<para> <para>
The operator "!=" is mapped to "&lt;&gt;" on input, so they are The operator "!=" is mapped to "&lt;&gt;" on input, so they are
@ -206,7 +209,7 @@ into tokens without requiring spaces between each token.
unary operators only RIGHTARG should be defined. unary operators only RIGHTARG should be defined.
</para> </para>
<para> <para>
Also, the Also, the
<replaceable class="parameter">func_name</replaceable> procedure must have <replaceable class="parameter">func_name</replaceable> procedure must have
been previously defined using <command>CREATE FUNCTION</command> and must been previously defined using <command>CREATE FUNCTION</command> and must
be defined to accept the correct number of arguments be defined to accept the correct number of arguments
@ -221,11 +224,11 @@ Also, the
operator, area-greater-than, &gt;&gt;&gt;. operator, area-greater-than, &gt;&gt;&gt;.
Hence, the query optimizer could freely convert: Hence, the query optimizer could freely convert:
<programlisting> <programlisting>
"0,0,1,1"::box &gt;&gt;&gt; MYBOXES.description "0,0,1,1"::box &gt;&gt;&gt; MYBOXES.description
</programlisting> </programlisting>
to to
<programlisting> <programlisting>
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting> MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
</para> </para>
<para> <para>
This allows the execution code to always use the latter This allows the execution code to always use the latter
@ -238,16 +241,16 @@ MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
equal, !==. equal, !==.
The negator operator allows the query optimizer to convert The negator operator allows the query optimizer to convert
<programlisting> <programlisting>
NOT MYBOXES.description === "0,0,1,1"::box NOT MYBOXES.description === "0,0,1,1"::box
</programlisting> </programlisting>
to to
<programlisting> <programlisting>
MYBOXES.description !== "0,0,1,1"::box MYBOXES.description !== "0,0,1,1"::box
</programlisting> </programlisting>
</para> </para>
<para> <para>
If a commutator operator name is supplied, If a commutator operator name is supplied,
<productname>Postgres</productname> <productname>Postgres</productname>
searches for it in the catalog. If it is found and it searches for it in the catalog. If it is found and it
does not yet have a commutator itself, then the commutator's does not yet have a commutator itself, then the commutator's
entry is updated to have the current (new) operator entry is updated to have the current (new) operator
@ -264,22 +267,22 @@ MYBOXES.description !== "0,0,1,1"::box
<para> <para>
The next two specifications are present to support the The next two specifications are present to support the
query optimizer in performing joins. query optimizer in performing joins.
<productname>Postgres</productname> can always <productname>Postgres</productname> can always
evaluate a join (i.e., processing a clause with two tuple evaluate a join (i.e., processing a clause with two tuple
variables separated by an operator that returns a boolean) variables separated by an operator that returns a boolean)
by iterative substitution [WONG76]. by iterative substitution [WONG76].
In addition, <productname>Postgres</productname> In addition, <productname>Postgres</productname>
is planning on implementing a hash-join algorithm along is planning on implementing a hash-join algorithm along
the lines of [SHAP86]; however, it must know whether this the lines of [SHAP86]; however, it must know whether this
strategy is applicable. strategy is applicable.
For example, a hash-join For example, a hash-join
algorithm is usable for a clause of the form: algorithm is usable for a clause of the form:
<programlisting> <programlisting>
MYBOXES.description === MYBOXES2.description MYBOXES.description === MYBOXES2.description
</programlisting> </programlisting>
but not for a clause of the form: but not for a clause of the form:
<programlisting> <programlisting>
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description. MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
</programlisting> </programlisting>
The HASHES flag gives the needed information to the query The HASHES flag gives the needed information to the query
optimizer concerning whether a hash join strategy is optimizer concerning whether a hash join strategy is
@ -292,12 +295,12 @@ MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
sort both relations using the operator, &lt;&lt;&lt;. On the other sort both relations using the operator, &lt;&lt;&lt;. On the other
hand, merge-sort is not usable with the clause: hand, merge-sort is not usable with the clause:
<programlisting> <programlisting>
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
</programlisting> </programlisting>
</para> </para>
<para> <para>
If other join strategies are found to be practical, If other join strategies are found to be practical,
<productname>Postgres</productname> <productname>Postgres</productname>
will change the optimizer and run-time system to use will change the optimizer and run-time system to use
them and will require additional specification when an them and will require additional specification when an
operator is defined. Fortunately, the research community operator is defined. Fortunately, the research community
@ -310,7 +313,7 @@ MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
the query optimizer can estimate result sizes. If a the query optimizer can estimate result sizes. If a
clause of the form: clause of the form:
<programlisting> <programlisting>
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
</programlisting> </programlisting>
is present in the qualification, is present in the qualification,
then <productname>Postgres</productname> may have to then <productname>Postgres</productname> may have to
@ -335,11 +338,11 @@ MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
<para> <para>
The difference between the function The difference between the function
<programlisting> <programlisting>
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box) my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
</programlisting> </programlisting>
and the operator and the operator
<programlisting> <programlisting>
MYBOXES.description === "0,0,1,1"::box MYBOXES.description === "0,0,1,1"::box
</programlisting> </programlisting>
is that <productname>Postgres</productname> is that <productname>Postgres</productname>
attempts to optimize operators and can attempts to optimize operators and can
@ -359,12 +362,13 @@ MYBOXES.description === "0,0,1,1"::box
</TITLE> </TITLE>
<PARA> <PARA>
Refer to the chapter on operators in the Refer to the chapter on operators in the
<citetitle>PostgreSQL User's Guide</citetitle> <citetitle>PostgreSQL User's Guide</citetitle>
for further information. for further information.
Refer to <command>DROP OPERATOR</command> to delete Refer to <command>DROP OPERATOR</command> to delete
user-defined operators from a database. user-defined operators from a database.
</para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-2"> <REFSECT1 ID="R1-SQL-CREATEOPERATOR-2">
<TITLE> <TITLE>
@ -374,7 +378,7 @@ user-defined operators from a database.
area-equality, for the BOX data type. area-equality, for the BOX data type.
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE OPERATOR === ( CREATE OPERATOR === (
LEFTARG = box, LEFTARG = box,
RIGHTARG = box, RIGHTARG = box,
PROCEDURE = area_equal_procedure, PROCEDURE = area_equal_procedure,
@ -385,8 +389,6 @@ CREATE OPERATOR === (
JOIN = area-join-procedure, JOIN = area-join-procedure,
SORT = <<<, <<<) SORT = <<<, <<<)
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-3"> <REFSECT1 ID="R1-SQL-CREATEOPERATOR-3">

9
doc/src/sgml/ref/create_rule.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a new rule Defines a new rule
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
@ -110,10 +111,11 @@ CREATE RULE <replaceable class="parameter">name</replaceable>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if the rule is successfully created. Message returned if the rule is successfully created.
</para>
</listitem>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -216,7 +218,7 @@ select * from EMP
<para> <para>
You must have rule definition access to a class in order You must have rule definition access to a class in order
to define a rule on it. Use <command>GRANT</command> to define a rule on it. Use <command>GRANT</command>
and <command>REVOKE</command> to change permissions. and <command>REVOKE</command> to change permissions.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
@ -307,6 +309,7 @@ create rule example_5 is
fail if the rule plus its various internal representations fail if the rule plus its various internal representations
exceed some value that is on the order of one page (8KB). exceed some value that is on the order of one page (8KB).
</PARA> </PARA>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATERULE-4"> <REFSECT1 ID="R1-SQL-CREATERULE-4">
<TITLE> <TITLE>

24
doc/src/sgml/ref/create_sequence.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Creates a new sequence number generator Creates a new sequence number generator
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -197,8 +197,11 @@ CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
If the minimum and maximum values are inconsistant. If the minimum and maximum values are inconsistant.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -254,7 +257,7 @@ SELECT last_value FROM sequence_name;
</para> </para>
<caution> <caution>
<para> <para>
Unexpected results may be obtained if a cache setting greater than one Unexpected results may be obtained if a cache setting greater than one
is used for a sequence object that will be used concurrently by multiple is used for a sequence object that will be used concurrently by multiple
backends. Each backend will allocate "cache" successive sequence values backends. Each backend will allocate "cache" successive sequence values
@ -266,7 +269,7 @@ SELECT last_value FROM sequence_name;
allocate distinct sequence values, the values may be generated out of allocate distinct sequence values, the values may be generated out of
sequence when all the backends are considered. (For example, with a cache sequence when all the backends are considered. (For example, with a cache
setting of 10, backend A might reserve values 1..10 and return nextval=1, setting of 10, backend A might reserve values 1..10 and return nextval=1,
then then
backend B might reserve values 11..20 and return nextval=11 before backend backend B might reserve values 11..20 and return nextval=11 before backend
A has generated nextval=2.) Thus, with a cache setting of one it is safe A has generated nextval=2.) Thus, with a cache setting of one it is safe
to assume that nextval values are generated sequentially; with a cache to assume that nextval values are generated sequentially; with a cache
@ -274,7 +277,8 @@ then
are all distinct, not that they are generated purely sequentially. are all distinct, not that they are generated purely sequentially.
Also, last_value will reflect the latest value reserved by any backend, Also, last_value will reflect the latest value reserved by any backend,
whether or not it has yet been returned by nextval. whether or not it has yet been returned by nextval.
</caution> </para>
</caution>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-3"> <REFSECT2 ID="R2-SQL-CREATESEQUENCE-3">
<REFSECT2INFO> <REFSECT2INFO>
@ -324,13 +328,13 @@ INSERT INTO distributors VALUES (NEXTVAL('serial'),'nothing');
<para> <para>
Set the sequence value after a COPY FROM: Set the sequence value after a COPY FROM:
<programlisting> <programlisting>
CREATE FUNCTION distributors_id_max() RETURNS INT4 CREATE FUNCTION distributors_id_max() RETURNS INT4
AS 'SELECT max(id) FROM distributors' AS 'SELECT max(id) FROM distributors'
LANGUAGE 'sql'; LANGUAGE 'sql';
BEGIN; BEGIN;
COPY distributors FROM 'input_file'; COPY distributors FROM 'input_file';
SELECT setval('serial', distributors_id_max()); SELECT setval('serial', distributors_id_max());
END; END;
</programlisting> </programlisting>
</para> </para>

259
doc/src/sgml/ref/create_table.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Creates a new table Creates a new table
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
@ -20,8 +20,7 @@
<SYNOPSIS> <SYNOPSIS>
CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ( CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> (
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
[ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>] [ NULL | NOT NULL ] [ UNIQUE ] [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> ]
[, NOT NULL ] [ ,UNIQUE ]
[<REPLACEABLE>column_constraint_clause</REPLACEABLE> | PRIMARY KEY } [ ... ] ] [<REPLACEABLE>column_constraint_clause</REPLACEABLE> | PRIMARY KEY } [ ... ] ]
[, ... ] [, ... ]
[, PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] [, PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
@ -135,24 +134,23 @@ requires the <REPLACEABLE CLASS="PARAMETER">column_constraint_clause</REPLACEABL
The optional INHERITS clause specifies a collection of table The optional INHERITS clause specifies a collection of table
names from which this table automatically inherits all fields. names from which this table automatically inherits all fields.
If any inherited field name appears more than once, If any inherited field name appears more than once,
<productname>Postgres</productname> <productname>Postgres</productname>
reports an error. reports an error.
<productname>Postgres</productname> automatically allows the created <productname>Postgres</productname> automatically allows the created
table to inherit functions on tables above it in the inheritance table to inherit functions on tables above it in the inheritance
hierarchy. hierarchy.
<note> <note>
<title>Aside</title> <title>Aside</title>
<para> <para>
Inheritance of functions is done according Inheritance of functions is done according
to the conventions of the Common Lisp Object System (CLOS). to the conventions of the Common Lisp Object System (CLOS).
</note> </para>
</note>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATETABLE-2"> <REFSECT2 ID="R2-SQL-CREATETABLE-2">
@ -201,8 +199,11 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already
<PARA> <PARA>
if data type of default value doesn't match the if data type of default value doesn't match the
column definition's data type. column definition's data type.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -217,7 +218,7 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already
<command>CREATE TABLE</command> will enter a new table into the current data <command>CREATE TABLE</command> will enter a new table into the current data
base. The table will be "owned" by the user issuing the base. The table will be "owned" by the user issuing the
command. command.
</para>
<PARA> <PARA>
The new table is created as a heap with no initial data. The new table is created as a heap with no initial data.
A table can have no more than 1600 columns (realistically, A table can have no more than 1600 columns (realistically,
@ -226,7 +227,7 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already
lower at some sites. A table cannot have the same name as lower at some sites. A table cannot have the same name as
a system catalog table. a system catalog table.
</PARA> </PARA>
</refsect1>
<REFSECT1 ID="R1-SQL-DEFAULTCLAUSE-1"> <REFSECT1 ID="R1-SQL-DEFAULTCLAUSE-1">
<REFSECT1INFO> <REFSECT1INFO>
@ -239,7 +240,7 @@ amcreate: "<replaceable class="parameter">table</replaceable>" relation already
<SYNOPSIS> <SYNOPSIS>
DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
</para>
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-1"> <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
@ -276,8 +277,10 @@ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
</para> </para>
</listitem> </listitem>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-2"> <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
@ -285,7 +288,9 @@ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <para>
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-3"> <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-3">
<REFSECT2INFO> <REFSECT2INFO>
@ -365,6 +370,7 @@ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
<para> <para>
In the current release (v6.4), <productname>Postgres</productname> In the current release (v6.4), <productname>Postgres</productname>
@ -386,7 +392,8 @@ DEFAULT CURRENT_TIMESTAMP
</quote>. </quote>.
This forces <productname>Postgres</productname> to consider the constant a string This forces <productname>Postgres</productname> to consider the constant a string
type and then to convert the value to <type>timestamp</type> at runtime. type and then to convert the value to <type>timestamp</type> at runtime.
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-4"> <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
@ -406,7 +413,7 @@ CREATE TABLE video_sales (
total CASH DEFAULT '$0.0' total CASH DEFAULT '$0.0'
); );
</ProgramListing> </ProgramListing>
</para>
<PARA> <PARA>
To assign an existing sequence To assign an existing sequence
as the default for the column <literal>did</literal>, as the default for the column <literal>did</literal>,
@ -418,7 +425,8 @@ CREATE TABLE distributors (
name VARCHAR(40) DEFAULT 'luso films' name VARCHAR(40) DEFAULT 'luso films'
); );
</ProgramListing> </ProgramListing>
</para>
</refsect2>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-COLUMNCONSTRAINT-1"> <REFSECT1 ID="R1-SQL-COLUMNCONSTRAINT-1">
@ -430,8 +438,9 @@ CREATE TABLE distributors (
</TITLE> </TITLE>
<para> <para>
<SYNOPSIS> <SYNOPSIS>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] { NOT NULL | UNIQUE | PRIMARY KEY | CHECK <replaceable class="parameter">constraint</replaceable> } [, ...] [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] { [ NULL | NOT NULL ] | UNIQUE | PRIMARY KEY | CHECK <replaceable class="parameter">constraint</replaceable> } [, ...]
</SYNOPSIS> </SYNOPSIS>
</para>
<REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-1"> <REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-1">
<REFSECT2INFO> <REFSECT2INFO>
@ -457,6 +466,17 @@ which should ensure uniqueness for
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY>
<TERM>
NULL
</TERM>
<LISTITEM>
<PARA>
The column is allowed to contain NULL values. This is the default.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
NOT NULL NOT NULL
@ -507,6 +527,8 @@ as a unique identifier for rows.
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-2"> <REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-2">
<REFSECT2INFO> <REFSECT2INFO>
@ -544,6 +566,7 @@ as a unique identifier for rows.
accepts the REFERENCES syntax but ignores the clause. accepts the REFERENCES syntax but ignores the clause.
</para> </para>
</note> </note>
</refsect2>
<REFSECT2 ID="R2-SQL-NOTNULL-1"> <REFSECT2 ID="R2-SQL-NOTNULL-1">
<REFSECT2INFO> <REFSECT2INFO>
@ -576,7 +599,7 @@ as a table constraint.
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable> <replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -594,38 +617,45 @@ as a table constraint.
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</refsect3>
<REFSECT3 ID="R3-SQL-NOTNULL-2"> <REFSECT3 ID="R3-SQL-NOTNULL-2">
<REFSECT3INFO> <REFSECT3INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
</REFSECT3INFO> </REFSECT3INFO>
<TITLE> <TITLE>
Description Description
</title> </title>
<para> <para>
</para>
</refsect3>
<REFSECT3 ID="R3-SQL-NOTNULL-3"> <REFSECT3 ID="R3-SQL-NOTNULL-3">
<REFSECT3INFO> <REFSECT3INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
</REFSECT3INFO> </REFSECT3INFO>
<TITLE> <TITLE>
Usage Usage
</title> </title>
<PARA> <PARA>
Define two NOT NULL column constraints on the table Define two NOT NULL column constraints on the table
<classname>distributors</classname>, <classname>distributors</classname>,
one of which being a named constraint: one of which being a named constraint:
</PARA>
<ProgramListing> <ProgramListing>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3) CONSTRAINT no_null NOT NULL, did DECIMAL(3) CONSTRAINT no_null NOT NULL,
name VARCHAR(40) NOT NULL name VARCHAR(40) NOT NULL
); );
</ProgramListing> </ProgramListing>
</para>
</refsect3>
</refsect2>
<REFSECT2 ID="R2-SQL-UNIQUECLAUSE-1"> <REFSECT2 ID="R2-SQL-UNIQUECLAUSE-1">
<REFSECT2INFO> <REFSECT2INFO>
@ -640,7 +670,7 @@ CREATE TABLE distributors (
<refsect3> <refsect3>
<title>Inputs</title> <title>Inputs</title>
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
@ -653,6 +683,7 @@ CREATE TABLE distributors (
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect3> </refsect3>
<refsect3> <refsect3>
@ -677,10 +708,12 @@ CREATE TABLE distributors (
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist></para> </variablelist>
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect3> </refsect3>
<refsect3> <refsect3>
@ -713,6 +746,7 @@ for more details.).
data integrity. See CREATE INDEX for more information. data integrity. See CREATE INDEX for more information.
</Para> </Para>
</Note> </Note>
</refsect3>
<REFSECT3 ID="R3-SQL-UNIQUECLAUSE-3"> <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-3">
<TITLE> <TITLE>
@ -737,6 +771,9 @@ CREATE TABLE distributors (
UNIQUE(name) UNIQUE(name)
); );
</ProgramListing> </ProgramListing>
</para>
</refsect3>
</refsect2>
<REFSECT2 ID="R2-SQL-CHECK-1"> <REFSECT2 ID="R2-SQL-CHECK-1">
<REFSECT2INFO> <REFSECT2INFO>
@ -773,6 +810,7 @@ The CHECK Constraint
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT3> </REFSECT3>
<REFSECT3 ID="R3-SQL-CHECK-2"> <REFSECT3 ID="R3-SQL-CHECK-2">
@ -786,7 +824,7 @@ The CHECK Constraint
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable> <replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -807,16 +845,18 @@ The CHECK Constraint
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT3> </REFSECT3>
<refsect3> <refsect3>
<title>Description</title> <title>Description</title>
<para> <para>
The CHECK constraint specifies a restriction on allowed values The CHECK constraint specifies a restriction on allowed values
within a column. within a column.
The CHECK constraint is also allowed as a table constraint. The CHECK constraint is also allowed as a table constraint.
</PARA> </PARA>
<PARA> <PARA>
@ -909,6 +949,8 @@ However, <productname>Postgres</productname> does not specifically
disallow this. disallow this.
</PARA> </PARA>
</refsect3> </refsect3>
</refsect2>
</refsect1>
<REFSECT1 ID="R1-SQL-TABLECONSTRAINT-1"> <REFSECT1 ID="R1-SQL-TABLECONSTRAINT-1">
<REFSECT1INFO> <REFSECT1INFO>
@ -919,20 +961,19 @@ disallow this.
</TITLE> </TITLE>
<para> <para>
<SYNOPSIS> <SYNOPSIS>
[ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ...] ) [ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ...] )
[ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> ) [ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> )
</SYNOPSIS> </SYNOPSIS>
<PARA> </para>
<REFSECT2 ID="R2-SQL-TABLECONSTRAINT-1"> <REFSECT2 ID="R2-SQL-TABLECONSTRAINT-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<title> <title>
Inputs Inputs
</title> </title>
<para> <para>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -951,9 +992,10 @@ Inputs
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The column name(s) for which to define a unique index The column name(s) for which to define a unique index
and, for PRIMARY KEY, a NOT NULL constraint. and, for PRIMARY KEY, a NOT NULL constraint.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
CHECK ( <replaceable class="parameter">constraint</replaceable> ) CHECK ( <replaceable class="parameter">constraint</replaceable> )
@ -965,26 +1007,30 @@ and, for PRIMARY KEY, a NOT NULL constraint.
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-TABLECONSTRAINT-2"> <REFSECT2 ID="R2-SQL-TABLECONSTRAINT-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<title> <title>
Outputs Outputs
</title> </title>
<para> <para>
The possible outputs for the table constraint clause are the same The possible outputs for the table constraint clause are the same
as for the corresponding portions of the column constraint clause. as for the corresponding portions of the column constraint clause.
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-TABLECONSTRAINT-3"> <REFSECT2 ID="R2-SQL-TABLECONSTRAINT-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<title> <title>
Description Description
</title> </title>
<para> <para>
A table constraint is an integrity constraint defined on one or A table constraint is an integrity constraint defined on one or
@ -1000,13 +1046,14 @@ Description
<note> <note>
<para> <para>
<productname>Postgres</productname> does not yet <productname>Postgres</productname> does not yet
(as of version 6.4) support FOREIGN KEY (as of version 6.4) support FOREIGN KEY
integrity constraints. The parser understands the FOREIGN KEY syntax, integrity constraints. The parser understands the FOREIGN KEY syntax,
but only prints a notice and otherwise ignores the clause. but only prints a notice and otherwise ignores the clause.
Foreign keys may be partially emulated by triggers (See the CREATE TRIGGER Foreign keys may be partially emulated by triggers (See the CREATE TRIGGER
statement). statement).
</para> </para>
</note> </note>
</refsect2>
<REFSECT2 ID="R2-SQL-UNIQUECLAUSE-4"> <REFSECT2 ID="R2-SQL-UNIQUECLAUSE-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -1017,8 +1064,9 @@ but only prints a notice and otherwise ignores the clause.
</TITLE> </TITLE>
<para> <para>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] ) [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] )
</SYNOPSIS> </SYNOPSIS>
</para>
<refsect3> <refsect3>
<title>Inputs</title> <title>Inputs</title>
<variablelist> <variablelist>
@ -1044,13 +1092,14 @@ but only prints a notice and otherwise ignores the clause.
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</refsect3> </refsect3>
<refsect3> <refsect3>
<title>Outputs</title> <title>Outputs</title>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable> <replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -1067,41 +1116,45 @@ but only prints a notice and otherwise ignores the clause.
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect3> </refsect3>
<refsect3> <refsect3>
<title> <title>
Description Description
</title> </title>
<PARA> <PARA>
The UNIQUE constraint specifies a rule that a group of one or The UNIQUE constraint specifies a rule that a group of one or
more distinct columns of a table may contain only unique values. more distinct columns of a table may contain only unique values.
The behavior of the UNIQUE table constraint is the same as that for column The behavior of the UNIQUE table constraint is the same as that for column
constraints, with the additional capability to span multiple columns. constraints, with the additional capability to span multiple columns.
</para> </para>
<para> <para>
See the section on the UNIQUE column constraint for more details. See the section on the UNIQUE column constraint for more details.
</para>
</refsect3>
<REFSECT3 ID="R3-SQL-UNIQUECLAUSE-4"> <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-4">
<TITLE> <TITLE>
Usage Usage
</title> </title>
<PARA> <PARA>
Define a UNIQUE table constraint for the table distributors: Define a UNIQUE table constraint for the table distributors:
<ProgramListing> <ProgramListing>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(03), did DECIMAL(03),
name VARCHAR(40), name VARCHAR(40),
UNIQUE(name) UNIQUE(name)
); );
</ProgramListing> </ProgramListing>
</para>
</refsect3>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-PRIMARYKEY-4"> <REFSECT2 ID="R2-SQL-PRIMARYKEY-4">
@ -1111,18 +1164,18 @@ CREATE TABLE distributors (
<TITLE> <TITLE>
PRIMARY KEY Constraint PRIMARY KEY Constraint
</TITLE> </TITLE>
<para> <para>
<SYNOPSIS> <SYNOPSIS>
[ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] )
</SYNOPSIS> </SYNOPSIS>
</para>
<refsect3> <refsect3>
<title>Inputs</title> <title>Inputs</title>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue> CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -1132,7 +1185,7 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...]
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -1149,10 +1202,10 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable>status</replaceable> <replaceable>status</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>ERROR: Cannot insert a duplicate key into a unique index.</term> <term>ERROR: Cannot insert a duplicate key into a unique index.</term>
@ -1164,6 +1217,7 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
@ -1178,12 +1232,13 @@ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></Retur
the specified columns do not have to include a NOT NULL the specified columns do not have to include a NOT NULL
constraint to be included in a PRIMARY KEY constraint. constraint to be included in a PRIMARY KEY constraint.
The PRIMARY KEY table constraint is similar to that for column constraints, The PRIMARY KEY table constraint is similar to that for column constraints,
with the additional capability of encompassing multiple columns. with the additional capability of encompassing multiple columns.
</PARA> </PARA>
<PARA> <PARA>
Refer to the section on the PRIMARY KEY column constraint for more Refer to the section on the PRIMARY KEY column constraint for more
information. information.
</para>
</REFSECT3> </REFSECT3>
</REFSECT2> </REFSECT2>
@ -1316,7 +1371,6 @@ information.
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATETABLE-4"> <REFSECT2 ID="R2-SQL-CREATETABLE-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -1357,14 +1411,16 @@ information.
) ON COMMIT DELETE ROWS ) ON COMMIT DELETE ROWS
</programlisting> </programlisting>
<para> <para>
Temporary tables are not currently available Temporary tables are not currently available
in <productname>Postgres</productname>. in <productname>Postgres</productname>.
<tip> <tip>
<para> <para>
In the current release of <productname>Postgres</productname> In the current release of <productname>Postgres</productname>
(v6.4), to create a temporary (v6.4), to create a temporary
table you must create and drop the table by explicit commands. table you must create and drop the table by explicit commands.
</tip> </para>
</tip>
</para>
<REFSECT3 ID="R3-SQL-UNIQUECLAUSE-1"> <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-1">
<REFSECT3INFO> <REFSECT3INFO>
@ -1375,6 +1431,7 @@ Temporary tables are not currently available
</TITLE> </TITLE>
<PARA> <PARA>
SQL92 specifies some additional capabilities for UNIQUE: SQL92 specifies some additional capabilities for UNIQUE:
</para>
<para> <para>
Table Constraint definition Table Constraint definition
</PARA> </PARA>
@ -1395,6 +1452,23 @@ Temporary tables are not currently available
</synopsis> </synopsis>
</refsect3> </refsect3>
<REFSECT3 ID="R3-SQL-NULL-1">
<REFSECT3INFO>
<DATE>1998-12-24</DATE>
</REFSECT3INFO>
<TITLE>
NULL clause
</TITLE>
<PARA>
The NULL "constraint" (actually a non-constraint)
is a <productname>Postgres</productname> extension to SQL92
is included for symmetry with the NOT NULL clause. Since it is the default
for any column, its presence is simply noise.
<synopsis>
[ CONSTRAINT name ] NULL
</synopsis>
</REFSECT3>
<REFSECT3 ID="R3-SQL-NOTNULL-4"> <REFSECT3 ID="R3-SQL-NOTNULL-4">
<REFSECT3INFO> <REFSECT3INFO>
<DATE>1998-09-11</DATE> <DATE>1998-09-11</DATE>
@ -1453,10 +1527,10 @@ the column. Not our problem...
<note> <note>
<para> <para>
<productname>Postgres</productname> does not yet support <productname>Postgres</productname> does not yet support
either domains or assertions. either domains or assertions.
</para> </para>
</note> </note>
</para>
<PARA> <PARA>
An assertion is a special type of integrity constraint and share An assertion is a special type of integrity constraint and share
the same namespace as other constraints. the same namespace as other constraints.
@ -1672,7 +1746,7 @@ affect a column or a table.
<REFPURPOSE> <REFPURPOSE>
Creates a new table Creates a new table
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -1726,6 +1800,8 @@ allowed syntax.
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</refsect2>
<REFSECT2 ID="R2-SQL-CREATETABLEAS-2"> <REFSECT2 ID="R2-SQL-CREATETABLEAS-2">
<REFSECT2INFO> <REFSECT2INFO>
@ -1736,7 +1812,10 @@ allowed syntax.
</TITLE> </TITLE>
<PARA> <PARA>
Refer to CREATE TABLE and SELECT for a summary of possible output Refer to CREATE TABLE and SELECT for a summary of possible output
messages. messages.
</para>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-SQL-CREATETABLEAS-1"> <REFSECT1 ID="R1-SQL-CREATETABLEAS-1">
<REFSECT1INFO> <REFSECT1INFO>
@ -1749,8 +1828,8 @@ messages.
CREATE TABLE AS enables a table to be created from the contents of CREATE TABLE AS enables a table to be created from the contents of
an existing table. It has functionality equivalent to SELECT TABLE INTO, an existing table. It has functionality equivalent to SELECT TABLE INTO,
but with perhaps a more obvious syntax. but with perhaps a more obvious syntax.
</para>
</refsect1> </refsect1>
</refentry> </refentry>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

18
doc/src/sgml/ref/create_trigger.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Creates a new trigger Creates a new trigger
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE> <DATE>1998-09-21</DATE>
@ -92,8 +93,11 @@ CREATE TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> { BEFORE | AFTE
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message is returned if the trigger is successfully created. This message is returned if the trigger is successfully created.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -148,8 +152,8 @@ CREATE TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> { BEFORE | AFTE
Refer to <command>DROP TRIGGER</command> for information on how to Refer to <command>DROP TRIGGER</command> for information on how to
remove triggers. remove triggers.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATETRIGGER-2"> <REFSECT1 ID="R1-SQL-CREATETRIGGER-2">
<TITLE> <TITLE>
@ -160,7 +164,7 @@ CREATE TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> { BEFORE | AFTE
table before appending or updating a row in the table films: table before appending or updating a row in the table films:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE TRIGGER if_dist_exists CREATE TRIGGER if_dist_exists
BEFORE INSERT OR UPDATE ON films FOR EACH ROW BEFORE INSERT OR UPDATE ON films FOR EACH ROW
EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did'); EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
</ProgramListing> </ProgramListing>
@ -169,7 +173,7 @@ CREATE TRIGGER if_dist_exists
reference to the table films: reference to the table films:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE TRIGGER if_film_exists CREATE TRIGGER if_film_exists
BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did'); EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
</ProgramListing> </ProgramListing>
@ -197,18 +201,20 @@ CREATE TRIGGER if_film_exists
constraint as in: constraint as in:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did DECIMAL(3),
name VARCHAR(40), name VARCHAR(40),
CONSTRAINT if_film_exists CONSTRAINT if_film_exists
FOREIGN KEY(did) REFERENCES films FOREIGN KEY(did) REFERENCES films
ON UPDATE CASCADE ON DELETE CASCADE ON UPDATE CASCADE ON DELETE CASCADE
); );
</ProgramListing> </ProgramListing>
<PARA> <PARA>
However, foreign keys are not yet implemented (as of version 6.4) in However, foreign keys are not yet implemented (as of version 6.4) in
<productname>Postgres</productname>. <productname>Postgres</productname>.
</PARA> </PARA>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

18
doc/src/sgml/ref/create_type.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a new base data type Defines a new base data type
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE> <DATE>1998-09-21</DATE>
@ -175,9 +176,11 @@ EXTERNALLENGTH <replaceable class="parameter">externallength</replaceable>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if the type is successfully created. Message returned if the type is successfully created.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -290,11 +293,13 @@ it with the fact that the data is not present></comment>
length. If you need a larger type you must create a Large length. If you need a larger type you must create a Large
Object type. The interface for these types is discussed Object type. The interface for these types is discussed
at length in at length in
<comment>This section reference needs replacing</comment> <comment>This section reference needs replacing</comment>
Section 7, the large object interface. The Section 7, the large object interface. The
length of all large object types is always VARIABLE. length of all large object types is always VARIABLE.
</para>
</refsect2> </refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
<para> <para>
@ -339,6 +344,7 @@ it with the fact that the data is not present></comment>
with an underscore. with an underscore.
</para> </para>
</refsect2> </refsect2>
<REFSECT2 ID="R2-SQL-CREATETYPE-3"> <REFSECT2 ID="R2-SQL-CREATETYPE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-21</DATE> <DATE>1998-09-21</DATE>
@ -352,8 +358,8 @@ it with the fact that the data is not present></comment>
<PARA> <PARA>
See also <command>CREATE FUNCTION</command>, See also <command>CREATE FUNCTION</command>,
<command>CREATE OPERATOR</command> and the chapter on Large Objects <command>CREATE OPERATOR</command> and the chapter on Large Objects
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>. in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>
@ -362,7 +368,6 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-CREATETYPE-4"> <REFSECT2 ID="R2-SQL-CREATETYPE-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -376,6 +381,7 @@ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
</REFENTRY> </REFENTRY>

9
doc/src/sgml/ref/create_user.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Creates account information for a new user Creates account information for a new user
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE> <DATE>1998-09-21</DATE>
@ -130,6 +131,7 @@ CREATE USER<REPLACEABLE CLASS="PARAMETER"> username</REPLACEABLE>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEUSER-2"> <REFSECT2 ID="R2-SQL-CREATEUSER-2">
@ -161,7 +163,9 @@ CREATE USER<REPLACEABLE CLASS="PARAMETER"> username</REPLACEABLE>
if "<replaceable class="parameter">username</replaceable>" not found. if "<replaceable class="parameter">username</replaceable>" not found.
</PARA> </PARA>
<comment>I don't understand this and I don't know how to get <comment>I don't understand this and I don't know how to get
this error message.</comment> this error message.</comment>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -226,6 +230,7 @@ this error message.</comment>
+--------------------------+--------------------------+-------+ +--------------------------+--------------------------+-------+
</programlisting> </programlisting>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEUSER-2"> <REFSECT1 ID="R1-SQL-CREATEUSER-2">
<TITLE> <TITLE>
@ -277,6 +282,8 @@ this error message.</comment>
<PARA> <PARA>
There is no CREATE USER statement in SQL92. There is no CREATE USER statement in SQL92.
</PARA> </PARA>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

8
doc/src/sgml/ref/create_view.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Constructs a virtual table Constructs a virtual table
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE> <DATE>1998-09-21</DATE>
@ -55,6 +56,7 @@ An SQL query which will provide the columns and rows of the view.
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEVIEW-2"> <REFSECT2 ID="R2-SQL-CREATEVIEW-2">
@ -104,8 +106,11 @@ An SQL query which will provide the columns and rows of the view.
<programlisting> <programlisting>
CREATE VIEW vista AS SELECT 'Hello World'::text CREATE VIEW vista AS SELECT 'Hello World'::text
</programlisting> </programlisting>
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -146,6 +151,7 @@ An SQL query which will provide the columns and rows of the view.
Currently, views are read only. Currently, views are read only.
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-CREATEVIEW-2"> <REFSECT1 ID="R1-SQL-CREATEVIEW-2">
<TITLE> <TITLE>

429
doc/src/sgml/ref/createdb.sgml
View File

@ -1,223 +1,266 @@
<REFENTRY ID="APP-CREATEDB"> <REFENTRY ID="APP-CREATEDB">
<REFMETA> <REFMETA>
<REFENTRYTITLE> <REFENTRYTITLE>
<application>createdb</application> <application>createdb</application>
</REFENTRYTITLE> </REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO> <REFMISCINFO>Application</REFMISCINFO>
</REFMETA> </REFMETA>
<REFNAMEDIV> <REFNAMEDIV>
<REFNAME> <REFNAME>
<application>createdb</application> <application>createdb</application>
</REFNAME> </REFNAME>
<REFPURPOSE> <REFPURPOSE>
Create a new <productname>Postgres</productname> database Create a new <productname>Postgres</productname> database
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> </refnamediv>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIV>
<DATE>1998-10-02</DATE> <REFSYNOPSISDIVINFO>
</REFSYNOPSISDIVINFO> <DATE>1998-10-02</DATE>
<SYNOPSIS> </REFSYNOPSISDIVINFO>
createdb [ <replaceable class="parameter">dbname</replaceable> ] <SYNOPSIS>
createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] createdb [ <replaceable class="parameter">dbname</replaceable> ]
createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -D <replaceable class="parameter">datadir</replaceable> ] [ -D <replaceable class="parameter">datadir</replaceable> ]
[ -u ] [ <replaceable class="parameter">dbname</replaceable> ] [ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEDB-1"> <REFSECT2 ID="R2-APP-CREATEDB-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
-h <replaceable class="parameter">host</replaceable> -h <replaceable class="parameter">host</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the hostname of the machine on which the Specifies the hostname of the machine on which the
<application>postmaster</application> <application>postmaster</application>
is running. Defaults to using a local Unix domain socket is running. Defaults to using a local Unix domain socket
rather than an IP connection.. rather than an IP connection..
</para>
<varlistentry> </listitem>
<term> </varlistentry>
-p <replaceable class="parameter">port</replaceable> <varlistentry>
</term> <term>
<listitem> -p <replaceable class="parameter">port</replaceable>
<para> </term>
Specifies the Internet TCP/IP port or local Unix domain socket file <listitem>
extension on which the <application>postmaster</application> <para>
is listening for connections. The port number defaults to 5432, Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar> or the value of the <envar>PGPORT</envar>
environment variable (if set). environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-u -u
</term> </term>
<listitem> <listitem>
<para> <para>
Use password authentication. Use password authentication.
Prompts for Prompts for
<replaceable class="parameter">username</replaceable> <replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>. and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-D <replaceable class="parameter">datadir</replaceable> -D <replaceable class="parameter">datadir</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the alternate database location for this database installation. Specifies the alternate database location for this database installation.
This is the location of the installation system tables, not the location This is the location of the installation system tables, not the location
of this specific database, which may be different. of this specific database, which may be different.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the name of the database to be created. The name must be Specifies the name of the database to be created. The name must be
unique among all <productname>Postgres</productname> databases in this installation. unique among all <productname>Postgres</productname> databases in this installation.
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
defaults to the value of the defaults to the value of the
<envar>USER</envar> <envar>USER</envar>
environment variable. environment variable.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-CREATEDB-2"> <REFSECT2 ID="R2-APP-CREATEDB-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>createdb</application> will create files in the <application>createdb</application> will create files in the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename> <filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the new database. data area for the new database.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>. createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
<application>createdb</application> could not attach to the <para>
<application>postmaster</application> <application>createdb</application> could not attach to the
process on the specified host and port. If you see this message, <application>postmaster</application>
ensure that the <application>postmaster</application> process on the specified host and port. If you see this message,
is running on the proper host and that you have specified the proper ensure that the <application>postmaster</application>
port. If your site uses an authentication system, ensure that you is running on the proper host and that you have specified the proper
have obtained the required authentication credentials. port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>. createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
You do not have a valid entry in the relation <literal>pg_shadow</literal> <para>
and and will not be allowed to access <productname>Postgres</productname>. You do not have a valid entry in the relation <literal>pg_shadow</literal>
Contact your <productname>Postgres</productname> administrator. and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>. createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
You do not have permission to create new databases. <para>
Contact your <productname>Postgres</productname> site administrator. You do not have permission to create new databases.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists. ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>. createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
The database already exists. <para>
The database already exists.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>. createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
An internal error occurred in <application>psql</application> <para>
or in the backend server. Ensure that your site administrator has An internal error occurred in <application>psql</application>
properly installed <productname>Postgres</productname>and initialized the site with or in the backend server. Ensure that your site administrator has
<application>initdb</application>. properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
<note>
<para>
<application>createdb</application> internally runs
CREATE DATABASE from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<note> <REFSECT1 ID="R1-APP-CREATEDB-1">
<para> <REFSECT1INFO>
<application>createdb</application> internally runs <DATE>1998-10-02</DATE>
CREATE DATABASE from <application>psql</application> </REFSECT1INFO>
while connected to the <literal>template1</literal> database. <TITLE>
</note> Description
</TITLE>
<REFSECT1 ID="R1-APP-CREATEDB-1"> <PARA>
<REFSECT1INFO> <application>createdb</application> creates a new
<DATE>1998-10-02</DATE> <productname>Postgres</productname> database.
</REFSECT1INFO> The person who executes this command becomes
<TITLE> the database administrator, or <acronym>DBA</acronym>,
Description
</TITLE>
<PARA>
<application>createdb</application> creates a new
<productname>Postgres</productname> database.
The person who executes this command becomes
the database administrator, or <acronym>DBA</acronym>,
for this database and is the only for this database and is the only
person, other than the <productname>Postgres</productname> super-user, person, other than the <productname>Postgres</productname> super-user,
who can destroy it. who can destroy it.
</para>
<para>
<application>createdb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createdb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
</para>
</refsect1>
<para> <REFSECT1 ID="R1-APP-CREATEDB-2">
<application>createdb</application> is a shell script that invokes <REFSECT1INFO>
<application>psql</application>. <DATE>1998-10-02</DATE>
Hence, a <application>postmaster</application> </REFSECT1INFO>
process must be running on the database server host before <TITLE>
<application>createdb</application> Usage
is executed. The </TITLE>
<envar>PGOPTION</envar> <PARA>
and To create the database <literal>demo</literal>
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<REFSECT1 ID="R1-APP-CREATEDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create the database <literal>demo</literal>
using the postmaster on the local host, port 5432: using the postmaster on the local host, port 5432:
<programlisting> <programlisting>
createdb demo createdb demo
</programlisting> </programlisting>
To create the database <literal>demo</literal> To create the database <literal>demo</literal>
using the postmaster on host eden, port 5000: using the postmaster on host eden, port 5000:
<programlisting> <programlisting>
createdb -p 5000 -h eden demo createdb -p 5000 -h eden demo
</programlisting> </programlisting>
</para>
</refsect1>
</REFENTRY> </REFENTRY>

427
doc/src/sgml/ref/createuser.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Create a new <productname>Postgres</productname> user Create a new <productname>Postgres</productname> user
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
@ -23,215 +24,267 @@ createuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replac
[ -d | -D ] [ -u | -U ] [ <replaceable class="parameter">username</replaceable> ] [ -d | -D ] [ -u | -U ] [ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEUSER-1"> <REFSECT2 ID="R2-APP-CREATEUSER-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
-h <replaceable class="parameter">host</replaceable> -h <replaceable class="parameter">host</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the hostname of the machine on which the Specifies the hostname of the machine on which the
<application>postmaster</application> <application>postmaster</application>
is running. Defaults to using a local Unix domain socket is running. Defaults to using a local Unix domain socket
rather than an IP connection.. rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-p <replaceable class="parameter">port</replaceable> -p <replaceable class="parameter">port</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the Internet TCP/IP port or local Unix domain socket file Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application> extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432, is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar> or the value of the <envar>PGPORT</envar>
environment variable (if set). environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-d -d
</term> </term>
<listitem> <listitem>
<para> <para>
Allows the user to create databases. Allows the user to create databases.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-D -D
</term> </term>
<listitem> <listitem>
<para> <para>
Forbids the user to create databases. Forbids the user to create databases.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-i <replaceable class="parameter">userid</replaceable> -i <replaceable class="parameter">userid</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the numeric identifier to be associated with this user. Specifies the numeric identifier to be associated with this user.
This identifier must be unique among all <productname>Postgres</productname> users, and is not required This identifier must be unique among all <productname>Postgres</productname> users, and is not required
to match the operating system UID. to match the operating system UID.
You will be prompted for an identifier if none is specified on the command line, You will be prompted for an identifier if none is specified on the command line,
and it will suggest an identifier matching the UID. and it will suggest an identifier matching the UID.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-u -u
</term> </term>
<listitem> <listitem>
<para> <para>
Allows the user to create other users. Allows the user to create other users.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-U -U
</term> </term>
<listitem> <listitem>
<para> <para>
Forbids the user to create other users. Forbids the user to create other users.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">username</replaceable> <replaceable class="parameter">username</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the name of the <productname>Postgres</productname> user to be created. Specifies the name of the <productname>Postgres</productname> user to be created.
This name must be unique among all <productname>Postgres</productname> users. This name must be unique among all <productname>Postgres</productname> users.
You will be prompted for a name if none is specified on the command line. You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-CREATEUSER-2"> <REFSECT2 ID="R2-APP-CREATEUSER-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>createuser</application> will add an entry in the <application>createuser</application> will add an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table. <literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createuser: database access failed. createuser: database access failed.
<listitem> </term>
<para> <listitem>
<application>createuser</application> could not attach to the <para>
<application>postmaster</application> <application>createuser</application> could not attach to the
process on the specified host and port. If you see this message, <application>postmaster</application>
ensure that the <application>postmaster</application> process on the specified host and port. If you see this message,
is running on the proper host and that you have specified the proper ensure that the <application>postmaster</application>
port. If your site uses an authentication system, ensure that you is running on the proper host and that you have specified the proper
have obtained the required authentication credentials. port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createuser: database access failed. createuser: database access failed.
<listitem> </term>
<para> <listitem>
You do not have a valid entry in the relation <literal>pg_shadow</literal> <para>
and and will not be allowed to access <productname>Postgres</productname>. Contact your You do not have a valid entry in the relation <literal>pg_shadow</literal>
<productname>Postgres</productname> administrator. and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
createuser: <replaceable class="parameter">username</replaceable> cannot create users. createuser: <replaceable class="parameter">username</replaceable> cannot create users.
<listitem> </term>
<para> <listitem>
You do not have permission to create new users; contact your <para>
<productname>Postgres</productname> site administrator. You do not have permission to create new users; contact your
<productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
createuser: user "<replaceable class="parameter">username</replaceable>" already exists createuser: user "<replaceable class="parameter">username</replaceable>" already exists
<listitem> </term>
<para> <listitem>
The user to be added already has an entry in the <literal>pg_shadow</literal> <para>
class. The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
database access failed database access failed
<listitem> </term>
<para> <listitem>
An internal error occurred in <application>psql</application> <para>
or in the backend server. Ensure that your site administrator has An internal error occurred in <application>psql</application>
properly installed <productname>Postgres</productname>and initialized the site with or in the backend server. Ensure that your site administrator has
<application>initdb</application>. properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
<note> <note>
<para> <para>
<application>createuser</application> internally runs <application>createuser</application> internally runs
CREATE USER from <application>psql</application> CREATE USER from <application>psql</application>
while connected to the <literal>template1</literal> database. while connected to the <literal>template1</literal> database.
</note> </para>
</note>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-CREATEUSER-1"> <REFSECT1 ID="R1-APP-CREATEUSER-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
<application>createuser</application> creates a <application>createuser</application> creates a
new <productname>Postgres</productname> user. new <productname>Postgres</productname> user.
Only users with <literal>usesuper</literal> set in Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can create the <literal>pg_shadow</literal> class can create
new <productname>Postgres</productname> users. As shipped, new <productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can create users. the user <literal>postgres</literal> can create users.
</para>
<para> <para>
<application>createuser</application> is a shell script that invokes <application>createuser</application> is a shell script that invokes
<application>psql</application>. <application>psql</application>.
Hence, a <application>postmaster</application> Hence, a <application>postmaster</application>
process must be running on the database server host before process must be running on the database server host before
<application>createuser</application> is executed. <application>createuser</application> is executed.
The The
<envar>PGOPTION</envar> <envar>PGOPTION</envar>
and and
<envar>PGREALM</envar> <envar>PGREALM</envar>
environment variables will be passed on to environment variables will be passed on to
<application>psql</application> <application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">. and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
Once invoked, <application>createuser</application> Once invoked, <application>createuser</application>
will ask a series of questions to obtain parameters not specified on will ask a series of questions to obtain parameters not specified on
the command line. The new user's database login name and a numeric the command line. The new user's database login name and a numeric
user identifier must be specified. user identifier must be specified.
</para>
<note> <note>
<para> <para>
The <productname>Postgres</productname> user identifier The <productname>Postgres</productname> user identifier
does not need to be the same as the user's Unix UID. However, typically does not need to be the same as the user's Unix UID. However, typically
they are assigned to be the same. they are assigned to be the same.
</note> </para>
</note>
<para>
You must also describe the privileges of the new user for security purposes.
Specifically, you will be asked whether the new user should be able to
act as <productname>Postgres</productname> super-user,
whether the new user may create new databases and whether the new user
is allowed to create other new users.
<para>
You must also describe the privileges of the new user for security purposes.
Specifically, you will be asked whether the new user should be able to
act as <productname>Postgres</productname> super-user,
whether the new user may create new databases and whether the new user
is allowed to create other new users.
</para>
</refsect1>
</REFENTRY> </REFENTRY>

64
doc/src/sgml/ref/declare.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Defines a cursor for table access Defines a cursor for table access
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-04</DATE> <DATE>1998-09-04</DATE>
@ -183,8 +184,8 @@ This error occurs if the cursor is not declared within a transaction block.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -215,19 +216,20 @@ backend was built. Since
BINARY cursors give you back the data in the native binary BINARY cursors give you back the data in the native binary
representation. So binary cursors will tend to be a representation. So binary cursors will tend to be a
little faster since they suffer less conversion overhead. little faster since they suffer less conversion overhead.
<para> </para>
<para>
As an example, if a query returns a value of one from an integer column, As an example, if a query returns a value of one from an integer column,
you would get a string of '1' with a default cursor you would get a string of '1' with a default cursor
whereas with a binary cursor you would get whereas with a binary cursor you would get
a 4-byte value equal to control-A ('^A'). a 4-byte value equal to control-A ('^A').
<caution>
<caution> <para>
<para> BINARY cursors should be used carefully. User applications such
BINARY cursors should be used carefully. User applications such as <application>psql</application> are not aware of binary cursors
as <application>psql</application> are not aware of binary cursors and expect data to come back in a text format.
and expect data to come back in a text format. </para>
</caution> </caution>
</para>
<PARA> <PARA>
However, string representation is architecture-neutral whereas binary However, string representation is architecture-neutral whereas binary
representation can differ between different machine architectures. representation can differ between different machine architectures.
@ -236,12 +238,13 @@ and expect data to come back in a text format.
you will probably not want your data returned in you will probably not want your data returned in
binary format. binary format.
<tip> <tip>
<para> <para>
If you intend to display the data in If you intend to display the data in
ASCII, getting it back in ASCII will save you some ASCII, getting it back in ASCII will save you some
effort on the client side. effort on the client side.
</tip> </para>
</tip>
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-DECLARE-3"> <REFSECT2 ID="R2-SQL-DECLARE-3">
@ -259,14 +262,15 @@ and expect data to come back in a text format.
does not have an explicit <command>OPEN cursor</command> does not have an explicit <command>OPEN cursor</command>
statement; a cursor is considered to be open when it is declared. statement; a cursor is considered to be open when it is declared.
<note> <note>
<para> <para>
In <acronym>SQL92</acronym> cursors are only available in In <acronym>SQL92</acronym> cursors are only available in
embedded applications. <application>ecpg</application>, the embedded applications. <application>ecpg</application>, the
embedded SQL preprocessor for <productname>Postgres</productname>, embedded SQL preprocessor for <productname>Postgres</productname>,
supports the <acronym>SQL92</acronym> conventions, including those supports the <acronym>SQL92</acronym> conventions, including those
involving DECLARE and OPEN statements. involving DECLARE and OPEN statements.
</note> </para>
</note>
</PARA> </PARA>
</REFSECT2> </REFSECT2>
@ -300,14 +304,16 @@ DECLARE liahona CURSOR
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
<acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym> <acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
and in modules. <productname>Postgres</productname> permits cursors to be used and in modules. <productname>Postgres</productname> permits cursors to be used
interactively. interactively.
<acronym>SQL92</acronym> allows embedded or modular cursors to <acronym>SQL92</acronym> allows embedded or modular cursors to
update database information. update database information.
All <productname>Postgres</productname> cursors are readonly. All <productname>Postgres</productname> cursors are readonly.
The BINARY keyword is a <productname>Postgres</productname> extension. The BINARY keyword is a <productname>Postgres</productname> extension.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

13
doc/src/sgml/ref/delete.sgml
View File

@ -13,7 +13,7 @@
Deletes rows from a table Deletes rows from a table
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -82,10 +82,13 @@
<PARA> <PARA>
If <replaceable class="parameter">count</replaceable> is 0, If <replaceable class="parameter">count</replaceable> is 0,
no rows were deleted. no rows were deleted.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-DELETE-1"> <REFSECT1 ID="R1-SQL-DELETE-1">
<REFSECT1INFO> <REFSECT1INFO>
@ -118,7 +121,7 @@
Remove all films but musicals: Remove all films but musicals:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
DELETE FROM films WHERE kind &lt;&gt; 'Musical'; DETETE FROM films WHERE kind &lt;&gt; 'Musical';
SELECT * FROM films; SELECT * FROM films;
@ -165,7 +168,7 @@ DELETE FROM <replaceable class="parameter">table</replaceable> WHERE CURRENT OF
</synopsis> </synopsis>
<para> <para>
where <replaceable class="parameter">cursor</replaceable> identifies an open cursor. Interactive cursors in <productname>Postgres</productname> are read-only. where <replaceable class="parameter">cursor</replaceable> identifies an open cursor. Interactive cursors in <productname>Postgres</productname> are read-only.
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>
</REFENTRY> </REFENTRY>

401
doc/src/sgml/ref/destroydb.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Create a new <productname>Postgres</productname> database Create a new <productname>Postgres</productname> database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
@ -22,203 +23,247 @@ destroydb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replace
[ -i ] [ <replaceable class="parameter">dbname</replaceable> ] [ -i ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-DESTROYDB-1"> <REFSECT2 ID="R2-APP-DESTROYDB-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
-h <replaceable class="parameter">host</replaceable> -h <replaceable class="parameter">host</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the hostname of the machine on which the Specifies the hostname of the machine on which the
<application>postmaster</application> <application>postmaster</application>
is running. Defaults to using a local Unix domain socket is running. Defaults to using a local Unix domain socket
rather than an IP connection.. rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-p <replaceable class="parameter">port</replaceable> -p <replaceable class="parameter">port</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the Internet TCP/IP port or local Unix domain socket file Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application> extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432, is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar> or the value of the <envar>PGPORT</envar>
environment variable (if set). environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-i -i
</term> </term>
<listitem> <listitem>
<para> <para>
Run in interactive mode. Run in interactive mode.
Prompts for confirmation before destroying a database. Prompts for confirmation before destroying a database.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the name of the database to be destroyed. The database Specifies the name of the database to be destroyed. The database
must be one of the existing <productname>Postgres</productname> databases must be one of the existing <productname>Postgres</productname> databases
in this installation. in this installation.
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
defaults to the value of the defaults to the value of the
<envar>USER</envar> <envar>USER</envar>
environment variable. environment variable.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-DESTROYDB-2"> <REFSECT2 ID="R2-APP-DESTROYDB-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>destroydb</application> will remove files from the <application>destroydb</application> will remove files from the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename> <filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the existing database. data area for the existing database.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>. destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
<application>destroydb</application> could not attach to the <para>
<application>postmaster</application> <application>destroydb</application> could not attach to the
process on the specified host and port. If you see this message, <application>postmaster</application>
ensure that the <application>postmaster</application> process on the specified host and port. If you see this message,
is running on the proper host and that you have specified the proper ensure that the <application>postmaster</application>
port. If your site uses an authentication system, ensure that you is running on the proper host and that you have specified the proper
have obtained the required authentication credentials. port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>. destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
You do not have a valid entry in the relation <literal>pg_shadow</literal> <para>
and and will not be allowed to access <productname>Postgres</productname>. You do not have a valid entry in the relation <literal>pg_shadow</literal>
Contact your <productname>Postgres</productname> administrator. and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>. destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
You do not have permission to destroy (or create) databases. <para>
Contact your <productname>Postgres</productname> site administrator. You do not have permission to destroy (or create) databases.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist. ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>. destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
The database to be removed does not have an entry in the <para>
<literal>pg_database</literal> class. The database to be removed does not have an entry in the
<literal>pg_database</literal> class.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you. ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>. destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
You are not the Database Administrator (DBA) for the specified database. <para>
You are not the Database Administrator (DBA) for the specified database.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>. destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem> </term>
<para> <listitem>
An internal error occurred in <application>psql</application> <para>
or in the backend server. Ensure that your site administrator has An internal error occurred in <application>psql</application>
properly installed <productname>Postgres</productname>and initialized the site with or in the backend server. Ensure that your site administrator has
<application>initdb</application>. properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
<note>
<para>
<application>destroydb</application> internally runs
<command>DESTROY DATABASE</command> from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<note> <REFSECT1 ID="R1-APP-DESTROYDB-1">
<para> <REFSECT1INFO>
<application>destroydb</application> internally runs <DATE>1998-10-02</DATE>
<command>DESTROY DATABASE</command> from <application>psql</application> </REFSECT1INFO>
while connected to the <literal>template1</literal> database. <TITLE>
</note> Description
</TITLE>
<PARA>
<application>destroydb</application> destroys an existing
<productname>Postgres</productname> database.
The person who executes this command must be
the database administrator, or <acronym>DBA</acronym>,
or must be the <productname>Postgres</productname> super-user.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.
</para>
<para>
All references to
the database are removed, including the directory containing this
database and its associated files.
</para>
<para>
<application>destroydb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroydb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
</para>
</refsect1>
<REFSECT1 ID="R1-APP-DESTROYDB-1"> <REFSECT1 ID="R1-APP-DESTROYDB-2">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Usage
</TITLE> </TITLE>
<PARA> <PARA>
<application>destroydb</application> destroys an existing To destroy the database <literal>demo</literal>
<productname>Postgres</productname> database.
The person who executes this command must be
the database administrator, or <acronym>DBA</acronym>,
or must be the <productname>Postgres</productname> super-user.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.
<para>
All references to
the database are removed, including the directory containing this
database and its associated files.
<para>
<application>destroydb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroydb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<REFSECT1 ID="R1-APP-DESTROYDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To destroy the database <literal>demo</literal>
using the postmaster on the local host, port 5432: using the postmaster on the local host, port 5432:
<programlisting> <programlisting>
destroydb demo destroydb demo
</programlisting> </programlisting>
</para>
<para> <para>
To destroy the database <literal>demo</literal> To destroy the database <literal>demo</literal>
using the postmaster on host eden, port 5000: using the postmaster on host eden, port 5000:
<programlisting> <programlisting>
destroydb -p 5000 -h eden demo destroydb -p 5000 -h eden demo
</programlisting> </programlisting>
</para>
</refsect1>
</REFENTRY> </REFENTRY>

350
doc/src/sgml/ref/destroyuser.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Destroy a <productname>Postgres</productname> user and associated databases Destroy a <productname>Postgres</productname> user and associated databases
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
@ -22,179 +23,222 @@ destroyuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <repla
[ <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-DESTROYUSER-1"> <REFSECT2 ID="R2-APP-DESTROYUSER-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
-h <replaceable class="parameter">host</replaceable> -h <replaceable class="parameter">host</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the hostname of the machine on which the Specifies the hostname of the machine on which the
<application>postmaster</application> <application>postmaster</application>
is running. Defaults to using a local Unix domain socket is running. Defaults to using a local Unix domain socket
rather than an IP connection.. rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-p <replaceable class="parameter">port</replaceable> -p <replaceable class="parameter">port</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the Internet TCP/IP port or local Unix domain socket file Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application> extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432, is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar> or the value of the <envar>PGPORT</envar>
environment variable (if set). environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">username</replaceable> <replaceable class="parameter">username</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the name of the <productname>Postgres</productname> user to be removed. Specifies the name of the <productname>Postgres</productname> user to be removed.
This name must exist in the <productname>Postgres</productname> installation. This name must exist in the <productname>Postgres</productname> installation.
You will be prompted for a name if none is specified on the command line. You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-DESTROYUSER-2"> <REFSECT2 ID="R2-APP-DESTROYUSER-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>destroyuser</application> will remove an entry in the <application>destroyuser</application> will remove an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table, <literal>pg_user</literal> or <literal>pg_shadow</literal> system table,
and will remove all databases for which that user is the administrator and will remove all databases for which that user is the administrator
(<acronym>DBA</acronym>). (<acronym>DBA</acronym>).
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroyuser: database access failed. destroyuser: database access failed.
<listitem> </term>
<para> <listitem>
<application>destroyuser</application> could not attach to the <para>
<application>postmaster</application> <application>destroyuser</application> could not attach to the
process on the specified host and port. If you see this message, <application>postmaster</application>
ensure that the <application>postmaster</application> process on the specified host and port. If you see this message,
is running on the proper host and that you have specified the proper ensure that the <application>postmaster</application>
port. If your site uses an authentication system, ensure that you is running on the proper host and that you have specified the proper
have obtained the required authentication credentials. port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroyuser: database access failed. destroyuser: database access failed.
<listitem> </term>
<para> <listitem>
You do not have a valid entry in the relation <literal>pg_shadow</literal> <para>
and and will not be allowed to access <productname>Postgres</productname>. Contact your You do not have a valid entry in the relation <literal>pg_shadow</literal>
<productname>Postgres</productname> administrator. and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users. destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users.
<listitem> </term>
<para> <listitem>
You do not have permission to delete users; contact your <para>
<productname>Postgres</productname> site administrator. You do not have permission to delete users; contact your
<productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists
<listitem> </term>
<para> <listitem>
The user to be added already has an entry in the <literal>pg_shadow</literal> <para>
class. The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
database access failed database access failed
<listitem> </term>
<para> <listitem>
An internal error occurred in <application>psql</application> <para>
or in the backend server. Ensure that your site administrator has An internal error occurred in <application>psql</application>
properly installed <productname>Postgres</productname>and initialized the site with or in the backend server. Ensure that your site administrator has
<application>initdb</application>. properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting
<listitem> </term>
<para> <listitem>
An internal error occurred in <application>psql</application> <para>
or in the backend server. There was possibly a Unix permissions problem with the An internal error occurred in <application>psql</application>
specified database. or in the backend server. There was possibly a Unix permissions problem with the
specified database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
</term>
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server.
</para>
</listitem>
</varlistentry>
<varlistentry> </variablelist>
<term> </para>
delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server.
</variablelist> <note>
<para>
<application>destroyuser</application> internally runs
DROP USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<note> <REFSECT1 ID="R1-APP-DESTROYUSER-1">
<para> <REFSECT1INFO>
<application>destroyuser</application> internally runs <DATE>1998-10-02</DATE>
DROP USER from <application>psql</application> </REFSECT1INFO>
while connected to the <literal>template1</literal> database. <TITLE>
</note> Description
</TITLE>
<REFSECT1 ID="R1-APP-DESTROYUSER-1"> <PARA>
<REFSECT1INFO> <application>destroyuser</application> removes an existing
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroyuser</application> removes an existing
<productname>Postgres</productname> user <productname>Postgres</productname> user
and the databases for which that user and the databases for which that user
is database administrator. is database administrator.
Only users with <literal>usesuper</literal> set in Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can destroy the <literal>pg_shadow</literal> class can destroy
<productname>Postgres</productname> users. As shipped, <productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can remove users. the user <literal>postgres</literal> can remove users.
</para>
<para> <para>
<application>destroyuser</application> is a shell script that invokes <application>destroyuser</application> is a shell script that invokes
<application>psql</application>. <application>psql</application>.
Hence, a <application>postmaster</application> Hence, a <application>postmaster</application>
process must be running on the database server host before process must be running on the database server host before
<application>destroyuser</application> is executed. <application>destroyuser</application> is executed.
The The
<envar>PGOPTION</envar> <envar>PGOPTION</envar>
and and
<envar>PGREALM</envar> <envar>PGREALM</envar>
environment variables will be passed on to environment variables will be passed on to
<application>psql</application> <application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">. and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
</para>
<para> <para>
Once invoked, <application>destroyuser</application> Once invoked, <application>destroyuser</application>
will warn you about the databases that will be destroyed in the will warn you about the databases that will be destroyed in the
process and permit you to abort the removal of the user if desired. process and permit you to abort the removal of the user if desired.
</para>
</refsect1>
</REFENTRY> </REFENTRY>

6
doc/src/sgml/ref/drop_aggregate.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes the definition of an aggregate function Removes the definition of an aggregate function
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -84,8 +85,11 @@ DROP AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> <REPLACEABLE CL
<PARA> <PARA>
This message occurs if the aggregate function specified does not This message occurs if the aggregate function specified does not
exist in the database. exist in the database.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

6
doc/src/sgml/ref/drop_database.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Destroys an existing database Destroys an existing database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -80,8 +81,11 @@ DROP DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message occurs if the specified database does not exist. This message occurs if the specified database does not exist.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

9
doc/src/sgml/ref/drop_function.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes a user-defined C function Removes a user-defined C function
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -82,8 +82,11 @@ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable
<PARA> <PARA>
This message is given if the function specified does not This message is given if the function specified does not
exist in the current database. exist in the current database.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -118,6 +121,7 @@ CREATE FUNCTION
to create aggregate functions. to create aggregate functions.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPFUNCTION-2"> <REFSECT1 ID="R1-SQL-DROPFUNCTION-2">
<TITLE> <TITLE>
@ -130,6 +134,7 @@ CREATE FUNCTION
DROP FUNCTION sqrt(int4); DROP FUNCTION sqrt(int4);
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-DROPFUNCTION-3"> <REFSECT1 ID="R1-SQL-DROPFUNCTION-3">
<TITLE> <TITLE>
Bugs Bugs

7
doc/src/sgml/ref/drop_index.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes an index from a database Removes an index from a database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -70,8 +71,11 @@ DROP INDEX <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>
<PARA> <PARA>
This message occurs if <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE> This message occurs if <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>
is not an index in the database. is not an index in the database.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -104,6 +108,7 @@ DROP INDEX <REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>
information on how to create indexes. information on how to create indexes.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPINDEX-2"> <REFSECT1 ID="R1-SQL-DROPINDEX-2">
<TITLE> <TITLE>

6
doc/src/sgml/ref/drop_language.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes a user-defined procedural language Removes a user-defined procedural language
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -72,8 +73,11 @@ DROP PROCEDURAL LANGUAGE '<REPLACEABLE CLASS="PARAMETER">langname</REPLACEABLE>'
This message occurs if the language This message occurs if the language
"<replaceable class="parameter">langname</replaceable>" is "<replaceable class="parameter">langname</replaceable>" is
not found. not found.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

8
doc/src/sgml/ref/drop_operator.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes an operator from the database Removes an operator from the database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
@ -104,8 +104,11 @@ DROP OPERATOR <REPLACEABLE CLASS="PARAMETER">id</REPLACEABLE> ( <REPLACEABLE CLA
<PARA> <PARA>
This message occurs if the specified right unary operator This message occurs if the specified right unary operator
specified does not exist. specified does not exist.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -147,6 +150,7 @@ DROP OPERATOR <REPLACEABLE CLASS="PARAMETER">id</REPLACEABLE> ( <REPLACEABLE CLA
operator classes that rely on the deleted operator. operator classes that rely on the deleted operator.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPOPERATOR-2"> <REFSECT1 ID="R1-SQL-DROPOPERATOR-2">
<TITLE> <TITLE>

5
doc/src/sgml/ref/drop_rule.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes an existing rule from the database Removes an existing rule from the database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -69,7 +70,11 @@ DROP RULE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message occurs if the specified rule does not exist. This message occurs if the specified rule does not exist.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

6
doc/src/sgml/ref/drop_sequence.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes an existing sequence Removes an existing sequence
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -70,7 +71,11 @@ DROP SEQUENCE <REPLACEABLE CLASS="PARAMETER">seqname</REPLACEABLE> [, ...]
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message occurs if the specified sequence does not exist. This message occurs if the specified sequence does not exist.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -105,6 +110,7 @@ DROP SEQUENCE <REPLACEABLE CLASS="PARAMETER">seqname</REPLACEABLE> [, ...]
information on how to create a sequence. information on how to create a sequence.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPSEQUENCE-2"> <REFSECT1 ID="R1-SQL-DROPSEQUENCE-2">
<TITLE> <TITLE>

6
doc/src/sgml/ref/drop_table.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes existing tables from a database Removes existing tables from a database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -70,7 +70,11 @@ DROP TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [, ...]
<LISTITEM> <LISTITEM>
<PARA> <PARA>
If the specified table or view does not exist in the database. If the specified table or view does not exist in the database.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

10
doc/src/sgml/ref/drop_trigger.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes the definition of a trigger Removes the definition of a trigger
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -80,9 +81,11 @@ DROP TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ON <REPLACEABLE C
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message occurs if the trigger specified does not exist. This message occurs if the trigger specified does not exist.
</para>
</VARIABLELIST> </listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -115,6 +118,7 @@ DROP TRIGGER <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ON <REPLACEABLE C
information on how to create triggers. information on how to create triggers.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPTRIGGER-2"> <REFSECT1 ID="R1-SQL-DROPTRIGGER-2">
<TITLE> <TITLE>

7
doc/src/sgml/ref/drop_type.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes a user-defined type from the system catalogs Removes a user-defined type from the system catalogs
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -69,8 +70,11 @@ DROP TYPE <REPLACEABLE CLASS="PARAMETER">typename</REPLACEABLE>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message occurs if the specified type is not found. This message occurs if the specified type is not found.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -123,6 +127,7 @@ DROP TYPE <REPLACEABLE CLASS="PARAMETER">typename</REPLACEABLE>
is unpredictable. is unpredictable.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPTYPE-2"> <REFSECT1 ID="R1-SQL-DROPTYPE-2">
<TITLE> <TITLE>

4
doc/src/sgml/ref/drop_user.sgml
View File

@ -12,7 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes an user account information Removes an user account information
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -74,6 +74,7 @@ DROP USER <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -111,6 +112,7 @@ DROP USER <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
how to create or modify user accounts. how to create or modify user accounts.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPUSER-2"> <REFSECT1 ID="R1-SQL-DROPUSER-2">
<TITLE> <TITLE>

40
doc/src/sgml/ref/drop_view.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Removes an existing view from a database Removes an existing view from a database
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE> <DATE>1998-09-22</DATE>
@ -60,19 +61,24 @@ DROP VIEW <REPLACEABLE CLASS="PARAMETER">view</REPLACEABLE>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The message returned if the command is successful. The message returned if the command is successful.
</para>
<VARLISTENTRY> </listitem>
<TERM> </varlistentry>
<ReturnValue> <VARLISTENTRY>
ERROR: RewriteGetRuleEventRel: rule "_RET<REPLACEABLE CLASS="PARAMETER">view</REPLACEABLE>" not found</ReturnValue> <TERM>
</TERM> <ReturnValue>
<LISTITEM> ERROR: RewriteGetRuleEventRel: rule "_RET<REPLACEABLE CLASS="PARAMETER">view</REPLACEABLE>" not found</ReturnValue>
<PARA> </TERM>
This message occurs if the specified view does not exist in <LISTITEM>
the database. <PARA>
</variablelist> This message occurs if the specified view does not exist in
the database.
</REFSECT2> </para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-DROPVIEW-1"> <REFSECT1 ID="R1-SQL-DROPVIEW-1">
@ -104,6 +110,7 @@ the database.
for information on how to create views. for information on how to create views.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-DROPVIEW-2"> <REFSECT1 ID="R1-SQL-DROPVIEW-2">
<TITLE> <TITLE>
@ -168,7 +175,8 @@ DROP VIEW <replaceable class="parameter">view</replaceable> { RESTRICT | CASCADE
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</refsect3> </para>
</refsect3>
<REFSECT3 ID="R3-SQL-DROPVIEW-2"> <REFSECT3 ID="R3-SQL-DROPVIEW-2">
<REFSECT3INFO> <REFSECT3INFO>
@ -177,7 +185,7 @@ DROP VIEW <replaceable class="parameter">view</replaceable> { RESTRICT | CASCADE
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<para> <para>
<tip> <tip>
<para> <para>
At present, to remove a referenced view from a At present, to remove a referenced view from a
@ -185,6 +193,8 @@ DROP VIEW <replaceable class="parameter">view</replaceable> { RESTRICT | CASCADE
you must drop it explicitly. you must drop it explicitly.
</para> </para>
</tip> </tip>
</para>
</refsect3>
</refsect2> </refsect2>
</refsect1> </refsect1>
</REFENTRY> </REFENTRY>

31
doc/src/sgml/ref/explain.sgml
View File

@ -12,6 +12,7 @@ EXPLAIN
<REFPURPOSE> <REFPURPOSE>
Shows statement execution details Shows statement execution details
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
@ -38,7 +39,9 @@ VERBOSE
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Flag to show detailed query plan. Flag to show detailed query plan.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
@ -46,9 +49,11 @@ Flag to show detailed query plan.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Any <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>. Any <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-EXPLAIN-2"> <REFSECT2 ID="R2-SQL-EXPLAIN-2">
@ -69,7 +74,9 @@ NOTICE: QUERY PLAN:
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Explicit query plan from the <productname>Postgres</productname> backend. Explicit query plan from the <productname>Postgres</productname> backend.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
EXPLAIN EXPLAIN
@ -77,9 +84,11 @@ EXPLAIN
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Flag sent after query plan is shown. Flag sent after query plan is shown.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -95,7 +104,7 @@ Description
The default output is the computed query cost. The default output is the computed query cost.
VERBOSE displays the full query plan and cost to your screen, VERBOSE displays the full query plan and cost to your screen,
and pretty-prints the plan to the postmaster log file. and pretty-prints the plan to the postmaster log file.
</para>
<REFSECT2 ID="R2-SQL-EXPLAIN-3"> <REFSECT2 ID="R2-SQL-EXPLAIN-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
@ -111,8 +120,9 @@ can be found in database textbooks.
Refer to the <citetitle>Programmer's Guide</citetitle> Refer to the <citetitle>Programmer's Guide</citetitle>
in the chapters on indexes and the genetic query optimizer for in the chapters on indexes and the genetic query optimizer for
more information. more information.
</para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-EXPLAIN-2"> <REFSECT1 ID="R1-SQL-EXPLAIN-2">
<TITLE> <TITLE>
@ -129,7 +139,7 @@ Seq Scan on foo (cost=0.00 size=0 width=4)
EXPLAIN EXPLAIN
</ProgramListing> </ProgramListing>
</para>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-EXPLAIN-3"> <REFSECT1 ID="R1-SQL-EXPLAIN-3">
@ -148,6 +158,9 @@ SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no EXPLAIN statement defined in SQL92. There is no EXPLAIN statement defined in SQL92.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- <!--

78
doc/src/sgml/ref/fetch.sgml
View File

@ -12,6 +12,7 @@ FETCH
<REFPURPOSE> <REFPURPOSE>
Gets rows using a cursor Gets rows using a cursor
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE> <DATE>1998-09-01</DATE>
@ -42,7 +43,10 @@ Inputs
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
defines the fetch direction. It can be one defines the fetch direction. It can be one
the following: the following:
</para>
</listitem>
</varlistentry>
</variablelist>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -52,7 +56,9 @@ FORWARD
<PARA> <PARA>
fetch next row(s). This is the default fetch next row(s). This is the default
if <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> is omitted. if <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> is omitted.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
BACKWARD BACKWARD
@ -60,7 +66,9 @@ BACKWARD
<LISTITEM> <LISTITEM>
<PARA> <PARA>
fetch previous row(s). fetch previous row(s).
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
RELATIVE RELATIVE
@ -68,8 +76,10 @@ RELATIVE
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Noise word for SQL92 compatibility. Noise word for SQL92 compatibility.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -79,8 +89,11 @@ Noise word for SQL92 compatibility.
<PARA> <PARA>
<REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE>
determines how many rows to fetch. It can be one of the following: determines how many rows to fetch. It can be one of the following:
</para>
</listitem>
</varlistentry>
<VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
@ -90,6 +103,9 @@ determines how many rows to fetch. It can be one of the following:
A signed integer that specify how many rows to fetch. A signed integer that specify how many rows to fetch.
Note that a negative integer is equivalent to changing the sense of Note that a negative integer is equivalent to changing the sense of
FORWARD and BACKWARD. FORWARD and BACKWARD.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -98,6 +114,9 @@ ALL
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Retrieve all remaining rows. Retrieve all remaining rows.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -106,6 +125,9 @@ NEXT
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Equivalent to specifying a count of <command>1</command>. Equivalent to specifying a count of <command>1</command>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -114,8 +136,9 @@ PRIOR
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Equivalent to specifying a count of <command>-1</command>. Equivalent to specifying a count of <command>-1</command>.
</para>
</VARIABLELIST> </listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -124,9 +147,11 @@ Equivalent to specifying a count of <command>-1</command>.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
An open cursor's name. An open cursor's name.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-FETCH-2"> <REFSECT2 ID="R2-SQL-FETCH-2">
@ -139,6 +164,7 @@ Outputs
<PARA> <PARA>
FETCH returns the results of the query defined by the specified cursor. FETCH returns the results of the query defined by the specified cursor.
The following messages will be returned if the query fails: The following messages will be returned if the query fails:
</para>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
@ -150,6 +176,9 @@ NOTICE: PerformPortalFetch: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPL
If <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> If <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
is not previously declared. is not previously declared.
The cursor must be declared within a transaction block. The cursor must be declared within a transaction block.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -159,6 +188,9 @@ NOTICE: FETCH/ABSOLUTE not supported, using RELATIVE
<PARA> <PARA>
<productname>Postgres</productname> does not support absolute <productname>Postgres</productname> does not support absolute
positioning of cursors. positioning of cursors.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -178,6 +210,9 @@ all rows should be retrieved and is equivalent to specifying the ALL keyword.
If the RELATIVE keyword has been used, the <productname>Postgres</productname> If the RELATIVE keyword has been used, the <productname>Postgres</productname>
assumes that the user intended <acronym>SQL92</acronym> behavior assumes that the user intended <acronym>SQL92</acronym> behavior
and returns this error message. and returns this error message.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
@ -209,18 +244,20 @@ Negative numbers are now allowed to be specified for the
row count. A negative number is equivalent to reversing row count. A negative number is equivalent to reversing
the sense of the FORWARD and BACKWARD keywords. For example, the sense of the FORWARD and BACKWARD keywords. For example,
<command>FORWARD -1</command> is the same as <command>BACKWARD 1</command>. <command>FORWARD -1</command> is the same as <command>BACKWARD 1</command>.
</para>
</tip> </tip>
</para>
<para> <para>
Note that the FORWARD and BACKWARD keywords are Note that the FORWARD and BACKWARD keywords are
<productname>Postgres</productname> extensions. <productname>Postgres</productname> extensions.
The <acronym>SQL92</acronym> syntax is also supported, specified The <acronym>SQL92</acronym> syntax is also supported, specified
in the second form of the command. See below for details in the second form of the command. See below for details
on compatibility issues. on compatibility issues.
</para>
<para> <para>
Once all rows are fetched, every other fetch access returns Once all rows are fetched, every other fetch access returns
no rows. no rows.
</para>
<para> <para>
Updating data in a cursor is not supported by Updating data in a cursor is not supported by
@ -229,10 +266,12 @@ on compatibility issues.
not generally possible, as is also the case with VIEW updates. not generally possible, as is also the case with VIEW updates.
Consequently, Consequently,
users must issue explicit UPDATE commands to replace data. users must issue explicit UPDATE commands to replace data.
</para>
<para> <para>
Cursors may only be used inside of transactions because Cursors may only be used inside of transactions because
the data that they store spans multiple user queries. the data that they store spans multiple user queries.
</para>
<REFSECT2 ID="R2-SQL-FETCH-3"> <REFSECT2 ID="R2-SQL-FETCH-3">
<REFSECT2INFO> <REFSECT2INFO>
@ -246,8 +285,9 @@ Notes
Refer to DECLARE statements to declare a cursor. Refer to DECLARE statements to declare a cursor.
Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements
for further information about transactions. for further information about transactions.
</para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-FETCH-2"> <REFSECT1 ID="R1-SQL-FETCH-2">
<TITLE> <TITLE>
@ -287,7 +327,7 @@ Usage
CLOSE liahona; CLOSE liahona;
COMMIT WORK; COMMIT WORK;
</ProgramListing> </ProgramListing>
</para>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-FETCH-3"> <REFSECT1 ID="R1-SQL-FETCH-3">
@ -327,7 +367,9 @@ ABSOLUTE
The cursor should be positioned to the specified absolute The cursor should be positioned to the specified absolute
row number. All row numbers in <productname>Postgres</productname> row number. All row numbers in <productname>Postgres</productname>
are relative numbers so this capability is not supported. are relative numbers so this capability is not supported.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
:<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> :<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
@ -335,9 +377,13 @@ are relative numbers so this capability is not supported.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Target host variable(s). Target host variable(s).
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- <!--

724
doc/src/sgml/ref/grant.sgml
View File

@ -1,225 +1,269 @@
<REFENTRY ID="SQL-GRANT"> <REFENTRY ID="SQL-GRANT">
<REFMETA> <REFMETA>
<REFENTRYTITLE> <REFENTRYTITLE>
GRANT GRANT
</REFENTRYTITLE> </REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO> <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA> </REFMETA>
<REFNAMEDIV> <REFNAMEDIV>
<REFNAME> <REFNAME>
GRANT GRANT
</REFNAME> </REFNAME>
<REFPURPOSE> <REFPURPOSE>
Grants access privilege to a user, a group or all users Grants access privilege to a user, a group or all users
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-23</DATE> <DATE>1998-09-23</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...] GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [, ...] ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [, ...]
TO { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> } TO { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> }
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-GRANT-1"> <REFSECT2 ID="R2-SQL-GRANT-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-23</DATE> <DATE>1998-09-23</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The possible privileges are: The possible privileges are:
</para>
<VARIABLELIST> </listitem>
<VARLISTENTRY> </varlistentry>
<TERM> <VARLISTENTRY>
SELECT <TERM>
</TERM> SELECT
<LISTITEM> </TERM>
<PARA> <LISTITEM>
Access all of the columns of a specific <PARA>
Access all of the columns of a specific
table/view. table/view.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
INSERT INSERT
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Insert data into all columns of a Insert data into all columns of a
specific table. specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
UPDATE UPDATE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Update all columns of a specific Update all columns of a specific
table. table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
DELETE DELETE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Delete rows from a specific table. Delete rows from a specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
RULE RULE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Define rules on the table/view Define rules on the table/view
(See CREATE RULE statement). (See CREATE RULE statement).
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
ALL ALL
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Grant all privileges. Grant all privileges.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> <VARLISTENTRY>
<TERM>
<VARLISTENTRY> <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
<TERM> </TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> <LISTITEM>
</TERM> <PARA>
<LISTITEM> The name of an object to which to grant access.
<PARA>
The name of an object to which to grant access.
The possible objects are: The possible objects are:
</para>
<itemizedlist mark="bullet" spacing="compact"> <para>
<listitem> <itemizedlist mark="bullet" spacing="compact">
<para> <listitem>
table <para>
table
</para>
</listitem>
<listitem> <listitem>
<para> <para>
view view
</para>
</listitem>
<listitem> <listitem>
<para> <para>
sequence sequence
</para>
</listitem>
<listitem> <listitem>
<para> <para>
index index
</itemizedlist> </para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
PUBLIC PUBLIC
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
A short form representing all users. A short form representing all users.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> to whom to grant privileges.
In the current release, the group must be created explicitly as described below.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
A <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> to whom to grant privileges. The name of a user to whom grant privileges. PUBLIC is a short form
In the current release, the group must be created explicitly as described below. representing all users.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
<VARLISTENTRY> <REFSECT2 ID="R2-SQL-GRANT-2">
<TERM> <REFSECT2INFO>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> <DATE>1998-09-23</DATE>
</TERM> </REFSECT2INFO>
<LISTITEM> <TITLE>
<PARA> Outputs
The name of a user to whom grant privileges. PUBLIC is a short form </TITLE>
representing all users. <PARA>
</VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
</para>
</listitem>
</varlistentry>
</REFSECT2> <VARLISTENTRY>
<TERM>
<REFSECT2 ID="R2-SQL-GRANT-2"> ERROR: ChangeAcl: class "<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>"
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
<VARLISTENTRY>
<TERM>
ERROR: ChangeAcl: class "<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>"
not found not found
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if the specified object is not available or Message returned if the specified object is not available or
if it is impossible if it is impossible
to give privileges to the specified group or users. to give privileges to the specified group or users.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARIABLELIST> <REFSECT1 ID="R1-SQL-GRANT-1">
<REFSECT1INFO>
</REFSECT2> <DATE>1998-09-23</DATE>
</REFSYNOPSISDIV> </REFSECT1INFO>
<TITLE>
<REFSECT1 ID="R1-SQL-GRANT-1"> Description
<REFSECT1INFO> </TITLE>
<DATE>1998-09-23</DATE> <PARA>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
GRANT allows the creator of an object to give specific permissions to GRANT allows the creator of an object to give specific permissions to
all users (PUBLIC) or to a certain user or group. all users (PUBLIC) or to a certain user or group.
Users other than the creator don't have any access permission Users other than the creator don't have any access permission
unless the creator GRANTs permissions, after the object unless the creator GRANTs permissions, after the object
is created. is created.
</para>
<para> <para>
Once a user has a privilege on an object, he is enabled to exercise Once a user has a privilege on an object, he is enabled to exercise
that privilege. that privilege.
There is no need to GRANT privileges to the creator of There is no need to GRANT privileges to the creator of
an object, the creator automatically holds ALL privileges, and can an object, the creator automatically holds ALL privileges, and can
also drop the object. also drop the object.
</para>
<REFSECT2 ID="R2-SQL-GRANT-3"> <REFSECT2 ID="R2-SQL-GRANT-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-23</DATE> <DATE>1998-09-23</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
Use the <command>psql \z</command> command Use the <command>psql \z</command> command
for further information about permissions for further information about permissions
on existing objects: on existing objects:
<programlisting> <programlisting>
Database = lusitania Database = lusitania
+------------------+---------------------------------------------+ +------------------+---------------------------------------------+
| Relation | Grant/Revoke Permissions | | Relation | Grant/Revoke Permissions |
@ -236,177 +280,211 @@ Use the <command>psql \z</command> command
a -- INSERT a -- INSERT
R -- RULE R -- RULE
arwR -- ALL arwR -- ALL
</programlisting> </programlisting>
<tip> <tip>
<para> <para>
Currently, to create a GROUP you have to insert Currently, to create a GROUP you have to insert
data manually into table pg_group as: data manually into table pg_group as:
<programlisting> <programlisting>
INSERT INTO pg_group VALUES ('todos'); INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos; CREATE USER miriam IN GROUP todos;
</programlisting> </programlisting>
Refer to REVOKE statements to revoke access privileges. Refer to REVOKE statements to revoke access privileges.
</tip> </para>
</tip>
</para>
</REFSECT2>
</refsect1>
</REFSECT2> <REFSECT1 ID="R1-SQL-GRANT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- grant insert privilege to all users on table films:
--
GRANT INSERT ON films TO PUBLIC;
</programlisting>
<REFSECT1 ID="R1-SQL-GRANT-2"> <programlisting>
<TITLE> -- grant all privileges to user manuel on view kinds:
Usage --
</TITLE> GRANT ALL ON kinds TO manuel;
<PARA> </ProgramListing>
<ProgramListing> </para>
-- grant insert privilege to all users on table films: </REFSECT1>
--
GRANT INSERT ON films TO PUBLIC;
</programlisting>
<programlisting> <REFSECT1 ID="R1-SQL-GRANT-3">
-- grant all privileges to user manuel on view kinds: <TITLE>
-- Compatibility
GRANT ALL ON kinds TO manuel; </TITLE>
</ProgramListing> <PARA>
</PARA>
</REFSECT1> <REFSECT2 ID="R2-SQL-GRANT-4">
<REFSECT2INFO>
<REFSECT1 ID="R1-SQL-GRANT-3"> <DATE>1998-09-23</DATE>
<TITLE> </REFSECT2INFO>
Compatibility <TITLE>
</TITLE> SQL92
<PARA> </TITLE>
</PARA> <PARA>
<REFSECT2 ID="R2-SQL-GRANT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The <acronym>SQL92</acronym> syntax for GRANT allows setting privileges The <acronym>SQL92</acronym> syntax for GRANT allows setting privileges
for individual columns for individual columns
within a table, and allows setting a privilege to grant within a table, and allows setting a privilege to grant
the same privileges to others. the same privileges to others.
<SYNOPSIS> <SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...] GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] [, ...] ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] [, ...]
TO { PUBLIC | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> [, ...] } TO { PUBLIC | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> [, ...] }
[ WITH GRANT OPTION ] [ WITH GRANT OPTION ]
</SYNOPSIS> </SYNOPSIS>
Fields are compatible with the those in the <acronym>Postgres</acronym> Fields are compatible with the those in the <acronym>Postgres</acronym>
implementation, with the following additions: implementation, with the following additions:
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
SELECT SELECT
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<acronym>SQL92</acronym> permits additional privileges to be specified: <acronym>SQL92</acronym> permits additional privileges to be specified:
</para>
</listitem>
</varlistentry>
<VARIABLELIST> <VARLISTENTRY>
<VARLISTENTRY> <TERM>
<TERM> REFERENCES
REFERENCES </TERM>
</TERM> <LISTITEM>
<LISTITEM> <PARA>
<PARA> Allowed to reference some or all of the columns of a specific
Allowed to reference some or all of the columns of a specific table/view in integrity constraints.
table/view in integrity constraints. </para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
USAGE USAGE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Allowed to use a domain, character set, collation Allowed to use a domain, character set, collation
or translation. or translation.
If an object specifies anything other than a table/view, If an object specifies anything other than a table/view,
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
must specify only USAGE. must specify only USAGE.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
<tip> <tip>
<para> <para>
Currently, to grant privileges in <productname>Postgres</productname> Currently, to grant privileges in <productname>Postgres</productname>
to only few columns, you must to only few columns, you must
create a view having desired columns and then grant privileges create a view having desired columns and then grant privileges
to that view. to that view.
</tip> </para>
</tip>
<VARLISTENTRY> <variablelist>
<TERM> <VARLISTENTRY>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> <TERM>
</TERM> <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
<LISTITEM> </TERM>
<PARA> <LISTITEM>
<PARA>
<variablelist> <variablelist>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<acronym>SQL92</acronym> allows an additional non-functional keyword: <acronym>SQL92</acronym> allows an additional non-functional keyword:
<simplelist> <simplelist>
<member> <member>
[ TABLE ] table [ TABLE ] table
</simplelist> </member>
</simplelist>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
CHARACTER SET CHARACTER SET
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Allowed to use the specified character set. Allowed to use the specified character set.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
COLLATION COLLATION
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Allowed to use the specified collation sequence. Allowed to use the specified collation sequence.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
TRANSLATION TRANSLATION
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Allowed to use the specified character set translation. Allowed to use the specified character set translation.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
DOMAIN DOMAIN
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Allowed to use the specified domain. Allowed to use the specified domain.
</para>
</listitem>
</varlistentry>
</variablelist> <VARLISTENTRY>
<TERM>
WITH GRANT OPTION
<VARLISTENTRY> </TERM>
<TERM> <LISTITEM>
WITH GRANT OPTION <PARA>
</TERM> Allowed to grant the same privilege to others.
<LISTITEM> </para>
<PARA> </listitem>
Allowed to grant the same privilege to others. </varlistentry>
</variablelist>
</variablelist> </para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- <!--

496
doc/src/sgml/ref/initdb.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Create a new <productname>Postgres</productname> database installation Create a new <productname>Postgres</productname> database installation
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
@ -24,256 +25,289 @@ initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <repla
[ --noclean | -n ] [ --debug | -d ] [ --noclean | -n ] [ --debug | -d ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-INITDB-1"> <REFSECT2 ID="R2-APP-INITDB-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
--pglib=<replaceable class="parameter">libdir</replaceable> --pglib=<replaceable class="parameter">libdir</replaceable>
</term> </term>
<term> <term>
-l <replaceable class="parameter">libdir</replaceable> -l <replaceable class="parameter">libdir</replaceable>
</term> </term>
<term> <term>
<envar>PGLIB</envar> <envar>PGLIB</envar>
<listitem> </term>
<para> <listitem>
Where are the files that make up <productname>Postgres</productname>? <para>
Where are the files that make up <productname>Postgres</productname>?
Apart from files that Apart from files that
have to go in particular directories because of their function, the have to go in particular directories because of their function, the
files that make up the <productname>Postgres</productname> software files that make up the <productname>Postgres</productname> software
were installed in a directory were installed in a directory
called the <replaceable class="parameter">libdir</replaceable> directory. called the <replaceable class="parameter">libdir</replaceable> directory.
An example of a file that will be found An example of a file that will be found
there that <application>initdb</application> there that <application>initdb</application>
needs is <filename>global1.bki.source</filename>, needs is <filename>global1.bki.source</filename>,
which contains all the information that goes which contains all the information that goes
into the shared catalog tables. into the shared catalog tables.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
--pgdata=<replaceable class="parameter">dbdir</replaceable> --pgdata=<replaceable class="parameter">dbdir</replaceable>
</term> </term>
<term> <term>
-r <replaceable class="parameter">dbdir</replaceable> -r <replaceable class="parameter">dbdir</replaceable>
</term> </term>
<term> <term>
<envar>PGDATA</envar> <envar>PGDATA</envar>
</term> </term>
<listitem> <listitem>
<para> <para>
Where in your Unix filesystem do you want the database data to go? Where in your Unix filesystem do you want the database data to go?
The top level directory is called the <envar>PGDATA</envar> directory. The top level directory is called the <envar>PGDATA</envar> directory.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
--username=<replaceable class="parameter">name</replaceable> --username=<replaceable class="parameter">name</replaceable>
</term> </term>
<term> <term>
-u <replaceable class="parameter">name</replaceable> -u <replaceable class="parameter">name</replaceable>
</term> </term>
<term> <term>
<envar>PGUSER</envar> <envar>PGUSER</envar>
</term> </term>
<listitem> <listitem>
<para> <para>
Who will be the <productname>Postgres</productname> superuser Who will be the <productname>Postgres</productname> superuser
for this database system? The for this database system? The
<productname>Postgres</productname> superuser is a Unix user <productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database who owns all files that store the database
system and also owns the postmaster and backend processes that access them. system and also owns the postmaster and backend processes that access them.
Or just let it default to you (the Unix user who runs Or just let it default to you (the Unix user who runs
<application>initdb</application>). <application>initdb</application>).
</para>
<note> <note>
<para> <para>
Only the Unix superuser (<literal>root</literal>) Only the Unix superuser (<literal>root</literal>)
can create a database system with an owner can create a database system with an owner
different from the <productname>Postgres</productname> superuser. different from the <productname>Postgres</productname> superuser.
</note> </para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Other, less commonly used, parameters are also available:
</variablelist> <variablelist>
<varlistentry>
<term>
--template=<replaceable class="parameter">template</replaceable>
</term>
<term>
-t <replaceable class="parameter">template</replaceable>
</term>
<listitem>
<para>
Replace the <literal>template1</literal>
database in an existing database system, and don't touch anything else.
This is useful when you need to upgrade your <literal>template1</literal>
database using <application>initdb</application>
from a newer release of <productname>Postgres</productname>,
or when your <literal>template1</literal>
database has become corrupted by some system problem. Normally the
contents of <literal>template1</literal>
remain constant throughout the life of the database system. You can't
destroy anything by running <application>initdb</application>
with the
<option>--template</option>
option.
</para>
</listitem>
</varlistentry>
<para> <varlistentry>
Other, less commonly used, parameters are also available: <term>
--noclean
</term>
<term>
-n
</term>
<listitem>
<para>
By default, when <application>initdb</application>
determines that error prevent it from completely creating the database
system, it removes any files it may have created before determining
that it can't finish the job. That includes any core files left by
the programs it invokes. This option inhibits any tidying-up and is
thus useful for debugging.
</para>
</listitem>
</varlistentry>
<variablelist> <varlistentry>
<varlistentry> <term>
<term> --debug
--template=<replaceable class="parameter">template</replaceable> </term>
</term> <term>
<term> -d
-t <replaceable class="parameter">template</replaceable> </term>
</term> <listitem>
<listitem> <para>
<para> Print debugging output from the bootstrap backend.
Replace the <literal>template1</literal> The bootstrap backend is the program <application>initdb</application>
database in an existing database system, and don't touch anything else. uses to create the catalog tables. This option generates a tremendous
This is useful when you need to upgrade your <literal>template1</literal> amount of output. It also turns off the final vacuuming step.
database using <application>initdb</application> </para>
from a newer release of <productname>Postgres</productname>, </listitem>
or when your <literal>template1</literal> </varlistentry>
database has become corrupted by some system problem. Normally the
contents of <literal>template1</literal>
remain constant throughout the life of the database system. You can't
destroy anything by running <application>initdb</application>
with the
<option>--template</option>
option.
<varlistentry> </variablelist>
<term> </para>
--noclean <para>
</term> Files are also input to <application>initdb</application>:
<term>
-n
</term>
<listitem>
<para>
By default, when <application>initdb</application>
determines that error prevent it from completely creating the database
system, it removes any files it may have created before determining
that it can't finish the job. That includes any core files left by
the programs it invokes. This option inhibits any tidying-up and is
thus useful for debugging.
<varlistentry> <variablelist>
<term> <varlistentry>
--debug <term>
</term> <application>postconfig</application>
<term> </term>
-d <listitem>
</term> <para>
<listitem> If appearing somewhere in the Unix command search path
<para> (defined by the PATH environment variable).
Print debugging output from the bootstrap backend.
The bootstrap backend is the program <application>initdb</application>
uses to create the catalog tables. This option generates a tremendous
amount of output. It also turns off the final vacuuming step.
</variablelist>
<para>
Files are also input to <application>initdb</application>:
<variablelist>
<varlistentry>
<term>
<application>postconfig</application>
</term>
<listitem>
<para>
If appearing somewhere in the Unix command search path
(defined by the PATH environment variable).
This is a program that specifies defaults for some of the This is a program that specifies defaults for some of the
command options. See below. command options. See below.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<filename><envar>PGLIB</envar>/global1.bki.source</filename> <filename><envar>PGLIB</envar>/global1.bki.source</filename>
</term> </term>
<listitem> <listitem>
<para> <para>
Contents for the shared catalog tables in the new database system. This Contents for the shared catalog tables in the new database system. This
file is part of the <productname>Postgres</productname> software. file is part of the <productname>Postgres</productname> software.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<filename><envar>PGLIB</envar>/local1_template1.bki.source</filename> <filename><envar>PGLIB</envar>/local1_template1.bki.source</filename>
</term> </term>
<listitem> <listitem>
<para> <para>
Contents for the template1 tables in the new database system. This Contents for the template1 tables in the new database system. This
file is part of the <productname>Postgres</productname> software. file is part of the <productname>Postgres</productname> software.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-INITDB-2"> <REFSECT2 ID="R2-APP-INITDB-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-26</DATE> <DATE>1998-09-26</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>initdb</application> will create files in the <envar>PGDATA</envar> <application>initdb</application> will create files in the <envar>PGDATA</envar>
data area which are the system tables and framework for a complete data area which are the system tables and framework for a complete
installation. installation.
</para>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-INITDB-1"> <REFSECT1 ID="R1-APP-INITDB-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-09-26</DATE> <DATE>1998-09-26</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
<application>initdb</application> creates a new <application>initdb</application> creates a new
<productname>Postgres</productname> database system. <productname>Postgres</productname> database system.
A database system is a A database system is a
collection of databases that are all administered by the same Unix user collection of databases that are all administered by the same Unix user
and managed by a single postmaster. and managed by a single postmaster.
</para>
<para>
Creating a database system consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that don't belong to any particular database), and
creating the <literal>template1</literal>
database. What is the <literal>template1</literal>
database? When you create a database, <productname>Postgres</productname>
does it by copying
everything from the <literal>template1</literal>
database. It contains catalog tables filled in for things like the
builtin types.
</para>
<para>
After <application>initdb</application>
creates the database, it completes the initialization by running
<application>vacuum</application>, which resets some optimization parameters.
</para>
<para>
There are three ways to give parameters to <application>initdb</application>.
<para> First, you can use <application>initdb</application> command options.
Creating a database system consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that don't belong to any particular database), and
creating the <literal>template1</literal>
database. What is the <literal>template1</literal>
database? When you create a database, <productname>Postgres</productname>
does it by copying
everything from the <literal>template1</literal>
database. It contains catalog tables filled in for things like the
builtin types.
<para>
After <application>initdb</application>
creates the database, it completes the initialization by running
<application>vacuum</application>, which resets some optimization parameters.
<para>
There are three ways to give parameters to <application>initdb</application>.
First, you can use <application>initdb</application> command options.
Second, you can set environment Second, you can set environment
variables before invoking <application>initdb</application>. variables before invoking <application>initdb</application>.
Third, you can have a program called <application>postconfig</application> Third, you can have a program called <application>postconfig</application>
in your Unix command search path. in your Unix command search path.
<application>initdb</application> invokes that program and that program then writes <application>initdb</application> invokes that program and that program then writes
<application>initdb</application> parameters to its standard output stream. <application>initdb</application> parameters to its standard output stream.
This third option is not a common thing to do, however. This third option is not a common thing to do, however.
</para>
<para> <para>
Command options always override parameters specified any other way. Command options always override parameters specified any other way.
The values returned by <application>postconfig</application> The values returned by <application>postconfig</application>
override any environment variables, but your override any environment variables, but your
<application>postconfig</application> <application>postconfig</application>
program may base its output on the environment variables if you want program may base its output on the environment variables if you want
their values to be used. their values to be used.
</para>
<para> <para>
The value that <application>postconfig</application> The value that <application>postconfig</application>
outputs must have the format outputs must have the format
<programlisting> <programlisting>
<replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ... <replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ...
</programlisting> </programlisting>
It can output nothing if it doesn't want to supply any parameters.
The <replaceable>var</replaceable> values are equal to
the corresponding environment variable
names. For example,
<programlisting>
PGDATA=/tmp/postgres_test
</programlisting>
has the
same effect as invoking <application>initdb</application>
with an environment variable called <envar>PGDATA</envar> whose value is
<filename>/tmp/postgres_test</filename>.
It can output nothing if it doesn't want to supply any parameters.
The <replaceable>var</replaceable> values are equal to
the corresponding environment variable
names. For example,
<programlisting>
PGDATA=/tmp/postgres_test
</programlisting>
has the
same effect as invoking <application>initdb</application>
with an environment variable called <envar>PGDATA</envar> whose value is
<filename>/tmp/postgres_test</filename>.
</para>
</refsect1>
</REFENTRY> </REFENTRY>

345
doc/src/sgml/ref/initlocation.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Create a secondary <productname>Postgres</productname> database storage area Create a secondary <productname>Postgres</productname> database storage area
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
@ -22,180 +23,206 @@ initlocation [ --location=<replaceable class="parameter">altdir</replaceable> |
[ <replaceable class="parameter">altdir</replaceable> ] [ <replaceable class="parameter">altdir</replaceable> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-INITLOCATION-1"> <REFSECT2 ID="R2-APP-INITLOCATION-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-02</DATE> <DATE>1998-10-02</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
--location=<replaceable class="parameter">altdir</replaceable> --location=<replaceable class="parameter">altdir</replaceable>
</term> </term>
<term> <term>
-D <replaceable class="parameter">altdir</replaceable> -D <replaceable class="parameter">altdir</replaceable>
</term> </term>
<term> <term>
<replaceable class="parameter">altdir</replaceable> <replaceable class="parameter">altdir</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Where in your Unix filesystem do you want alternate databases to go? Where in your Unix filesystem do you want alternate databases to go?
The top level directory is called the <envar>PGDATA</envar> directory, so you The top level directory is called the <envar>PGDATA</envar> directory, so you
might want to point your first alternate location at <envar>PGDATA2</envar>. might want to point your first alternate location at <envar>PGDATA2</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
--username=<replaceable class="parameter">name</replaceable> --username=<replaceable class="parameter">name</replaceable>
</term> </term>
<term> <term>
-u <replaceable class="parameter">name</replaceable> -u <replaceable class="parameter">name</replaceable>
</term> </term>
<term> <term>
<envar>PGUSER</envar> <envar>PGUSER</envar>
</term> </term>
<listitem> <listitem>
<para> <para>
Who will be the Unix filesystem owner of this database storage area? Who will be the Unix filesystem owner of this database storage area?
The The
<productname>Postgres</productname> superuser is a Unix user <productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database who owns all files that store the database
system and also owns the postmaster and backend processes that access them. system and also owns the postmaster and backend processes that access them.
Usually, this is the user who should run <application>initlocation</application> Usually, this is the user who should run <application>initlocation</application>
and who will thus have ownership of the directories and files. and who will thus have ownership of the directories and files.
</para>
<note> <note>
<para> <para>
Only the Unix superuser can create a database system with a Only the Unix superuser can create a database system with a
different user as the <productname>Postgres</productname> superuser. different user as the <productname>Postgres</productname> superuser.
Specifying a user other than the <productname>Postgres</productname> superuser Specifying a user other than the <productname>Postgres</productname> superuser
may lead to database security and data integrity problems. Refer to the may lead to database security and data integrity problems. Refer to the
<citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle> <citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
for more information. for more information.
</note> </para>
</note>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-INITLOCATION-2"> <REFSECT2 ID="R2-APP-INITLOCATION-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-26</DATE> <DATE>1998-09-26</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>initlocation</application> will create directories in <application>initlocation</application> will create directories in
the specified place. the specified place.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
We are initializing the database area with username postgres (uid=500). We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process. This user will own all the files and must also own the server process.
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable> Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable> Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Successful completion. Successful completion.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
We are initializing the database area with username postgres (uid=500). We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process. This user will own all the files and must also own the server process.
Creating Postgres database system directory /usr/local/src/testlocation Creating Postgres database system directory /usr/local/src/testlocation
mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied
</term> </term>
<listitem> <listitem>
<para> <para>
You do not have filesystem permission to write to the specified directory area. You do not have filesystem permission to write to the specified directory area.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Valid username not given. You must specify the username for Valid username not given. You must specify the username for
the Postgres superuser for the database system you are the Postgres superuser for the database system you are
initializing, either with the --username option or by default initializing, either with the --username option or by default
to the USER environment variable. to the USER environment variable.
</term> </term>
<listitem> <listitem>
<para> <para>
The username which you have specified is not the The username which you have specified is not the
<productname>Postgres</productname> superuser. <productname>Postgres</productname> superuser.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Can't tell what username to use. You don't have the USER Can't tell what username to use. You don't have the USER
environment variable set to your username and didn't specify the environment variable set to your username and didn't specify the
--username option --username option
</term> </term>
<listitem> <listitem>
<para> <para>
Specify the <option>--username</option> command line option. Specify the <option>--username</option> command line option.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<REFSECT1 ID="R1-APP-INITLOCATION-1"> <REFSECT1 ID="R1-APP-INITLOCATION-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-09-26</DATE> <DATE>1998-09-26</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
<application>initlocation</application> <application>initlocation</application>
creates a new <productname>Postgres</productname> secondary database storage area. creates a new <productname>Postgres</productname> secondary database storage area.
A secondary storage area contains a required tree of directories with A secondary storage area contains a required tree of directories with
the correct file permissions on those directories. the correct file permissions on those directories.
</para>
<para> <para>
Creating a database storage area consists of creating the directories in which Creating a database storage area consists of creating the directories in which
database data might live. database data might live.
</para>
<para> <para>
There are two kinds of arguments for <application>initlocation</application>. There are two kinds of arguments for <application>initlocation</application>.
First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>). First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
This environment variable should be known to the backend for later use in This environment variable should be known to the backend for later use in
<command>CREATE DATABASE/WITH LOCATION</command> <command>CREATE DATABASE/WITH LOCATION</command>
or or
<command>createdb -D <replaceable class="parameter">altdir</replaceable></command>. <command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
However, <emphasis>the backend daemon must have this variable in it's However, <emphasis>the backend daemon must have this variable in it's
environment</emphasis> for this to succeed. environment</emphasis> for this to succeed.
Second, you may be able to specify an explicit Second, you may be able to specify an explicit
absolute path to the top directory of the storage area. However,this second absolute path to the top directory of the storage area. However,this second
option is possible only if explicitly enabled during the option is possible only if explicitly enabled during the
<productname>Postgres</productname> installation. It is usually disabled <productname>Postgres</productname> installation. It is usually disabled
to alleviate security and data integrity concerns. to alleviate security and data integrity concerns.
</para>
<note>
<para>
<productname>Postgres</productname> will add <filename>/base/</filename>
to the specified path to create the storage area.
</para>
<para>
The backend requires that any argument to <option>WITH LOCATION</option> which is
in all uppercase and which has no path delimiters is an environment variable.
</para>
</note>
</refsect1>
<note> <REFSECT1 ID="R1-APP-INITLOCATION-2">
<para> <REFSECT1INFO>
<productname>Postgres</productname> will add <filename>/base/</filename> <DATE>1998-09-26</DATE>
to the specified path to create the storage area. </REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create a database in an alternate location, using an environment variable:
<para> <programlisting>
The backend requires that any argument to <option>WITH LOCATION</option> which is % setenv PGDATA2 /opt/postgres/data
in all uppercase and which has no path delimiters is an environment variable.
</note>
<REFSECT1 ID="R1-APP-INITLOCATION-2">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create a database in an alternate location, using an environment variable:
<programlisting>
% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2
</programlisting>
% initlocation PGDATA2
% createdb -D PGDATA2
</programlisting>
</para>
</refsect1>
</REFENTRY> </REFENTRY>

312
doc/src/sgml/ref/insert.sgml
View File

@ -12,105 +12,121 @@ INSERT
<REFPURPOSE> <REFPURPOSE>
Inserts new rows into a table Inserts new rows into a table
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> </refnamediv>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIV>
<DATE>1998-09-23</DATE> <REFSYNOPSISDIVINFO>
</REFSYNOPSISDIVINFO> <DATE>1998-09-23</DATE>
<SYNOPSIS> </REFSYNOPSISDIVINFO>
INSERT INTO <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] <SYNOPSIS>
INSERT INTO <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
{ VALUES ( <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [, ...] ) | SELECT <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> } { VALUES ( <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [, ...] ) | SELECT <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> }
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-INSERT-1"> <REFSECT2 ID="R2-SQL-INSERT-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-23</DATE> <DATE>1998-09-23</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of an existing table. The name of an existing table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>. A valid expression or value to assign to <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
A valid expression or value to assign to <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>. A valid query. Refer to the SELECT statement for a further description
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid query. Refer to the SELECT statement for a further description
of valid arguments. of valid arguments.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-INSERT-2"> <REFSECT2 ID="R2-SQL-INSERT-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-23</DATE> <DATE>1998-09-23</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>INSERT <replaceable>oid</replaceable></ReturnValue> 1 <ReturnValue>INSERT <replaceable>oid</replaceable></ReturnValue> 1
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if only one row was inserted. Message returned if only one row was inserted.
<ReturnValue><replaceable>oid</replaceable></ReturnValue> <ReturnValue><replaceable>oid</replaceable></ReturnValue>
is the row identifier. is the numeric <acronym>OID</acronym> of the inserted row.
</para>
<VARLISTENTRY> </listitem>
<TERM> </varlistentry>
<ReturnValue>INSERT 0 <replaceable>#</replaceable></ReturnValue> <VARLISTENTRY>
</TERM> <TERM>
<LISTITEM> <ReturnValue>INSERT 0 <replaceable>#</replaceable></ReturnValue>
<PARA> </TERM>
Message returned if more than one rows were inserted. <LISTITEM>
<ReturnValue><replaceable>#</replaceable></ReturnValue> <PARA>
Message returned if more than one rows were inserted.
<ReturnValue><replaceable>#</replaceable></ReturnValue>
is the number of rows inserted. is the number of rows inserted.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARIABLELIST> <REFSECT1 ID="R1-SQL-INSERT-1">
<REFSECT1INFO>
</REFSECT2> <DATE>1998-09-02</DATE>
</REFSYNOPSISDIV> </REFSECT1INFO>
<TITLE>
<REFSECT1 ID="R1-SQL-INSERT-1"> Description
<REFSECT1INFO> </TITLE>
<DATE>1998-09-02</DATE> <PARA>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
INSERT allows one to insert new rows into a table. One can insert INSERT allows one to insert new rows into a table. One can insert
a single row at time or several rows as a result of a query. a single row at time or several rows as a result of a query.
The columns in the target list may be listed in any order. The columns in the target list may be listed in any order.
@ -119,81 +135,85 @@ Description
it will be assumed as NULL. If the expression for each column it will be assumed as NULL. If the expression for each column
is not of the correct data type, automatic type coercion will be is not of the correct data type, automatic type coercion will be
attempted. attempted.
</para>
<para> <para>
You must have insert privilege to a table in order to append You must have insert privilege to a table in order to append
to it, as well as select privilege on any table specified to it, as well as select privilege on any table specified
in a WHERE clause. in a WHERE clause.
</para>
</refsect1>
<REFSECT1 ID="R1-SQL-INSERT-2"> <REFSECT1 ID="R1-SQL-INSERT-2">
<TITLE> <TITLE>
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
<ProgramListing> <ProgramListing>
--Insert a single row into table films; --Insert a single row into table films;
--(in the second example the column date_prod is omitted --(in the second example the column date_prod is omitted
--therefore will be stored in it a default value of NULL): --therefore will be stored in it a default value of NULL):
-- --
INSERT INTO films VALUES INSERT INTO films VALUES
('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute'); ('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute');
INSERT INTO films (code, title, did, date_prod, kind) INSERT INTO films (code, title, did, date_prod, kind)
VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama'); VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama');
</ProgramListing> </ProgramListing>
<ProgramListing> <ProgramListing>
--Insert a single row into table distributors, note that --Insert a single row into table distributors, note that
--only column "name" is specified, to the non specified --only column "name" is specified, to the non specified
--column "did" will be assigned its default value: --column "did" will be assigned its default value:
-- --
INSERT INTO distributors (name) VALUES ('British Lion'); INSERT INTO distributors (name) VALUES ('British Lion');
</ProgramListing> </ProgramListing>
<ProgramListing> <ProgramListing>
--Insert several rows into table films from table tmp: --Insert several rows into table films from table tmp:
-- --
INSERT INTO films INSERT INTO films
SELECT * FROM tmp; SELECT * FROM tmp;
</ProgramListing> </ProgramListing>
<ProgramListing> <ProgramListing>
--Insert into arrays: --Insert into arrays:
--Create an empty 3x3 gameboard for noughts-and-crosses --Create an empty 3x3 gameboard for noughts-and-crosses
--(all of these queries create the same board attribute) --(all of these queries create the same board attribute)
--(Refer to the <citetitle>PostgreSQL User's Guide</citetitle> for further --(Refer to the <citetitle>PostgreSQL User's Guide</citetitle> for further
--information about arrays). --information about arrays).
INSERT INTO tictactoe (game, board[1:3][1:3]) INSERT INTO tictactoe (game, board[1:3][1:3])
VALUES (1,'{{"","",""},{},{"",""}}'); VALUES (1,'{{"","",""},{},{"",""}}');
INSERT INTO tictactoe (game, board[3][3]) INSERT INTO tictactoe (game, board[3][3])
VALUES (2,'{}'); VALUES (2,'{}');
INSERT INTO tictactoe (game, board) INSERT INTO tictactoe (game, board)
VALUES (3,'{{,,},{,,},{,,}}'); VALUES (3,'{{,,},{,,},{,,}}');
</ProgramListing> </ProgramListing>
</para>
</REFSECT1>
</REFSECT1> <REFSECT1 ID="R1-SQL-INSERT-3">
<TITLE>
<REFSECT1 ID="R1-SQL-INSERT-3"> Compatibility
<TITLE> </TITLE>
Compatibility <PARA>
</TITLE> </PARA>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-INSERT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The INSERT statement is fully compatible with <acronym>SQL92</acronym>.
Possible limitations in features of the
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
clause are documented for the SELECT statement.
<REFSECT2 ID="R2-SQL-INSERT-4">
<REFSECT2INFO>
<DATE>1998-09-23</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The INSERT statement is fully compatible with <acronym>SQL92</acronym>.
Possible limitations in features of the
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
clause are documented for the SELECT statement.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>
<!-- <!--

297
doc/src/sgml/ref/listen.sgml
View File

@ -12,7 +12,7 @@ LISTEN
<REFPURPOSE> <REFPURPOSE>
Listen for notification on a notify condition Listen for notification on a notify condition
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-07</DATE> <DATE>1998-10-07</DATE>
@ -21,156 +21,165 @@ Listen for notification on a notify condition
LISTEN <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> LISTEN <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-LISTEN-1"> <REFSECT2 ID="R2-SQL-LISTEN-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-07</DATE> <DATE>1998-10-07</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Name of notify condition. Name of notify condition.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</VARIABLELIST> </REFSECT2>
</REFSECT2> <REFSECT2 ID="R2-SQL-LISTEN-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-LISTEN-2"> <VARIABLELIST>
<REFSECT2INFO> <VARLISTENTRY>
<DATE>1998-09-24</DATE> <TERM>
</REFSECT2INFO> <returnvalue>LISTEN</returnvalue>
<TITLE> </TERM>
Outputs <LISTITEM>
</TITLE> <PARA>
<PARA> Message returned upon successful completion of registration.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE Async_Listen: We are already listening on notifyname</returnvalue>
</TERM>
<LISTITEM>
<PARA>
If this backend is already registered for that notify condition.
</PARA>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<VARIABLELIST> <REFSECT1 ID="R1-SQL-LISTEN-1">
<VARLISTENTRY> <REFSECT1INFO>
<TERM> <DATE>1998-10-07</DATE>
<returnvalue>LISTEN</returnvalue> </REFSECT1INFO>
</TERM> <TITLE>
<LISTITEM> Description
<PARA> </TITLE>
Message returned upon successful completion of registration. <PARA>
</PARA> LISTEN registers the current <productname>Postgres</productname> backend as a
</LISTITEM> listener on the notify condition
</VARLISTENTRY> <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
<VARLISTENTRY> </para>
<TERM> <para>
<returnvalue>NOTICE Async_Listen: We are already listening on notifyname</returnvalue> Whenever the command
</TERM> <command>NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE></command>
<LISTITEM> is invoked, either by this backend or another one connected to
<PARA> the same database, all the backends currently listening on that notify
If this backend is already registered for that notify condition. condition are notified, and each will in turn notify its connected
</PARA> frontend application. See the discussion of <command>NOTIFY</command>
</VARIABLELIST> for more information.
</REFSECT2> </para>
</REFSYNOPSISDIV> <para>
A backend can be deregistered for a given notify condition with the
<command>UNLISTEN</command> command. Also, a backend's listen registrations
are automatically cleared when the backend process exits.
</para>
<para>
The method a frontend application must use to detect notify events depends on
which <productname>Postgres</productname> application programming interface it
uses. With the basic libpq library, the application issues
<command>LISTEN</command> as an ordinary SQL command, and then must
periodically call the routine <function>PQnotifies</function> to find out
whether any notify events have been received. Other interfaces such as
libpgtcl provide higher-level methods for handling notify events; indeed,
with libpgtcl the application programmer should not even issue
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
documentation for the library you are using for more details.
</para>
<para>
The reference page for <command>NOTIFY</command> contains a more extensive
discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>.
</para>
<REFSECT1 ID="R1-SQL-LISTEN-1"> <REFSECT2 ID="R2-SQL-LISTEN-3">
<REFSECT1INFO> <REFSECT2INFO>
<DATE>1998-10-07</DATE> <DATE>1998-10-07</DATE>
</REFSECT1INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Description Notes
</TITLE> </TITLE>
<PARA> <para>
LISTEN registers the current <productname>Postgres</productname> backend as a <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
listener on the notify condition can be any string valid as a name;
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>. it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
</para>
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</para>
</REFSECT2>
</refsect1>
<para> <REFSECT1 ID="R1-SQL-LISTEN-2">
Whenever the command <TITLE>
<command>NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE></command> Usage
is invoked, either by this backend or another one connected to </TITLE>
the same database, all the backends currently listening on that notify <PARA>
condition are notified, and each will in turn notify its connected <ProgramListing>
frontend application. See the discussion of <command>NOTIFY</command> -- Configure and execute a listen/notify sequence from psql
for more information. postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</para>
</REFSECT1>
<para> <REFSECT1 ID="R1-SQL-LISTEN-3">
A backend can be deregistered for a given notify condition with the <TITLE>
<command>UNLISTEN</command> command. Also, a backend's listen registrations Compatibility
are automatically cleared when the backend process exits. </TITLE>
<para> <REFSECT2 ID="R2-SQL-LISTEN-4">
The method a frontend application must use to detect notify events depends on <REFSECT2INFO>
which <productname>Postgres</productname> application programming interface it <DATE>1998-09-01</DATE>
uses. With the basic libpq library, the application issues </REFSECT2INFO>
<command>LISTEN</command> as an ordinary SQL command, and then must <TITLE>
periodically call the routine <function>PQnotifies</function> to find out SQL92
whether any notify events have been received. Other interfaces such as </TITLE>
libpgtcl provide higher-level methods for handling notify events; indeed, <PARA>
with libpgtcl the application programmer should not even issue
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
documentation for the library you are using for more details.
<para>
The reference page for <command>NOTIFY</command> contains a more extensive
discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>.
<REFSECT2 ID="R2-SQL-LISTEN-3">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</REFSECT2>
<REFSECT1 ID="R1-SQL-LISTEN-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LISTEN-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-LISTEN-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LISTEN</command> in <acronym>SQL92</acronym>. There is no <command>LISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

325
doc/src/sgml/ref/load.sgml
View File

@ -1,170 +1,179 @@
<REFENTRY ID="SQL-LOAD"> <REFENTRY ID="SQL-LOAD">
<REFMETA> <REFMETA>
<REFENTRYTITLE> <REFENTRYTITLE>
LOAD LOAD
</REFENTRYTITLE> </REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO> <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA> </REFMETA>
<REFNAMEDIV> <REFNAMEDIV>
<REFNAME> <REFNAME>
LOAD LOAD
</REFNAME> </REFNAME>
<REFPURPOSE> <REFPURPOSE>
Dynamically loads an object file Dynamically loads an object file
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'
</SYNOPSIS>
<REFSYNOPSISDIV> <REFSECT2 ID="R2-SQL-LOAD-1">
<REFSYNOPSISDIVINFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO> </REFSECT2INFO>
<SYNOPSIS> <TITLE>
<REPLACEABLE CLASS="PARAMETER"> Inputs
</REPLACEABLE> </TITLE>
LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>' <PARA>
</SYNOPSIS> </PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Object file for dynamic loading.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
<REFSECT2 ID="R2-SQL-LOAD-1"> </REFSECT2>
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Object file for dynamic loading.
</VARIABLELIST> <REFSECT2 ID="R2-SQL-LOAD-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</REFSECT2> <VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>LOAD</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned on successful completion.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<returnvalue>ERROR: LOAD: could not open file '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified file is not found. The file must be visible
<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
with the appropriate full path name specified, to avoid this message.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT2 ID="R2-SQL-LOAD-2"> <REFSECT1 ID="R1-SQL-LOAD-1">
<REFSECT2INFO> <REFSECT1INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Outputs Description
</TITLE> </TITLE>
<PARA> <PARA>
Loads an object (or ".o") file into the
<VARIABLELIST> <productname>Postgres</productname> backend address space. Once a
<VARLISTENTRY> file is loaded, all functions in that file can be accessed. This
<TERM> function is used in support of user-defined types and functions.
<returnvalue>LOAD</returnvalue> </para>
</TERM> <para>
<LISTITEM> If a file is not loaded using
<PARA> <command>LOAD</command>,
Message returned on successful completion. the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<VARLISTENTRY> <command>LOAD</command>
<TERM> can also be used to reload an object file if it has been edited and
<returnvalue>ERROR: LOAD: could not open file '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'</returnvalue> recompiled. Only objects created from C language files are supported
</TERM> at this time.
<LISTITEM> </para>
<PARA> <REFSECT2 ID="R2-SQL-LOAD-3">
Message returned if the specified file is not found. The file must be visible <REFSECT2INFO>
<emphasis>to the <productname>Postgres</productname> backend</emphasis>, <DATE>1998-09-24</DATE>
with the appropriate full path name specified, to avoid this message. </REFSECT2INFO>
<TITLE>
</VARIABLELIST> Notes
</TITLE>
</REFSECT2> <PARA>
</REFSYNOPSISDIV> Functions in loaded object files should not call functions in other
object files loaded through the
<REFSECT1 ID="R1-SQL-LOAD-1"> <command>LOAD</command>
<REFSECT1INFO> command. For example, all functions in file <literal>A</literal> should
<DATE>1998-09-24</DATE> call each other, functions in the standard or math libraries, or in
</REFSECT1INFO> Postgres itself. They should not call functions defined in a different
<TITLE> loaded file <literal>B</literal>.
Description
</TITLE>
<PARA>
Loads an object (or ".o") file into the
<productname>Postgres</productname> backend address space. Once a
file is loaded, all functions in that file can be accessed. This
function is used in support of user-defined types and functions.
<para>
If a file is not loaded using
<command>LOAD</command>,
the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<command>LOAD</command>
can also be used to reload an object file if it has been edited and
recompiled. Only objects created from C language files are supported
at this time.
<REFSECT2 ID="R2-SQL-LOAD-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Functions in loaded object files should not call functions in other
object files loaded through the
<command>LOAD</command>
command. For example, all functions in file <literal>A</literal> should
call each other, functions in the standard or math libraries, or in
Postgres itself. They should not call functions defined in a different
loaded file <literal>B</literal>.
This is because if <literal>B</literal> is reloaded, the Postgres loader is This is because if <literal>B</literal> is reloaded, the Postgres loader is
not able to relocate the calls from the functions in <literal>A</literal> into not able to relocate the calls from the functions in <literal>A</literal> into
the new address space of <literal>B</literal>. the new address space of <literal>B</literal>.
If <literal>B</literal> is not reloaded, however, there will If <literal>B</literal> is not reloaded, however, there will
not be a problem. not be a problem.
</para>
<para> <para>
Object files must be compiled to contain position independent code. Object files must be compiled to contain position independent code.
For example, For example,
on DECstations you must use on DECstations you must use
<application>/bin/cc</application> <application>/bin/cc</application>
with the <literal>-G 0</literal> option when compiling object files to be with the <literal>-G 0</literal> option when compiling object files to be
loaded. loaded.
</para>
<para> <para>
Note that if you are porting <productname>Postgres</productname> Note that if you are porting <productname>Postgres</productname>
to a new platform, <command>LOAD</command> to a new platform, <command>LOAD</command>
will have to work in order to support ADTs. will have to work in order to support ADTs.
</para>
</REFSECT2>
</refsect1>
</REFSECT2> <REFSECT1 ID="R1-SQL-LOAD-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Load the file /usr/postgres/demo/circle.o
--
LOAD '/usr/postgres/demo/circle.o'
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOAD-2"> <REFSECT1 ID="R1-SQL-LOAD-3">
<TITLE> <TITLE>
Usage Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
<ProgramListing> </PARA>
--Load the file /usr/postgres/demo/circle.o
--
LOAD '/usr/postgres/demo/circle.o'
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOAD-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-LOAD-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
<REFSECT2 ID="R2-SQL-LOAD-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

238
doc/src/sgml/ref/lock.sgml
View File

@ -12,7 +12,7 @@ LOCK
<REFPURPOSE> <REFPURPOSE>
Explicit lock of a table inside a transaction Explicit lock of a table inside a transaction
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -21,70 +21,77 @@ Explicit lock of a table inside a transaction
LOCK [ TABLE ] <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> LOCK [ TABLE ] <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-LOCK-1"> <REFSECT2 ID="R2-SQL-LOCK-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-01</DATE> <DATE>1998-09-01</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of an existing table to lock. The name of an existing table to lock.
</VARIABLELIST> </para>
</listitem>
</varlistentry>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-LOCK-2"> <REFSECT2 ID="R2-SQL-LOCK-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
DELETE 0 DELETE 0
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned on a successful lock. Message returned on a successful lock.
<command>LOCK</command> is implemented as a <command>LOCK</command> is implemented as a
<command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command> <command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command>
which is guaranteed to not delete any rows. which is guaranteed to not delete any rows.
</para>
<VARLISTENTRY> </listitem>
<TERM> </varlistentry>
ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist. <VARLISTENTRY>
</TERM> <TERM>
<LISTITEM> ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist.
<PARA> </TERM>
Message returned if <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> <LISTITEM>
<PARA>
Message returned if <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
does not exist. does not exist.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARIABLELIST> <REFSECT1 ID="R1-SQL-LOCK-1">
<REFSECT1INFO>
</REFSECT2> <DATE>1998-09-24</DATE>
</REFSYNOPSISDIV> </REFSECT1INFO>
<TITLE>
<REFSECT1 ID="R1-SQL-LOCK-1"> Description
<REFSECT1INFO> </TITLE>
<DATE>1998-09-24</DATE> <PARA>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>LOCK</command> locks in exclusive mode a table inside <command>LOCK</command> locks in exclusive mode a table inside
a transaction. The classic use for this is a transaction. The classic use for this is
the case where you want to select some data, then the case where you want to select some data, then
@ -98,8 +105,8 @@ Description
their own update, causing a deadlock while you both wait their own update, causing a deadlock while you both wait
for the other to release the select-induced shared lock so for the other to release the select-induced shared lock so
you can get an exclusive lock to do the update. you can get an exclusive lock to do the update.
</para>
<para> <para>
Another example of deadlock is where one user locks one Another example of deadlock is where one user locks one
table, and another user locks a second table. While both table, and another user locks a second table. While both
keep their existing locks, the first user tries to lock keep their existing locks, the first user tries to lock
@ -108,71 +115,76 @@ Description
the tables to become available. The only solution to this the tables to become available. The only solution to this
is for both users to lock tables in the same order, so is for both users to lock tables in the same order, so
user's lock acquisitions and requests to not form a deadlock. user's lock acquisitions and requests to not form a deadlock.
</para>
<note>
<para>
<productname>Postgres</productname> does detect deadlocks and will
rollback transactions to resolve the deadlock. Usually, at least one
of the deadlocked transactions will complete successfully.
</para>
</note>
<note> <REFSECT2 ID="R2-SQL-LOCK-3">
<para> <REFSECT2INFO>
<productname>Postgres</productname> does detect deadlocks and will <DATE>1998-09-24</DATE>
rollback transactions to resolve the deadlock. Usually, at least one </REFSECT2INFO>
of the deadlocked transactions will complete successfully. <TITLE>
</note> Notes
</TITLE>
<REFSECT2 ID="R2-SQL-LOCK-3"> <para>
<REFSECT2INFO> <command>LOCK</command> is a <productname>Postgres</productname>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<command>LOCK</command> is a <productname>Postgres</productname>
language extension. language extension.
<para> </para>
<command>LOCK</command> works only inside transactions. <para>
<command>LOCK</command> works only inside transactions.
<note> <note>
<title>Bug</title> <title>Bug</title>
<para> <para>
If the locked table is dropped then it will be automatically If the locked table is dropped then it will be automatically
unlocked even if a transaction is still in progress. unlocked even if a transaction is still in progress.
</note> </para>
</note>
</para>
</REFSECT2>
</refsect1>
</REFSECT2> <REFSECT1 ID="R1-SQL-LOCK-2">
<TITLE>
<REFSECT1 ID="R1-SQL-LOCK-2"> Usage
<TITLE> </TITLE>
Usage <PARA>
</TITLE> </PARA>
<PARA> <ProgramListing>
</PARA> --Explicit locking to prevent deadlock:
<ProgramListing> --
--Explicit locking to prevent deadlock: BEGIN WORK;
--
BEGIN WORK;
LOCK films; LOCK films;
SELECT * FROM films; SELECT * FROM films;
UPDATE films SET len = INTERVAL '100 minute' UPDATE films SET len = INTERVAL '100 minute'
WHERE len = INTERVAL '117 minute'; WHERE len = INTERVAL '117 minute';
COMMIT WORK; COMMIT WORK;
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-LOCK-3"> <REFSECT1 ID="R1-SQL-LOCK-3">
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-LOCK-4"> <REFSECT2 ID="R2-SQL-LOCK-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>, There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>,
which instead uses <command>SET TRANSACTION</command> to specify which instead uses <command>SET TRANSACTION</command> to specify
concurrency level on transactions. concurrency level on transactions.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

141
doc/src/sgml/ref/move.sgml
View File

@ -12,7 +12,7 @@ MOVE
<REFPURPOSE> <REFPURPOSE>
Moves cursor position Moves cursor position
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -21,99 +21,104 @@ Moves cursor position
MOVE [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] [ <REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE> ] MOVE [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] [ <REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE> ]
{ IN | FROM } <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> { IN | FROM } <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
FETCH [ RELATIVE ] [ { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL | NEXT | PRIOR ] } ] FROM ] <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> FETCH [ RELATIVE ] [ { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL | NEXT | PRIOR ] } ] FROM ] <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
</refsynopsisdiv>
<REFSECT1 ID="R1-SQL-MOVE-1"> <REFSECT1 ID="R1-SQL-MOVE-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
<command>MOVE</command> allows a user to move cursor position a specified <command>MOVE</command> allows a user to move cursor position a specified
number of rows. number of rows.
<command>MOVE</command> works like the <command>FETCH</command> command, <command>MOVE</command> works like the <command>FETCH</command> command,
but only positions the cursor and does but only positions the cursor and does
not return rows. not return rows.
</para>
<para>
Refer to the <command>FETCH</command> command for details on syntax and usage.
</para>
<para> <REFSECT2 ID="R2-SQL-MOVE-3">
Refer to the <command>FETCH</command> command for details on syntax and usage. <REFSECT2INFO>
<DATE>1998-09-24</DATE>
<REFSECT2 ID="R2-SQL-MOVE-3"> </REFSECT2INFO>
<REFSECT2INFO> <TITLE>
<DATE>1998-09-24</DATE> Notes
</REFSECT2INFO> </TITLE>
<TITLE> <PARA>
Notes <command>MOVE</command> is a <productname>Postgres</productname>
</TITLE>
<PARA>
<command>MOVE</command> is a <productname>Postgres</productname>
language extension. language extension.
</para>
<para> <para>
Refer to <command>FETCH</command> for a description Refer to <command>FETCH</command> for a description
of valid arguments. of valid arguments.
Refer to <command>DECLARE</command> to declare a cursor. Refer to <command>DECLARE</command> to declare a cursor.
Refer to <command>BEGIN WORK</command>, <command>COMMIT WORK</command>, Refer to <command>BEGIN WORK</command>, <command>COMMIT WORK</command>,
<command>ROLLBACK WORK</command> statements <command>ROLLBACK WORK</command> statements
for further information about transactions. for further information about transactions.
</para>
</REFSECT2>
</refsect1>
</REFSECT2> <REFSECT1 ID="R1-SQL-MOVE-2">
<TITLE>
<REFSECT1 ID="R1-SQL-MOVE-2"> Usage
<TITLE> </TITLE>
Usage <PARA>
</TITLE> <ProgramListing>
<PARA> --set up and use a cursor:
<ProgramListing> --
--set up and use a cursor: BEGIN WORK;
--
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM films; DECLARE liahona CURSOR FOR SELECT * FROM films;
--Skip first 5 rows: --Skip first 5 rows:
-- --
MOVE FORWARD 5 IN liahona; MOVE FORWARD 5 IN liahona;
<computeroutput> <computeroutput>
MOVE MOVE
</computeroutput> </computeroutput>
--Fetch 6th row in the cursor liahona: --Fetch 6th row in the cursor liahona:
-- --
FETCH 1 IN liahona; FETCH 1 IN liahona;
<computeroutput> <computeroutput>
FETCH FETCH
code |title |did| date_prod|kind |len code |title |did| date_prod|kind |len
-----+------+---+----------+----------+------ -----+------+---+----------+----------+------
P_303|48 Hrs|103|1982-10-22|Action | 01:37 P_303|48 Hrs|103|1982-10-22|Action | 01:37
(1 row) (1 row)
</computeroutput> </computeroutput>
-- close the cursor liahona and commit work: -- close the cursor liahona and commit work:
-- --
CLOSE liahona; CLOSE liahona;
COMMIT WORK; COMMIT WORK;
</ProgramListing> </ProgramListing>
</para>
</REFSECT1>
</REFSECT1> <REFSECT1 ID="R1-SQL-MOVE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT1 ID="R1-SQL-MOVE-3"> <REFSECT2 ID="R2-SQL-MOVE-4">
<TITLE> <REFSECT2INFO>
Compatibility <DATE>1998-09-01</DATE>
</TITLE> </REFSECT2INFO>
<PARA> <TITLE>
</PARA> SQL92
</TITLE>
<REFSECT2 ID="R2-SQL-MOVE-4"> <PARA>
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no SQL92 <command>MOVE</command> statement. There is no SQL92 <command>MOVE</command> statement.
Instead, <acronym>SQL92</acronym> allows Instead, <acronym>SQL92</acronym> allows
one to <command>FETCH</command> rows from an absolute cursor position, one to <command>FETCH</command> rows from an absolute cursor position,
implicitly moving the cursor to the correct place. implicitly moving the cursor to the correct place.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

401
doc/src/sgml/ref/notify.sgml
View File

@ -12,7 +12,7 @@ NOTIFY
<REFPURPOSE> <REFPURPOSE>
Signals all frontends and backends listening on a notify condition Signals all frontends and backends listening on a notify condition
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-07</DATE> <DATE>1998-10-07</DATE>
@ -23,208 +23,215 @@ Signals all frontends and backends listening on a notify condition
NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> NOTIFY <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-NOTIFY-1"> <REFSECT2 ID="R2-SQL-NOTIFY-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-07</DATE> <DATE>1998-10-07</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Notify condition to be signaled. Notify condition to be signaled.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</VARIABLELIST> <REFSECT2 ID="R2-SQL-NOTIFY-2">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</REFSECT2> <VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTIFY
</TERM>
<LISTITEM>
<PARA>
Acknowledgement that notify command has executed.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
Notify events
</TERM>
<LISTITEM>
<PARA>
Events are delivered to listening frontends; whether and how each frontend
application reacts depends on its programming.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT2 ID="R2-SQL-NOTIFY-2"> <REFSECT1 ID="R1-SQL-NOTIFY-1">
<REFSECT2INFO> <REFSECT1INFO>
<DATE>1998-10-07</DATE> <DATE>1998-10-07</DATE>
</REFSECT2INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Outputs Description
</TITLE> </TITLE>
<PARA> <PARA>
The <command>NOTIFY</command> command sends a notify event to each
frontend application that has previously executed
<command>LISTEN <replaceable class="parameter">notifyname</replaceable></command>
for the specified notify condition in the current database.
</para>
<para>
The information passed to the frontend for a notify event includes the notify
condition name and the notifying backend process's PID. It is up to the
database designer to define the condition names that will be used in a given
database and what each one means.
</para>
<para>
Commonly, the notify condition name is the same as the name of some table in
the database, and the notify event essentially means "I changed this table,
take a look at it to see what's new". But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
example, a database designer could use several different condition names
to signal different sorts of changes to a single table.
</para>
<para>
<command>NOTIFY</command> provides a simple form of signal or
IPC (interprocess communication) mechanism for a collection of processes
accessing the same <productname>Postgres</productname> database.
Higher-level mechanisms can be built by using tables in the database to
pass additional data (beyond a mere condition name) from notifier to
listener(s).
</para>
<para>
When <command>NOTIFY</command> is used to signal the occurrence of changes
to a particular table, a useful programming technique is to put the
<command>NOTIFY</command> in a rule that is triggered by table updates.
In this way, notification happens automatically when the table is changed,
and the application programmer can't accidentally forget to do it.
</para>
<para>
<command>NOTIFY</command> interacts with SQL transactions in some important
ways. Firstly, if a <command>NOTIFY</command> is executed inside a
transaction, the notify events are not delivered until and unless the
transaction is committed. This is appropriate, since if the transaction
is aborted we would like all the commands within it to have had no effect
--- including <command>NOTIFY</command>. But it can be disconcerting if one
is expecting the notify events to be delivered immediately. Secondly, if
a listening backend receives a notify signal while it is within a transaction,
the notify event will not be delivered to its connected frontend until just
after the transaction is completed (either committed or aborted). Again, the
reasoning is that if a notify were delivered within a transaction that was
later aborted, one would want the notification to be undone somehow --- but
the backend cannot "take back" a notify once it has sent it to the frontend.
So notify events are only delivered between transactions. The upshot of this
is that applications using <command>NOTIFY</command> for real-time signaling
should try to keep their transactions short.
</para>
<para>
<command>NOTIFY</command> behaves like Unix signals in one important
respect: if the same condition name is signaled multiple times in quick
succession, recipients may get only one notify event for several executions
of <command>NOTIFY</command>. So it is a bad idea to depend on the number
of notifies received. Instead, use <command>NOTIFY</command> to wake up
applications that need to pay attention to something, and use a database
object (such as a sequence) to keep track of what happened or how many times
it happened.
</para>
<para>
It is common for a frontend that sends <command>NOTIFY</command> to be
listening on the same notify name itself. In that case it will get back a
notify event, just like all the other listening frontends. Depending on the
application logic, this could result in useless work --- for example,
re-reading a database table to find the same updates that that frontend just
wrote out. In <productname>Postgres</productname> 6.4 and later, it is
possible to avoid such extra work by noticing whether the notifying backend
process's PID (supplied in the notify event message) is the same as one's own
backend's PID (available from libpq). When they are the same, the notify
event is one's own work bouncing back, and can be ignored. (Despite what was
said in the preceding paragraph, this is a safe technique.
<productname>Postgres</productname> keeps self-notifies separate from notifies
arriving from other backends, so you cannot miss an outside notify by ignoring
your own notifies.)
</para>
<VARIABLELIST> <REFSECT2 ID="R2-SQL-NOTIFY-3">
<VARLISTENTRY> <REFSECT2INFO>
<TERM> <DATE>1998-10-07</DATE>
NOTIFY </REFSECT2INFO>
</TERM> <TITLE>
<LISTITEM> Notes
<PARA> </TITLE>
Acknowledgement that notify command has executed. <para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
</para>
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</para>
<para>
In <productname>Postgres</productname> releases prior to 6.4, the backend
PID delivered in a notify message was always the PID of the frontend's own
backend. So it was not possible to distinguish one's own notifies from other
clients' notifies in those earlier releases.
</para>
</REFSECT2>
</refsect1>
<VARLISTENTRY> <REFSECT1 ID="R1-SQL-NOTIFY-2">
<TERM> <TITLE>
Notify events Usage
</TERM> </TITLE>
<LISTITEM> <PARA>
<PARA> <ProgramListing>
Events are delivered to listening frontends; whether and how each frontend -- Configure and execute a listen/notify sequence from psql
application reacts depends on its programming. postgres=> listen virtual;
</PARA> LISTEN
</LISTITEM> postgres=> notify virtual;
</VARLISTENTRY> NOTIFY
</VARIABLELIST> ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</REFSECT2> </ProgramListing>
</REFSYNOPSISDIV> </para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-NOTIFY-1"> <REFSECT1 ID="R1-SQL-NOTIFY-3">
<REFSECT1INFO> <TITLE>
<DATE>1998-10-07</DATE> Compatibility
</REFSECT1INFO> </TITLE>
<TITLE>
Description
</TITLE>
<PARA>
The <command>NOTIFY</command> command sends a notify event to each
frontend application that has previously executed
<command>LISTEN <replaceable class="parameter">notifyname</replaceable></command>
for the specified notify condition in the current database.
<para>
The information passed to the frontend for a notify event includes the notify
condition name and the notifying backend process's PID. It is up to the
database designer to define the condition names that will be used in a given
database and what each one means.
<para>
Commonly, the notify condition name is the same as the name of some table in
the database, and the notify event essentially means "I changed this table,
take a look at it to see what's new". But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
example, a database designer could use several different condition names
to signal different sorts of changes to a single table.
<para>
<command>NOTIFY</command> provides a simple form of signal or
IPC (interprocess communication) mechanism for a collection of processes
accessing the same <productname>Postgres</productname> database.
Higher-level mechanisms can be built by using tables in the database to
pass additional data (beyond a mere condition name) from notifier to
listener(s).
<para>
When <command>NOTIFY</command> is used to signal the occurrence of changes
to a particular table, a useful programming technique is to put the
<command>NOTIFY</command> in a rule that is triggered by table updates.
In this way, notification happens automatically when the table is changed,
and the application programmer can't accidentally forget to do it.
<para>
<command>NOTIFY</command> interacts with SQL transactions in some important
ways. Firstly, if a <command>NOTIFY</command> is executed inside a
transaction, the notify events are not delivered until and unless the
transaction is committed. This is appropriate, since if the transaction
is aborted we would like all the commands within it to have had no effect
--- including <command>NOTIFY</command>. But it can be disconcerting if one
is expecting the notify events to be delivered immediately. Secondly, if
a listening backend receives a notify signal while it is within a transaction,
the notify event will not be delivered to its connected frontend until just
after the transaction is completed (either committed or aborted). Again, the
reasoning is that if a notify were delivered within a transaction that was
later aborted, one would want the notification to be undone somehow --- but
the backend cannot "take back" a notify once it has sent it to the frontend.
So notify events are only delivered between transactions. The upshot of this
is that applications using <command>NOTIFY</command> for real-time signaling
should try to keep their transactions short.
<para>
<command>NOTIFY</command> behaves like Unix signals in one important
respect: if the same condition name is signaled multiple times in quick
succession, recipients may get only one notify event for several executions
of <command>NOTIFY</command>. So it is a bad idea to depend on the number
of notifies received. Instead, use <command>NOTIFY</command> to wake up
applications that need to pay attention to something, and use a database
object (such as a sequence) to keep track of what happened or how many times
it happened.
<para>
It is common for a frontend that sends <command>NOTIFY</command> to be
listening on the same notify name itself. In that case it will get back a
notify event, just like all the other listening frontends. Depending on the
application logic, this could result in useless work --- for example,
re-reading a database table to find the same updates that that frontend just
wrote out. In <productname>Postgres</productname> 6.4 and later, it is
possible to avoid such extra work by noticing whether the notifying backend
process's PID (supplied in the notify event message) is the same as one's own
backend's PID (available from libpq). When they are the same, the notify
event is one's own work bouncing back, and can be ignored. (Despite what was
said in the preceding paragraph, this is a safe technique.
<productname>Postgres</productname> keeps self-notifies separate from notifies
arriving from other backends, so you cannot miss an outside notify by ignoring
your own notifies.)
<REFSECT2 ID="R2-SQL-NOTIFY-3">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
can be any string valid as a name;
it need not correspond to the name of any actual table. If
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 31 characters long.
<para>
In some previous releases of
<productname>Postgres</productname>,
<REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
<para>
In <productname>Postgres</productname> releases prior to 6.4, the backend
PID delivered in a notify message was always the PID of the frontend's own
backend. So it was not possible to distinguish one's own notifies from other
clients' notifies in those earlier releases.
</REFSECT2>
<REFSECT1 ID="R1-SQL-NOTIFY-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence from psql
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-NOTIFY-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-NOTIFY-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>NOTIFY</command> statement in <acronym>SQL92</acronym>.
<REFSECT2 ID="R2-SQL-NOTIFY-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>NOTIFY</command> statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

611
doc/src/sgml/ref/pg_dump.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Extract a <productname>Postgres</productname> database into a script file Extract a <productname>Postgres</productname> database into a script file
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-11-05</DATE> <DATE>1998-11-05</DATE>
@ -25,308 +26,386 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceab
[ <replaceable class="parameter">dbname</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-PG-DUMP-1"> <REFSECT2 ID="R2-APP-PG-DUMP-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-11-05</DATE> <DATE>1998-11-05</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>pg_dump</application> accepts the following command line arguments: <application>pg_dump</application> accepts the following command line arguments:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the name of the database to be extracted. Specifies the name of the database to be extracted.
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
defaults to the value of the defaults to the value of the
<envar>USER</envar> <envar>USER</envar>
environment variable. environment variable.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-a -a
</term> </term>
<listitem> <listitem>
<para> <para>
Dump out only the data, no schema (definitions). Dump out only the data, no schema (definitions).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-d -d
</term> </term>
<listitem> <listitem>
<para> <para>
Dump data as proper insert strings. Dump data as proper insert strings.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-D -D
</term> </term>
<listitem> <listitem>
<para> <para>
Dump data as inserts with attribute names Dump data as inserts with attribute names
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-f <replaceable class="parameter">filename</replaceable> -f <replaceable class="parameter">filename</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the output file. Defaults to <filename>stdout</filename>. Specifies the output file. Defaults to <filename>stdout</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-n -n
</term> </term>
<listitem> <listitem>
<para> <para>
Suppress double quotes around identifiers unless absolutely necessary. Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words This may cause trouble loading this dumped data if there are reserved words
used for identifiers. used for identifiers.
This was the default behavior in pre-v6.4 <application>pg_dump</application>. This was the default behavior in pre-v6.4 <application>pg_dump</application>.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-N -N
</term> </term>
<listitem> <listitem>
<para> <para>
Include double quotes around identifiers. Include double quotes around identifiers.
This is the default. This is the default.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-o -o
</term> </term>
<listitem> <listitem>
<para> <para>
Dump object identifiers (<acronym>OID</acronym>s) for every table. Dump object identifiers (<acronym>OID</acronym>s) for every table.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-s -s
</term> </term>
<listitem> <listitem>
<para> <para>
Dump out only the schema (definitions), no data. Dump out only the schema (definitions), no data.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-t <replaceable class="parameter">table</replaceable> -t <replaceable class="parameter">table</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Dump data for <replaceable class="parameter">table</replaceable> only. Dump data for <replaceable class="parameter">table</replaceable> only.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-u -u
</term> </term>
<listitem> <listitem>
<para> <para>
Use password authentication. Prompts for username and password. Use password authentication. Prompts for username and password.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-v -v
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies verbose mode Specifies verbose mode
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-z -z
</term> </term>
<listitem> <listitem>
<para> <para>
Include ACLs (grant/revoke commands) and table ownership information. Include ACLs (grant/revoke commands) and table ownership information.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
<para>
<application>pg_dump</application> also accepts
the following command line arguments for connection parameters:
<para> <variablelist>
<application>pg_dump</application> also accepts <varlistentry>
the following command line arguments for connection parameters: <term>
-h <replaceable class="parameter">host</replaceable>
<variablelist> </term>
<varlistentry> <listitem>
<term> <para>
-h <replaceable class="parameter">host</replaceable> Specifies the hostname of the machine on which the
</term> <application>postmaster</application>
<listitem> is running. Defaults to using a local Unix domain socket
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection.. rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-p <replaceable class="parameter">port</replaceable> -p <replaceable class="parameter">port</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the Internet TCP/IP port or local Unix domain socket file Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application> extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432, is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar> or the value of the <envar>PGPORT</envar>
environment variable (if set). environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-u -u
</term> </term>
<listitem> <listitem>
<para> <para>
Use password authentication. Use password authentication.
Prompts for Prompts for
<replaceable class="parameter">username</replaceable> <replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>. and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
<REFSECT2 ID="R2-APP-PG-DUMP-2"> <REFSECT2 ID="R2-APP-PG-DUMP-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-11-05</DATE> <DATE>1998-11-05</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>pg_dump</application> will create a file or <application>pg_dump</application> will create a file or
write to <filename>stdout</filename>. write to <filename>stdout</filename>.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem> </term>
<para> <listitem>
<application>pg_dump</application> could not attach to the <para>
<application>postmaster</application> <application>pg_dump</application> could not attach to the
process on the specified host and port. If you see this message, <application>postmaster</application>
ensure that the <application>postmaster</application> process on the specified host and port. If you see this message,
is running on the proper host and that you have specified the proper ensure that the <application>postmaster</application>
port. If your site uses an authentication system, ensure that you is running on the proper host and that you have specified the proper
have obtained the required authentication credentials. port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed. Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem> </term>
<para> <listitem>
You do not have a valid entry in the relation <literal>pg_shadow</literal> <para>
and and will not be allowed to access <productname>Postgres</productname>. You do not have a valid entry in the relation <literal>pg_shadow</literal>
Contact your <productname>Postgres</productname> administrator. and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem> </term>
<para> <listitem>
You do not have permission to read the database. <para>
Contact your <productname>Postgres</productname> site administrator. You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
<note>
<para>
<application>pg_dump</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dump</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<note> <REFSECT1 ID="R1-APP-PG-DUMP-1">
<para> <REFSECT1INFO>
<application>pg_dump</application> internally executes <DATE>1998-11-05</DATE>
<command>SELECT</command> statements. If you have problems running </REFSECT1INFO>
<application>pg_dump</application>, <TITLE>
make sure you are able to select information from the database using, for Description
example, <application>psql</application>. </TITLE>
</note> <PARA>
<application>pg_dump</application> is a utility for dumping out a
<REFSECT1 ID="R1-APP-PG-DUMP-1"> <productname>Postgres</productname> database into a script file
<REFSECT1INFO>
<DATE>1998-11-05</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dump</application> is a utility for dumping out a
<productname>Postgres</productname> database into a script file
containing query commands. The script containing query commands. The script
files are in text format and can be used to reconstruct the database, files are in text format and can be used to reconstruct the database,
even on other machines and other architectures. even on other machines and other architectures.
<application>pg_dump</application> <application>pg_dump</application>
will produce the queries necessary to re-generate all will produce the queries necessary to re-generate all
user-defined types, functions, tables, indices, aggregates, and user-defined types, functions, tables, indices, aggregates, and
operators. In addition, all the data is copied out in text format so operators. In addition, all the data is copied out in text format so
that it can be readily copied in again, as well as imported into tools that it can be readily copied in again, as well as imported into tools
for editing. for editing.
</para>
<para> <para>
<application>pg_dump</application> <application>pg_dump</application>
is useful for dumping out the contents of a database to move from one is useful for dumping out the contents of a database to move from one
<productname>Postgres</productname> installation to another. After running <productname>Postgres</productname> installation to another. After running
<application>pg_dump</application>, <application>pg_dump</application>,
one should examine the output script file for any warnings, especially one should examine the output script file for any warnings, especially
in light of the limitations listed below. in light of the limitations listed below.
</para>
</refsect1>
<REFSECT1 ID="R1-APP-PG-DUMP-2"> <REFSECT1 ID="R1-APP-PG-DUMP-2">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-11-05</DATE> <DATE>1998-11-05</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
<application>pg_dump</application> has a few limitations. <application>pg_dump</application> has a few limitations.
The limitations mostly stem from The limitations mostly stem from
difficulty in extracting certain meta-information from the system difficulty in extracting certain meta-information from the system
catalogs. catalogs.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
partial indices partial indices
<listitem> </term>
<para> <listitem>
<application>pg_dump</application> <para>
does not understand partial indices. The reason is <application>pg_dump</application>
the same as above; partial index predicates are stored as plans. does not understand partial indices. The reason is
the same as above; partial index predicates are stored as plans.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
large objects large objects
<listitem> </term>
<para> <listitem>
<application>pg_dump</application> does not handle large objects. <para>
Large objects are ignored and must be dealt with manually. <application>pg_dump</application> does not handle large objects.
Large objects are ignored and must be dealt with manually.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect1>
<REFSECT1 ID="R1-APP-PG-DUMP-3"> <REFSECT1 ID="R1-APP-PG-DUMP-3">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-11-05</DATE> <DATE>1998-11-05</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
To dump a database of the same name as the user: To dump a database of the same name as the user:
<programlisting> <programlisting>
% pg_dump > db.out % pg_dump > db.out
</programlisting> </programlisting>
</para>
<para> <para>
To reload this database: To reload this database:
<programlisting>
psql -e database < db.out
</programlisting>
<programlisting>
psql -e database < db.out
</programlisting>
</para>
</refsect1>
</REFENTRY> </REFENTRY>

482
doc/src/sgml/ref/pg_dumpall.sgml
View File

@ -12,6 +12,7 @@
<REFPURPOSE> <REFPURPOSE>
Extract all <productname>Postgres</productname> databases into a script file Extract all <productname>Postgres</productname> databases into a script file
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE> <DATE>1998-10-04</DATE>
@ -22,246 +23,301 @@ pg_dumpall [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replac
[ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ] [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-APP-PG-DUMPALL-1"> <REFSECT2 ID="R2-APP-PG-DUMPALL-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-10-04</DATE> <DATE>1998-10-04</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<application>pg_dumpall</application> accepts the following command line arguments: <application>pg_dumpall</application> accepts the following command line arguments:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
-a -a
</term> </term>
<listitem> <listitem>
<para> <para>
Dump out only the data, no schema (definitions). Dump out only the data, no schema (definitions).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-d -D
</term> </term>
<listitem> <listitem>
<para> <para>
Dump data as proper insert strings. Dump data as inserts with attribute names
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-D -n
</term> </term>
<listitem> <listitem>
<para> <para>
Dump data as inserts with attribute names Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-n -o
</term> </term>
<listitem> <listitem>
<para> <para>
Suppress double quotes around identifiers unless absolutely necessary. Dump object identifiers (<acronym>OID</acronym>s) for every table.
This may cause trouble loading this dumped data if there are reserved words </para>
used for identifiers. </listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-o -s
</term> </term>
<listitem> <listitem>
<para> <para>
Dump object identifiers (<acronym>OID</acronym>s) for every table. Dump out only the schema (definitions), no data.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-s -u
</term> </term>
<listitem> <listitem>
<para> <para>
Dump out only the schema (definitions), no data. Use password authentication. Prompts for username and password.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-u -v
</term> </term>
<listitem> <listitem>
<para> <para>
Use password authentication. Prompts for username and password. Specifies verbose mode
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-v -z
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies verbose mode Include ACLs (grant/revoke commands) and table ownership information.
</para>
</listitem>
</varlistentry>
<varlistentry> </variablelist>
<term> </para>
-z <para>
</term> <application>pg_dumpall</application> also accepts
<listitem> the following command line arguments for connection parameters:
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</variablelist> <variablelist>
<varlistentry>
<para> <term>
<application>pg_dumpall</application> also accepts -h <replaceable class="parameter">host</replaceable>
the following command line arguments for connection parameters: </term>
<listitem>
<variablelist> <para>
<varlistentry> Specifies the hostname of the machine on which the
<term> <application>postmaster</application>
-h <replaceable class="parameter">host</replaceable> is running. Defaults to using a local Unix domain socket
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection.. rather than an IP connection..
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-p <replaceable class="parameter">port</replaceable> -p <replaceable class="parameter">port</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
Specifies the Internet TCP/IP port or local Unix domain socket file Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application> extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432, is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar> or the value of the <envar>PGPORT</envar>
environment variable (if set). environment variable (if set).
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
-u -u
</term> </term>
<listitem> <listitem>
<para> <para>
Use password authentication. Use password authentication.
Prompts for Prompts for
<replaceable class="parameter">username</replaceable> <replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>. and <replaceable class="parameter">password</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</variablelist> <REFSECT2 ID="R2-APP-PG-DUMPALL-2">
<REFSECT2INFO>
<REFSECT2 ID="R2-APP-PG-DUMPALL-2"> <DATE>1998-10-04</DATE>
<REFSECT2INFO> </REFSECT2INFO>
<DATE>1998-10-04</DATE> <TITLE>
</REFSECT2INFO> Outputs
<TITLE> </TITLE>
Outputs <PARA>
</TITLE> <application>pg_dumpall</application> will create a file or
<PARA>
<application>pg_dumpall</application> will create a file or
write to <filename>stdout</filename>. write to <filename>stdout</filename>.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Connection to database 'template1' failed. Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem> </term>
<para> <listitem>
<application>pg_dumpall</application> could not attach to the <para>
<application>postmaster</application> <application>pg_dumpall</application> could not attach to the
process on the specified host and port. If you see this message, <application>postmaster</application>
ensure that the <application>postmaster</application> process on the specified host and port. If you see this message,
is running on the proper host and that you have specified the proper ensure that the <application>postmaster</application>
port. If your site uses an authentication system, ensure that you is running on the proper host and that you have specified the proper
have obtained the required authentication credentials. port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed. Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem> </term>
<para> <listitem>
You do not have a valid entry in the relation <literal>pg_shadow</literal> <para>
and and will not be allowed to access <productname>Postgres</productname>. You do not have a valid entry in the relation <literal>pg_shadow</literal>
Contact your <productname>Postgres</productname> administrator. and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem> </term>
<para> <listitem>
You do not have permission to read the database. <para>
Contact your <productname>Postgres</productname> site administrator. You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</variablelist> <note>
<para>
<application>pg_dumpall</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dumpall</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</para>
</note>
</refsect2>
</refsynopsisdiv>
<note> <REFSECT1 ID="R1-APP-PG-DUMPALL-1">
<para> <REFSECT1INFO>
<application>pg_dumpall</application> internally executes <DATE>1998-10-04</DATE>
<command>SELECT</command> statements. If you have problems running </REFSECT1INFO>
<application>pg_dumpall</application>, <TITLE>
make sure you are able to select information from the database using, for Description
example, <application>psql</application>. </TITLE>
</note> <PARA>
<application>pg_dumpall</application>
<REFSECT1 ID="R1-APP-PG-DUMPALL-1"> is a utility for dumping out all Postgres databases into one file.
<REFSECT1INFO> It also dumps the pg_shadow table, which is global to all databases.
<DATE>1998-10-04</DATE> <application>pg_dumpall</application> includes in this file the proper commands
</REFSECT1INFO> to automatically create each dumped database before loading.
<TITLE> </para>
Description <para>
</TITLE> <application>pg_dumpall</application> takes all <application>pg_dump</application>
<PARA>
<application>pg_dumpall</application>
is a utility for dumping out all Postgres databases into one file.
It also dumps the pg_shadow table, which is global to all databases.
<application>pg_dumpall</application> includes in this file the proper commands
to automatically create each dumped database before loading.
<para>
<application>pg_dumpall</application> takes all <application>pg_dump</application>
options, but <option>-f</option>, <option>-t</option> and options, but <option>-f</option>, <option>-t</option> and
<replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">dbname</replaceable>
should be omitted. should be omitted.
</para>
<para> <para>
Refer to Refer to
<xref linkend="app-pg-dump" endterm="pg-dump"> <xref linkend="app-pg-dump" endterm="pg-dump">
for more information on this capability. for more information on this capability.
</para
</refsect1>
<REFSECT1 ID="R1-APP-PG-DUMPALL-2"> <REFSECT1 ID="R1-APP-PG-DUMPALL-2">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-10-04</DATE> <DATE>1998-10-04</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
To dump all databases: To dump all databases:
<programlisting> <programlisting>
% pg_dumpall -o > db.out % pg_dumpall -o > db.out
</programlisting> </programlisting>
<tip> <tip>
<para> <para>
You can use most <application>pg_dump</application> options You can use most <application>pg_dump</application> options
for <application>pg_dumpall</application>. for <application>pg_dumpall</application>.
</tip> </para>
</tip>
<para> </para>
To reload this database: <para>
To reload this database:
<programlisting>
psql -e template1 < db.out
</programlisting>
<tip>
<para>
You can use most <application>psql</application> options
when reloading.
</tip>
<programlisting>
psql -e template1 < db.out
</programlisting>
</para>
<tip>
<para>
You can use most <application>psql</application> options
when reloading.
</para>
</tip>
</refsect1>
</REFENTRY> </REFENTRY>

1709
doc/src/sgml/ref/psql-ref.sgml
View File

File diff suppressed because it is too large Load Diff

201
doc/src/sgml/ref/reset.sgml
View File

@ -12,7 +12,7 @@ RESET
<REFPURPOSE> <REFPURPOSE>
Restores run-time parameters for session to default values Restores run-time parameters for session to default values
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -21,115 +21,122 @@ Restores run-time parameters for session to default values
RESET <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> RESET <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-RESET-1"> <REFSECT2 ID="R2-SQL-RESET-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST>
<VARIABLELIST> <VARLISTENTRY>
<VARLISTENTRY> <TERM>
<TERM> <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> </TERM>
</TERM> <LISTITEM>
<LISTITEM> <PARA>
<PARA>
Refer to the SET statement for more information on available Refer to the SET statement for more information on available
variables. variables.
</variablelist> </para>
</listitem>
</varlistentry>
</variablelist>
</para>
</REFSECT2>
</REFSECT2> <REFSECT2 ID="R2-SQL-RESET-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-RESET-2"> <VARIABLELIST>
<REFSECT2INFO> <VARLISTENTRY>
<DATE>1998-09-24</DATE> <TERM>
</REFSECT2INFO> RESET VARIABLE
<TITLE> </TERM>
Outputs <LISTITEM>
</TITLE> <PARA>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
RESET VARIABLE
</TERM>
<LISTITEM>
<PARA>
Message returned if Message returned if
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is successfully reset <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is successfully reset
to its default value.. to its default value..
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARIABLELIST> <REFSECT1 ID="R1-SQL-RESET-1">
<REFSECT1INFO>
</REFSECT2> <DATE>1998-09-24</DATE>
</REFSYNOPSISDIV> </REFSECT1INFO>
<TITLE>
<REFSECT1 ID="R1-SQL-RESET-1"> Description
<REFSECT1INFO> </TITLE>
<DATE>1998-09-24</DATE> <PARA>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>RESET</command> restores variables to the <command>RESET</command> restores variables to the
default values. default values.
Refer to the <command>SET</command> command for details on Refer to the <command>SET</command> command for details on
allowed values and defaults. allowed values and defaults.
<command>RESET</command> is an alternate form for <command>RESET</command> is an alternate form for
<synopsis> <synopsis>
<command>SET <replaceable class="parameter">variable</replaceable> = DEFAULT</command> <command>SET <replaceable class="parameter">variable</replaceable> = DEFAULT</command>
</synopsis> </synopsis>
</para>
<REFSECT2 ID="R2-SQL-RESET-3"> <REFSECT2 ID="R2-SQL-RESET-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
The RESET statement is a <productname>Postgres</productname> language extension. The RESET statement is a <productname>Postgres</productname> language extension.
<para> </para>
<para>
Refer to SET/SHOW statements to set/show variable values. Refer to SET/SHOW statements to set/show variable values.
</para>
</REFSECT2>
</refsect1>
</REFSECT2> <REFSECT1 ID="R1-SQL-RESET-2">
</refsect1> <TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- reset DateStyle to its default;
RESET DateStyle;
</programlisting>
<programlisting>
-- reset Geqo to its default;
RESET GEQO;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-RESET-2"> <REFSECT1 ID="R1-SQL-RESET-3">
<TITLE> <TITLE>
Usage Compatibility
</TITLE> </TITLE>
<PARA>
<ProgramListing>
-- reset DateStyle to its default;
RESET DateStyle;
</programlisting>
<programlisting>
-- reset Geqo to its default;
RESET GEQO;
</ProgramListing>
</REFSECT1> <REFSECT2 ID="R2-SQL-RESET-4">
<REFSECT2INFO>
<REFSECT1 ID="R1-SQL-RESET-3"> <DATE>1998-09-24</DATE>
<TITLE> </REFSECT2INFO>
Compatibility <TITLE>
</TITLE> SQL92
<PARA> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-RESET-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>RESET</command> in <acronym>SQL92</acronym>. There is no <command>RESET</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

520
doc/src/sgml/ref/revoke.sgml
View File

@ -12,7 +12,7 @@ REVOKE
<REFPURPOSE> <REFPURPOSE>
Revokes access privilege from a user, a group or all users. Revokes access privilege from a user, a group or all users.
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -25,200 +25,232 @@ REVOKE <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
FROM { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> } FROM { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> }
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-REVOKE-1"> <REFSECT2 ID="R2-SQL-REVOKE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The possible privileges are: The possible privileges are:
</para>
</listitem>
</varlistentry>
<VARIABLELIST> <VARLISTENTRY>
<VARLISTENTRY> <TERM>
<TERM> SELECT
SELECT </TERM>
</TERM> <LISTITEM>
<LISTITEM> <PARA>
<PARA> Privilege to access all of the columns of a specific
Privilege to access all of the columns of a specific
table/view. table/view.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
INSERT INSERT
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Privilege to insert data into all columns of a Privilege to insert data into all columns of a
specific table. specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
UPDATE UPDATE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Privilege to update all columns of a specific Privilege to update all columns of a specific
table. table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
DELETE DELETE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Privilege to delete rows from a specific table. Privilege to delete rows from a specific table.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
RULE RULE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Privilege to define rules on table/view. Privilege to define rules on table/view.
(See <command>CREATE RULE</command>). (See <command>CREATE RULE</command>).
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
ALL ALL
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Rescind all privileges. Rescind all privileges.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> <VARLISTENTRY>
<TERM>
<VARLISTENTRY> <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
<TERM> </TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> <LISTITEM>
</TERM> <PARA>
<LISTITEM> The name of an object from which to revoke access.
<PARA>
The name of an object from which to revoke access.
The possible objects are: The possible objects are:
<itemizedlist mark="bullet" spacing="compact"> <itemizedlist mark="bullet" spacing="compact">
<listitem> <listitem>
<para> <para>
table table
</para>
</listitem>
<listitem> <listitem>
<para> <para>
view view
</para>
</listitem>
<listitem> <listitem>
<para> <para>
sequence sequence
</para>
</listitem>
<listitem> <listitem>
<para> <para>
index index
</itemizedlist> </para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of a group from whom to revoke privileges. The name of a group from whom to revoke privileges.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of a user from whom revoke privileges. Use the PUBLIC keyword The name of a user from whom revoke privileges. Use the PUBLIC keyword
to specify all users. to specify all users.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
PUBLIC PUBLIC
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Rescind the specified privilege(s) for all users. Rescind the specified privilege(s) for all users.
</para>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</LISTITEM> <REFSECT2 ID="R2-SQL-REVOKE-2">
</VARLISTENTRY> <REFSECT2INFO>
</VARIABLELIST> <DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</REFSECT2> <VARIABLELIST>
<VARLISTENTRY>
<REFSECT2 ID="R2-SQL-REVOKE-2"> <TERM>
<REFSECT2INFO> CHANGE
<DATE>1998-09-24</DATE> </TERM>
</REFSECT2INFO> <LISTITEM>
<TITLE> <PARA>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully. Message returned if successfully.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
ERROR ERROR
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if object is not available or impossible Message returned if object is not available or impossible
to revoke privileges from a group or users. to revoke privileges from a group or users.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARIABLELIST> <REFSECT1 ID="R1-SQL-REVOKE-1">
<REFSECT1INFO>
</REFSECT2> <DATE>1998-09-24</DATE>
</REFSYNOPSISDIV> </REFSECT1INFO>
<TITLE>
<REFSECT1 ID="R1-SQL-REVOKE-1"> Description
<REFSECT1INFO> </TITLE>
<DATE>1998-09-24</DATE> <PARA>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
REVOKE allows creator of an object to revoke permissions granted REVOKE allows creator of an object to revoke permissions granted
before, from all users (via PUBLIC) or a certain user or group. before, from all users (via PUBLIC) or a certain user or group.
</para>
<REFSECT2 ID="R2-SQL-REVOKE-3"> <REFSECT2 ID="R2-SQL-REVOKE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
Refer to psql \z command for further information about permissions Refer to psql \z command for further information about permissions
on existing objects: on existing objects:
<programlisting> <programlisting>
Database = lusitania Database = lusitania
+------------------+---------------------------------------------+ +------------------+---------------------------------------------+
| Relation | Grant/Revoke Permissions | | Relation | Grant/Revoke Permissions |
@ -235,102 +267,118 @@ Notes
a -- INSERT a -- INSERT
R -- RULE R -- RULE
arwR -- ALL arwR -- ALL
</programlisting> </programlisting>
</para>
<tip> <tip>
<para> <para>
Currently, to create a GROUP you have to insert Currently, to create a GROUP you have to insert
data manually into table pg_group as: data manually into table pg_group as:
<programlisting> <programlisting>
INSERT INTO pg_group VALUES ('todos'); INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos; CREATE USER miriam IN GROUP todos;
</programlisting> </programlisting>
</tip> </para>
</tip>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-REVOKE-2"> <REFSECT1 ID="R1-SQL-REVOKE-2">
<TITLE> <TITLE>
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
<ProgramListing> <ProgramListing>
-- revoke insert privilege from all users on table films: -- revoke insert privilege from all users on table films:
-- --
REVOKE INSERT ON films FROM PUBLIC; REVOKE INSERT ON films FROM PUBLIC;
-- revoke all privileges from user manuel on view kinds: -- revoke all privileges from user manuel on view kinds:
-- --
REVOKE ALL ON kinds FROM manuel; REVOKE ALL ON kinds FROM manuel;
</ProgramListing> </ProgramListing>
</para>
</REFSECT1>
</REFSECT1> <REFSECT1 ID="R1-SQL-REVOKE-3">
<TITLE>
Compatibility
</TITLE>
<REFSECT1 ID="R1-SQL-REVOKE-3"> <REFSECT2 ID="R2-SQL-REVOKE-4">
<TITLE> <REFSECT2INFO>
Compatibility <DATE>1998-09-01</DATE>
</TITLE> </REFSECT2INFO>
<PARA> <TITLE>
SQL92
<REFSECT2 ID="R2-SQL-REVOKE-4"> </TITLE>
<REFSECT2INFO> <PARA>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The SQL92 syntax for <command>REVOKE</command> The SQL92 syntax for <command>REVOKE</command>
has additional capabilities for rescinding has additional capabilities for rescinding
privileges, including those on individual columns in tables: privileges, including those on individual columns in tables:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
<synopsis> <synopsis>
REVOKE { SELECT | DELETE | USAGE | ALL PRIVILEGES } [, ...] REVOKE { SELECT | DELETE | USAGE | ALL PRIVILEGES } [, ...]
ON <replaceable class="parameter">object</replaceable> ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE } FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
REVOKE { INSERT | UPDATE | REFERENCES } [, ...] [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] REVOKE { INSERT | UPDATE | REFERENCES } [, ...] [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
ON <replaceable class="parameter">object</replaceable> ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE } FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
</synopsis> </synopsis>
<listitem> </term>
<para> <listitem>
Refer to the <command>GRANT</command> command for details on individual fields. <para>
Refer to the <command>GRANT</command> command for details on individual fields.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<synopsis> <synopsis>
REVOKE GRANT OPTION FOR <replaceable class="parameter">privilege</replaceable> [, ...] REVOKE GRANT OPTION FOR <replaceable class="parameter">privilege</replaceable> [, ...]
ON <replaceable class="parameter">object</replaceable> ON <replaceable class="parameter">object</replaceable>
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE } FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } { RESTRICT | CASCADE }
</synopsis> </synopsis>
<listitem> </term>
<para> <listitem>
Rescinds authority for a user to grant the specified privilege to others. <para>
Refer to the <command>GRANT</command> command for details on individual fields. Rescinds authority for a user to grant the specified privilege to others.
Refer to the <command>GRANT</command> command for details on individual fields.
</variablelist> </para>
</listitem>
<para> </varlistentry>
</variablelist>
</para>
<para>
The possible objects are: The possible objects are:
<simplelist> <simplelist>
<member> [ TABLE ] table/view <member> [ TABLE ] table/view
<member> CHARACTER SET character-set </member>
<member> COLLATION collation <member> CHARACTER SET character-set
<member> TRANSLATION translation </member>
<member> DOMAIN domain <member> COLLATION collation
</simplelist> </member>
<member> TRANSLATION translation
<para> </member>
If user1 gives a privilege WITH GRANT OPTION to user2, <member> DOMAIN domain
</member>
</simplelist>
</para>
<para>
If user1 gives a privilege WITH GRANT OPTION to user2,
and user2 gives it to user3 then user1 can revoke and user2 gives it to user3 then user1 can revoke
this privilege in cascade using the CASCADE keyword. this privilege in cascade using the CASCADE keyword.
</para>
<para> <para>
If user1 gives a privilege WITH GRANT OPTION to user2, If user1 gives a privilege WITH GRANT OPTION to user2,
and user2 gives it to user3 then if user1 try revoke and user2 gives it to user3 then if user1 try revoke
this privilege it fails if he/she specify the RESTRICT this privilege it fails if he/she specify the RESTRICT
keyword. keyword.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

183
doc/src/sgml/ref/rollback.sgml
View File

@ -12,6 +12,7 @@ ROLLBACK
<REFPURPOSE> <REFPURPOSE>
Aborts the current transaction Aborts the current transaction
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -20,105 +21,113 @@ Aborts the current transaction
ROLLBACK [ WORK ] ROLLBACK [ WORK ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-ROLLBACK-1"> <REFSECT2 ID="R2-SQL-ROLLBACK-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
None. None.
</para>
</REFSECT2>
</REFSECT2> <REFSECT2 ID="R2-SQL-ROLLBACK-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-ROLLBACK-2"> <VARIABLELIST>
<REFSECT2INFO> <VARLISTENTRY>
<DATE>1998-09-24</DATE> <TERM>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
ABORT ABORT
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if successful. Message returned if successful.
</para>
</listitem>
</VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
NOTICE: UserAbortTransactionBlock and not in in-progress state NOTICE: UserAbortTransactionBlock and not in in-progress state
ABORT ABORT
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
If there is not any transaction currently in progress. If there is not any transaction currently in progress.
</para>
</listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARLISTENTRY> <REFSECT1 ID="R1-SQL-ROLLBACK-1">
</VARIABLELIST> <REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT2> </REFSECT1INFO>
</REFSYNOPSISDIV> <TITLE>
Description
<REFSECT1 ID="R1-SQL-ROLLBACK-1"> </TITLE>
<REFSECT1INFO> <PARA>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>ROLLBACK</command> rolls back the current transaction and causes <command>ROLLBACK</command> rolls back the current transaction and causes
all the updates made by the transaction to be discarded. all the updates made by the transaction to be discarded.
</para>
<REFSECT2 ID="R2-SQL-ROLLBACK-3"> <REFSECT2 ID="R2-SQL-ROLLBACK-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
The keyword WORK is noise and can be omitted. The keyword WORK is noise and can be omitted.
</para>
<para> <para>
Use the <command>COMMIT</command> statement to successfully Use the <command>COMMIT</command> statement to successfully
terminate a transaction. terminate a transaction.
</para>
</refsect2>
</REFSECT1>
</REFSECT1> <REFSECT1 ID="R1-SQL-ROLLBACK-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--To abort all changes:
--
ROLLBACK WORK;
</ProgramListing>
</para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-ROLLBACK-2"> <REFSECT1 ID="R1-SQL-ROLLBACK-3">
<TITLE> <TITLE>
Usage Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
<ProgramListing> </PARA>
--To abort all changes:
--
ROLLBACK WORK;
</ProgramListing>
</REFSECT1> <REFSECT2 ID="R2-SQL-ROLLBACK-4">
<REFSECT2INFO>
<REFSECT1 ID="R1-SQL-ROLLBACK-3"> <DATE>1998-09-24</DATE>
<TITLE> </REFSECT2INFO>
Compatibility <TITLE>
</TITLE> SQL92
<PARA> </TITLE>
</PARA> <PARA>
<REFSECT2 ID="R2-SQL-ROLLBACK-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
Full compatibility. Full compatibility.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

28
doc/src/sgml/ref/select.sgml
View File

@ -156,7 +156,7 @@ SELECT [ALL|DISTINCT [ON <replaceable class="PARAMETER">column</replaceable>] ]
<title> <title>
Outputs Outputs
</title> </title>
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -177,8 +177,11 @@ SELECT [ALL|DISTINCT [ON <replaceable class="PARAMETER">column</replaceable>] ]
<listitem> <listitem>
<para> <para>
The count of rows returned by the query. The count of rows returned by the query.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para>
</refsect2> </refsect2>
</refsynopsisdiv> </refsynopsisdiv>
@ -513,6 +516,7 @@ SELECT distributors.* WHERE name = 'Westwood';
108|Westward 108|Westward
</programlisting> </programlisting>
</para> </para>
</refsect2>
<refsect2 id="R2-SQL-SELECT-5"> <refsect2 id="R2-SQL-SELECT-5">
<refsect2info> <refsect2info>
@ -613,6 +617,8 @@ SELECT [ ALL | DISTINCT ] <replaceable class="PARAMETER">expression</replaceable
</title> </title>
<para> <para>
All input fields are described in detail for SELECT. All input fields are described in detail for SELECT.
</para>
</refsect2>
<refsect2 id="R2-SQL-SELECTINTO-2"> <refsect2 id="R2-SQL-SELECTINTO-2">
<refsect2info> <refsect2info>
@ -623,6 +629,9 @@ All input fields are described in detail for SELECT.
</title> </title>
<para> <para>
All output fields are described in detail for SELECT. All output fields are described in detail for SELECT.
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-SELECTINTO-1"> <refsect1 id="R1-SQL-SELECTINTO-1">
<refsect1info> <refsect1info>
@ -632,13 +641,14 @@ All output fields are described in detail for SELECT.
Description Description
</title> </title>
<para> <para>
SELECT INTO creates a new table from the results of a query. Typically, this SELECT INTO creates a new table from the results of a query. Typically, this
query draws data from an existing table, but any SQL query is allowed. query draws data from an existing table, but any SQL query is allowed.
<note> <note>
<para> <para>
CREATE TABLE AS is functionally equivalent to the SELECT INTO command. CREATE TABLE AS is functionally equivalent to the SELECT INTO command.
</note> </para>
</note>
</para>
</refsect1> </refsect1>
</refentry> </refentry>

1104
doc/src/sgml/ref/set.sgml
View File

File diff suppressed because it is too large Load Diff

234
doc/src/sgml/ref/show.sgml
View File

@ -12,6 +12,7 @@ SHOW
<REFPURPOSE> <REFPURPOSE>
Shows run-time parameters for session Shows run-time parameters for session
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -20,144 +21,151 @@ Shows run-time parameters for session
SHOW <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> SHOW <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-SHOW-1"> <REFSECT2 ID="R2-SQL-SHOW-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Refer to <command>SET</command> for more information on available Refer to <command>SET</command> for more information on available
variables. variables.
</VARLISTENTRY> </para>
</VARIABLELIST> </listitem>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSECT2> <REFSECT2 ID="R2-SQL-SHOW-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-SHOW-2"> <VARIABLELIST>
<REFSECT2INFO> <VARLISTENTRY>
<DATE>1998-09-24</DATE> <TERM>
</REFSECT2INFO> <returnvalue>NOTICE: <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is <replaceable>value</replaceable></ReturnValue>
<TITLE> SHOW VARIABLE
Outputs </TERM>
</TITLE> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE: <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> is <replaceable>value</replaceable></ReturnValue>
SHOW VARIABLE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully. Message returned if successfully.
</listitem> </para>
</listitem>
</varlistentry>
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE: Unrecognized variable <replaceable>value</replaceable></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if <ReturnValue>value</ReturnValue> does not exist.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<returnvalue>NOTICE: Unrecognized variable <replaceable>value</replaceable></ReturnValue> NOTICE: Time zone is unknown
</TERM> SHOW VARIABLE
<LISTITEM> </TERM>
<PARA> <LISTITEM>
Message returned if <ReturnValue>value</ReturnValue> does not exist. <PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
NOTICE: Time zone is unknown
SHOW VARIABLE
</TERM>
<LISTITEM>
<PARA>
If the TZ environment variable is not set. If the TZ environment variable is not set.
</para>
</listitem>
</varlistentry>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</VARIABLELIST> <REFSECT1 ID="R1-SQL-SHOW-1">
<REFSECT1INFO>
</REFSECT2> <DATE>1998-09-24</DATE>
</REFSYNOPSISDIV> </REFSECT1INFO>
<TITLE>
<REFSECT1 ID="R1-SQL-SHOW-1"> Description
<REFSECT1INFO> </TITLE>
<DATE>1998-09-24</DATE> <PARA>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>SHOW</command> will display the current <command>SHOW</command> will display the current
configuration parameters for configuration parameters for
variable during a session. variable during a session.
</para>
<para> <para>
The session can be configured using <command>SET</command> statement, The session can be configured using <command>SET</command> statement,
and values and values
can be restored to the defaults using <command>RESET</command> statement. can be restored to the defaults using <command>RESET</command> statement.
Parameters and values are case-insensitive. Parameters and values are case-insensitive.
</para>
<REFSECT2 ID="R2-SQL-SHOW-3"> <REFSECT2 ID="R2-SQL-SHOW-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
The <command>SHOW</command> is a <productname>Postgres</productname> The <command>SHOW</command> is a <productname>Postgres</productname>
language extension. language extension.
</para>
<para> <para>
Refer to <command>SET</command>/<command>RESET</command> Refer to <command>SET</command>/<command>RESET</command>
to set/reset variable values. to set/reset variable values.
See also <command>SET TIME ZONE</command>. See also <command>SET TIME ZONE</command>.
</para>
</REFSECT2>
</REFSECT1>
</REFSECT2> <REFSECT1 ID="R1-SQL-SHOW-2">
</REFSECT1> <TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- show DateStyle;
SHOW DateStyle;
NOTICE:DateStyle is Postgres with US (NonEuropean) conventions
<REFSECT1 ID="R1-SQL-SHOW-2"> -- show Geqo;
<TITLE> SHOW GEQO;
Usage NOTICE:GEQO is ON
</TITLE> </ProgramListing>
<PARA> </para>
<ProgramListing> </REFSECT1>
-- show DateStyle;
SHOW DateStyle;
NOTICE:DateStyle is Postgres with US (NonEuropean) conventions
-- show Geqo; <REFSECT1 ID="R1-SQL-SHOW-3">
SHOW GEQO; <TITLE>
NOTICE:GEQO is ON Compatibility
</ProgramListing> </TITLE>
<PARA>
</PARA>
</REFSECT1> <REFSECT2 ID="R2-SQL-SHOW-4">
<REFSECT2INFO>
<REFSECT1 ID="R1-SQL-SHOW-3"> <DATE>1998-09-24</DATE>
<TITLE> </REFSECT2INFO>
Compatibility <TITLE>
</TITLE> SQL92
<PARA> </TITLE>
</PARA> <PARA>
<REFSECT2 ID="R2-SQL-SHOW-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>SET</command> defined in <acronym>SQL92</acronym>. There is no <command>SET</command> defined in <acronym>SQL92</acronym>.
</refsect2> </para>
</refsect1> </refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

30
doc/src/sgml/ref/unlisten.sgml
View File

@ -12,7 +12,7 @@ UNLISTEN
<REFPURPOSE> <REFPURPOSE>
Stop listening for notification Stop listening for notification
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-10-19</DATE> <DATE>1998-10-19</DATE>
@ -38,7 +38,9 @@ Inputs
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Name of previously registered notify condition. Name of previously registered notify condition.
</para>
</listitem>
</varlistentry>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<literal>*</literal> <literal>*</literal>
@ -46,6 +48,9 @@ Name of previously registered notify condition.
<LISTITEM> <LISTITEM>
<PARA> <PARA>
All current listen registrations for this backend are cleared. All current listen registrations for this backend are cleared.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
@ -68,8 +73,12 @@ Outputs
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Acknowledgement that statement has executed. Acknowledgement that statement has executed.
</para>
</listitem>
</varlistentry>
</VARIABLELIST> </VARIABLELIST>
</para>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -88,12 +97,13 @@ UNLISTEN cancels any existing registration of the current
condition <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>. condition <REPLACEABLE CLASS="PARAMETER">notifyname</REPLACEABLE>.
The special condition wildcard "*" cancels all listener registrations The special condition wildcard "*" cancels all listener registrations
for the current session. for the current session.
</para>
<para> <para>
<xref linkend="sql-notify" endterm="sql-notify-ref"> <xref linkend="sql-notify" endterm="sql-notify-ref">
contains a more extensive contains a more extensive
discussion of the use of <command>LISTEN</command> and discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>. <command>NOTIFY</command>.
</para>
<REFSECT2 ID="R2-SQL-UNLISTEN-3"> <REFSECT2 ID="R2-SQL-UNLISTEN-3">
<REFSECT2INFO> <REFSECT2INFO>
@ -106,21 +116,22 @@ Notes
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
needs not to be a valid class name but can be any string valid needs not to be a valid class name but can be any string valid
as a name up to 32 characters long. as a name up to 32 characters long.
</para>
<para> <para>
The backend does not complain if you UNLISTEN something you were not The backend does not complain if you UNLISTEN something you were not
listening for. listening for.
Each backend will automatically execute <command>UNLISTEN *</command> when Each backend will automatically execute <command>UNLISTEN *</command> when
exiting. exiting.
</para>
<para> <para>
A restriction in some previous releases of A restriction in some previous releases of
<productname>Postgres</productname> that a <productname>Postgres</productname> that a
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
which does not correspond to an actual table must be enclosed in double-quotes which does not correspond to an actual table must be enclosed in double-quotes
is no longer present. is no longer present.
</para>
</REFSECT2> </REFSECT2>
</refsect1>
<REFSECT1 ID="R1-SQL-UNLISTEN-2"> <REFSECT1 ID="R1-SQL-UNLISTEN-2">
<TITLE> <TITLE>
@ -144,14 +155,13 @@ NOTIFY
-- notice no NOTIFY event is received -- notice no NOTIFY event is received
postgres=> postgres=>
</programlisting> </programlisting>
</para>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-UNLISTEN-3"> <REFSECT1 ID="R1-SQL-UNLISTEN-3">
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-UNLISTEN-4"> <REFSECT2 ID="R2-SQL-UNLISTEN-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -162,5 +172,7 @@ SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no <command>UNLISTEN</command> in <acronym>SQL92</acronym>. There is no <command>UNLISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

240
doc/src/sgml/ref/update.sgml
View File

@ -12,7 +12,7 @@ UPDATE
<REFPURPOSE> <REFPURPOSE>
Replaces values of columns in a table Replaces values of columns in a table
</REFPURPOSE> </REFPURPOSE>
</refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
@ -23,127 +23,134 @@ UPDATE <REPLACEABLE CLASS="PARAMETER">table</replaceable> SET <REPLACEABLE CLASS
[ WHERE <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> ] [ WHERE <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-UPDATE-1"> <REFSECT2 ID="R2-SQL-UPDATE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER">table</replaceable> <REPLACEABLE CLASS="PARAMETER">table</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of an existing table. The name of an existing table.
</LISTITEM> </para>
</VARLISTENTRY> </LISTITEM>
<VARLISTENTRY> </VARLISTENTRY>
<TERM> <VARLISTENTRY>
<REPLACEABLE CLASS="PARAMETER">column</replaceable> <TERM>
</TERM> <REPLACEABLE CLASS="PARAMETER">column</replaceable>
<LISTITEM> </TERM>
<PARA> <LISTITEM>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</replaceable>. <PARA>
</LISTITEM> The name of a column in <REPLACEABLE CLASS="PARAMETER">table</replaceable>.
</VARLISTENTRY> </para>
<VARLISTENTRY> </LISTITEM>
<TERM> </VARLISTENTRY>
<REPLACEABLE CLASS="PARAMETER">expression</replaceable> <VARLISTENTRY>
</TERM> <TERM>
<LISTITEM> <REPLACEABLE CLASS="PARAMETER">expression</replaceable>
<PARA> </TERM>
<LISTITEM>
<PARA>
A valid expression or value to assign to column. A valid expression or value to assign to column.
</LISTITEM> </para>
</VARLISTENTRY> </LISTITEM>
<VARLISTENTRY> </VARLISTENTRY>
<TERM> <VARLISTENTRY>
<REPLACEABLE CLASS="PARAMETER">fromlist</REPLACEABLE> <TERM>
</TERM> <REPLACEABLE CLASS="PARAMETER">fromlist</REPLACEABLE>
<LISTITEM> </TERM>
<PARA> <LISTITEM>
<PARA>
A <productname>Postgres</productname> A <productname>Postgres</productname>
non-standard extension to allow columns non-standard extension to allow columns
from other tables to appear in the WHERE condition. from other tables to appear in the WHERE condition.
</LISTITEM> </para>
</VARLISTENTRY> </LISTITEM>
<VARLISTENTRY> </VARLISTENTRY>
<TERM> <VARLISTENTRY>
<REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> <TERM>
</TERM> <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>
<LISTITEM> </TERM>
<PARA> <LISTITEM>
<PARA>
Refer to the SELECT statement for a further description Refer to the SELECT statement for a further description
of the WHERE clause. of the WHERE clause.
</LISTITEM> </para>
</VARLISTENTRY> </LISTITEM>
</VARIABLELIST> </VARLISTENTRY>
</REFSECT2> </VARIABLELIST>
</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-UPDATE-2"> <REFSECT2 ID="R2-SQL-UPDATE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
UPDATE <replaceable class="parameter">#</replaceable> UPDATE <replaceable class="parameter">#</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Message returned if successful. Message returned if successful.
The <replaceable class="parameter">#</replaceable> The <replaceable class="parameter">#</replaceable>
means the number of rows updated. means the number of rows updated.
If <replaceable class="parameter">#</replaceable> If <replaceable class="parameter">#</replaceable>
is equal 0 no rows are updated. is equal 0 no rows are updated.
</LISTITEM> </para>
</VARLISTENTRY> </LISTITEM>
</VARIABLELIST> </VARLISTENTRY>
</VARIABLELIST>
</para>
</REFSECT2>
</REFSYNOPSISDIV>
</REFSECT2> <REFSECT1 ID="R1-SQL-UPDATE-1">
</REFSYNOPSISDIV> <REFSECT1INFO>
<DATE>1998-09-24</DATE>
<REFSECT1 ID="R1-SQL-UPDATE-1"> </REFSECT1INFO>
<REFSECT1INFO> <TITLE>
<DATE>1998-09-24</DATE> Description
</REFSECT1INFO> </TITLE>
<TITLE> <PARA>
Description
</TITLE>
<PARA>
UPDATE changes the values of the columns specified for UPDATE changes the values of the columns specified for
all rows which satisfy condition. Only the columns all rows which satisfy condition. Only the columns
to be modified need appear as column. to be modified need appear as column.
</para>
<PARA> <PARA>
Array references use the same syntax found in SELECT. Array references use the same syntax found in SELECT.
That is, either single array elements, a range of array That is, either single array elements, a range of array
elements or the entire array may be replaced with a single elements or the entire array may be replaced with a single
query. query.
</para>
<PARA> <PARA>
You must have write access to the table in order to modify You must have write access to the table in order to modify
it, as well as read access to any table whose values are it, as well as read access to any table whose values are
mentioned in the WHERE condition. mentioned in the WHERE condition.
</para>
</REFSECT1>
</REFSECT1> <REFSECT1 ID="R1-SQL-UPDATE-2">
<TITLE>
<REFSECT1 ID="R1-SQL-UPDATE-2"> Usage
<TITLE> </TITLE>
Usage <PARA>
</TITLE> </PARA>
<PARA> <ProgramListing>
</PARA>
<ProgramListing>
--Change word "Drama" with "Dramatic" on column kind: --Change word "Drama" with "Dramatic" on column kind:
-- --
UPDATE films UPDATE films
@ -159,32 +166,35 @@ Usage
M_401|War and Peace|104|1967-02-12|Dramatic | 05:57 M_401|War and Peace|104|1967-02-12|Dramatic | 05:57
T_601|Yojimbo |106|1961-06-16|Dramatic | 01:50 T_601|Yojimbo |106|1961-06-16|Dramatic | 01:50
DA101|Das Boot |110|1981-11-11|Dramatic | 02:29 DA101|Das Boot |110|1981-11-11|Dramatic | 02:29
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-UPDATE-3"> <REFSECT1 ID="R1-SQL-UPDATE-3">
<TITLE> <TITLE>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-UPDATE-4"> <REFSECT2 ID="R2-SQL-UPDATE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-24</DATE> <DATE>1998-09-24</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
SQL92 defines a different syntax for positioned UPDATE statement: SQL92 defines a different syntax for positioned UPDATE statement:
<programlisting> <programlisting>
UPDATE table SET column = expression [, ...] UPDATE table SET column = expression [, ...]
WHERE CURRENT OF <replaceable class="parameter">cursor</replaceable> WHERE CURRENT OF <replaceable class="parameter">cursor</replaceable>
</programlisting> </programlisting>
where <replaceable class="parameter">cursor</replaceable> where <replaceable class="parameter">cursor</replaceable>
identifies an open cursor. identifies an open cursor.
</para>
</refsect2>
</refsect1>
</REFENTRY> </REFENTRY>

Some files were not shown because too many files have changed in this diff Show More