of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@michvhf.com>.
<Para>
<ProductName>PostgreSQL</ProductName> is available without cost. This manual
describes version 6.4 of <ProductName>PostgreSQL</ProductName>.
-
+</Para>
<Para>
We will use <ProductName>Postgres</ProductName>
to mean the version distributed as <ProductName>PostgreSQL</ProductName>.
-
+</Para>
<Para>
Check the Administrator's Guide for a list of currently supported machines.
In general,
<ProductName>Postgres</ProductName> is portable to any Unix/Posix-compatible system
with full libc library support.
-
+</Para>
</Sect1>
|Mariposa | 1953 |
+----------+----------+
</ProgramListing>
+</Para>
<Para>
On the other hand, to find the names of all cities,
sub-values that can be accessed from the query
language. For example, you can create attributes that
are arrays of base types.
+</Para>
<Sect2>
<Title>Arrays</Title>
+-------------------+
</ProgramListing>
</Para>
-
+</sect2>
</Sect1>
<Sect1>
|Mariposa | 1320 |
+---------+------------+
</ProgramListing>
+</Para>
<Para>
The default beginning of a time range is the earliest
the current time; thus, the above time range can be
abbreviated as ``[,].''
</Para>
+</sect1>
<Sect1>
<Title>More Advanced Features</Title>
<ProductName>Postgres</ProductName> has many features not touched upon in this
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.
+</Para>
+</sect1>
</Chapter>
</Para>
</ListItem>
</ItemizedList>
+</Para>
<Para>
A single <Application>postmaster</Application> manages a given collection of
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
-
+</sect1>
</Chapter>
</Para>
</ListItem>
</ItemizedList>
-
+</para>
<Para>
A single <Application>postmaster</Application> manages a given collection of
databases on a single host. Such a collection of
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
-
+</sect1>
</Chapter>
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session
consists of the following cooperating UNIX processes (programs):
+</Para>
<ItemizedList>
<ListItem>
<Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting
for requests, whereas frontend and backend processes
come and go.
+</Para>
<Para>
The <FileName>libpq</FileName> library allows a single
machine may not be accessible (or may only be accessed
using a different filename) on the database server
machine.
+</Para>
<Para>
You should also be aware that the <Application>postmaster</Application> and
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
-
+</sect1>
</Chapter>
<!--
-$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
- Thomas Lockhart 1998-08-03
<application>genbki</application>
input that builds tables and C header files that describe those
tables.
+</para>
<para>
Related information may be found in documentation for
<application>initdb</application>,
<application>createdb</application>,
and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>.
+</para>
<sect1>
<title><acronym>BKI</acronym> File Format</title>
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
anyway).
+</para>
<para>
Commands are composed of a command name followed by space separated
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
undefined.
+</para>
<para>
Macros are defined using
undefine macro macro_name
</programlisting>
and redefined using the same syntax as define.
+</para>
<para>
Lists of general commands and macro commands
follow.
+</para>
+</sect1>
<sect1>
<title>General Commands</title>
Open the class called
<replaceable class="parameter">classname</replaceable>
for further manipulation.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
is not already opened. If no
<replaceable class="parameter">classname</replaceable>
is given, then the currently open class is closed.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
Print the currently open class.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">oid_value</replaceable>
is not <quote>0</quote>, then this value will be used as the instance's
object identifier. Otherwise, it is an error.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
As above, but the system generates a unique object identifier.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
Create a class named
<replaceable class="parameter">classname</replaceable>
with the attributes given in parentheses.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">classname</replaceable>
for writing but do not record its existence in the system catalogs.
(This is primarily to aid in bootstrapping.)
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<para>
Destroy the class named
<replaceable class="parameter">classname</replaceable>.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">collection_1</replaceable>,
<replaceable class="parameter">collection_2</replaceable>
etc., respectively.
-
+</para>
+</listitem>
</varlistentry>
+
</variablelist>
<note>
<para>
This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04
+</para>
</note>
+</sect1>
<sect1>
<title>Macro Commands</title>
with the arguments
<replaceable class="parameter">args</replaceable>
declared in a C-like manner.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
which has its value
read from the file called
<replaceable class="parameter">filename</replaceable>.
-
+</para>
+</listitem>
</varlistentry>
+
</variablelist>
+</para>
+</sect1>
<sect1>
<title>Debugging Commands</title>
<note>
<para>
This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05
+</para>
</note>
<variablelist>
<listitem>
<para>
Randomly print the open class.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
Toggle display of time information.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
Set retrievals to now.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
Set retrievals to snapshots of the specfied time.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
Set retrievals to ranges of the specified times.
Either time may be replaced with space
if an unbounded time range is desired.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">type2</replaceable>,
etc. to the class
<replaceable class="parameter">classname</replaceable>.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">oldclassname</replaceable>
class to
<replaceable class="parameter">newclassname</replaceable>.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">classname</replaceable>
to
<replaceable class="parameter">newattname</replaceable>.
-
+</para>
+</listitem>
</varlistentry>
</variablelist>
+</para>
+</sect1>
<sect1>
<title>Example</title>
print
close pg_opclass
</programlisting>
-
+</para>
+</sect1>
</chapter>
Contributed by <ULink url="mailto:geek+@cmu.edu">Brian Gallew</ULink>
</Para>
</Note>
+</para>
<Para>
Configuring gcc to use certain flags by default is a simple matter of
"*<Replaceable>section_name</Replaceable>:" (e.g. "*asm:").
The second line is a list of flags,
and the third line is blank.
+</para>
<Para>
The easiest change to make is to append
</ProgramListing>
This will always omit frame pointers, any will build 486-optimized
code unless -m386 is specified on the command line.
+</para>
<Para>
You can actually do quite a lot of customization with the specs file.
Always remember, however, that these changes are global, and affect
all users of the system.
+</para>
</Chapter>
<chapter id="config">
<title id="install-config">Configuration Options</title>
-<sect1>
-<title>Parameters for Configuration (<application>configure</application>)</title>
-
-<para>
-The full set of parameters available in <application>configure</application>
-can be obtained by typing
-
-<programlisting>
-$ ./configure --help
-</programlisting>
-
-<para>
-The following parameters may be of interest to installers:
-
-<programlisting>
+ <sect1>
+
<title>Parameters for Configuration (<application>configure</application>)</title>
+
+
The full set of parameters available in <application>configure</application>
+ can be obtained by typing
+
+ $ ./configure --help
+ </programlisting>
+ </para>
+ The following parameters may be of interest to installers:
+
Directory and file names:
--prefix=PREFIX install architecture-independent files in PREFIX
[/usr/local/pgsql]
--enable-cassert enable assertion checks (debugging)
--with-CC=<replaceable>compiler</replaceable> use specific C compiler
--with-CXX=<replaceable>compiler</replaceable> use specific C++ compiler
-</programlisting>
-
-<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.
-
-<sect1>
-<title>Parameters for Building (<application>make</application>)</title>
-
-<para>
-Many installation-related parameters can be set in the building
-stage of <productname>Postgres</productname> installation.
-
-<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.
-
-<synopsis>
-make [ <replaceable>variable</replaceable>=<replaceable class="parameter">value</replaceable> [,...] ]
-</synopsis>
-
-<para>
-A few of the many variables which can be specified are:
-
-<variablelist>
-<varlistentry>
-<term>
-<envar>POSTGRESDIR</envar>
-
-<listitem>
-<para>
-Top of the installation tree.
-
-<varlistentry>
-<term>
-<envar>BINDIR</envar>
-
-<listitem>
-<para>
-Location of applications and utilities.
-
-<varlistentry>
-<term>
-<envar>LIBDIR</envar>
-
-<listitem>
-<para>
-Location of object libraries, including shared libraries.
-
-<varlistentry>
-<term>
-<envar>HEADERDIR</envar>
-
-<listitem>
-<para>
-Location of include files.
-
-<varlistentry>
-<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>
+ </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>
+ Many installation-related parameters can be set in the building
+ stage of <productname>Postgres</productname> installation.
+ </para>
+ <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.
+
+ <synopsis>
+ make [ <replaceable>variable</replaceable>=<replaceable class="parameter">value</replaceable> [,...] ]
+ </synopsis>
+ </para>
+ <para>
+ A few of the many variables which can be specified are:
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <envar>POSTGRESDIR</envar>
+ </term>
+ <listitem>
+ <para>
+ Top of the installation tree.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <envar>BINDIR</envar>
+ </term>
+ <listitem>
+ <para>
+ Location of applications and utilities.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <envar>LIBDIR</envar>
+ </term>
+ <listitem>
+ <para>
+ Location of object libraries, including shared libraries.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <envar>HEADERDIR</envar>
+ </term>
+ <listitem>
+ <para>
+ Location of include files.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <envar>ODBCINST</envar>
+ </term>
+ <listitem>
+ <para>
+ Location of installation-wide <application>psqlODBC</application>
+ (<acronym>ODBC</acronym>) configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <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>
+ </term>
+ <listitem>
+ <para>
+ Set flags for the C compiler.
+ Should be assigned with "+=" to retain relevant default parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ 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>
+ <term>
+ <envar>USE_TCL</envar>
+ </term>
+ <listitem>
+ <para>
+ Enable Tcl interface building.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <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>
+ <term>
+ <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>
+
+ </variablelist>
+ </para>
+ <para>
+ Here is an example <filename>Makefile.custom</filename> for a
+ PentiumPro Linux system:
+
+ <programlisting>
# Makefile.custom
# Thomas Lockhart 1998-03-01
HSTYLE= /home/tgl/SGML/db118.d/docbook/html
PSTYLE= /home/tgl/SGML/db118.d/docbook/print
-</programlisting>
-
-<Sect1>
-<Title>Locale Support</Title>
-
-<Para>
-<Note>
-<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.
-
-</Para>
-</Note>
-While doing a project for a company in Moscow, Russia,
-I encountered the problem that postgresql had no
-support of national alphabets. After looking for possible workarounds
-I decided to develop support of locale myself.
-I'm not a C-programer but already had some experience with locale programming
-when I work with perl
-(debugging) and glimpse. After several days of digging through
- 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!
-I did support only for
-<envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>,
-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
-and (to my surprise) it was
-incorporated into the <productname>Postgres</productname> distribution.
-
-<Para>
- People often complain that locale doesn't work for them.
-There are several common mistakes:
-
-<ItemizedList>
-<ListItem>
-<Para>
- Didn't properly configure postgresql before compilation.
- You must run configure with --enable-locale option to enable locale support.
- Didn't setup environment correctly when starting postmaster.
- You must define environment variables
-<envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>
-before running postmaster
- because backend gets information about locale from environment.
-I use following shell script
- (runpostgres):
-
-<ProgramListing>
- #!/bin/sh
-
- export LC_CTYPE=koi8-r
- export LC_COLLATE=koi8-r
- postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe'
-</ProgramListing>
-
- and run it from rc.local as
-
-<ProgramListing>
- /bin/su - postgres -c "/home/postgres/runpostgres"
-</ProgramListing>
-
-</Para>
-</ListItem>
-<ListItem>
-<Para>
- Broken locale support in OS (for example, locale support in libc
-under Linux several times has changed
- and this caused a lot of problems). Latest perl has also support of
-locale and if locale is broken <command>perl -v</command> will
- complain something like:
-
-<programlisting>
- 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist
- 8:18[mira]:~/WWW/postgres>perl -v
- perl: warning: Setting locale failed.
- perl: warning: Please check that your locale settings:
- LC_ALL = (unset),
- LC_CTYPE = "not_exist",
- LANG = (unset)
- are supported and installed on your system.
- perl: warning: Falling back to the standard locale ("C").
-</programlisting>
-
-</Para>
-</ListItem>
-<ListItem>
-<Para>
- Wrong location of locale files!
-
- Possible locations include:
-<filename>/usr/lib/locale</filename>
-(Linux, Solaris), <filename>/usr/share/locale</filename> (Linux),
-<filename>/usr/lib/nls/loc</filename> (DUX 4.0).
-
- Check <command>man locale</command> to find the correct location.
-Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and
- <filename>/usr/share/locale</filename> to be sure that
-the next libc will not break my locale.
-</Para>
-</ListItem>
-</ItemizedList>
-
-<Sect2>
-<Title>What are the Benefits?</Title>
-
-<Para>
-You can use ~* and order by operators for strings contain characters
-from national alphabets. Non-english users
-definitely need that. If you won't use locale stuff just undefine
-the USE_LOCALE variable.
-
-<Sect2>
-<Title>What are the Drawbacks?</Title>
-
-<Para>
-There is one evident drawback of using locale - it's speed!
-So, use locale only if you really need it.
-
-
-<Sect1>
-<Title>Kerberos Authentication</Title>
-
-<Para>
-<productname>Kerberos</productname> is an industry-standard secure authentication
-system suitable for distributed computing over a public network.
-
-<sect2>
-<title>Availability</title>
-
-<para>
-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>.
-
-<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.
-</note>
-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>
-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>.
-
-<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>
-expects to find the associated libraries, header files and its own
-server key file.
-
-<para>
-After compilation is complete, <Productname>Postgres</Productname>
- must be registered as a <productname>Kerberos</productname>
-service. See the
-<citetitle>Kerberos Operations Notes</citetitle>
-and related manual pages for more details on registering services.
-
-<sect2>
-<title>Operation</title>
-
-<para>
-After initial installation, <Productname>Postgres</Productname>
-should operate in all ways as a normal
-<productname>Kerberos</productname>
-service. For details on the use of authentication, see the
-<citetitle>PostgreSQL User's Guide</citetitle> reference sections
-for <application>postmaster</application>
-and <application>psql</application>.
-
-<para>
-In the
-<productname>Kerberos</productname>
-Version 5 hooks, the following assumptions are made about user
-and service naming:
-
-<itemizedlist>
-<listitem>
-<para>
-User principal names (anames) are assumed to
-contain the actual Unix/<Productname>Postgres</Productname> user name
- in the first component.
-
-<listitem>
-<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
-suffixes removed).
-
-</itemizedlist>
-
-<para>
-<table tocentry="1">
-<title>Kerberos Parameter Examples</title>
-<titleabbrev>Kerberos</titleabbrev>
-
-<tgroup cols="2">
-<thead>
-<row>
-<entry>
-Parameter
-</entry>
-<entry>
-Example
-</entry>
-
-<tbody>
-<row>
-<entry>
-user
-</entry>
-<entry>
-frew@S2K.ORG
-</entry>
-
-<row>
-<entry>
-user
-</entry>
-<entry>
-aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
-</entry>
-
-<row>
-<entry>
-host
-</entry>
-<entry>
-postgres_dbms/ucbvax@S2K.ORG
-</entry>
-</tbody>
-</tgroup>
-</table>
-
-<para>
-Support for Version 4 will disappear sometime after the production
-release of Version 5 by MIT.
+ </programlisting>
+ </para>
+ </sect1>
+ <Sect1>
+ <Title>Locale Support</Title>
+
+ <Para>
+ <Note>
+ <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.
+
+ </Para>
+ </Note>
+ While doing a project for a company in Moscow, Russia,
+ I encountered the problem that postgresql had no
+ support of national alphabets. After looking for possible workarounds
+ I decided to develop support of locale myself.
+ I'm not a C-programer but already had some experience with locale programming
+ when I work with perl
+ (debugging) and glimpse. After several days of digging through
+ 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!
+ I did support only for
+ <envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>,
+ 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
+ and (to my surprise) it was
+ incorporated into the <productname>Postgres</productname> distribution.
+ </para>
+ <Para>
+ People often complain that locale doesn't work for them.
+ There are several common mistakes:
+
+ <ItemizedList>
+ <ListItem>
+ <Para>
+ Didn't properly configure postgresql before compilation.
+ You must run configure with --enable-locale option to enable locale support.
+ Didn't setup environment correctly when starting postmaster.
+ You must define environment variables
+ <envar>LC_CTYPE</envar> and <envar>LC_COLLATE</envar>
+ before running postmaster
+ because backend gets information about locale from environment.
+ I use following shell script
+ (runpostgres):
+
+ <ProgramListing>
+ #!/bin/sh
+
+ export LC_CTYPE=koi8-r
+ export LC_COLLATE=koi8-r
+ postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe'
+ </ProgramListing>
+
+ and run it from rc.local as
+
+ <ProgramListing>
+ /bin/su - postgres -c "/home/postgres/runpostgres"
+ </ProgramListing>
+
+ </Para>
+ </ListItem>
+ <ListItem>
+ <Para>
+ Broken locale support in OS (for example, locale support in libc
+ under Linux several times has changed
+ and this caused a lot of problems). Latest perl has also support of
+ locale and if locale is broken <command>perl -v</command> will
+ complain something like:
+
+ <programlisting>
+ 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist
+ 8:18[mira]:~/WWW/postgres>perl -v
+ perl: warning: Setting locale failed.
+ perl: warning: Please check that your locale settings:
+ LC_ALL = (unset),
+ LC_CTYPE = "not_exist",
+ LANG = (unset)
+ are supported and installed on your system.
+ perl: warning: Falling back to the standard locale ("C").
+ </programlisting>
+
+ </Para>
+ </ListItem>
+ <ListItem>
+ <Para>
+ Wrong location of locale files!
+
+ Possible locations include:
+ <filename>/usr/lib/locale</filename>
+ (Linux, Solaris), <filename>/usr/share/locale</filename> (Linux),
+ <filename>/usr/lib/nls/loc</filename> (DUX 4.0).
+
+ Check <command>man locale</command> to find the correct location.
+ Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and
+ <filename>/usr/share/locale</filename> to be sure that
+ the next libc will not break my locale.
+ </Para>
+ </ListItem>
+ </ItemizedList>
+ </para>
+
+ <Sect2>
+ <Title>What are the Benefits?</Title>
+
+ <Para>
+ You can use ~* and order by operators for strings contain characters
+ from national alphabets. Non-english users
+ definitely need that. If you won't use locale stuff just undefine
+ the USE_LOCALE variable.
+ </para>
+ </sect2>
+
+ <Sect2>
+ <Title>What are the Drawbacks?</Title>
+
+ <Para>
+ There is one evident drawback of using locale - it's speed!
+ So, use locale only if you really need it.
+ </para>
+ </sect2>
+ </sect1>
+
+ <Sect1>
+ <Title>Kerberos Authentication</Title>
+
+ <Para>
+ <productname>Kerberos</productname> is an industry-standard secure authentication
+ system suitable for distributed computing over a public network.
+ </para>
+
+ <sect2>
+ <title>Availability</title>
+
+ <para>
+ 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>
+
+ <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>
+ <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>
+ expects to find the associated libraries, header files and its own
+ server key file.
+ </para>
+ <para>
+ After compilation is complete, <Productname>Postgres</Productname>
+ must be registered as a <productname>Kerberos</productname>
+ service. See the
+ <citetitle>Kerberos Operations Notes</citetitle>
+ and related manual pages for more details on registering services.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Operation</title>
+
+ <para>
+ After initial installation, <Productname>Postgres</Productname>
+ should operate in all ways as a normal
+ <productname>Kerberos</productname>
+ service. For details on the use of authentication, see the
+ <citetitle>PostgreSQL User's Guide</citetitle> reference sections
+ for <application>postmaster</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:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ User principal names (anames) are assumed to
+ contain the actual Unix/<Productname>Postgres</Productname> user name
+ in the first component.
+ </para>
+ </listitem>
+ <listitem>
+ <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
+ suffixes removed).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ <para>
+ <table tocentry="1">
+ <title>Kerberos Parameter Examples</title>
+ <titleabbrev>Kerberos</titleabbrev>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ Parameter
+ </entry>
+ <entry>
+ Example
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ user
+ </entry>
+ <entry>
+ frew@S2K.ORG
+ </entry>
+ </row>
+ <row>
+ <entry>
+ user
+ </entry>
+ <entry>
+ aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
+ </entry>
+ </row>
+ <row>
+ <entry>
+ host
+ </entry>
+ <entry>
+ postgres_dbms/ucbvax@S2K.ORG
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ Support for Version 4 will disappear sometime after the production
+ release of Version 5 by MIT.
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
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
for the <citetitle>Programmer's Guide</citetitle>.
-
+</para>
+</listitem>
<listitem>
<para>
Jan also contributed a second procedural language, PL/pgSQL, to go with the
original PL/pgTCL procedural language he contributed last release.
+</para>
+</listitem>
<listitem>
<para>
We have optional multiple-byte character set support from Tatsuo Iishi
to complement our existing locale support.
+</para>
+</listitem>
<listitem>
<para>
Client/server communications has been cleaned up, with better support for
asynchronous messages and interrupts thanks to Tom Lane.
+</para>
+</listitem>
<listitem>
<para>
the type extensibility features of <productname>Postgres</productname>.
There is a new chapter in the <citetitle>User's Guide</citetitle>
which covers this topic.
+</para>
+</listitem>
<listitem>
<para>
in the <citetitle>User's Guide</citetitle> for details.
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.
+</para>
+</listitem>
<listitem>
<para>
Several more <acronym>SQL92</acronym>-compatible syntax features have been
added, including <command>INSERT DEFAULT VALUES</command>
+</para>
+</listitem>
<listitem>
<para>
The automatic configuration and installation system has received some
attention, and should be more robust for more platforms than it has ever
been.
+</para>
+</listitem>
</itemizedlist>
-
+</para>
<sect2>
<title>Migration to v6.4</title>
or <application>pg_dumpall</application>
is required for those wishing to migrate data from any
previous release of <productname>Postgres</productname>.
-
-
+</para>
+</sect2>
<sect2>
<title>Detailed Change List</title>
new Makefile.shlib for shared library configuration(Tom)
</programlisting>
</Para>
-
+</sect2>
</Sect1>
postprocessed a bit before it can be loaded into <ProductName>Postgres</ProductName>. We
hope that the large increase in speed and reliability will
make up for the slight decrease in convenience.
-<Para>
+</para>
</Tip>
- You should expect to read (and reread, and re-reread) the
+</para>
+<para>
+ You should expect to read (and reread, and re-reread) the
manual pages for the C compiler, cc(1), and the link
editor, ld(1), if you have specific questions. In
addition, the regression test suites in the directory
</Para>
</ListItem>
</ItemizedList>
+</para>
<Sect1>
<Title><Acronym>ULTRIX</Acronym></Title>
<!--
-$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
Thomas Lockhart
$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
Include more details on editing with Emacs.
Remove mention of the old "migration" flat files.
It should be able to answer
common questions and to allow a user to find those answers on his own
without resorting to mailing list support.
+</para>
<sect1>
<title>Documentation Roadmap</title>
<acronym>man pages</acronym>, for quick reference.
</para></listitem>
</itemizedlist>
+</para>
<para>
<table tocentry="1">
</tbody>
</tgroup>
</table>
+</para>
<para>
There are man pages available for installation, as well as a large number
of plain-text README-type files throughout the <productname>Postgres</productname>
source tree.
+</para>
+</sect1>
<sect1>
<title>The Documentation Project</title>
<productname>Postgres</productname> installation. We discuss here
working with the documentation sources and generating documentation
packages.
+</para>
<para>
The purpose of <productname>DocBook</productname> <acronym>SGML</acronym>
final form (e.g. using Norm Walsh's
<productname>Modular Style Sheets</productname>).</para>
+
<para>
See <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">
Introduction to DocBook</ulink> for a nice "quickstart" summary of
<ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/"> DocBook Elements</ulink>
provides a powerful cross-reference for features of
<productname>DocBook</productname>.
+</para>
<para>
This documentation set is constructed using several tools, including
<ulink url="http://www.jclark.com/jade/"> <productname>jade</productname></ulink>
and Norm Walsh's
<ulink url="http://www.berkshire.net/~norm/docbook/dsssl">Modular DocBook Stylesheets</ulink>.
+</para>
<para>
Currently, hardcopy is produced by importing <firstterm>Rich Text
<productname>ApplixWare</productname> for minor formatting fixups then
exporting as a Postscript file.</para>
+
<para>
<ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/">
<productname>TeX</productname></ulink> is a supported format for
support in the <productname>TeX</productname>
stylesheets.</para>
+</sect1>
+
<sect1>
<title>Documentation Sources</title>
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
+</para>
<para>
The purpose of <acronym>SGML</acronym> is to allow an author to
<productname>DocBook</productname> <acronym>DTD</acronym>), and to
have the document style define how that content is rendered into a
final form (e.g. using Norm Walsh's stylesheets).
+</para>
<para>
Documentation has accumulated from several sources. As we integrate
distribution. However, this will not happen immediately, and will not
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.
+</para>
<para>
Here is the documentation plan for v6.5:
<listitem>
<para>
Start compiling index information for the User's and Administrator's Guides.
+</para>
+</listitem>
<listitem>
<para>
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
design problems.
+</para>
+</listitem>
<listitem>
<para>
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
primary doc set.
+</para>
+</listitem>
<listitem>
<para>
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
+</para>
+</listitem>
<listitem>
<para>
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
available in .gif and .ps, and should be redrawn or removed.
+</para>
+</listitem>
</itemizedlist>
+</para>
<sect2>
<title>Document Structure</title>
</listitem>
</varlistentry>
</variablelist>
+</para>
<!--
Disable for the hardcopy production release.
Too much tabular info and not very helpful in hardcopy.
- thomas 1998-10-27
-->
+</sect2>
<sect2>
<title>Documentation Files</title>
</tbody>
</tgroup>
</table>
+</para>
+</sect2>
<sect2>
<title>Document Conversion</title>
</tbody>
</tgroup>
</table>
-
+</para>
+</sect2>
<sect2>
<title>Styles and Conventions</title>
</table>
</para>
-->
+</sect2>
<sect2>
<title>SGML Authoring Tools</title>
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
<acronym>SGML</acronym> DocBook tags.
+</para>
<para>
<acronym>SGML</acronym> and <productname>DocBook</productname> do not suffer
from an oversupply of open-source authoring tools. The most common toolset is
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.
+</para>
<sect3>
<title>emacs/psgml</title>
an <acronym>SGML</acronym> <firstterm>major mode</firstterm>. When properly configured,
this will allow you to use <application>emacs</application> to insert tags and
check markup consistancy.
+</para>
<para>
Put the following in your <filename>~/.emacs</filename> environment file:
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
---<sgmltag>
+--</sgmltag>
</programlisting>
+</para>
<para>
The <productname>Postgres</productname> distribution includes a
parsed DTD definitions file <filename>reference.ced</filename>.
You may find that
+</para>
<para>
When using <application>emacs</application>/psgml, a comfortable way of working with
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".
+</para>
</sect3>
</sect2>
<filename>/usr/share/lib/sgml/</filename>,
or
<filename>/usr/local/lib/sgml/</filename>.
+</para>
<para>
<acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by
importing into <productname>ApplixWare-4.4.1</productname>.
After a little cleanup (see the following
section) the output is "printed" to a postscript file.
+</para>
<para>
Some figures were redrawn to avoid having bitmap
these tools. <productname>FreeBSD</productname> seems to have them
available. Please report package status to the docs mailing list and
we will include that information here.
+</para>
<sect2>
<title><acronym>RPM</acronym> installation on
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 <acronym>RTF</acronym>.
+</para>
<para>
These instructions do not cover new <application>jade</application>/DocBook
<ulink url="http://www.sgmltools.org/"><productname>sgml-tools</productname></ulink>
package. The authors have not tried this package since it adopted DocBook,
but it is almost certainly a good candidate for use.
+</para>
<sect3><title>Prerequisites</title>
<listitem><para><ulink url="http://www.sil.org/sgml/publicSW.html">
Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
</itemizedlist>
+</para>
</sect3>
<sect3>
<title>Installing Jade</title>
-<para>
<procedure>
<title>Installing Jade</title>
<para>
Read the installation instructions at the above listed
URL.
+</para>
+</step>
<step performance="required">
<para>
unzip -aU jade1_1.zip
</programlisting>
</para>
+</step>
<step performance="required">
<para><productname>Jade</productname> is not built using
<command>ranlib</command> command, leave them as they are in the
<filename>Makefile</filename>.
</para>
+</step>
<step performance="required">
<para>Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para>
+</step>
<step performance="required">
<para>Once the software is built, <command>make install</command> will
do the obvious.</para>
-
+</step>
</procedure>
+</sect3>
<sect3>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
-<para>
<procedure>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<programlisting>
CATALOG /usr/local/share/sgml/CATALOG
</programlisting>
+</para>
+</step>
<step performance="required">
<para>
PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
</programlisting>
+</para>
+</step>
<step performance="required">
<para>
named <filename>ISO</filename>. Again, proper catalog entries should
accompany the entity kit you fetch.
</para>
+</step>
</procedure>
+</sect3>
<sect3>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
-<para>
<procedure>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<step performance="required">
<para>Read the installation instructions at the above listed
URL.</para>
+</step>
<step performance="required">
<para>To install Norman's style sheets, simply unzip the distribution
unzip -aU db119.zip
</programlisting>
</para>
+</step>
<step performance="required">
<para>One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
<citetitle><productname>PostgreSQL</productname> User's Guide</citetitle>.
+</para>
<substeps>
<programlisting>
jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
+</para>
<para>
<filename>book1.htm</filename> is the top level node of the output..
+</para>
+</step>
<step performance="required">
<para>
<programlisting>
jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
+</para>
+</step>
</substeps>
+</step>
</procedure>
+</sect3>
<sect3>
<title>Installing <productname>PSGML</productname></title>
-<para>
<procedure>
<title>Installing <productname>PSGML</productname></title>
<step performance="required">
<para>Read the installation instructions at the above listed
URL.</para>
+</step>
<step performance="required">
<para>Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place.
+</para>
+</step>
<step performance="required" id="psgml-setup">
<para>
(cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
</programlisting>
+</para>
+</step>
<step performance="optional">
<para>
(cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
</programlisting>
</para>
-
+</step>
<step performance="optional">
<para>There is one important thing to note with
<filename>/usr/local/lib/sgml</filename>. If, as in the examples in
this chapter, you use <filename>/usr/local/share/sgml</filename>, you
have to compensate for this.
+</para>
<substeps>
<step performance="optional">
<para>
You can set the
<filename>SGML_CATALOG_FILES</filename> environment variable.
+</para>
+</step>
<step performance="optional">
<para>
You can
customize your <productname>PSGML</productname> installation (its
manual tells you how).
+</para>
+</step>
<step performance="optional">
<para>
<filename>psgml.el</filename> before compiling and installing
<productname>PSGML</productname>, changing the hard-coded paths to
match your own default.</para>
+</step>
</substeps>
+</step>
</procedure>
+</sect3>
<sect3><title>Installing <productname>JadeTeX</productname></title>
and <productname>DocBook</productname>. It may be the preferred toolset
for working with <acronym>SGML</acronym> but we have not had a chance to
evaluate the new package.
+</para>
<!--
</para></sect2></sect1>
-->
-
+</sect1>
</appendix>
<!-- Keep this comment at the end of the file
to copy and use the rest of the <ProductName>PostgreSQL</ProductName>.
</Para>
</Note>
-
+</para>
<Sect1>
<Title>Why Embedded <Acronym>SQL</Acronym>?</Title>
from variables in your <Acronym>C</Acronym> program.
Many <Acronym>RDBMS</Acronym> packages
support this embedded language.
+</Para>
<Para> There is an ANSI-standard describing how the embedded language should
work. <Application>ecpg</Application> was designed to meet this standard
other <Acronym>RDBMS</Acronym> packages to
<ProductName>Postgres</ProductName> and thus promoting the spirit of free
software.
-
+</Para>
+</sect1>
<Sect1>
<Title>The Concept</Title>
<Acronym>SQL</Acronym> statements you need to
put them in a special declare section.
You use a special syntax for the <Acronym>SQL</Acronym> queries.
+</Para>
<Para>
Before compiling you run the file through
as input to the <Acronym>SQL</Acronym> statements and variables that will
contain the
result are passed.
+</Para>
<Para>
Then you compile and at link time you link with a special library that
the <Acronym>SQL</Acronym> query using the ordinary interface
(<FileName>libpq</FileName>) and puts back
the result in the arguments dedicated for output.
+</Para>
<Para>
Then you run your program and when the control arrives to
statement the <Acronym>SQL</Acronym> statement is performed against
the database and you
can continue with the result.
-
+</Para>
+</sect1>
<Sect1>
<Title>How To Use <Application>egpc</Application></Title>
<Para>
This section describes how to use the <Application>egpc</Application> tool.
+</Para>
<Sect2>
-<Title>Preprocessor
+<Title>Preprocessor</title>
<Para>
The preprocessor is called <Application>ecpg</Application>.
After installation it resides in
the <ProductName>Postgres</ProductName> <FileName>bin/</FileName> directory.
-
+</Para>
+</sect2>
<Sect2>
-<Title>Library
+<Title>Library</title>
<Para>
The <Application>ecpg</Application> library is called
uses the <FileName>libpq</FileName> library for communication to the
<ProductName>Postgres</ProductName> server so you will
have to link your program with <Parameter>-lecpg -lpq</Parameter>.
+</Para>
<Para>
The library has some methods that are "hidden" but that could prove very
turns on debug logging if called with the first argument non-zero.
Debug logging is done on <replaceable class="parameter">stream</replaceable>.
Most <Acronym>SQL</Acronym> statement logs its arguments and result.
+</Para>
<Para>
The most important one (<Function>ECPGdo</Function>)
</Para>
</ListItem>
</itemizedlist>
+</Para>
+</sect2>
<Sect2>
-<Title>Error handling
+<Title>Error handling</title>
<Para>
To be able to detect errors from the <ProductName>Postgres</ProductName>
} sqlerrm;
} sqlca;
</ProgramListing>
+</Para>
<Para>
If an error occured in the last <Acronym>SQL</Acronym> statement
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 table did not contain the requested row.
+</Para>
<Para>
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
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.)
+</Para>
<Para>
List of errors that can occur:
</ListItem>
</VarListEntry>
</VariableList>
-
+</Para>
</Sect2>
+</sect1>
<Sect1>
<Title>Limitations</Title>
client process per application process both the database part and the
application part is run in the same process. In later versions of oracle
this is no longer supported.
+</Para>
<Para>
This would require a total redesign of the <ProductName>Postgres</ProductName> access model and
</ListItem>
</VarListEntry>
</VariableList>
+</Para>
+</sect1>
<Sect1>
<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title>
To be written by someone who knows the different
<Acronym>RDBMS</Acronym> packages and who
actually does port something...
+</Para>
+</sect1>
<Sect1>
<Title>Installation</Title>
together with <ProductName>Postgres</ProductName>. So you
should get your precompiler, libraries and header files compiled and
installed by default as a part of your installation.
+</Para>
+</sect1>
<Sect1>
<Title>For the Developer</Title>
So, read this before looking at the internals of the
<Application>ecpg</Application>. If
you are not interested in how it really works, skip this section.
+</Para>
<Sect2>
<Title>ToDo List</Title>
<ListItem>
<Para>
Records or structures have to be defined in the declare section.
-
+</Para>
</ListItem>
</VarListEntry>
<Term> exec sql type</Term>
<ListItem>
<Para>
+</Para>
+</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql prepare</Term>
<ListItem>
<Para>
+</Para>
+</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql allocate</Term>
<ListItem>
<Para>
+</Para>
+</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql free</Term>
<ListItem>
<Para>
+</Para>
+</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql whenever sqlwarning</Term>
<ListItem>
<Para>
+</Para>
+</listitem>
</VarListEntry>
<VarListEntry>
<Term> SQLSTATE</Term>
<ListItem>
<Para>
+</Para>
+</listitem>
</VarListEntry>
</VariableList>
</Para>
other configuration parameters. If you have these scripts for an old
database you would like to just apply them to get a
<ProductName>Postgres</ProductName> database that works in the same way.
+</Para>
<Para>
To set up a database you need a few scripts with table definitions and
</ListItem>
</VarListEntry>
</VariableList>
+</Para>
+</sect2>
<Sect2>
<Title>The Preprocessor</Title>
<Para>
First four lines are written to the output. Two comments and two include
lines necessary for the interface to the library.
+</Para>
<Para>
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
everything to the output without looking at it further.
+</Para>
<Para>
When it comes to an <Command>EXEC SQL</Command> statements it interviens and
In the section only variable declarations are allowed. Every variable
declare within this section is also entered in a list of variables
indexed on their name together with the corresponding type.
+</Para>
<Para>
The declaration is echoed to the file to make the variable a normal
C-variable also.
+</Para>
<Para>
The special types VARCHAR and VARCHAR2 are converted into a named struct
<Command>exec sql</Command> and ends with <Command>;</Command>.
Everything inbetween is treated
as an <Acronym>SQL</Acronym> statement and parsed for variable substitution.
+</Para>
<Para>
Variable substitution occur when a symbol starts with a colon
a variable for input or
output the pointers to the variables are written to the output to allow
for access by the function.
+</Para>
<Para>
For every variable that is part of the <Acronym>SQL</Acronym> request
<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>
</SimpleList>
+</Para>
<Para>
Since the array fetches are not implemented yet the two last arguments
</ListItem>
</VarListEntry>
</VariableList>
-
+</Para>
</Sect2>
<Sect2>
</ProgramListing>
(the indentation in this manual is added for readability and not
something that the preprocessor can do.)
+</Para>
+</sect2>
<Sect2>
<Title>The Library</Title>
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
arguments.
+</Para>
<Para>
The arguments are:
</ListItem>
</VarListEntry>
</VariableList>
+</Para>
<Para>
All the <Acronym>SQL</Acronym> statements are performed in one transaction
unless you issue
a commit transaction. This works so that the first transaction or the
first after a commit or rollback always begins a transaction.
+</Para>
<Para>
To be completed: entries describing the other entries.
-
+</Para>
+</sect2>
+</sect1>
</Chapter>
and will be described in depth (in the section
on interfacing types and operators to indices)
after we have discussed basic extensions.
+</para>
</ListItem>
</ItemizedList>
</Para>
+</sect1>
</Chapter>
</TGROUP>
</TABLE>
</Para>
+</sect1>
<sect1>
<title>String Functions</title>
<para>
Most functions explicitly defined for text will work for char() and varchar() arguments.
</para>
+</sect1>
<sect1>
<title>Date/Time Functions</title>
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>).
</Para>
+</sect1>
<sect1>
<title>Geometric Functions</title>
</TGROUP>
</TABLE>
</Para>
+</sect1>
<sect1>
<title id="cidr-funcs">IP V4 Functions</title>
<!--
-$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
$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
Change Id field in chapter tag to change html output file name.
for the Institute of Automatic Control at the University of Mining and Technology in Freiberg, Germany.
</Para>
</Note>
+</para>
<Sect1>
<Title>Query Handling as a Complex Optimization Problem</Title>
(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,
b-tree, hash in <ProductName>Postgres</ProductName>) as access paths for relations.
+</para>
<Para>
The current <ProductName>Postgres</ProductName> optimizer implementation performs a <FirstTerm>near-
optimization technique is inadequate to support database application
domains that involve the need for extensive queries, such as artificial
intelligence.
+</para>
<Para>
The Institute of Automatic Control at the University of Mining and
support knowledge based system for the maintenance of an electrical
power grid. The DBMS needed to handle large <Command>join</Command> queries for the
inference machine of the knowledge based system.
+</para>
<Para>
Performance difficulties within exploring the space of possible query
plans arose the demand for a new optimization technique being developed.
+</para>
<Para>
In the following we propose the implementation of a <FirstTerm>Genetic Algorithm</FirstTerm>
as an option for the database query optimization problem.
-
+</para>
+</sect1>
<Sect1>
<Title>Genetic Algorithms (<Acronym>GA</Acronym>)</Title>
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
by its <FirstTerm>fitness</FirstTerm>.
+</para>
<Para>
The coordinates of an individual in the search space are represented
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
<FirstTerm>integer</FirstTerm>.
+</para>
<Para>
Through simulation of the evolutionary operations <FirstTerm>recombination</FirstTerm>,
<FirstTerm>mutation</FirstTerm>, and <FirstTerm>selection</FirstTerm> new generations of search points are found
that show a higher average fitness than their ancestors.
+</para>
<Para>
According to the "comp.ai.genetic" <Acronym>FAQ</Acronym> it cannot be stressed too
| | t := t + 1 |
+===+=====================================+
</ProgramListing>
+</para>
+</sect1>
<Sect1>
<Title>Genetic Query Optimization (<Acronym>GEQO</Acronym>) in Postgres</Title>
is encoded by the integer string '4-1-3-2',
which means, first join relation '4' and '1', then '3', and
then '2', where 1, 2, 3, 4 are relids in <ProductName>Postgres</ProductName>.
+</para>
<Para>
Parts of the <Acronym>GEQO</Acronym> module are adapted from D. Whitley's Genitor
algorithm.
+</para>
<Para>
Specific characteristics of the <Acronym>GEQO</Acronym> implementation in <ProductName>Postgres</ProductName>
</Para>
</ListItem>
</ItemizedList>
+</para>
<Para>
The <Acronym>GEQO</Acronym> module gives the following benefits to the <ProductName>Postgres</ProductName> DBMS
</Para>
</ListItem>
</ItemizedList>
+</para>
</Sect1>
<Function>OrderedElemPop</Function>, file <FileName>backend/utils/mmgr/oset.c</FileName>.
The same problems arise with long queries when using the normal
<ProductName>Postgres</ProductName> query optimization algorithm.
+</para>
+</sect3>
<Sect3>
<Title>Improve genetic algorithm parameter settings</Title>
</Para>
</ListItem>
</ItemizedList>
+</para>
+</sect3>
<Sect3>
<Title>Find better solution for integer overflow</Title>
value of <StructField>rel->size</StructField> to its logarithm.
Modifications of <StructName>Rel</StructName> in <FileName>backend/nodes/relation.h</FileName> will
surely have severe impacts on the whole <ProductName>Postgres</ProductName> implementation.
+</para>
+</sect3>
<Sect3>
<Title>Find solution for exhausted memory</Title>
Of course the <StructName>rel</StructName> data structure of the <Command>join</Command> keeps growing and
growing the more relations are packed into it.
Suggestions are welcome :-(
-
+</para>
+</sect3>
+</sect2>
<Sect2>
<Title>Further Improvements</Title>
<Para>
Enable bushy query tree processing within <ProductName>Postgres</ProductName>;
that may improve the quality of query plans.
+</para>
<BIBLIOGRAPHY Id="geqo-biblio">
<TITLE>
</BIBLIOENTRY>
</BIBLIOGRAPHY>
+</sect2>
+</sect1>
</Chapter>
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>.
-
+</para>
<Para>
<Note>
- thomas 1998-03-01
</Para>
</Note>
-
+</para>
<Para>
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
method is already in the postgres tree (<FileName>src/backend/access/gist</FileName>).
-
+</para>
<Para>
<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
(PostgreSQL 6.3 Sun Feb 1 14:57:30 EST 1998)
</ProgramListing>
-
+</para>
<Para>
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
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
to hold it up while there are so many competent people around.
-
+</para>
<Para>
A few notes on the sources:
-
+</para>
<Para>
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
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
more portable that the original makefile.
-
+</para>
<Para>
2. I built the example sources right under pgsql/src (just extracted the
tar file there). The aforementioned Makefile assumes it is one level
below pgsql/src (in our case, in pgsql/src/pggist).
-
+</para>
<Para>
3. The changes I made to the *.c files were all about #include's,
function prototypes and typecasting. Other than that, I just threw
away a bunch of unused vars and added a couple parentheses to please
gcc. I hope I did not screw up too much :)
-
+</para>
<Para>
4. There is a comment in polyproc.sql:
<ProductName>Postgres</ProductName> versions
back and tried the query. My system went nuts and I had to shoot down
the postmaster in about ten minutes.
-
+</para>
<Para>
I will continue to look into GiST for a while, but I would also
appreciate
more examples of R-tree usage.
-
+</para>
</Chapter>
was reset to start at 6.0,
putting the numbers back into the sequence originally begun by
the <ProductName>Postgres</ProductName> Project.
+</Para>
<Para>
The emphasis on development for the v1.0.x releases of
identifying and understanding existing problems in the backend
to augmenting features and capabilities, although
work continues in all areas.
+</Para>
<Para>
Major enhancements include:
+</Para>
<ItemizedList>
<ListItem>
Built-in types have been improved, including new wide-range date/time types
and additional geometric type support.
</Para>
+
</ListItem>
<ListItem>
<Para>
</Para>
</ListItem>
</ItemizedList>
-</Para>
</Sect2>
-</sect1>
\ No newline at end of file
+</sect1>
<Para>
This manual set is organized into several parts:
+</Para>
<VariableList>
<VarListEntry>
<Para>
In addition to this manual set, there are other resources to help you with
<ProductName>Postgres</ProductName> installation and use:
+</Para>
<VariableList>
<VarListEntry>
|Mariposa | 1953 |
+----------+----------+
</ProgramListing>
+</para>
<Para>
On the other hand, to find the names of all cities,
</Para>
</ListItem>
</ItemizedList>
-
+</para>
<Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands
In general, most Unix-compatible
platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>.
-
+</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
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
running X-Windows.
The rule is you can never have too much memory.
-
+</para>
<Para>
Check that you have sufficient disk space. You will need about
30 Mbytes for <filename>/usr/src/pgsql</filename>,
<programlisting>
$ df -k
</programlisting>
-
+</para>
</Sect1>
<Sect1>
<Title>Installation Procedure</Title>
-<Para>
<Procedure>
<Title><ProductName>Postgres</ProductName> Installation</Title>
<Para>
Create the <ProductName>Postgres</ProductName> superuser account
(<literal>postgres</literal> is commonly used) if it does not already exist.
-
+</para>
<para>
The owner of the Postgres files can be any unprivileged user account.
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.
-
+</para>
</Step>
<Step Performance="required">
<Para>
Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the
remaining steps in the installation will happen in this account.
-
+</para>
+</step>
<Step Performance="required">
<Para>
Ftp file
in the HACKERS mailing list. Full releases always require a dump/reload
from previous releases. It is therefore a bad idea to skip this
step.
-
+</para>
<tip>
<para>
Do not use the <application>pg_dumpall</application>
script from v6.0 or everything
will be owned by the <ProductName>Postgres</ProductName> super user.
+</para>
</tip>
<para>
<programlisting>
$ pg_dumpall -z > db.out
</programlisting>
-
+</para>
<para>
To use the latest <application>pg_dumpall</application> script on your
existing older database before upgrading <productname>Postgres</productname>,
$ /etc/rc.d/init.d/postgres.init stop
</programlisting>
to halt <productname>Postgres</productname>.
+</para>
</tip>
</Para>
</Step>
<Para>
Make new source and install directories. The actual paths can be
different for your installation but you must be consistant throughout this procedure.
+</para>
<note>
<para>
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.
Usually it is sufficient to specify these at the <command>make install</command> stage
of installation.
+</para>
</note>
<para>
send email to
<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.
+</para>
</note>
</Para>
-
+</step>
<Step Performance="optional">
<Para>
Choose configuration options. Check <xref linkend="config" endterm="install-config">
present.)
</ProgramListing>
</Para>
-
+</step>
<Step Performance="required">
<Para>
Here is the configure script used on a Sparc Solaris 2.5 system
<para>
Of course, you may type these three lines all
on the same line.
+</para>
</tip>
</Para>
</Step>
</substeps>
-
+</step>
<Step Performance="required">
<Para>
Install the <application>man</application> and
$ cd /usr/src/pgsql/doc
$ gmake install
</ProgramListing>
-
+</para>
<para>
The documentation is also available in Postscript format. Look for files
ending with <filename>.ps.gz</filename> in the same directory.
-
+</para>
+</step>
<Step Performance="required">
<Para>
Compile the program. Type
You will probably find a number of warning
messages in make.log. Unless you have problems later on, these
messages may be safely ignored.
+</para>
</note>
-
+</para>
<Para>
If the compiler fails with a message stating that
the <application>flex</application> command
<Para>
If necessary, tell your system how to find the new shared libraries. You can
do <emphasis>one</emphasis> of the following, preferably the first:
-
+</para>
<SubSteps>
<Step Performance="optional">
<Para>
<ProgramListing>
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</ProgramListing>
+</para>
</Step>
</SubSteps>
</Para>
</Step>
-<Step Performance="optional">
-<Para>
-If you used the <option>--with-perl</option> option to configure, check
-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
-an unprivileged userid, then the Perl module won't have been installed,
-for lack of write privileges on the Perl library directories. You can
-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
-<ProgramListing>
-$ cd /usr/src/pgsql/src/interfaces/perl5
-$ gmake install
-</ProgramListing>
-</Para>
-</Step>
-
-<Step Performance="required">
-<Para>
- If it has not already been done, then prepare account <literal>postgres</literal>
+ <Step Performance="optional">
+ If you used the <option>--with-perl</option> option to configure, check
+ 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
+ an unprivileged userid, then the Perl module won't have been installed,
+ for lack of write privileges on the Perl library directories. You can
+ 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
+ $ cd /usr/src/pgsql/src/interfaces/perl5
+ $ gmake install
+ </ProgramListing>
+ </Para>
+ </Step>
+
+ <Step Performance="required">
+ If it has not already been done, then prepare account <literal>postgres</literal>
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.
-
-<para>
-There are several ways to influence the runtime environment of the
- <ProductName>Postgres</ProductName>
-server. Refer to the <citetitle>Administrator's Guide</citetitle>
- for more information.
-
-<note>
-<para>
-The following instructions are for a
- bash/sh shell. Adapt accordingly for other shells.
-</note>
-
-</Para>
-
-<substeps>
-
-<Step Performance="required">
-<Para>
- Add the following lines to your login environment:
-
- shell, <filename>~/.bash_profile</filename>:
-<ProgramListing>
-PATH=$PATH:/usr/local/pgsql/bin
-MANPATH=$MANPATH:/usr/local/pgsql/man
-PGLIB=/usr/local/pgsql/lib
-PGDATA=/usr/local/pgsql/data
-export PATH MANPATH PGLIB PGDATA
-</ProgramListing>
-</Para>
-
-<Step Performance="required">
-<para>
-Several regression tests could failed if the user's locale collation
-scheme is different from that of standard C locale.
-
-<para>
-If you configure and compile <ProductName>Postgres</ProductName>
- with the <option>--enable-locale</option> option then
- set locale environment to C (or unset all LC_* variables)
-by putting these additional lines to your login environment
- before starting postmaster:
-<ProgramListing>
-LC_COLLATE=C
-LC_CTYPE=C
-LC_COLLATE=C
-export LC_COLLATE LC_CTYPE LC_COLLATE
-</ProgramListing>
-
-<ProgramListing>
-
-</ProgramListing>
-
-
-<Step Performance="required">
-<Para>
- Make sure that you have defined these variables before continuing
- with the remaining steps. The easiest way to do this is to type:
-<ProgramListing>
-$ source ~/.bash_profile
-</ProgramListing>
-</Para>
-</Step>
-
-</substeps>
+ </para>
+ <para>
+ There are several ways to influence the runtime environment of the
+ <ProductName>Postgres</ProductName>
+ server. Refer to the <citetitle>Administrator's Guide</citetitle>
+ for more information.
+ <note>
+ <para>
+ The following instructions are for a
+ bash/sh shell. Adapt accordingly for other shells.
+ </para>
+ </note>
+ </Para>
+
+ <substeps>
+
+ <Step Performance="required">
+ <Para>
+ Add the following lines to your login environment:
+
+ shell, <filename>~/.bash_profile</filename>:
+ <ProgramListing>
+ PATH=$PATH:/usr/local/pgsql/bin
+ MANPATH=$MANPATH:/usr/local/pgsql/man
+ PGLIB=/usr/local/pgsql/lib
+ PGDATA=/usr/local/pgsql/data
+ export PATH MANPATH PGLIB PGDATA
+ </ProgramListing>
+ </Para>
+ </step>
+ <Step Performance="required">
+ <para>
+ Several regression tests could failed if the user's locale collation
+ scheme is different from that of standard C locale.
+ </para>
+ <para>
+ If you configure and compile <ProductName>Postgres</ProductName>
+ with the <option>--enable-locale</option> option then
+ set locale environment to C (or unset all LC_* variables)
+ by putting these additional lines to your login environment
+ before starting postmaster:
+ <ProgramListing>
+ LC_COLLATE=C
+ LC_CTYPE=C
+ LC_COLLATE=C
+ export LC_COLLATE LC_CTYPE LC_COLLATE
+ </ProgramListing>
+
+ <ProgramListing>
+
+ </ProgramListing>
+ </para>
+ </step>
+
+ <Step Performance="required">
+ <Para>
+ Make sure that you have defined these variables before continuing
+ with the remaining steps. The easiest way to do this is to type:
+ <ProgramListing>
+ $ source ~/.bash_profile
+ </ProgramListing>
+ </Para>
+ </Step>
+
+ </substeps>
+ </step>
<Step Performance="required">
<Para>
<para>
Briefly test that the backend will start and run by running it from
the command line.
-
+</para>
<substeps>
<Step Performance="required">
<ProgramListing>
$ createdb
</ProgramListing>
-
+</para>
+</step>
<Step Performance="required">
<para>
Connect to the new database:
<ProgramListing>
$ psql
</ProgramListing>
-
+</para>
+</step>
<Step Performance="required">
<para>
And run a sample query:
<ProgramListing>
postgres=> SELECT datetime 'now';
</ProgramListing>
-
+</para>
+</step>
<Step Performance="required">
<para>
Exit <application>psql</application>:
<ProgramListing>
postgres=> \q
</ProgramListing>
-
+</para>
+</step>
<Step Performance="required">
<para>
Remove the test database (unless you will want to use it later for other tests):
<ProgramListing>
$ destroydb
</ProgramListing>
-
+</para>
+</step>
</substeps>
-
+</step>
<Step Performance="required">
<Para>
Run postmaster in the background from your <ProductName>Postgres</ProductName>
superuser account (typically account <literal>postgres</literal>).
<emphasis>Do not run <application>postmaster</application>
from the root account!</emphasis>
-
+</para>
<Para>
Usually, you will want to modify
your computer so that it will automatically start postmaster whenever
it boots. It is not required; the <ProductName>Postgres</ProductName>
server can
be run successfully from non-privileged accounts without root intervention.
-
+</para>
<para>
Here are some suggestions on how to do this, contributed by various
users.
-
+</para>
<para>
Whatever you do, postmaster must be run by
the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
$ cd
$ nohup postmaster > regress.log 2>&1 &
</ProgramListing>
-
+</para>
+</listitem>
<listitem>
<para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
<programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>
+</para>
+</listitem>
<listitem>
<para>
enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under
the postmaster process so the parent is init.
+</para>
+</listitem>
<listitem>
<para>
which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from
<filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
+</para>
+</listitem>
<listitem>
<para>
(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
effects.)
+</para>
+</listitem>
</itemizedlist>
For a i686/Linux-ELF platform, no tests failed since this is the
v6.4 regression testing reference platform.
</Para>
+</listitem>
<listitem>
<Para>
floating point numbers. select_views produces massively different output,
but the differences are due to minor floating point differences.
</Para>
-</itemizedlist>
+</listitem>
+</itemizedlist>
+</para>
<Para>
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
</Step>
</substeps>
-
+</step>
<Step Performance="required">
<Para>
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
done at regular intervals:
-
+</para>
<procedure>
<title>Minimal Backup Procedure</title>
<para>
Run the <acronym>SQL</acronym> command <command>VACUUM</command>.
This will clean up your database.
-
+</para>
+</step>
<step performance="required">
<para>
Back up your system. (You should probably keep the last few
backups on hand.) Preferably, no one else should be using the
system at the time.
-
+</para>
+</step>
</procedure>
<para>
$ cd /usr/local/pgsql/doc
$ gunzip user.ps.tz | lpr
</programlisting>
-
+</para>
<para>
Here is how
you might do it if you have Ghostscript on your system and are
$ gzip user.ps
$ lpr -l -s -r manpage.hp
</programlisting>
-
+</para>
</Step>
<Step Performance="required">
<listitem>
<para>
The version of <ProductName>Postgres</ProductName> (v6.4, 6.3.2, beta 981014, etc.).
+</para>
+</listitem>
<listitem>
<para>
Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
+</para>
+</listitem>
<listitem>
<para>
Your hardware (SPARC, i486, etc.).
+</para>
+</listitem>
<listitem>
<para>
applied, changes you made, etc.), what tests failed, etc.
It is normal to get many warning when you compile. You do
not need to report these.
+</para>
+</listitem>
</itemizedlist>
</Para>
</Step>
</Procedure>
+</sect1>
<Sect1>
<Title>Playing with <ProductName>Postgres</ProductName></Title>
</Para>
</Note>
-<Sect2>
-<Title>Ultrix4.x</Title>
-
-<para>
-<note>
-<para>
-There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
-</note>
-
-<para>
- You need to install the libdl-1.1 package since Ultrix 4.x doesn't
- have a dynamic loader. It's available in
- s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
-</Para>
-</Sect2>
-
-<Sect2>
-<Title>Linux</Title>
-
-<Sect3>
-<Sect3Info>
-<Author>
-<FirstName>Thomas G.</FirstName>
-<SurName>Lockhart</SurName>
-</Author>
-<Date>1998-02-19</Date>
-</Sect3Info>
-<Title>Linux ELF</Title>
-
-<Para>
-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.
-The linux-elf port installs cleanly. See the Linux FAQ for more details.
-</Para>
-</Sect3>
+ <Sect2>
+ <Title>Ultrix4.x</Title>
+
+ <para>
+ <note>
+ <para>
+ There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
+ </para>
+ </note>
+ </para>
+ <para>
+ You need to install the libdl-1.1 package since Ultrix 4.x doesn't
+ have a dynamic loader. It's available in
+ s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
+ </Para>
+ </Sect2>
+
+ <Sect2>
+ <Title>Linux</Title>
+
+ <Sect3>
+ <Sect3Info>
+ <Author>
+ <FirstName>Thomas G.</FirstName>
+ <SurName>Lockhart</SurName>
+ </Author>
+ <Date>1998-02-19</Date>
+ </Sect3Info>
+ <Title>Linux ELF</Title>
+
+ <Para>
+ 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.
+ The linux-elf port installs cleanly. See the Linux FAQ for more details.
+ </Para>
+ </Sect3>
<Sect3>
<Sect3Info>
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
the general public. Contact Info@RnA.nl for information.
-
+</para>
<Para>
We have no recent reports of successful NeXT installations (as of v6.2.1).
However, the client-side libraries should work even
So, although <ProductName>Postgres</ProductName> has some object-oriented features,
it is firmly in the relational database world. In fact, some commercial databases
have recently incorporated features pioneered by <ProductName>Postgres</ProductName>.
+</Para>
</Sect1>
<para>
Written by <ulink url="peter@retep.org.uk">Peter T. Mount</ulink>, the
author of the <acronym>JDBC</acronym> driver.
+</para>
</note>
+</para>
<para>
<acronym>JDBC</acronym> is a core <acronym>API</acronym> of Java 1.1 and later.
It provides a standard set of
interfaces to <acronym>SQL</acronym>-compliant databases.
+</para>
<para>
<application>Postgres</application> provides
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
protocol. Because of this, the driver is platform independent. Once compiled,
the driver can be used on any platform.
+</para>
<sect1>
<title>Building the <acronym>JDBC</acronym> Interface</title>
-<para>
-
<sect2>
<title>Compiling the Driver</title>
<programlisting>
% make
</programlisting>
+</para>
<para>
Upon completion, you will find the archive <filename>postgresql.jar</filename>
loading techniques for performance reasons,
and <application>javac</application> cannot cope.
The <filename>Makefile</filename> will generate the jar archive.
+</para>
</note>
+</para>
+</sect2>
<sect2>
<title>Installing the Driver</title>
<para>
To use the driver, the jar archive postgresql.jar needs to be included in
the CLASSPATH.
+</para>
<para>
Example:
+</para>
<para>
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
installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6.
+</para>
<para>
To run the application, I would use:
+</para>
<para>
export CLASSPATH = \
/usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:.
java uk.org.retep.finder.Main
+</para>
<para>
Loading the driver is covered later on in this chapter.
-<para>
+</para>
+</sect2>
+</sect1>
<sect1>
<title>Preparing the Database for <acronym>JDBC</acronym></title>
<para>
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
must be running with the -i flag.
+</para>
<para>
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
domain sockets. For the <acronym>JDBC</acronym> driver to connect to the same localhost, you need
to add something like:
+</para>
<para>
host all 127.0.0.1 255.255.255.255 password
+</para>
<para>
Here access to all databases are possible from the local machine
with <acronym>JDBC</acronym>.
+</para>
<para>
The <acronym>JDBC</acronym> Driver supports trust, ident,
password and crypt authentication methods.
-
-<para>
+</para>
+</sect1>
<sect1>
<title>Using the Driver</title>
<acronym>JDBC</acronym> programming, but
should help to get you started. For more information refer to the standard
<acronym>JDBC</acronym> <acronym>API</acronym> documentation.
+</para>
<para>
Also, take a look at the examples included with the source. The basic
example is used here.
-<para>
+</para>
+</sect1>
<sect1>
<title>Importing <acronym>JDBC</acronym></title>
<para>
Do not import the postgresql package. If you do, your source will not
compile, as javac will get confused.
+</para>
</important>
+</para>
+</sect1>
<sect1>
<title>Loading the Driver</title>
<para>
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.
+</para>
<para>
In the first method, your code implicitly loads the driver using the
This will load the driver, and while loading, the driver will automatically
register itself with <acronym>JDBC</acronym>.
+</para>
<para>
Note: The <function>forName()</function> method
can throw a ClassNotFoundException, so you will
need to catch it if the driver is not available.
+</para>
<para>
This is the most common method to use, but restricts your code to use just
<application>Postgres</application>.
If your code may access another database in the future, and you
don't use our extensions, then the second method is advisable.
+</para>
<para>
The second method passes the driver as a parameter to the JVM as it starts,
using the -D argument.
+</para>
<para>
Example:
<programlisting>
% java -Djdbc.drivers=postgresql.Driver example.ImageViewer
</programlisting>
+</para>
<para>
In this example, the JVM will attempt to load the driver as part of it's
initialisation. Once done, the ImageViewer is started.
+</para>
<para>
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
that would also change is the URL, which is covered next.
+</para>
<para>
One last thing. When your code then tries to open a Connection, and you get
this is probably
caused by the driver not being in the classpath, or the value in the parameter
not being correct.
+</para>
+</sect1>
<sect1>
<title>Connecting to the Database</title>
<listitem>
<para>
jdbc:postgresql:<replaceable class="parameter">database</replaceable>
+</para>
+</listitem>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
+</para>
+</listitem>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
+</para>
+</listitem>
+
</itemizedlist>
where:
<varlistentry>
<term>
<replaceable class="parameter">host</replaceable>
-
+</term>
<listitem>
<para>
The hostname of the server. Defaults to "localhost".
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">port</replaceable>
-
+</term>
<listitem>
<para>
The port number the server is listening on. Defaults to the Postgres
standard port number (5432).
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<replaceable class="parameter">database</replaceable>
-
+</term>
<listitem>
<para>
The database name.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</para>
<para>
To connect, you need to get a Connection instance from
<acronym>JDBC</acronym>. To do this,
you would use the DriverManager.getConnection() method:
+</para>
<para>
Connection db = DriverManager.getConnection(url,user,pwd);
-<para>
+</para>
+</sect1>
<sect1>
<title>Issuing a Query and Processing the Result</title>
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
the entire result.
-<para>
+</para>
<sect2>
<title>Using the Statement Interface</title>
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
lifetime. You have to remember that only one ResultSet can exist per Statement.
+</para>
+</listitem>
<listitem>
<para>
If you need to perform a query while processing a ResultSet, you can
simply create and use another Statement.
+</para>
+</listitem>
<listitem>
<para>
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
Threads and Servlets later in this document if you are thinking of using them,
as it covers some important points.
+</para>
+</listitem>
</itemizedlist>
-
+</para>
+</sect2>
<sect2>
<title>Using the ResultSet Interface</title>
<para>
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.
+</para>
+</listitem>
<listitem>
<para>
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
will allow you to access a field as many times as you want.
+</para>
+</listitem>
<listitem>
<para>
You must close a ResultSet by calling <function>close()</function> once you have finished with it.
+</para>
+</listitem>
<listitem>
<para>
Once you request another query with the Statement used to create a
ResultSet, the currently open instance is closed.
+</para>
+</listitem>
</itemizedlist>
+</para>
<para>
An example is as follows:
rs.close();
st.close();
</programlisting>
-
+</para>
+</sect2>
+</sect1>
<sect1>
<title>Performing Updates</title>
<programlisting>
st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
</programlisting>
-
+</para>
+</sect1>
<sect1>
<title>Closing the Connection</title>
<programlisting>
db.close();
</programlisting>
+</para>
+</sect1>
<sect1>
<title>Using Large Objects</title>
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
Table/Index pair, and are refered to from your own tables, by an OID value.
+</para>
<para>
Now, there are you methods of using Large Objects. The first is the
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
the extension to provide large object support.
+</para>
<para>
In <acronym>JDBC</acronym>, the standard way to access them is using the getBinaryStream()
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
methods make the large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the object.
+</para>
<para>
For example, suppose
<programlisting>
create table images (imgname name,imgoid oid);
</programlisting>
+</para>
<para>
To insert an image, you would use:
ps.close();
fis.close();
</programlisting>
+</para>
<para>
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
reference to it.
+</para>
<para>
Retrieving an image is even easier (I'm using PreparedStatement here, but
}
ps.close();
</programlisting>
+</para>
<para>
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
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.
-
+</para>
+</sect1>
<sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>
You can add your own functions
to the backend, which can then be called from queries, or even add your own
data types.
+</para>
<para>
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
It's up to you, and your applications requirements.
</programlisting>
+</para>
+</sect1>
<sect1>
<title>Further Reading</title>
and the <acronym>JDBC</acronym> Specification.
Both are available on
<ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>.
+</para>
<para>
<ulink url="http://www.retep.org.uk">My own web site</ulink>
contains updated information not included in this
document, and also includes precompiled drivers for v6.4, and earlier.
-
-</chapter>
\ No newline at end of file
+</para>
+</sect1>
+</chapter>
<!--
-$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
$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
Small sentence cleanups. Add tags for acronyms and products.
</Para>
</ListItem>
</itemizedlist>
+</para>
+</listitem>
<ListItem>
<Para>
</Para>
</ListItem>
</itemizedlist>
+</para>
+</listitem>
</itemizedlist>
+</para>
<Para>
As for why no non-unique keys are defined explicitly in standard <acronym>SQL</acronym> syntax?
<ProductName>PostgreSQL</ProductName> is copyright (C) 1996-8
by the PostgreSQL Global Development Group,
and is distributed under the terms of the Berkeley license.
+</Para>
<Para>
<ProductName>Postgres95</ProductName> is copyright (C) 1994-5
Hewlett-Packard Co. OSF/1 is a trademark of the Open
Software Foundation.
</Para>
+</Sect1>
+
</TITLE>
<PARA><FUNCTION>pg_connect</FUNCTION> opens a connection to the
<ProductName>Postgres</ProductName> backend.
+</Para>
<para>
Two syntaxes are available. In the older one, each possible option
The result is a list describing the possible connection options and their
current default values.
Each entry in the list is a sublist of the format:
+</Para>
<para>
{optname label dispchar dispsize value}
+</Para>
<Para>
where the optname is usable as an option in
<FUNCTION>pg_connect -conninfo</FUNCTION>.
Query result handles start with the connection handle and add a period
and a result number.
+</Para>
<PARA>
Note that lack of a Tcl error is not proof that the query succeeded!
in pg_exec.
</PARA>
</REFSECT1>
+</refentry>
<REFENTRY ID="PGTCL-PGRESULT">
<REFMETA>
<PARA>
<FUNCTION>pg_result</FUNCTION> returns information about a query result
created by a prior <FUNCTION>pg_exec</FUNCTION>.
+</Para>
<para>
You can keep a query result around for as long as you need it, but when
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
the idle loop to be entered.
+</Para>
<para>
You should not invoke the SQL statements LISTEN or UNLISTEN directly when
../src/test/examples
../src/bin/psql
</ProgramListing>
+</Para>
<Para>
Frontend programs which use <FileName>libpq</FileName> must include the
<synopsis>
ConnStatusType *PQstatus(PGconn *conn)
</synopsis>
+</Para>
<Para>
A failed connection attempt is signaled by status CONNECTION_BAD.
communications failure might result in the status changing to
CONNECTION_BAD prematurely. In that case the application could
try to recover by calling PQreset.
+</Para>
</ListItem>
<ListItem>
<synopsis>
char *PQerrorMessage(PGconn* conn);
</synopsis>
+</Para>
<Para>
Nearly all libpq functions will set PQerrorMessage if they fail.
Note that by libpq convention, a non-empty PQerrorMessage will
include a trailing newline.
+</Para>
</ListItem>
<ListItem>
int PQfnumber(PGresult *res,
char* field_name);
</synopsis>
+</Para>
<Para>
-1 is returned if the given name does not match any field.
+</Para>
</ListItem>
<ListItem>
The PQexec function is adequate for submitting queries in simple synchronous
applications. It has a couple of major deficiencies however:
-<Para>
<ItemizedList>
<ListItem>
<Para>
underlying functions that PQexec is built from: PQsendQuery and
PQgetResult.
-<Para>
<ItemizedList>
<ListItem>
<Para>
next SQL command. This can be avoided by proper use of three more
functions:
-<Para>
<ItemizedList>
<ListItem>
<Para>
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below). An example is given
in the sample programs section.
+</Para>
<Para>
A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
a query that is still being processed by the backend.
+</Para>
<Para>
<ItemizedList>
<Para>
Note that if the current query is part of a transaction, cancellation
will abort the whole transaction.
+</Para>
<Para>
PQrequestCancel can safely be invoked from a signal handler. So, it is
cancellation of queries that it issues through PQexec. Note that
PQrequestCancel will have no effect if the connection is not currently open
or the backend is not currently processing a query.
+</Para>
</Sect1>
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.
-<Para>
<ItemizedList>
<ListItem>
<Para>
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
not necessary for there to be any associated relation.
+</Para>
<Para>
<FileName>libpq</FileName> applications submit LISTEN and UNLISTEN
commands as ordinary SQL queries. Subsequently, arrival of NOTIFY
messages can be detected by calling PQnotifies().
-<Para>
<ItemizedList>
<ListItem>
<Para>
<Para>
The second sample program gives an example of the use
of asynchronous notification.
+</Para>
<Para>
PQnotifies() does not actually read backend data; it just returns messages
<synopsis>
int PQendcopy(PGconn *conn);
</synopsis>
+</Para>
<Para>
As an example:
fprintf(stderr, "%s", message);
}
</ProgramListing>
+</Para>
<Para>
To use a special notice processor, call <function>PQsetNoticeProcessor</function> just after
creation of a new PGconn object.
+</Para>
</Sect1>
}
</ProgramListing>
-<Para>
+</Para>
</Sect2>
</Sect1>
lo_open. On success, <Acronym>lo_close</Acronym> returns zero. On error,
the return value is negative.
</Para>
+</sect2>
</Sect1>
<Sect1>
location for the installation. Remember that all database access actually
occurs through the database backend, so that any location specified must
be accessible by the backend.
+</Para>
<Para>
Alternate database locations are created and referenced by an environment variable
although using variable names with a prefix of <quote>PGDATA</quote> is recommended
to avoid confusion
and conflict with other variables.
+</Para>
<Note>
<Para>
For security and integrity reasons,
any path or environment variable specified has some
additional path fields appended.
+</Para>
<Para>
Alternate database locations must be prepared by running
<Application>initlocation</Application>.
+</Para>
<Para>
To create a data storage area using the environment variable
Creating Postgres database system directory /alt/postgres/data
Creating Postgres database system directory /alt/postgres/data/base
</ProgramListing>
+</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:
<ProgramListing>
% createdb -D PGDATA2 mydb
ERROR: Unable to create database directory /alt/postgres/data/base/mydb
createdb: database creation failed on mydb.
</ProgramListing>
+</Para>
</Sect1>
<Title>Database Privileges</Title>
<Para>
+</para>
</Sect2>
<Sect2>
databases on a single host, this term more precisely denotes any
particular set of installed
<Productname>Postgres</Productname> binaries and databases.
+</para>
<para>
The
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>)
for security reasons.
+</para>
<para>
The
the method described below
and maintain a set of template databases for use by
<application>createdb</application>.
+</para>
<para>
The <application>postmaster</application>
can take several command-line arguments to tune its behavior.
However, supplying arguments is necessary only if you intend to run multiple
sites or a non-default site.
+</para>
<para>
The <Productname>Postgres</Productname> backend
doing this bypasses the shared buffer pool and lock table associated
with a postmaster/site, therefore this is not recommended in a multiuser
site.
+</para>
+</sect1>
<sect1>
<title>Notation</title>
<quote>...</quote> or <filename>/usr/local/pgsql/</filename>
at the front of a file name is used to represent the
path to the <Productname>Postgres</Productname> superuser's home directory.
+</para>
<para>
In a command synopsis, brackets
Anything in braces
(<quote>{</quote> and <quote>}</quote>) and containing vertical bars (<quote>|</quote>)
indicates that you must choose one.
+</para>
<para>
In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean
expressions. <quote>|</quote> is the boolean operator OR.
+</para>
<para>
Examples will show commands executed from various accounts and programs.
<quote>$</quote>.
<acronym>SQL</acronym> commands will be preceeded with <quote>=></quote>
or will have no leading prompt, depending on the context.
+</para>
<note>
<para>
flagging commands is not universally consistant throughout the documentation set.
Please report problems to
<ulink url="mailto:docs@postgresql.org">the Documentation Mailing List</ulink>.
+</para>
</note>
</sect1>
<Title>ODBC Interface</Title>
-<Para>
<Note>
<Para>
Background information originally by
between frontend applications and database servers,
allowing a user or developer to write applications which are
transportable between servers from different manufacturers..
+</Para>
<Sect1>
<Title>Background</Title>
on the backend to an <acronym>ODBC</acronym>-compatible data source.
This could be anything from a text file to an Oracle or
<productname>Postgres</productname> <acronym>RDBMS</acronym>.
+</Para>
<Para>
The backend access come from <acronym>ODBC</acronym> drivers,
allow data access. <productname>psqlODBC</productname> is such a driver,
along with others that are
available, such as the OpenLink <acronym>ODBC</acronym> drivers.
+</Para>
<Para>
Once you write an <acronym>ODBC</acronym> application,
you <emphasis>should</emphasis> be able to connect to <emphasis>any</emphasis>
back end database, regardless of the vendor, as long as the database schema
is the same.
+</Para>
<Para>
For example. you could have <productname>MS SQL Server</productname>
your Windows application would make exactly the
same calls and the back end data source would look the same (to the Windows
app).
+</Para>
<para>
<ulink url="http://www.insightdist.com/">Insight Distributors</ulink>
<ulink url="http://www.insightdist.com/psqlodbc/"><acronym>FAQ</acronym></ulink>,
ongoing development on the code base, and actively participate on the
<ulink url="mailto:interfaces@postgresql.org">interfaces mailing list</ulink>.
+</Para>
+</sect1>
<sect1>
<title><productname>Windows</productname> Applications</title>
<ListItem>
<Para>
Access, Delphi, and Visual Basic all support <acronym>ODBC</acronym> directly.
-
+</Para>
+</listitem>
<ListItem>
<Para>
Under C++, such as Visual C++,
you can use the C++ <acronym>ODBC</acronym> <acronym>API</acronym>.
+</Para>
+</listitem>
<ListItem>
<Para>
<acronym>ODBC</acronym> <acronym>API</acronym>
set within an MFC 4.2 class. This is the easiest route if you are doing
Windows C++ development under Windows NT.
+</Para>
+</listitem>
</ItemizedList>
+</Para>
<sect2>
<title>Writing Applications</title>
to the <productname>Postgres</productname> server,
or is that only when another database program
like MS SQL Server or Access needs to access the data?</quote>
-
+</para>
<Para>
The <acronym>ODBC</acronym> <acronym>API</acronym>
is the way to go.
For <productname>Visual C++</productname> coding you can find out more at
Microsoft's web site or in your <productname>VC++</productname> docs.
+</Para>
<Para>
Visual Basic and the other RAD tools have Recordset objects
directly to access data. Using the data-aware controls, you can quickly
link to the <acronym>ODBC</acronym> back end database
(<Emphasis>very</Emphasis> quickly).
+</Para>
<Para>
Playing around with MS Access will help you sort this out. Try using
<literal>File->Get External Data</literal>.
+</Para>
<Tip>
<Para>
</Para>
</Tip>
-->
+</sect2>
+</sect1>
<sect1>
<title>Unix Installation</title>
demonstrated under Linux with <productname>Postgres</productname> v6.4
using the <productname>psqlODBC</productname>
driver contained in the <productname>Postgres</productname> distribution.
+</Para>
<sect2>
<title>Building the Driver</title>
document, but there is a <filename>README</filename>
that can be found inside the <productname>iodbc</productname> compressed
.shar file that should explain how to get it up and running.
+</Para>
<para>
Having said that, any driver manager that you can find for your platform
should support the <productname>psqlODBC</productname> driver
or any <acronym>ODBC</acronym> driver.
+</Para>
<para>
The Unix configuration files for <productname>psqlODBC</productname>
these include Linux and FreeBSD but we are hoping other users will
contribute the necessary information to quickly expand the number of
platforms for which the driver can be built.
+</Para>
<para>
There are actually two separate methods to build the driver depending on
client applications on multiple, heterogeneous platforms. The integrated
installation is convenient when the target client is the same as the
server, or when the client and server have similar runtime configurations.
+</Para>
<para>
Specifically if you have received the <productname>psqlODBC</productname>
If you received the driver as a standalone package than you will run
configure and make from the directory in which you unpacked the
driver source.
+</Para>
<procedure>
<title>Integrated Installation</title>
<para>
This installation procedure is appropriate for an integrated installation.
+</Para>
<step performance="required">
<para>
% ./configure --with-odbc
% make
</programlisting>
-
+</Para>
+</step>
<step performance="required">
<para>
Rebuild the <productname>Postgres</productname> distribution:
<programlisting>
% make install
</programlisting>
-
+</Para>
+</step>
</procedure>
<para>
<programlisting>
% make ODBCINST=<replaceable>filename</replaceable> install
</programlisting>
+</Para>
<procedure>
<title>Pre-v6.4 Integrated Installation</title>
v6.4, you have the original source tree available,
and you want to use the newest version of the <acronym>ODBC</acronym>
driver, then you may want to try this form of installation.
+</Para>
<step performance="required">
<para>
Copy the output tar file to your target system and unpack it into a
clean directory.
-
+</Para>
+</step>
<step performance="required">
<para>
From the directory containing the
% make
% make POSTGRESDIR=<replaceable class="parameter">PostgresTopDir</replaceable> install
</programlisting>
+</Para>
+</step>
<step performance="optional">
<para>
<programlisting>
% make BINDIR=bindir LIBDIR=libdir HEADERDIR=headerdir ODBCINST=instfile install
</programlisting>
-
+</Para>
+</step>
</procedure>
<procedure>
for building the <acronym>ODBC</acronym> driver for multiple, heterogeneous
clients who do not have a locally-installed <productname>Postgres</productname>
source tree.
+</Para>
<para>
The default location for libraries and headers
as <filename>/share/odbcinst.ini</filename> (if <filename>/share</filename>
exists) or as <filename>/etc/odbcinst.ini</filename>
(if <filename>/share</filename> does not exist).
+</Para>
<note>
<para>
have this requirement, and you can choose another destination which
is writable by your non-root <productname>Postgres</productname> superuser
account instead.
+</Para>
</note>
<step performance="required">
<productname>Postgres</productname> distribution or may be obtained from
<ulink url="http://www.insightdist.com/psqlodbc">Insight Distributors</ulink>,
the current maintainers of the non-Unix sources.
+</Para>
<para>
Copy the zip
The <option>-a</option> option
is necessary to get rid of <acronym>DOS</acronym>
CR/LF pairs in the source files.
+</Para>
<para>
If you have the gzipped tar package than simply run
<programlisting>
tar -xzf <replaceable>packagename</replaceable>
</programlisting>
+</Para>
<substeps>
<para>
To create a tar file for a complete standalone installation
from the main <productname>Postgres</productname> source tree:
-
+</Para>
+</step>
</substeps>
-
+</step>
<step performance="required">
<para>
Configure the main <productname>Postgres</productname> distribution.
-
+</Para>
+</step>
<step performance="required">
<para>
Create the tar file:
% cd interfaces/odbc
% make standalone
</programlisting>
+</Para>
+</step>
<step performance="required">
<para>
Copy the output tar file to your target system. Be sure to transfer as
a binary file if using <application>ftp</application>.
+</Para>
+</step>
<step performance="required">
<para>
Unpack the tar file into a clean
directory.
+</Para>
+</step>
<step performance="required">
<para>
<programlisting>
% ./configure
</programlisting>
+</Para>
<para>
The configuration can be done with options:
<filename><replaceable>rootdir</replaceable>/include/iodbc</filename>, and
<option>--with-odbc</option> installs <filename>odbcinst.ini</filename> in the
specified directory.
+</Para>
<para>
Note that both of these options can also be used from the integrated build
your <productname>Postgres</productname> installation.
<option>--with-odbc</option> applies only to the configuration file
<filename>odbcinst.ini</filename>.
+</Para>
+</step>
<step performance="required">
<para>
<programlisting>
% make ODBCINST=<replaceable>instdir</replaceable>
</programlisting>
+</Para>
<para>
You can also override the default location for installation on the
headaches. It is safest simply to allow the driver to install the
odbcinst.ini file in the default directory or the directory you specified
on the './configure' command line with --with-odbc.
+</Para>
+</step>
<!--
This doesn't currently work - thomas 1998-10-19
<programlisting>
% make POSTGRESDIR=<replaceable>targettree</replaceable> install
</programlisting>
+</Para>
<para>
To override the library and header installation directories separately
<envar>LIBDIR</envar> and <envar>HEADERDIR</envar>
to be rooted at the new directory you specify.
<envar>ODBCINST</envar> is independent of <envar>POSTGRESDIR</envar>.
+</Para>
<para>
Here is how you would specify the various destinations explicitly:
<programlisting>
% make BINDIR=<replaceable>bindir</replaceable> LIBDIR=<replaceable>libdir</replaceable> HEADERDIR=<replaceable>headerdir</replaceable> install
</programlisting>
+</Para>
<para>
For example, typing
will cause the libraries and headers to be installed in the directories
<filename>/opt/psqlodbc/lib</filename>
and <filename>/opt/psqlodbc/include/iodbc</filename> respectively.
+</Para>
<para>
The command
should cause the libraries to be installed in /opt/psqlodbc/lib and
the headers in /usr/local/include/iodbc. If this doesn't work as
expected please contact one of the maintainers.
-
+</Para>
+</step>
</procedure>
+</sect2>
+</sect1>
<sect1>
<title>Configuration Files</title>
for the <productname>psqlODBC</productname> driver.
The file uses conventions typical for <productname>Windows</productname>
Registry files, but despite this restriction can be made to work.
+</Para>
<para>
The <filename>.odbc.ini</filename> file has three required sections.
usually a single word, without path names of any sort.
The <productname>Postgres</productname> server manages the actual access
to the database, and you need only specify the name from the client.
+</Para>
</tip>
Other entries may be inserted to control the format of the display.
The third required section is <literal>[ODBC]</literal>
which must contain the <literal>InstallDir</literal> keyword
and which may contain other options.
+</Para>
<para>
Here is an example <filename>.odbc.ini</filename> file,
[ODBC]
InstallDir = /opt/applix/axdata/axshlib
</programlisting>
-
+</Para>
+</sect1>
<sect1>
<title>ApplixWare</title>
-<para>
-
<sect2>
<title>Configuration</title>
in order for it to
be able to access the <productname>Postgres</productname>
<acronym>ODBC</acronym> software drivers.
+</Para>
<procedure>
<title>Enabling ApplixWare Database Access</title>
<productname>ApplixWare</productname> on <productname>Linux</productname>.
Refer to the <citetitle>Linux Sys Admin</citetitle> on-line book
for more detailed information.
+</Para>
<step performance="required">
<para>
This library is included with the ApplixWare distribution,
but <filename>axnet.cnf</filename> needs to be modified to point to the
correct location.
+</Para>
<para>
As root, edit the file
<filename><replaceable>applixroot</replaceable>/applix/axdata/axnet.cnf</filename>.
+</Para>
<substeps>
<programlisting>
#libFor elfodbc /ax/<replaceable>...</replaceable>
</programlisting>
-
+</Para>
+</step>
<step performance="required">
<para>
Change line to read
for the <acronym>ODBC</acronym> support library.
If you have installed applix somewhere else,
change the path accordingly.
-
+</Para>
+</step>
</substeps>
+</step>
<step performance="required">
<para>
to the database-specific portion of <filename>.odbc.ini</filename>
so that text fields will not be shown as <literal>**BLOB**</literal>.
-
+</Para>
+</step>
</procedure>
<procedure>
<step performance="required">
<para>
Bring up <application>Applix Data</application>
+</Para>
+</step>
<step performance="required">
<para>
Select the <productname>Postgres</productname> database of interest.
+</Para>
<substeps>
<step performance="required">
<para>
Select <command>Query->Choose Server</command>.
-
+</Para>
+</step>
<step performance="required">
<para>
Select <acronym>ODBC</acronym>, and click <command>Browse</command>.
should be shown. Make sure that the <option>Host: field</option>
is empty (if it is not, axnet will try to contact axnet on another machine
to look for the database).
-
+</Para>
+</step>
<step performance="required">
<para>
Select the database in the box that was launched by <command>Browse</command>,
then click <command>OK</command>.
-
+</Para>
+</step>
<step performance="required">
<para>
Enter username and password in the login identification dialog,
and click <command>OK</command>.
-
+</Para>
+</step>
</substeps>
<para>
in the lower left corner of the
data window. If you get an error dialog box, see the debugging section
below.
-
+</Para>
+</step>
<step performance="required">
<para>
The 'Ready' message will appear in the lower left corner of the data
window. This indicates that you can now enter queries.
-
+</Para>
+</step>
<step performance="required">
<para>
Select a table from Query->Choose tables, and then select Query->Query
to access the database. The first 50 or so rows from the table should
appear.
-
+</Para>
+</step>
</procedure>
+</sect2>
<sect2>
<title>Common Problems</title>
<varlistentry>
<term>
Cannot launch gateway on server
-
+</term>
<listitem>
<para>
<literal>elfodbc</literal> can't find <filename>libodbc.so</filename>.
Check your <filename>axnet.cnf</filename>.
+</Para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
Error from ODBC Gateway:
IM003::[iODBC][Driver Manager]Specified driver could not be loaded
-
+</term>
<listitem>
<para>
<filename>libodbc.so</filename> cannot find the driver listed in
<filename>.odbc.ini</filename>. Verify the settings.
+</Para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
Server: Broken Pipe
+</term>
<listitem>
<para>
problem. You might not have an up-to-date version
of the <productname>Postgres</productname>
<acronym>ODBC</acronym> package.
+</Para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
setuid to 256: failed to launch gateway
+</term>
<listitem>
<para>
exceed eight (8) characters in length.
Problem description ontributed by
<ulink url="mailto:scampbell@lear.com">Steve Campbell</ulink>.
+</Para>
+</listitem>
+</varlistentry>
</variablelist>
+</para>
<para>
<note>
Contributed by
<ulink url="mailto:scampbell@lear.com">Steve Campbell</ulink> on
1998-10-20.
+</para>
</note>
The <application>axnet</application> program's security system
(so it can read/write in each user's directory).
I would hesitate to recommend this, however, since we have no idea what
security holes this creates.
+</para>
+</sect2>
<sect2>
<title>Debugging ApplixWare ODBC Connections</title>
<para>
One good tool for debugging connection problems uses the Unix system
utility <application>strace</application>.
-
+</para>
<procedure>
<title>Debugging with strace</title>
<step performance="required">
<para>
Start applixware.
-
+</para>
+</step>
<step performance="required">
<para>
Start an <application>strace</application> on
cary 10432 0.0 2.6 1740 392 ? S Oct 9 0:00 axnet
cary 27883 0.9 31.0 12692 4596 ? S 10:24 0:04 axmain
</programlisting>
+</para>
<para>
Then run
<programlisting>
strace -f -s 1024 -p 10432
</programlisting>
+</para>
+</step>
<step performance="required">
<para>
Check the strace output.
-
+</para>
<note>
<title>Note from Cary</title>
go to <filename>stderr</filename>,
but I'm not sure where <filename>stderr</filename>
is sent, so <application>strace</application> is the way to find out.
+</para>
</note>
-
+</step>
</procedure>
<para>
</programlisting>
So what is happening is that applix elfodbc is searching for libodbc.so, but it
can't find it. That is why axnet.cnf needed to be changed.
+</para>
+</sect2>
<sect2>
<title>Running the ApplixWare Demo</title>
create the tables tries to use a NULL condition
on many of the database columns,
and <productname>Postgres</productname> does not currently allow this option.
-
+</para>
<para>
To get around this problem, you can do the following:
+</para>
<procedure>
<title>Modifying the ApplixWare Demo</title>
<para>
Copy <filename>/opt/applix/axdata/eng/Demos/sqldemo.am</filename>
to a local directory.
+</para>
+</step>
<step performance="required">
<para>
Edit this local copy of <filename>sqldemo.am</filename>:
+</para>
<substeps>
<step performance="required">
<para>
Search for 'null_clause = "NULL"
+</para>
+</step>
<step performance="required">
<para>
Change this to null_clause = ""
+</para>
+</step>
</substeps>
-
+</step>
<step performance="required">
<para>
Start <application>Applix Macro Editor</application>.
+</para>
+</step>
<step performance="required">
<para>
Open the sqldemo.am file from the <application>Macro Editor</application>.
+</para>
+</step>
<step performance="required">
<para>
Select <command>File->Compile and Save</command>.
+</para>
+</step>
<step performance="required">
<para>
Exit <application>Macro Editor</application>.
+</para>
+</step>
<step performance="required">
<para>
Start <application>Applix Data</application>.
+</para>
+</step>
<step performance="required">
<para>
Select <command>*->Run Macro</command>
+</para>
+</step>
<step performance="required">
<para>
Enter the value <quote>sqldemo</quote>, then click <command>OK</command>.
+</para>
<para>
You should see the progress in the status line of the data window
(in the lower left corner).
+</para>
+</step>
<step performance="required">
<para>
You should now be able to access the demo tables.
-
+</para>
+</step>
</procedure>
-
+</sect2>
<sect2>
<title>Useful Macros</title>
in order for it to
be able to access the <productname>Postgres</productname>
<acronym>ODBC</acronym> software drivers.
-
+</para>
<procedure>
<title>Enabling ApplixWare Database Access</title>
<productname>ApplixWare</productname> on <productname>Linux</productname>.
Refer to the <citetitle>Linux Sys Admin</citetitle> on-line book
for more detailed information.
-
+</para>
<step performance="required">
<para>
You must modify <filename>axnet.cnf</filename> so that
This library is included with the ApplixWare distribution,
but <filename>axnet.cnf</filename> needs to be modified to point to the
correct location.
-
+</para>
<para>
As root, edit the file
<filename><replaceable>applixroot</replaceable>/applix/axdata/axnet.cnf</filename>.
-
+</para>
<substeps>
<step performance="required">
<programlisting>
#libFor elfodbc /ax/<replaceable>...</replaceable>
</programlisting>
+</para>
+</step>
<step performance="required">
<para>
for the <acronym>ODBC</acronym> support library.
If you have installed applix somewhere else,
change the path accordingly.
+</para>
+</step>
</substeps>
+</step>
<step performance="required">
<para>
to the database-specific portion of <filename>.odbc.ini</filename>
so that text fields will not be shown as <literal>**BLOB**</literal>.
+</para>
+</step>
</procedure>
<step performance="required">
<para>
Bring up <application>Applix Data</application>
+</para>
+</step>
<step performance="required">
<para>
Select the <productname>Postgres</productname> database of interest.
+</para>
<substeps>
<step performance="required">
<para>
Select <command>Query->Choose Server</command>.
+</para>
+</step>
<step performance="required">
<para>
should be shown. Make sure that the <option>Host: field</option>
is empty (if it is not, axnet will try to contact axnet on another machine
to look for the database).
+</para>
+</step>
<step performance="required">
<para>
Select the database in the box that was launched by <command>Browse</command>,
then click <command>OK</command>.
+</para>
+</step>
<step performance="required">
<para>
Enter username and password in the login identification dialog,
and click <command>OK</command>.
+</para>
+</step>
</substeps>
in the lower left corner of the
data window. If you get an error dialog box, see the debugging section
below.
-
+</para>
+</step>
<step performance="required">
<para>
The 'Ready' message will appear in the lower left corner of the data
window. This indicates that you can now enter queries.
+</para>
+</step>
<step performance="required">
<para>
Select a table from Query->Choose tables, and then select Query->Query
to access the database. The first 50 or so rows from the table should
appear.
+</para>
+</step>
</procedure>
+</sect2>
<sect2>
<title>Common Problems</title>
<varlistentry>
<term>
Cannot launch gateway on server
-
+</term>
<listitem>
<para>
<literal>elfodbc</literal> can't find <filename>libodbc.so</filename>.
Check your <filename>axnet.cnf</filename>.
-
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
Error from ODBC Gateway:
IM003::[iODBC][Driver Manager]Specified driver could not be loaded
+</term>
<listitem>
<para>
<filename>libodbc.so</filename> cannot find the driver listed in
<filename>.odbc.ini</filename>. Verify the settings.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
Server: Broken Pipe
+</term>
<listitem>
<para>
problem. You might not have an up-to-date version
of the <productname>Postgres</productname>
<acronym>ODBC</acronym> package.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</para>
+</sect2>
<sect2>
<title>Debugging ApplixWare ODBC Connections</title>
<para>
One good tool for debugging connection problems uses the Unix system
utility <application>strace</application>.
-
+</para>
<procedure>
<title>Debugging with strace</title>
<step performance="required">
<para>
Start applixware.
-
+</para>
+</step>
<step performance="required">
<para>
Start an <application>strace</application> on
cary 10432 0.0 2.6 1740 392 ? S Oct 9 0:00 axnet
cary 27883 0.9 31.0 12692 4596 ? S 10:24 0:04 axmain
</programlisting>
+</para>
<para>
Then run
<programlisting>
strace -f -s 1024 -p 10432
</programlisting>
-
+</para>
+</step>
<step performance="required">
<para>
Check the strace output.
+</para>
<note>
<title>Note from Cary</title>
go to <filename>stderr</filename>,
but I'm not sure where <filename>stderr</filename>
is sent, so <application>strace</application> is the way to find out.
+</para>
</note>
-
+</step>
</procedure>
<para>
</programlisting>
So what is happening is that applix elfodbc is searching for libodbc.so, but it
can't find it. That is why axnet.cnf needed to be changed.
-
+</para>
+</sect2>
<sect2>
<title>Running the ApplixWare Demo</title>
create the tables tries to use a NULL condition
on many of the database columns,
and <productname>Postgres</productname> does not currently allow this option.
+</para>
<para>
To get around this problem, you can do the following:
+</para>
<procedure>
<title>Modifying the ApplixWare Demo</title>
<para>
Copy <filename>/opt/applix/axdata/eng/Demos/sqldemo.am</filename>
to a local directory.
+</para>
+</step>
<step performance="required">
<para>
Edit this local copy of <filename>sqldemo.am</filename>:
+</para>
<substeps>
<step performance="required">
<para>
Search for 'null_clause = "NULL"
+</para>
+</step>
<step performance="required">
<para>
Change this to null_clause = ""
-
+</para>
+</step>
</substeps>
-
+</step>
<step performance="required">
<para>
Start <application>Applix Macro Editor</application>.
-
+</para>
+</step>
<step performance="required">
<para>
Open the sqldemo.am file from the <application>Macro Editor</application>.
+</para>
+</step>
<step performance="required">
<para>
Select <command>File->Compile and Save</command>.
+</para>
+</step>
<step performance="required">
<para>
Exit <application>Macro Editor</application>.
+</para>
+</step>
<step performance="required">
<para>
Start <application>Applix Data</application>.
+</para>
+</step>
<step performance="required">
<para>
Select <command>*->Run Macro</command>
+</para>
+</step>
<step performance="required">
<para>
Enter the value <quote>sqldemo</quote>, then click <command>OK</command>.
+</para>
<para>
You should see the progress in the status line of the data window
(in the lower left corner).
+</para>
+</step>
<step performance="required">
<para>
You should now be able to access the demo tables.
+</para>
+</step>
</procedure>
+</sect2>
<sect2>
<title>Useful Macros</title>
<para>
You should be careful about the file protections on any file containing
username and password information.
+</para>
</caution>
-
+</para>
+</sect2>
<sect2>
<title>Supported Platforms</title>
with FreeBSD and with Solaris. There are no known restrictions
on the basic code for other platforms which already support
<productname>Postgres</productname>.
-
+</para>
+</sect2>
+</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
+sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
pg_operator. Every entry in pg_operator includes
the name of the procedure that implements the operator and the
class <Acronym>OIDs</Acronym> of the input and output types.
+</Para>
<Para>
To view all variations of the <Quote>||</Quote> string concatenation operator,
<ProgramListing>
select * from emp where int4lt(salary, 40000);
</ProgramListing>
+</Para>
<Para>
<Application>psql</Application>
has a command (<Command>\dd</Command>) to show these operators.
-
+</Para>
<sect1>
<title>Lexical Precedence</title>
<row>
<entry>
Element
+</entry>
<entry>
Precedence
+</entry>
<entry>
Description
+</entry>
+</row>
</thead>
<tbody>
<row>
<entry>
UNION
+</entry>
<entry>
left
+</entry>
<entry>
SQL select construct
+</entry>
+</row>
<row>
<entry>
::
+</entry>
<entry>
+</entry>
<entry>
<productname>Postgres</productname> typecasting
-
+</entry>
+</row>
<row>
<entry>
[ ]
+</entry>
<entry>
left
+</entry>
<entry>
array delimiters
-
+</entry>
+</row>
<row>
<entry>
.
+</entry>
<entry>
left
+</entry>
<entry>
table/column delimiter
-
+</entry>
+</row>
<row>
<entry>
-
+</entry>
<entry>
right
+</entry>
<entry>
unary minus
-
+</entry>
+</row>
<row>
<entry>
;
+</entry>
<entry>
left
+</entry>
<entry>
statement termination, logarithm
-
+</entry>
+</row>
<row>
<entry>
:
+</entry>
<entry>
right
+</entry>
<entry>
exponentiation
-
+</entry>
+</row>
<row>
<entry>
|
+</entry>
<entry>
left
+</entry>
<entry>
start of interval
-
+</entry>
+</row>
<row>
<entry>
* /
+</entry>
<entry>
left
+</entry>
<entry>
multiplication, division
-
+</entry>
+</row>
<row>
<entry>
+ -
+</entry>
<entry>
left
+</entry>
<entry>
addition, subtraction
-
+</entry>
+</row>
<row>
<entry>
IS
+</entry>
<entry>
+</entry>
<entry>
test for TRUE, FALSE, NULL
+</entry>
+</row>
<row>
<entry>
ISNULL
+</entry>
<entry>
+</entry>
<entry>
test for NULL
-
+</entry>
+</row>
<row>
<entry>
NOTNULL
+</entry>
<entry>
+</entry>
<entry>
test for NOT NULL
-
+</entry>
+</row>
<row>
<entry>
(all other operators)
+</entry>
<entry>
+</entry>
<entry>
native and user-defined
-
+</entry>
+</row>
<row>
<entry>
IN
+</entry>
<entry>
+</entry>
<entry>
set membership
-
+</entry>
+</row>
<row>
<entry>
BETWEEN
+</entry>
<entry>
+</entry>
<entry>
containment
-
+</entry>
+</row>
<row>
<entry>
LIKE
+</entry>
<entry>
+</entry>
<entry>
string pattern matching
-
+</entry>
+</row>
<row>
<entry>
< >
+</entry>
<entry>
+</entry>
<entry>
boolean inequality
-
+</entry>
+</row>
<row>
<entry>
=
+</entry>
<entry>
right
+</entry>
<entry>
equality
-
+</entry>
+</row>
<row>
<entry>
NOT
+</entry>
<entry>
right
+</entry>
<entry>
negation
-
+</entry>
+</row>
<row>
<entry>
AND
+</entry>
<entry>
left
+</entry>
<entry>
logical intersection
-
+</entry>
+</row>
<row>
<entry>
OR
+</entry>
<entry>
left
+</entry>
<entry>
logical union
-
+</entry>
+</row>
</tbody>
+</tgroup>
</table>
+</para>
+</sect1>
<sect1>
<title>General Operators</title>
<para>
The operators listed here are defined for a number of native data types,
ranging from numeric types to data/time types.
-
+</para>
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Operators</TITLE>
</TGROUP>
</TABLE>
</Para>
+</sect1>
<sect1>
<title id="math-opers">Numerical Operators</title>
</TGROUP>
</TABLE>
</Para>
+</sect1>
<sect1>
<title>Geometric Operators</title>
</TGROUP>
</TABLE>
</Para>
+</sect1>
<sect1>
<title>Time Interval Operators</title>
</TGROUP>
</TABLE>
</Para>
+</sect1>
<Sect1>
<title id="cidr-opers">IP V4 Operators</title>
<para>
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.
+</para>
<para>
In the following explanation, a
is assumed to contain 8 bits. In addition, the term
<firstterm>item</firstterm>
refers to data which is stored in <productname>Postgres</productname> classes.
+</para>
<sect1>
<title>Page Structure</title>
</entry>
</row>
</thead>
+
<tbody>
+
<row>
<entry>
itemPointerData
</entry>
+</row>
+
<row>
<entry>
filler
</entry>
+</row>
+
<row>
<entry>
itemData...
</entry>
+</row>
+
<row>
<entry>
Unallocated Space
</entry>
+</row>
+
<row>
<entry>
ItemContinuationData
</entry>
+</row>
+
<row>
<entry>
Special Space
</entry>
+</row>
+
<row>
<entry>
``ItemData 2''
</entry>
+</row>
+
<row>
<entry>
``ItemData 1''
</entry>
+</row>
+
<row>
<entry>
ItemIdData
</entry>
+</row>
+
<row>
<entry>
PageHeaderData
</entry>
+</row>
+
</tbody>
</tgroup>
</table>
+</para>
<!--
.\" Running
buffer pool may be subdivided into equal sized pages on a frame by
frame basis within a class. The internal fragmentation information is
used to aid in determining when page reorganization should occur.
+</para>
<para>
Following the page header are item identifiers
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
its interpretation.
+</para>
<para>
The items themselves are stored in space allocated backwards from
itemPointerData
which points to the next piece and the piece itself. The last piece
is handled normally.
+</para>
+</sect1>
<sect1>
<title>Files</title>
<listitem>
<para>
Location of shared (global) database files.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
<listitem>
<para>
Location of local database files.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</para>
+</sect1>
<sect1>
<title>Bugs</title>
<para>
The page format may change in the future to provide more efficient
access to large objects.
+</para>
<para>
This section contains insufficient detail to be of any assistance in
writing a new access method.
-
+</para>
+</sect1>
</chapter>
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
</Para>
</Note>
-
+</para>
<Para>
The optional file <filename>data/pg_options</filename> contains runtime
options used by the backend to control trace messages and other backend
New options and parameters must be defined in
<filename>backend/utils/misc/trace.c</filename> and
<filename>backend/include/utils/trace.h</filename>.
-
+</para>
<Para>
For example suppose we want to add conditional trace messages and a tunable
numeric parameter to the code in file <filename>foo.c</filename>.
}
}
</programlisting>
-
+</para>
<para>
Existing files using private trace flags can be changed by simply adding
the following code:
/* int my_own_flag = 0; -- removed */
#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
</programlisting>
-
+</para>
<para>
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
foo=1
fooparam=17
</programlisting>
-
+</para>
<para>
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
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
sending the SIGHUP directly to it.
-
+</para>
<para>
pg_options can also be specified with the <option>-T</option> switch of
<productname>Postgres</productname>:
<programlisting>
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
</programlisting>
-
+</para>
<Para>
The functions used for printing errors and debug messages can now make use
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
980127.19:52:14.466 [29286] Async_NotifyHandler done
</programlisting>
-
+</para>
<para>
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
easier to write simple awk or perl scripts which monitor the log to
detect database errors or problem, or to compute transaction time statistics.
-
+</para>
<para>
Messages printed to syslog use the log facility LOG_LOCAL0.
The use of syslog can be controlled with the syslog pg_option.
<varlistentry>
<term>
all
-
+</term>
<listitem>
<para>
Global trace flag. Allowed values are:
+</para>
<variablelist>
<varlistentry>
<term>
0
-
+</term>
<listitem>
<para>
Trace messages enabled individually
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
1
-
+</term>
<listitem>
<para>
Enable all trace messages
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
-1
-
+</term>
<listitem>
<para>
Disable all trace messages
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
verbose
-
+</term>
<listitem>
<para>
Verbosity flag. Allowed values are:
+</para>
<variablelist>
<varlistentry>
<term>
0
-
+</term>
<listitem>
<para>
No messages. This is the default.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
1
-
+</term>
<listitem>
<para>
Print information messages.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
2
-
+</term>
<listitem>
<para>
Print more information messages.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
query
-
+</term>
<listitem>
<para>
Query trace flag. Allowed values are:
+</para>
<variablelist>
<varlistentry>
<term>
0
-
+</term>
<listitem>
<para>
Don't print query.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
1
-
+</term>
<listitem>
<para>
Print a condensed query in one line.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
4
-
+</term>
<listitem>
<para>
Print the full query.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
plan
-
+</term>
<listitem>
<para>
Print query plan.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
parse
-
+</term>
<listitem>
<para>
Print parser output.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
rewritten
-
+</term>
<listitem>
<para>
Print rewritten query.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
parserstats
-
+</term>
<listitem>
<para>
Print parser statistics.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
plannerstats
-
+</term>
<listitem>
<para>
Print planner statistics.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
executorstats
-
+</term>
<listitem>
<para>
Print executor statistics.
-
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
shortlocks
-
+</term>
<listitem>
<para>
Currently unused but needed to enable features in the future.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
locks
-
+</term>
<listitem>
<para>
Trace locks.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
userlocks
-
+</term>
<listitem>
<para>
Trace user locks.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
spinlocks
-
+</term>
<listitem>
<para>
Trace spin locks.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
notify
-
+</term>
<listitem>
<para>
Trace notify functions.
-
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
malloc
-
+</term>
<listitem>
<para>
Currently unused.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
palloc
-
+</term>
<listitem>
<para>
Currently unused.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
lock_debug_oidmin
-
+</term>
<listitem>
<para>
Minimum relation oid traced by locks.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
lock_debug_relid
-
+</term>
<listitem>
<para>
oid, if not zero, of relation traced by locks.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
lock_read_priority
-
+</term>
<listitem>
<para>
Currently unused.
-
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
deadlock_timeout
-
+</term>
<listitem>
<para>
Deadlock check timer.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
syslog
-
+</term>
<listitem>
<para>
syslog flag. Allowed values are:
+</para>
<variablelist>
<varlistentry>
<term>
0
-
+</term>
<listitem>
<para>
Messages to stdout/stderr.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
1
-
+</term>
<listitem>
<para>
Messages to stdout/stderr and syslog.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
2
-
+</term>
<listitem>
<para>
Messages only to syslog.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
hostlookup
-
+</term>
<listitem>
<para>
Enable hostname lookup in ps_status.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
showportnumber
-
+</term>
<listitem>
<para>
Show port number in ps_status.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
notifyunlock
-
+</term>
<listitem>
<para>
Unlock of pg_listener after notify.
+</para>
+</listitem>
+</varlistentry>
<varlistentry>
<term>
notifyhack
-
+</term>
<listitem>
<para>
Remove duplicate tuples from pg_listener.
+</para>
+</listitem>
+</varlistentry>
</variablelist>
number of platforms. Check
<ulink url="http://www.postgresql.org/docs/admin/ports.htm">the web site</ulink>
for the latest information.
+</para>
<Sect1>
<Title>Currently Supported Platforms</Title>
</TBODY>
</TGROUP>
</TABLE>
-
+</para>
<para>
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.
-
+</para>
<note>
<para>
For <productname>Windows NT</productname>,
for up to date information. You may also want to
look for possible patches on the
<ulink url="http://postgresql.org">Postgres web site</ulink>.
+</para>
</note>
+</sect1>
<Sect1>
<Title>Unsupported Platforms</Title>
</TBODY>
</TGROUP>
</TABLE>
+</para>
<Para>
Note that Windows ports of the frontend are apparently possible
Updates for protocol 2.0 by <ULink url="mailto:tgl@sss.pgh.pa.us">Tom Lane</ULink>.
</Para>
</Note>
+</para>
<Para>
<ProductName>Postgres</ProductName> uses a message-based protocol for communication between frontends
This was done in such
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.
+</para>
<Para>
This document describes version 2.0 of the protocol, implemented in
<ProductName>Postgres</ProductName> v6.4 and later.
+</para>
<Para>
Higher level features built on this protocol (for example, how <FileName>libpq</FileName> passes
certain environment variables after the connection is established)
are covered elsewhere.
+</para>
<Sect1>
<Title>Overview</Title>
The three major components are the frontend (running on the client) and the
postmaster and backend (running on the server). The postmaster and backend
have different roles but may be implemented by the same executable.
+</para>
<Para>
A frontend sends a startup packet to the postmaster. This includes the names
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)
and responds to the frontend accordingly.
+</para>
<Para>
The frontend then sends any required authentication information. Once the
and hands over the connection to a backend. The backend then sends a message
indicating successful startup (normal case) or failure (for example, an
invalid database name).
+</para>
<Para>
Subsequent communications are query and result packets exchanged between the
query/result communication. (However, the postmaster is involved when the
frontend wishes to cancel a query currently being executed by its backend.
Further details about that appear below.)
+</para>
<Para>
When the frontend wishes to disconnect it sends an appropriate packet and
closes the connection without waiting for a response for the backend.
+</para>
<Para>
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
frontend to the postmaster, which comprise a packet length then the packet
itself. The difference is historical.
+</para>
+</sect1>
<Sect1>
<Title>Protocol</Title>
startup, query, function call, and termination.
There are also special provisions for notification responses and command
cancellation, which can occur at any time after the startup phase.
+</para>
<Sect2>
<Para>
Startup is divided into an authentication phase and a backend startup phase.
+</para>
<Para>
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
method the frontend must use. The postmaster then responds with one of the
following messages:
+</para>
<Para>
<VariableList>
<Para>
If the frontend does not support the authentication method requested by the
postmaster, then it should immediately close the connection.
+</para>
<Para>
After sending AuthenticationOk, the postmaster attempts to launch a backend
successful startup. The frontend should send no messages at this point.
The possible messages from the backend during this phase are:
-<Para>
<VariableList>
<VarListEntry>
<Term>
BackendKeyData indicates successful conclusion of the startup phase),
or to consider ReadyForQuery as ending the startup phase and each subsequent
query cycle.
-
+</para>
+</sect2>
<Sect2>
<Title>Query</Title>
on the contents of the query command string, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely
send a new query or function call.
+</para>
<Para>
The possible response messages from the backend are:
-<Para>
<VariableList>
<VarListEntry>
<Term>
<Para>
A frontend must be prepared to accept ErrorResponse and NoticeResponse
messages whenever it is expecting any other type of message.
+</para>
<Para>
Actually, it is possible for NoticeResponse to arrive even when the frontend
In that case it will send a NoticeResponse before closing the connection.)
It is recommended that the frontend check for such asynchronous notices just
before issuing any new command.
+</para>
<Para>
Also, if the frontend issues any listen(l) commands then it must be prepared
to accept NotificationResponse messages at any time; see below.
-
+</para>
+</sect2>
<Sect2>
<Title>Function Call</Title>
depending on the results of the function call, and finally a ReadyForQuery
response message. ReadyForQuery informs the frontend that it may safely send
a new query or function call.
+</para>
<Para>
The possible response messages from the backend are:
-<Para>
<VariableList>
<VarListEntry>
<Term>
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
NotificationResponse messages at any time; see below.
-
+</para>
+</sect2>
<Sect2>
<Title>Notification Responses</Title>
If a frontend issues a listen(l) command, then the backend will send a
NotificationResponse message (not to be confused with NoticeResponse!)
whenever a notify(l) command is executed for the same notification name.
+</para>
<Para>
Notification responses are permitted at any point in the protocol (after
expecting any message. Indeed, it should be able to handle
NotificationResponse messages even when it is not engaged in a query.
-<Para>
<VariableList>
<VarListEntry>
<Term>
commands need not have anything to do with names of relations (tables)
in the SQL database. Notification names are simply arbitrarily chosen
condition names.
-
+</para>
+</sect2>
<Sect2>
<Title>Cancelling Requests in Progress</Title>
the frontend during query processing. Cancel requests should be relatively
infrequent, so we make them slightly cumbersome in order to avoid a penalty
in the normal case.
+</para>
<Para>
To issue a cancel request, the frontend opens a new connection to the
message that would ordinarily be sent across a new connection. The postmaster
will process this request and then close the connection. For security
reasons, no direct reply is made to the cancel request message.
+</para>
<Para>
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
request matches the PID and secret key for a currently executing backend, the
postmaster signals the backend to abort processing of the current query.
+</para>
<Para>
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
no effect. If the cancellation is effective, it results in the current
command being terminated early with an error message.
+</para>
<Para>
The upshot of all this is that for reasons of both security and efficiency,
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
succeeding.
+</para>
<Para>
Since the cancel request is sent to the postmaster and not across the
unauthorized persons might try to cancel queries. The security risk is
addressed by requiring a dynamically generated secret key to be supplied
in cancel requests.
-
+</para>
+</sect2>
<Sect2>
<Title>Termination</Title>
The normal, graceful termination procedure is that the frontend sends a
Terminate message and immediately closes the connection. On receipt of the
message, the backend immediately closes the connection and terminates.
+</para>
<Para>
An ungraceful termination may occur due to software failure (i.e., core dump)
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
to terminate itself.
-
+</para>
+</sect2>
+</sect1>
<Sect1>
<Title>Message Data Types</Title>
<Para>
This section describes the base data types used in messages.
-<Para>
<VariableList>
<VarListEntry>
<Term>
</VarListEntry>
</VariableList>
</Para>
+</sect1>
<Sect1>
<Title>Message Formats</Title>
<Para>
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).
-
-<Para>
+</para>
<VariableList>
<VarListEntry>
</VarListEntry>
</VariableList>
-<Para>
-
</Para>
+
</ListItem>
</VarListEntry>
<VarListEntry>
</ListItem>
</VarListEntry>
</VariableList>
-</Para>
+</sect1>
</Chapter>
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
starting the program.
+</para>
<Para>
In csh/tcsh or other C shells:
<ProgramListing>
unset PAGER
</ProgramListing>
-
+</para>
+</sect1>
</Chapter>
single <FileName>postmaster</FileName> process constitutes an installation
or site.
</Para>
+</sect1>
<Sect1>
<Title>Creating a New Class</Title>
date date
);
</ProgramListing>
+</para>
<Para>
Note that keywords are case-insensitive and identifiers
are usually case-insensitive.
<Acronym>Postgres</Acronym> allows <Acronym>SQL92</Acronym> <FirstTerm>delimited identifiers</FirstTerm>
(identifiers surrounded by double-quotes) to include mixed-case and spaces, tabs, etc.
+</para>
<Para>
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual
classes have properties that are extensions of the
relational model.
</Para>
+</sect1>
<Sect1>
<Title>Populating a Class with Instances</Title>
INSERT INTO weather
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
</ProgramListing>
+</para>
<Para>
You can also use the <Command>copy</Command> command to perform load large
where the path name for the source file must be available to the backend server
machine, not just the client.
+</para>
+</sect1>
<Sect1>
<Title>Querying a Class</Title>
<ProgramListing>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</ProgramListing>
+</para>
<Para>
Arbitrary Boolean operators
ORDER BY city;
</ProgramListing>
</Para>
+</sect1>
<Sect1>
<Title>Redirecting SELECT Queries</Title>
<ProgramListing>
SELECT * INTO TABLE temp FROM weather;
</ProgramListing>
+</para>
<Para>
This forms an implicit <Command>create</Command> command, creating a new
then, of course, perform any operations on the resulting
class that we can perform on other classes.
</Para>
+</sect1>
<Sect1>
<Title>Joins Between Classes</Title>
the <Command>select distinct</Command> statement.
</Para>
</Note>
+</para>
<Para>
In this case, both W1 and W2 are surrogates for an
A query can contain an arbitrary number of
class names and surrogates.
</Para>
+</sect1>
<Sect1>
<Title>Updates</Title>
WHERE date > '11/28/1994';
</ProgramListing>
</Para>
+</sect1>
<Sect1>
<Title>Deletions</Title>
empty. The system will not request confirmation before
doing this.
</Para>
+</sect1>
<Sect1>
<Title>Using Aggregate Functions</Title>
GROUP BY city;
</ProgramListing>
</Para>
-
+</sect1>
</Chapter>
Consult these commands for more details;
for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt.
</Para>
+</sect1>
<Sect1>
<Title>Concepts</Title>
single <Application>postmaster</Application> process constitutes an installation
or site.
</Para>
+</sect1>
<Sect1>
<Title>Creating a New Class</Title>
date date
);
</ProgramListing>
+</para>
<Para>
Note that both keywords and identifiers are case-insensitive; identifiers can become
classes have properties that are extensions of the
relational model.
</Para>
+</sect1>
<Sect1>
<Title>Populating a Class with Instances</Title>
INSERT INTO weather
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
</ProgramListing>
+</Para>
<Para>
You can also use the <Command>copy</Command> command to perform load large
amounts of data from flat (<Acronym>ASCII</Acronym>) files.
</Para>
+</sect1>
<Sect1>
<Title>Querying a Class</Title>
<ProgramListing>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</ProgramListing>
+</Para>
<Para>
Arbitrary Boolean operators
ORDER BY city;
</ProgramListing>
</Para>
+</sect1>
<Sect1>
<Title>Redirecting SELECT Queries</Title>
<ProgramListing>
SELECT * INTO TABLE temp FROM weather;
</ProgramListing>
+</Para>
<Para>
This forms an implicit <Command>create</Command> command, creating a new
then, of course, perform any operations on the resulting
class that we can perform on other classes.
</Para>
+</sect1>
<Sect1>
<Title>Joins Between Classes</Title>
the <Command>select distinct</Command> statement.
</Para>
</Note>
+</para>
<Para>
In this case, both W1 and W2 are surrogates for an
A query can contain an arbitrary number of
class names and surrogates.
</Para>
+</sect1>
<Sect1>
<Title>Updates</Title>
WHERE date > '11/28/1994';
</ProgramListing>
</Para>
+</sect1>
<Sect1>
<Title>Deletions</Title>
empty. The system will not request confirmation before
doing this.
</Para>
+</sect1>
<Sect1>
<Title>Using Aggregate Functions</Title>
GROUP BY city;
</ProgramListing>
</Para>
-
+</sect1>
</Chapter>
<REFPURPOSE>
Aborts the current transaction
</REFPURPOSE>
+</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-27</DATE>
</TITLE>
<PARA>
None.
+</para>
</REFSECT2>
<LISTITEM>
<PARA>
Message returned if successful.
-
+</para>
+</listitem>
+</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
NOTICE: UserAbortTransactionBlock and not in in-progress state
<LISTITEM>
<PARA>
If there is not any transaction currently in progress.
-
+</para>
+</listitem>
</VARLISTENTRY>
</VARIABLELIST>
-
+</para>
</REFSECT2>
</REFSYNOPSISDIV>
This command is identical
in behavior to the <acronym>SQL92</acronym> command <command>ROLLBACK</command>,
and is present only for historical reasons.
-
+</para>
<REFSECT2 ID="R2-SQL-ABORT-3">
<REFSECT2INFO>
<DATE>1998-09-27</DATE>
<para>
Use the <command>COMMIT</command> statement to successfully
terminate a transaction.
-
+</para>
+</refsect2>
</REFSECT1>
<REFSECT1 ID="R1-SQL-ABORT-2">
--
ABORT WORK;
</ProgramListing>
+</para>
</REFSECT1>
<TITLE>
Compatibility
</TITLE>
-<PARA>
<REFSECT2 ID="R2-SQL-ABORT-4">
<REFSECT2INFO>
for historical reasons. <command>ROLLBACK</command> is the <acronym>SQL92</acronym>
equivalent command.
</PARA>
+</refsect2>
+</refsect1>
</REFENTRY>
<REFPURPOSE>
Modifies table properties
</REFPURPOSE>
+</refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
-
+</para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-ALTERTABLE-2">
<LISTITEM>
<PARA>
Message returned if table or column is not available.
-
+</para>
+</listitem>
+</VARLISTENTRY>
</VARIABLELIST>
-
+</para>
</REFSECT2>
</REFSYNOPSISDIV>
the affected table. Thus, the table or column will
remain of the same type and size after this command is
executed.
+</para>
<PARA>
You must own the table in order to change its schema.
</PARA>
</TITLE>
<PARA>
The keyword COLUMN is noise and can be omitted.
-
+</para>
<PARA>
<Quote>[*]</Quote> following a name of a table indicates that statement
should be run over that table and all tables below it in the
inheritance hierarchy.
The <citetitle>PostgreSQL User's Guide</citetitle> has further
information on inheritance.
+</para>
<PARA>
Refer to CREATE TABLE for a further description
of valid arguments.
-
+</para>
</REFSECT2>
</REFSECT1>
<ProgramListing>
ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
</ProgramListing>
+</para>
<PARA>
To rename an existing column:
<ProgramListing>
ALTER TABLE distributors RENAME COLUMN address TO city;
</ProgramListing>
+</para>
<PARA>
To rename an existing table:
<ProgramListing>
ALTER TABLE distributors RENAME TO suppliers;
</ProgramListing>
+</para>
</REFSECT1>
<PARA>
<command>ALTER TABLE/RENAME</command>
is a <productname>Postgres</productname> language extension.
+</para>
<PARA>
SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
statement which are not yet directly supported by
<ProductName>Postgres</ProductName>:
+</para>
<VARIABLELIST>
<VARLISTENTRY>
the new definition. If any constraints on this column already
exist, they will be retained using a boolean AND with the new
constraint.
+</para>
<PARA>
Currently, to set new default constraints on an existing column
constraints can be destroyed.
If CASCADE is specified, Any constraints that are dependent on
this constraint are also dropped.
+</para>
<PARA>
Currently, to remove a default value or constraints on an
CREATE TABLE distributors AS SELECT * FROM temp;
DROP TABLE temp;
</ProgramListing>
-
+</para>
+</listitem>
+</varlistentry>
+
<VARLISTENTRY>
<TERM>
<Synopsis>
objects can be destroyed.
If CASCADE is specified, all objects that are dependent on
this column are also dropped.
+</para>
<PARA>
Currently, to remove an existing column the table must be
DROP TABLE temp;
</ProgramListing>
</PARA>
+</listitem>
+</varlistentry>
</VARIABLELIST>
+</refsect2>
+</refsect1>
</REFENTRY>
<REFPURPOSE>
Modifies user account information
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
<TITLE>
Outputs
</TITLE>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <returnvalue>ALTER USER</returnvalue>
- </TERM>
- <LISTITEM>
- <PARA>
- Message returned if the alteration was successful.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
-
- <VARLISTENTRY>
- <TERM>
- <returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
- </TERM>
- <LISTITEM>
- <PARA>
- Error message returned if the user specified doesn't
- exist.
-
- </variablelist>
- </REFSECT2>
- </REFSYNOPSISDIV>
-
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <returnvalue>ALTER USER</returnvalue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the alteration was successful.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+
+ <VARLISTENTRY>
+ <TERM>
+ <returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Error message returned if the user specified doesn't
+ exist.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
<REFSECT1 ID="R1-SQL-ALTERUSER-1">
<REFSECT1INFO>
<DATE>1998-09-08</DATE>
The standard leaves
the definition of users to the implementation.
</PARA>
+ </refsect2>
</refsect1>
</REFENTRY>
Begins a transaction
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
Inputs
</TITLE>
<PARA>
- None
+ None
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-BEGINWORK-2">
<returnvalue>NOTICE: BeginTransactionBlock and not in default state</returnvalue>
</TERM>
<LISTITEM>
- <PARA>
- This indicates that a transaction was already in progress.
-The current transaction is not affected.
-
- </VARIABLELIST>
+ <PARA>
+ This indicates that a transaction was already in progress.
+ The current transaction is not affected.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
to terminate a transaction.
</PARA>
</REFSECT2>
+ </refsect1>
<REFSECT1 ID="R1-SQL-BEGINWORK-2">
<TITLE>
<ProgramListing>
BEGIN WORK;
</ProgramListing>
+ </para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-BEGINWORK-3">
<PARA>
<command>BEGIN</command>
is a <productname>Postgres</productname> language extension.
-
+ </para>
<REFSECT2 ID="R2-SQL-BEGINWORK-4">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
<REFPURPOSE>
Close a cursor
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CLOSE-2">
This warning is given if
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> is not
declared or has already been closed.
-
- </VARIABLELIST>
-
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFPURPOSE>
Gives storage clustering advice to the backend
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
- <REFSYNOPSISDIVINFO>
- <DATE>1998-09-08</DATE>
- </REFSYNOPSISDIVINFO>
- <SYNOPSIS>
-CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
- </SYNOPSIS>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-09-08</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CLUSTER-1">
<REFSECT2INFO>
</LISTITEM>
</VARLISTENTRY>
- </VARIABLELIST>
-
- </REFSECT2>
+ </VARIABLELIST>
+ </para>
+ </REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CLUSTER-1">
<TITLE>
Notes
</TITLE>
- <PARA>
+
<para>
The table is actually copied to a temporary table in index
order, then renamed back to the original name. For this
will not be preserved. From then on, <command>CLUSTER</command> should be
fast because most of the heap data has already been
ordered, and the existing index is used.
- </para>
-
-
+ </para>
+ </refsect2>
+ </refsect1>
+
<REFSECT1 ID="R1-SQL-CLUSTER-2">
- <TITLE>
- Usage
- </TITLE>
- <PARA>
- Cluster the employees relation on the basis of its salary attribute
- </PARA>
- <ProgramListing>
-CLUSTER emp_ind ON emp
- </ProgramListing>
+ <TITLE>
+ Usage
+ </TITLE>
+ Cluster the employees relation on the basis of its salary attribute
+ </PARA>
+ CLUSTER emp_ind ON emp
+ </ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CLUSTER-3">
- <TITLE>
- Compatibility
- </TITLE>
- <PARA>
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CLUSTER-4">
- <REFSECT2INFO>
- <DATE>1998-09-08</DATE>
- </REFSECT2INFO>
<TITLE>
- SQL92
+ Compatibility
</TITLE>
<PARA>
- There is no <command>CLUSTER</command> statement in SQL92.
</PARA>
- </refsect2>
+
+ <REFSECT2 ID="R2-SQL-CLUSTER-4">
+ <REFSECT2INFO>
+ <DATE>1998-09-08</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no <command>CLUSTER</command> statement in SQL92.
+ </PARA>
+ </refsect2>
</refsect1>
</REFENTRY>
<REFPURPOSE>
Commits the current transaction
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
Inputs
</TITLE>
<PARA>
-None
-
+ None
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-COMMIT-2">
<VARLISTENTRY>
<TERM>
<returnvalue>NOTICE EndTransactionBlock and not inprogress/abort state</returnvalue>
- </TERM>
- <LISTITEM>
- <PARA>
-If there is no transaction in progress.
-
- </VARIABLELIST>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ If there is no transaction in progress.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
<REFPURPOSE>
Copies data between files and tables
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-08</DATE>
<LISTITEM>
<PARA>
Specifies that output goes to a pipe or terminal.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <replaceable class="parameter">delimiter</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- A character that delimits the input or output fields.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">delimiter</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ A character that delimits the input or output fields.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-COPY-2">
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: <replaceable>error message</replaceable></ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- The copy failed for the reason stated in the error message.
-
- </VARIABLELIST>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The copy failed for the reason stated in the error message.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
<TITLE>
Description
</TITLE>
- <PARA>
+ <para>
<command>COPY</command> moves data between
<productname>Postgres</productname> tables and
standard Unix files.
-<para>
-<command>COPY</command> instructs
- the <productname>Postgres</productname> backend
-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.
-If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
-the backend.
-
+ <command>COPY</command> instructs
+ the <productname>Postgres</productname> backend
+ 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.
+ If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
+ the backend.
+ </para>
<REFSECT2 ID="R2-SQL-COPY-3">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
<TITLE>
Notes
</TITLE>
- <para>
- The BINARY keyword will force all data to be
- stored/read as binary objects rather than as text. It is
- somewhat faster than the normal copy command, but is not
- generally portable, and the files generated are somewhat larger,
- although this factor is highly dependent on the data itself. By
- default, a text copy uses a tab ("\t") character as a delimiter.
- The delimiter may also be changed to any other single character
- with the keyword phrase USING DELIMITERS. Characters
- in data fields which happen to match the delimiter character will
- be quoted.
- </para>
-
- <para>
+ The BINARY keyword will force all data to be
+ stored/read as binary objects rather than as text. It is
+ somewhat faster than the normal copy command, but is not
+ generally portable, and the files generated are somewhat larger,
+ although this factor is highly dependent on the data itself. By
+ default, a text copy uses a tab ("\t") character as a delimiter.
+ The delimiter may also be changed to any other single character
+ with the keyword phrase USING DELIMITERS. Characters
+ in data fields which happen to match the delimiter character will
+ be quoted.
+ </para>
+
You must have select access on any table whose values are read by
<command>COPY</command>, and either insert or update access to a
table into which values are being inserted by <command>COPY</command>.
The backend also needs appropriate Unix permissions for any file read
or written by <command>COPY</command>.
- </para>
- <para>
+ </para>
The keyword phrase USING DELIMITERS specifies a single character
-to be used for all delimiters between columns. If multiple characters
-are specified in the delimiter string, only the first character is
+ to be used for all delimiters between columns. If multiple characters
+ are specified in the delimiter string, only the first character is
used.
-
- <tip>
-<para>
- Do not confuse <command>COPY</command> with the
- <application>psql</application> instruction <command>\copy</command>.
-</tip>
-
+
+ <tip>
+ <para>
+ Do not confuse <command>COPY</command> with the
+ <application>psql</application> instruction <command>\copy</command>.
+ </para>
+ </tip>
+ </para>
</REFSECT2>
</refsect1>
-
+
<refsect1 ID="R1-SQL-COPY-2">
<refsect1info>
<date>1998-05-04</date>
<REFPURPOSE>
Defines a new aggregate function
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
The initial value for the second transition function argument.
</para>
</listitem>
- </varlistentry>
- </variablelist>
-
+ </varlistentry>
+ </variablelist>
+ </para>
</REFSECT2>
-
+
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2">
<REFSECT2INFO>
<DATE>1998-09-09</DATE>
Outputs
</TITLE>
<PARA>
-
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>CREATE</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- Message returned if the command completes successfully.
- </VARIABLELIST>
-
+
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the command completes successfully.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
-
+
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-1">
<REFSECT1INFO>
<DATE>1998-09-09</DATE>
<TITLE>
Description
</TITLE>
-<para>
- <command>CREATE AGGREGATE</command>
-allows a user or programmer to extend <productname>Postgres</productname>
-functionality by defining new aggregate functions. Some aggregate functions
-for base types such as <function>min(int4)</function>
- and <function>avg(float8)</function> are already provided in the base
-distribution. If one defines new types or needs an aggregate function not
-already provided then <command>CREATE AGGREGATE</command>
-can be used to provide the desired features.
-
+ <command>CREATE AGGREGATE</command>
+
allows a user or programmer to extend <productname>Postgres</productname>
+ functionality by defining new aggregate functions. Some aggregate functions
+ for base types such as <function>min(int4)</function>
+ and <function>avg(float8)</function> are already provided in the base
+ distribution. If one defines new types or needs an aggregate function not
+ already provided then <command>CREATE AGGREGATE</command>
+ can be used to provide the desired features.
+ </para>
<PARA>
An aggregate function can require up to three functions, two
state transition functions,
-<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
- and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
-<programlisting>
-<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
-<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2
-</programlisting>
+ <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
+ and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
+ <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
+ <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2
+ </programlisting>
and a final calculation function,
- <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>:
-<programlisting>
-<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value
-</programlisting>
-
-<para>
-<productname>Postgres</productname> creates up to two temporary variables
-(referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
-and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>)
-to hold intermediate results used as arguments to the transition functions.
-
-<para>
+ <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>:
+ <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value
+ </programlisting>
+ </para>
+
<productname>Postgres</productname> creates up to two temporary variables
+ (referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
+ and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>)
+ to hold intermediate results used as arguments to the transition functions.
+ </para>
These transition functions are required to have the following properties:
<itemizedlist>
<listitem>
<para>
The arguments to
-<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
- must be
-<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
-of type
-<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
-and
-<REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE>
-of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>.
-The return value must be of type
-<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
-and will be used as the first argument in the next call to
-<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>.
+ <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
+ must be
+ <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
+ of type
+ <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
+ and
+ <REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE>
+ of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>.
+ The return value must be of type
+ <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
+ and will be used as the first argument in the next call to
+ <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>.
</para>
</listitem>
-
+
<listitem>
<para>
The argument and return value of
-<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
-must be
-<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
-of type
-<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
+ <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
+ must be
+ <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
+ of type
+ <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
</para>
</listitem>
<listitem>
<para>
The arguments to the final-calculation-function
must be
-<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
-and
-<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
-and its return value must
+ <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
+ and
+ <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
+ and its return value must
be a <productname>Postgres</productname>
- base type (not necessarily
- <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
-which had been specified for BASETYPE).
+ base type (not necessarily
+ <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
+ which had been specified for BASETYPE).
</para>
</listitem>
<listitem>
</listitem>
</itemizedlist>
</PARA>
-
+
<para>
An aggregate function may also require one or two initial conditions,
one for
well as a FINALFUNC (a division function) to produce its
answer. In any case, at least one state function must be
defined, and any SFUNC2 must have a corresponding INITCOND2.
- </para>
-
+ </para>
+
</REFSECT2>
-
+ </refsect1>
+
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2">
<TITLE>
Usage
</TITLE>
<PARA>
-Refer to the chapter on aggregate functions
- in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
- on aggregate functions for
-complete examples of usage.
-
+ Refer to the chapter on aggregate functions
+ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
+ on aggregate functions for
+ complete examples of usage.
+ </para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-3">
<TITLE>
Compatibility
</TITLE>
- <PARA>
-
+
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4">
<REFSECT2INFO>
-<DATE>1998-09-09</DATE>
+ <DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
<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.
</PARA>
-
+ </refsect2>
+ </refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
<REFPURPOSE>
Creates a new database
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
(e.g. '<filename>/usr/local/pgsql/data</filename>').
In either case, the location must be pre-configured
by <command>initlocation</command>.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
-
+
<REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: Unable to create database directory <replaceable class="parameter">directory</replaceable>
-</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
-There was a problem with creating the required directory; this operation will
-need permissions for the <literal>postgres</literal> user on the specified location.
-
- </VARIABLELIST>
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ There was a problem with creating the required directory; this operation will
+ need permissions for the <literal>postgres</literal> user on the specified location.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
Use <command>DROP DATABASE</command> to remove a database.
</para>
</REFSECT2>
-
+ </refsect1>
+
<REFSECT1 ID="R1-SQL-CREATEDATABASE-2">
<TITLE>
Usage
To create a new database:
</PARA>
<ProgramListing>
-<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
+
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
</ProgramListing>
<PARA>
To create a new database in an alternate area <filename>~/private_db</filename>:
</PARA>
<ProgramListing>
-<prompt>$</prompt> <userinput>mkdir private_db</userinput>
-<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
-<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
-
-<prompt>$</prompt> <userinput>psql olly</userinput>
-<computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
- Please read the file COPYRIGHT for copyright terms of POSTGRESQL
-
- type \? for help on slash commands
- type \q to quit
- type \g or terminate with semicolon to execute query
- You are currently connected to the database: template1
-
-<prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
- <computeroutput>CREATEDB</computeroutput>
+
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
+
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
+ <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
+
+
<prompt>$</prompt> <userinput>psql olly</userinput>
+ <computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
+ Please read the file COPYRIGHT for copyright terms of POSTGRESQL
+
+ type \? for help on slash commands
+ type \q to quit
+ type \g or terminate with semicolon to execute query
+ You are currently connected to the database: template1
+
+
<prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
+ <computeroutput>CREATEDB</computeroutput>
</ProgramListing>
</REFSECT1>
<TITLE>
Compatibility
</TITLE>
- <PARA>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
<REFSECT2INFO>
<REFPURPOSE>
Defines a new function
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">path</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- May be either an SQL-query or an absolute path to an
- object file.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <replaceable class="parameter">langname</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- may be '<literal>C</literal>', '<literal>sql</literal>',
- '<literal>internal</literal>'
- or '<replaceable class="parameter">plname</replaceable>',
- where '<replaceable class="parameter">plname</replaceable>'
- is the name of a created procedural
- language. See <command>CREATE LANGUAGE</command> for details.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ May be either an SQL-query or an absolute path to an
+ object file.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">langname</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ may be '<literal>C</literal>', '<literal>sql</literal>',
+ '<literal>internal</literal>'
+ or '<replaceable class="parameter">plname</replaceable>',
+ where '<replaceable class="parameter">plname</replaceable>'
+ is the name of a created procedural
+ language. See <command>CREATE LANGUAGE</command> for details.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
Outputs
</TITLE>
<PARA>
-
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>CREATE</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- This is returned if the command completes successfully.
- </VARIABLELIST>
+
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This is returned if the command completes successfully.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
</TITLE>
<PARA>
<command>CREATE FUNCTION</command> allows a
-<productname>Postgres</productname> user
-to register a function
+
<productname>Postgres</productname> user
+ to register a function
with a database. Subsequently, this user is treated as the
owner of the function.
</PARA>
<PARA>
Refer to the chapter on functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
- for further information.
+ for further information.
</PARA>
<PARA>
Use <command>DROP FUNCTION</command>
to drop user-defined functions.
</PARA>
</REFSECT2>
+ </refsect1>
<REFSECT1 ID="R1-SQL-CREATEFUNCTION-2">
<TITLE>
To create a simple SQL function:
</PARA>
<ProgramListing>
-CREATE FUNCTION one() RETURNS int4
- AS 'SELECT 1 AS RESULT'
- LANGUAGE 'sql';
-
-SELECT one() AS answer;
-
-<computeroutput>
-answer
-------
-1
-</computeroutput>
+ CREATE FUNCTION one() RETURNS int4
+ AS 'SELECT 1 AS RESULT'
+ LANGUAGE 'sql';
+
+ SELECT one() AS answer;
+
+ <computeroutput>
+ answer
+ ------
+ 1
+ </computeroutput>
</ProgramListing>
<para>
To create a C function, calling a routine from a user-created
is correct. It is intended for use in a CHECK contraint.
</para>
<programlisting>
-<userinput>
-CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
+ <userinput>
+ CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
-
-CREATE TABLE product
-(
- id char(8) PRIMARY KEY,
- eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
- REFERENCES brandname(ean_prefix),
- eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
- CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
-);</userinput>
+
+ CREATE TABLE product
+ (
+ id char(8) PRIMARY KEY,
+ eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
+ REFERENCES brandname(ean_prefix),
+ eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
+ CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
+ );</userinput>
</programlisting>
</REFSECT1>
<REFPURPOSE>
Constructs a secondary index
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
</programlisting>
</PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <replaceable class="parameter">func_name</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- A user-defined function, which returns a value that can
- be indexed.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
-
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">func_name</replaceable>
+ </TERM>
+ <LISTITEM>
+ A user-defined function, which returns a value that can
+ be indexed.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEINDEX-2">
</VARLISTENTRY>
<VARLISTENTRY>
- <TERM>
- <ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- This error occurs if it is impossible to create the index.
-
- </VARIABLELIST>
-
+ <TERM>
+ <ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This error occurs if it is impossible to create the index.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
Description
</TITLE>
<PARA>
- <command>CREATE INDEX</command> constructs an index
- <replaceable class="parameter">index_name</replaceable>.
-on the specified
-<replaceable class="parameter">table</replaceable>.
-
-<tip>
-<para>
-Indexes are primarily used to enhance database performance.
-But inappropriate use will result in slower performance.
-</tip>
-
+ <command>CREATE INDEX</command> constructs an index
+ <replaceable class="parameter">index_name</replaceable>.
+ on the specified
+ <replaceable class="parameter">table</replaceable>.
+
+ <tip>
+ <para>
+ Indexes are primarily used to enhance database performance.
+ But inappropriate use will result in slower performance.
+ </para>
+ </tip>
+ </para>
<para>
In the first syntax shown above, the key fields for the
index are specified as column names; a column may also have
to remove an index.
</para>
</REFSECT2>
-
+ </refsect1>
+
<REFSECT1 ID="R1-SQL-CREATEINDEX-2">
<TITLE>
Usage
<REFPURPOSE>
Defines a new language for functions
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
procedures.
</PARA>
</LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <replaceable class="parameter">comment</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- The <function>LANCOMPILER</function> argument is the
- string that will be
- inserted in the <literal>LANCOMPILER</literal> attribute
- of the new
- <filename>pg_language</filename> entry. At present,
- <productname>Postgres</productname> does not use
- this attribute in any way.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
-
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">comment</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The <function>LANCOMPILER</function> argument is the
+ string that will be
+ inserted in the <literal>LANCOMPILER</literal> attribute
+ of the new
+ <filename>pg_language</filename> entry. At present,
+ <productname>Postgres</productname> does not use
+ this attribute in any way.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
+
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-2">
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
- <TERM>
- <ReturnValue>ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- This error is returned if the function
- <replaceable class="parameter">funcname</replaceable>()
- is not found.
- </VARIABLELIST>
+ <TERM>
+ <ReturnValue>ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This error is returned if the function
+ <replaceable class="parameter">funcname</replaceable>()
+ is not found.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
file or anything else that tells the call handler what to
do in detail.
</para>
+ </refsect2>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-4">
<REFSECT2INFO>
of the dots to complete the PL call handler.
See <command>CREATE FUNCTION</command> for information on how to compile
it into a loadable module
-.</para>
+ .</para>
<para>
The following commands then register the sample procedural
language:
- <programlisting>
-CREATE FUNCTION plsample_call_handler () RETURNS opaque
+ CREATE FUNCTION plsample_call_handler () RETURNS opaque
AS '/usr/local/pgsql/lib/plsample.so'
LANGUAGE 'C';
-
-CREATE PROCEDURAL LANGUAGE 'plsample'
+
+ CREATE PROCEDURAL LANGUAGE 'plsample'
HANDLER plsample_call_handler
LANCOMPILER 'PL/Sample';
- </programlisting>
+ </programlisting>
+ </para>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-7">
<REFPURPOSE>
Defines a new user operator
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE>
Outputs
</TITLE>
<PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>CREATE</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- Message returned if the operator is successfully created.
-
- </VARIABLELIST>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the operator is successfully created.
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
Description
</TITLE>
<PARA>
-<command>CREATE OPERATOR</command> defines a new operator,
- <replaceable class="parameter">name</replaceable>.
- The user who defines an operator becomes its owner.
- </para>
- The operator <replaceable class="parameter">name</replaceable>
- is a sequence of up to thirty two (32) characters in any combination
-from the following:
-<literallayout>
- + - * / < > = ~ ! @ # % ^ & | ` ? $ :
-</literallayout>
-<note>
-<para>
-No alphabetic characters are allowed in an operator name.
-This enables <productname>Postgres</productname> to parse SQL input
-into tokens without requiring spaces between each token.
-</note>
-
- </para>
+ <command>CREATE OPERATOR</command> defines a new operator,
+ <replaceable class="parameter">name</replaceable>.
+ The user who defines an operator becomes its owner.
+ </para>
+ <para>
+ The operator <replaceable class="parameter">name</replaceable>
+ is a sequence of up to thirty two (32) characters in any combination
+ from the following:
+ <literallayout>
+ + - * / < > = ~ ! @ # % ^ & | ` ? $ :
+ </literallayout>
+ <note>
+ No alphabetic characters are allowed in an operator name.
+
This enables <productname>Postgres</productname> to parse SQL input
+ into tokens without requiring spaces between each token.
+ </para>
+ </note>
+ </para>
<para>
The operator "!=" is mapped to "<>" on input, so they are
therefore equivalent.
unary operators only RIGHTARG should be defined.
</para>
<para>
-Also, the
- <replaceable class="parameter">func_name</replaceable> procedure must have
+ Also, the
+ <replaceable class="parameter">func_name</replaceable> procedure must have
been previously defined using <command>CREATE FUNCTION</command> and must
be defined to accept the correct number of arguments
- (either one or two).
+ (either one or two).
</para>
<para>
The commutator operator is present so that
- <productname>Postgres</productname> can
+
<productname>Postgres</productname> can
reverse the order of the operands if it wishes.
- For example, the operator area-less-than, <<<,
- would have a commutator
- operator, area-greater-than, >>>.
- Hence, the query optimizer could freely convert:
+ For example, the operator area-less-than, <<<,
+ would have a commutator
+ operator, area-greater-than, >>>.
+ Hence, the query optimizer could freely convert:
<programlisting>
-"0,0,1,1"::box >>> MYBOXES.description
+ "0,0,1,1"::box >>> MYBOXES.description
</programlisting>
to
<programlisting>
-MYBOXES.description <<< "0,0,1,1"::box</programlisting>
+ MYBOXES.description <<< "0,0,1,1"::box</programlisting>
</para>
<para>
This allows the execution code to always use the latter
what.
</para>
<para>
- Suppose that an
+ Suppose that an
operator, area-equal, ===, exists, as well as an area not
equal, !==.
The negator operator allows the query optimizer to convert
<programlisting>
-NOT MYBOXES.description === "0,0,1,1"::box
+ NOT MYBOXES.description === "0,0,1,1"::box
</programlisting>
to
<programlisting>
-MYBOXES.description !== "0,0,1,1"::box
+ MYBOXES.description !== "0,0,1,1"::box
</programlisting>
</para>
<para>
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
does not yet have a commutator itself, then the commutator's
entry is updated to have the current (new) operator
<para>
The next two specifications are present to support the
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
variables separated by an operator that returns a boolean)
by iterative substitution [WONG76].
-In addition, <productname>Postgres</productname>
+
In addition, <productname>Postgres</productname>
is planning on implementing a hash-join algorithm along
the lines of [SHAP86]; however, it must know whether this
strategy is applicable.
-For example, a hash-join
+ For example, a hash-join
algorithm is usable for a clause of the form:
<programlisting>
-MYBOXES.description === MYBOXES2.description
+ MYBOXES.description === MYBOXES2.description
</programlisting>
but not for a clause of the form:
<programlisting>
-MYBOXES.description <<< MYBOXES2.description.
+ MYBOXES.description <<< MYBOXES2.description.
</programlisting>
The HASHES flag gives the needed information to the query
optimizer concerning whether a hash join strategy is
sort both relations using the operator, <<<. On the other
hand, merge-sort is not usable with the clause:
<programlisting>
-MYBOXES.description <<< MYBOXES2.description
+ MYBOXES.description <<< MYBOXES2.description
</programlisting>
</para>
<para>
If other join strategies are found to be practical,
-<productname>Postgres</productname>
- will change the optimizer and run-time system to use
+
<productname>Postgres</productname>
+ will change the optimizer and run-time system to use
them and will require additional specification when an
operator is defined. Fortunately, the research community
invents new join strategies infrequently, and the added
the query optimizer can estimate result sizes. If a
clause of the form:
<programlisting>
-MYBOXES.description <<< "0,0,1,1"::box
+ MYBOXES.description <<< "0,0,1,1"::box
</programlisting>
is present in the qualification,
- then <productname>Postgres</productname> may have to
+
then <productname>Postgres</productname> may have to
estimate the fraction of the instances in MYBOXES that
satisfy the clause. The function
- <replaceable class="parameter">res_proc</replaceable>
- must be a registered function (meaning it is already defined using
+ <replaceable class="parameter">res_proc</replaceable>
+ must be a registered function (meaning it is already defined using
define function(l)) which accepts one argument of the correct
data type and returns a floating point number. The
query optimizer simply calls this function, passing the
<para>
The difference between the function
<programlisting>
-my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
+ my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
</programlisting>
and the operator
<programlisting>
-MYBOXES.description === "0,0,1,1"::box
+ MYBOXES.description === "0,0,1,1"::box
</programlisting>
is that <productname>Postgres</productname>
- attempts to optimize operators and can
+ attempts to optimize operators and can
decide to use an index to restrict the search space when
operators are involved. However, there is no attempt to
optimize functions, and they are performed by brute force.
</TITLE>
<PARA>
Refer to the chapter on operators in the
-<citetitle>PostgreSQL User's Guide</citetitle>
+ <citetitle>PostgreSQL User's Guide</citetitle>
for further information.
Refer to <command>DROP OPERATOR</command> to delete
-user-defined operators from a database.
-
+ user-defined operators from a database.
+ </para>
</REFSECT2>
+ </refsect1>
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-2">
<TITLE>
area-equality, for the BOX data type.
</PARA>
<ProgramListing>
-CREATE OPERATOR === (
- LEFTARG = box,
- RIGHTARG = box,
- PROCEDURE = area_equal_procedure,
- COMMUTATOR = ===,
- NEGATOR = !==,
- RESTRICT = area_restriction_procedure,
- HASHES,
- JOIN = area-join-procedure,
- SORT = <<<, <<<)
- </ProgramListing>
-
-
+ CREATE OPERATOR === (
+ LEFTARG = box,
+ RIGHTARG = box,
+ PROCEDURE = area_equal_procedure,
+ COMMUTATOR = ===,
+ NEGATOR = !==,
+ RESTRICT = area_restriction_procedure,
+ HASHES,
+ JOIN = area-join-procedure,
+ SORT = <<<, <<<)
+ </ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-3">
<REFPURPOSE>
Defines a new rule
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-11</DATE>
<LISTITEM>
<PARA>
Message returned if the rule is successfully created.
-
- </VARLISTENTRY>
- </VARIABLELIST>
-
+ </para>
+ </listitem>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
<para>
You must have rule definition access to a class in order
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>
</REFSECT2>
</refsect1>
fail if the rule plus its various internal representations
exceed some value that is on the order of one page (8KB).
</PARA>
+ </refsect1>
<REFSECT1 ID="R1-SQL-CREATERULE-4">
<TITLE>
<REFPURPOSE>
Creates a new sequence number generator
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<LISTITEM>
<PARA>
If the minimum and maximum values are inconsistant.
-
- </VARIABLELIST>
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
</para>
<caution>
-<para>
- 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
- backends. Each backend will allocate "cache" successive sequence values
- during one access to the sequence object and increase the sequence
- object's last_value accordingly. Then, the next cache-1 uses of nextval
- within that backend simply return the preallocated values without touching
- the shared object. So, numbers allocated but not used in the current session
- will be lost. Furthermore, although multiple backends are guaranteed to
- allocate distinct sequence values, the values may be generated out of
- 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,
-then
- 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
- to assume that nextval values are generated sequentially; with a cache
- setting greater than one you should only assume that the nextval values
- are all distinct, not that they are generated purely sequentially.
- Also, last_value will reflect the latest value reserved by any backend,
- whether or not it has yet been returned by nextval.
-</caution>
+ <para>
+ 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
+ backends. Each backend will allocate "cache" successive sequence values
+ during one access to the sequence object and increase the sequence
+ object's last_value accordingly. Then, the next cache-1 uses of nextval
+ within that backend simply return the preallocated values without touching
+ the shared object. So, numbers allocated but not used in the current session
+ will be lost. Furthermore, although multiple backends are guaranteed to
+ allocate distinct sequence values, the values may be generated out of
+ 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,
+ then
+ 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
+ to assume that nextval values are generated sequentially; with a cache
+ setting greater than one you should only assume that the nextval values
+ are all distinct, not that they are generated purely sequentially.
+ Also, last_value will reflect the latest value reserved by any backend,
+ whether or not it has yet been returned by nextval.
+ </para>
+ </caution>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-3">
<REFSECT2INFO>
<para>
Set the sequence value after a COPY FROM:
<programlisting>
-CREATE FUNCTION distributors_id_max() RETURNS INT4
- AS 'SELECT max(id) FROM distributors'
- LANGUAGE 'sql';
-BEGIN;
-COPY distributors FROM 'input_file';
-SELECT setval('serial', distributors_id_max());
-END;
+ CREATE FUNCTION distributors_id_max() RETURNS INT4
+ AS 'SELECT max(id) FROM distributors'
+ LANGUAGE 'sql';
+ BEGIN;
+ COPY distributors FROM 'input_file';
+ SELECT setval('serial', distributors_id_max());
+ END;
</programlisting>
</para>
-
+
</REFSECT1>
<REFSECT1 ID="R1-SQL-CREATESEQUENCE-3">
</TITLE>
<PARA>
<command>CREATE SEQUENCE</command> is a <productname>Postgres</productname>
- language extension.
+ language extension.
</PARA>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-4">
<REFPURPOSE>
Creates a new table
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-11</DATE>
<SYNOPSIS>
CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> (
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
- [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>]
- [, NOT NULL ] [ ,UNIQUE ]
+ [ NULL | NOT NULL ] [ UNIQUE ] [ DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE> ]
[<REPLACEABLE>column_constraint_clause</REPLACEABLE> | PRIMARY KEY } [ ... ] ]
[, ... ]
[, PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
</LISTITEM>
</VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- INHERITS <REPLACEABLE CLASS="PARAMETER">inherited_table</REPLACEABLE>
- </TERM>
- <LISTITEM>
- <PARA>
- The optional INHERITS clause specifies a collection of table
- names from which this table automatically inherits all fields.
- If any inherited field name appears more than once,
-<productname>Postgres</productname>
- reports an error.
- <productname>Postgres</productname> automatically allows the created
- table to inherit functions on tables above it in the inheritance
- hierarchy.
-<note>
-<title>Aside</title>
-<para>
- Inheritance of functions is done according
- to the conventions of the Common Lisp Object System (CLOS).
-</note>
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
-
- </VARIABLELIST>
-
-
+ <VARLISTENTRY>
+ <TERM>
+ INHERITS <REPLACEABLE CLASS="PARAMETER">inherited_table</REPLACEABLE>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The optional INHERITS clause specifies a collection of table
+ names from which this table automatically inherits all fields.
+ If any inherited field name appears more than once,
+ <productname>Postgres</productname>
+ reports an error.
+ <productname>Postgres</productname> automatically allows the created
+ table to inherit functions on tables above it in the inheritance
+ hierarchy.
+ <note>
+ <title>Aside</title>
+ <para>
+ Inheritance of functions is done according
+ to the conventions of the Common Lisp Object System (CLOS).
+ </para>
+ </note>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATETABLE-2">
<PARA>
if data type of default value doesn't match the
column definition's data type.
-
- </VARIABLELIST>
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
<command>CREATE TABLE</command> will enter a new table into the current data
base. The table will be "owned" by the user issuing the
command.
-
+ </para>
<PARA>
The new table is created as a heap with no initial data.
A table can have no more than 1600 columns (realistically,
lower at some sites. A table cannot have the same name as
a system catalog table.
</PARA>
-
+ </refsect1>
- <REFSECT1 ID="R1-SQL-DEFAULTCLAUSE-1">
+ <REFSECT1 ID="R1-SQL-DEFAULTCLAUSE-1">
<REFSECT1INFO>
<DATE>1998-09-11</DATE>
</REFSECT1INFO>
<SYNOPSIS>
DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
</SYNOPSIS>
-
+ </para>
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-1">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
<listitem>
<simpara>
a niladic function
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
+ </simpara>
</listitem>
- </VARLISTENTRY>
-
- </variablelist>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
+ </refsect2>
+
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-2">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
</REFSECT2INFO>
<TITLE>
- Outputs
- </TITLE>
- <PARA>
-
+ Outputs
+ </TITLE>
+ <para>
+ </para>
+ </refsect2>
+
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-3">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
</listitem>
</varlistentry>
</variablelist>
+ </para>
<para>
In the current release (v6.4), <productname>Postgres</productname>
</quote>.
This forces <productname>Postgres</productname> to consider the constant a string
type and then to convert the value to <type>timestamp</type> at runtime.
-
+ </para>
+ </refsect2>
<REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-4">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
total CASH DEFAULT '$0.0'
);
</ProgramListing>
-
+ </para>
<PARA>
To assign an existing sequence
as the default for the column <literal>did</literal>,
name VARCHAR(40) DEFAULT 'luso films'
);
</ProgramListing>
-
+ </para>
+ </refsect2>
</REFSECT1>
<REFSECT1 ID="R1-SQL-COLUMNCONSTRAINT-1">
</TITLE>
<para>
<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>
+ </para>
<REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-1">
<REFSECT2INFO>
</LISTITEM>
</VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ NULL
+ </TERM>
+ <LISTITEM>
+ <PARA>
+The column is allowed to contain NULL values. This is the default.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+
<VARLISTENTRY>
<TERM>
NOT NULL
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
+ </para>
+ </refsect2>
<REFSECT2 ID="R2-SQL-COLUMNCONSTRAINT-2">
<REFSECT2INFO>
accepts the REFERENCES syntax but ignores the clause.
</para>
</note>
+ </refsect2>
<REFSECT2 ID="R2-SQL-NOTNULL-1">
<REFSECT2INFO>
as a table constraint.
</PARA>
- <REFSECT3 ID="R3-SQL-NOTNULL-1">
- <REFSECT3INFO>
- <DATE>1998-09-11</DATE>
- </REFSECT3INFO>
- <TITLE>
- Outputs
- </TITLE>
- <PARA>
- </PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
-<replaceable>status</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>ERROR: ExecAppend: Fail to add null value in not
- null attribute "<replaceable class="parameter">column</replaceable>".</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- This error occurs at runtime if one tries to insert a null value
- into a column which has a NOT NULL constraint.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
-
- <REFSECT3 ID="R3-SQL-NOTNULL-2">
- <REFSECT3INFO>
- <DATE>1998-09-11</DATE>
- </REFSECT3INFO>
- <TITLE>
-Description
-</title>
-<para>
-
- <REFSECT3 ID="R3-SQL-NOTNULL-3">
- <REFSECT3INFO>
- <DATE>1998-09-11</DATE>
- </REFSECT3INFO>
- <TITLE>
-Usage
-</title>
-
- <PARA>
- Define two NOT NULL column constraints on the table
- <classname>distributors</classname>,
-one of which being a named constraint:
- </PARA>
- <ProgramListing>
-CREATE TABLE distributors (
- did DECIMAL(3) CONSTRAINT no_null NOT NULL,
- name VARCHAR(40) NOT NULL
-);
- </ProgramListing>
+ <REFSECT3 ID="R3-SQL-NOTNULL-1">
+ <REFSECT3INFO>
+ <DATE>1998-09-11</DATE>
+ </REFSECT3INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable>status</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: ExecAppend: Fail to add null value in not
+ null attribute "<replaceable class="parameter">column</replaceable>".</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This error occurs at runtime if one tries to insert a null value
+ into a column which has a NOT NULL constraint.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </refsect3>
+ <REFSECT3 ID="R3-SQL-NOTNULL-2">
+ <REFSECT3INFO>
+ <DATE>1998-09-11</DATE>
+ </REFSECT3INFO>
+ <TITLE>
+ Description
+ </title>
+ <para>
+ </para>
+ </refsect3>
+
+ <REFSECT3 ID="R3-SQL-NOTNULL-3">
+ <REFSECT3INFO>
+ <DATE>1998-09-11</DATE>
+ </REFSECT3INFO>
+ <TITLE>
+ Usage
+ </title>
+
+ <PARA>
+ Define two NOT NULL column constraints on the table
+ <classname>distributors</classname>,
+ one of which being a named constraint:
+
+ <ProgramListing>
+ CREATE TABLE distributors (
+ did DECIMAL(3) CONSTRAINT no_null NOT NULL,
+ name VARCHAR(40) NOT NULL
+ );
+ </ProgramListing>
+ </para>
+ </refsect3>
+ </refsect2>
+
<REFSECT2 ID="R2-SQL-UNIQUECLAUSE-1">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
<refsect3>
<title>Inputs</title>
-<para>
- <variablelist>
- <varlistentry>
- <term>
- CONSTRAINT <replaceable class="parameter">name</replaceable>
- </term>
- <listitem>
- <para>
- An arbitrary label given to a constraint.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ CONSTRAINT <replaceable class="parameter">name</replaceable>
+ </term>
+ <listitem>
+ <para>
+ An arbitrary label given to a constraint.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
</refsect3>
-
+
<refsect3>
<title>Outputs</title>
<PARA>
<para>
This error occurs at runtime if one tries to insert a
duplicate value into a column.
- </para>
- </listitem>
- </varlistentry>
- </variablelist></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
</refsect3>
-
+
<refsect3>
<title>
Description
data integrity. See CREATE INDEX for more information.
</Para>
</Note>
+ </refsect3>
<REFSECT3 ID="R3-SQL-UNIQUECLAUSE-3">
<TITLE>
UNIQUE(name)
);
</ProgramListing>
+ </para>
+ </refsect3>
+ </refsect2>
<REFSECT2 ID="R2-SQL-CHECK-1">
<REFSECT2INFO>
<LISTITEM>
<PARA>
An arbitrary name given to a constraint.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <replaceable>condition</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- Any valid conditional expression evaluating to a boolean result.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
- </REFSECT3>
-
- <REFSECT3 ID="R3-SQL-CHECK-2">
- <REFSECT3INFO>
- <DATE>1998-09-11</DATE>
- </REFSECT3INFO>
- <TITLE>
- Outputs
- </TITLE>
- <PARA>
- <VARIABLELIST>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-<replaceable>status</replaceable>
+ <replaceable>condition</replaceable>
</TERM>
<LISTITEM>
<PARA>
-
+ Any valid conditional expression evaluating to a boolean result.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
+ </REFSECT3>
+
+ <REFSECT3 ID="R3-SQL-CHECK-2">
+ <REFSECT3INFO>
+ <DATE>1998-09-11</DATE>
+ </REFSECT3INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
- <ReturnValue>
- ERROR: ExecAppend: rejected due to CHECK constraint
- "<replaceable class="parameter">table_column</replaceable>".
- </ReturnValue>
+ <replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
- This error occurs at runtime if one tries to insert an illegal
- value into a column subject to a CHECK constraint.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
+
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ ERROR: ExecAppend: rejected due to CHECK constraint
+ "<replaceable class="parameter">table_column</replaceable>".
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This error occurs at runtime if one tries to insert an illegal
+ value into a column subject to a CHECK constraint.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
+ </para>
</REFSECT3>
-
+
<refsect3>
<title>Description</title>
<para>
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.
</PARA>
<PARA>
The SQL92 CHECK column constraints can only be defined on, and
refer to, one column of the table. <productname>Postgres</productname>
- does not have
+ does not have
this restriction.
</PARA>
</refsect3>
<para>
This occurs at run-time if one tries to insert a duplicate value into
a column subject to a PRIMARY KEY constraint.
- </PARA>
+ </PARA>
</listitem>
</varlistentry>
</variablelist>
disallow this.
</PARA>
</refsect3>
-
- <REFSECT1 ID="R1-SQL-TABLECONSTRAINT-1">
- <REFSECT1INFO>
- <DATE>1998-09-11</DATE>
- </REFSECT1INFO>
- <TITLE>
+ </refsect2>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-TABLECONSTRAINT-1">
+ <REFSECT1INFO>
+ <DATE>1998-09-11</DATE>
+ </REFSECT1INFO>
+ <TITLE>
Table CONSTRAINT Clause
- </TITLE>
+ </TITLE>
+ <para>
<SYNOPSIS>
-[ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ...] )
-[ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> )
+ [ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ...] )
+ [ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> )
</SYNOPSIS>
- <PARA>
-
+ </para>
<REFSECT2 ID="R2-SQL-TABLECONSTRAINT-1">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
</REFSECT2INFO>
-<title>
-Inputs
-</title>
-
-<para>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- CONSTRAINT <replaceable class="parameter">name</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- An arbitrary name given to an integrity constraint.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <replaceable class="parameter">column</replaceable> [, ...]
- </TERM>
- <LISTITEM>
- <PARA>
- The column name(s) for which to define a unique index
-and, for PRIMARY KEY, a NOT NULL constraint.
- </PARA>
- </LISTITEM>
- <VARLISTENTRY>
- <TERM>
- CHECK ( <replaceable class="parameter">constraint</replaceable> )
- </TERM>
- <LISTITEM>
- <PARA>
- A boolean expression to be evaluated as the constraint.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
-
+ <title>
+ Inputs
+ </title>
+
+ <para>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ CONSTRAINT <replaceable class="parameter">name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ An arbitrary name given to an integrity constraint.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">column</replaceable> [, ...]
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The column name(s) for which to define a unique index
+ and, for PRIMARY KEY, a NOT NULL constraint.
+ </PARA>
+ </LISTITEM>
+ </varlistentry>
+ <VARLISTENTRY>
+ <TERM>
+ CHECK ( <replaceable class="parameter">constraint</replaceable> )
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ A boolean expression to be evaluated as the constraint.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
+ </refsect2>
+
<REFSECT2 ID="R2-SQL-TABLECONSTRAINT-2">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
</REFSECT2INFO>
-<title>
-Outputs
-</title>
-
-<para>
-The possible outputs for the table constraint clause are the same
-as for the corresponding portions of the column constraint clause.
-
+ <title>
+ Outputs
+ </title>
+
+ <para>
+ The possible outputs for the table constraint clause are the same
+ as for the corresponding portions of the column constraint clause.
+ </para>
+ </refsect2>
+
<REFSECT2 ID="R2-SQL-TABLECONSTRAINT-3">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
</REFSECT2INFO>
-<title>
-Description
-</title>
-
+ <title>
+ Description
+ </title>
+
<para>
A table constraint is an integrity constraint defined on one or
more columns of a base table. The four variations of "Table
<note>
<para>
<productname>Postgres</productname> does not yet
-(as of version 6.4) support FOREIGN KEY
-integrity constraints. The parser understands the FOREIGN KEY syntax,
-but only prints a notice and otherwise ignores the clause.
+ (as of version 6.4) support FOREIGN KEY
+ integrity constraints. The parser understands the FOREIGN KEY syntax,
+ but only prints a notice and otherwise ignores the clause.
Foreign keys may be partially emulated by triggers (See the CREATE TRIGGER
statement).
</para>
</note>
-
+ </refsect2>
+
<REFSECT2 ID="R2-SQL-UNIQUECLAUSE-4">
<REFSECT2INFO>
<DATE>1998-09-11</DATE>
UNIQUE Constraint
</TITLE>
<para>
- <synopsis>
-[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] )
- </SYNOPSIS>
+ <synopsis>
+ [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] )
+ </SYNOPSIS>
+ </para>
<refsect3>
<title>Inputs</title>
<variablelist>
<varlistentry>
<term>
- CONSTRAINT <replaceable class="parameter">name</replaceable>
+ CONSTRAINT <replaceable class="parameter">name</replaceable>
</term>
<listitem>
<para>
</varlistentry>
</variablelist>
</refsect3>
+
<refsect3>
<title>Outputs</title>
<PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
-<replaceable>status</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- ERROR: Cannot insert a duplicate key into a unique index.
- </term>
- <listitem>
- <para>
- This error occurs at runtime if one tries to insert a
- duplicate value into a column.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable>status</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ ERROR: Cannot insert a duplicate key into a unique index.
+ </term>
+ <listitem>
+ <para>
+ This error occurs at runtime if one tries to insert a
+ duplicate value into a column.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
</refsect3>
-
+
<refsect3>
<title>
-Description
+ Description
</title>
-
+
<PARA>
The UNIQUE constraint specifies a rule that a group of one or
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
-constraints, with the additional capability to span multiple columns.
+ The behavior of the UNIQUE table constraint is the same as that for column
+ constraints, with the additional capability to span multiple columns.
</para>
<para>
-See the section on the UNIQUE column constraint for more details.
-
- <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-4">
- <TITLE>
-Usage
-</title>
-
- <PARA>
- Define a UNIQUE table constraint for the table distributors:
- <ProgramListing>
-CREATE TABLE distributors (
- did DECIMAL(03),
- name VARCHAR(40),
- UNIQUE(name)
-);
- </ProgramListing>
-
+ See the section on the UNIQUE column constraint for more details.
+ </para>
+ </refsect3>
+ <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-4">
+ <TITLE>
+ Usage
+ </title>
+
+ <PARA>
+ Define a UNIQUE table constraint for the table distributors:
+ <ProgramListing>
+ CREATE TABLE distributors (
+ did DECIMAL(03),
+ name VARCHAR(40),
+ UNIQUE(name)
+ );
+ </ProgramListing>
+ </para>
+ </refsect3>
</REFSECT2>
<REFSECT2 ID="R2-SQL-PRIMARYKEY-4">
<TITLE>
PRIMARY KEY Constraint
</TITLE>
-<para>
- <SYNOPSIS>
- [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] )
- </SYNOPSIS>
-
+ <SYNOPSIS>
+ [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] )
+ </SYNOPSIS>
+ </para>
<refsect3>
<title>Inputs</title>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
-CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue>
+ CONSTRAINT <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue>
</TERM>
<LISTITEM>
<PARA>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...]
+ <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...]
</TERM>
<LISTITEM>
<PARA>
</VARIABLELIST>
</para>
</refsect3>
-
+
<refsect3>
<title>Outputs</title>
<variablelist>
<varlistentry>
<term>
-<replaceable>status</replaceable>
-</term>
-<listitem>
-<para>
- <variablelist>
- <varlistentry>
- <term>ERROR: Cannot insert a duplicate key into a unique index.</term>
+ <replaceable>status</replaceable>
+ </term>
<listitem>
<para>
- This occurs at run-time if one tries to insert a duplicate value into
- a column subject to a PRIMARY KEY constraint.
- </PARA>
- </listitem>
- </varlistentry>
- </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term>ERROR: Cannot insert a duplicate key into a unique index.</term>
+ <listitem>
+ <para>
+ This occurs at run-time if one tries to insert a duplicate value into
+ a column subject to a PRIMARY KEY constraint.
+ </PARA>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
-
+
<refsect3>
<title>Description</title>
<PARA>
(non duplicate), non-null values. The column definitions of
the specified columns do not have to include a NOT NULL
constraint to be included in a PRIMARY KEY constraint.
-
-The PRIMARY KEY table constraint is similar to that for column constraints,
-with the additional capability of encompassing multiple columns.
+
+ The PRIMARY KEY table constraint is similar to that for column constraints,
+ with the additional capability of encompassing multiple columns.
</PARA>
<PARA>
-Refer to the section on the PRIMARY KEY column constraint for more
-information.
+ Refer to the section on the PRIMARY KEY column constraint for more
+ information.
+ </para>
</REFSECT3>
</REFSECT2>
-
+
</refsect1>
<REFSECT1 ID="R1-SQL-CREATETABLE-2">
</TITLE>
<PARA>
CREATE TABLE/INHERITS is a <productname>Postgres</productname>
- language extension.
+ language extension.
</PARA>
</refsect2>
<TITLE>
Compatibility
</TITLE>
- <PARA>
<REFSECT2 ID="R2-SQL-CREATETABLE-4">
<REFSECT2INFO>
) ON COMMIT DELETE ROWS
</programlisting>
<para>
-Temporary tables are not currently available
- in <productname>Postgres</productname>.
-<tip>
- <para>
- In the current release of <productname>Postgres</productname>
- (v6.4), to create a temporary
- table you must create and drop the table by explicit commands.
-</tip>
-
+ Temporary tables are not currently available
+ in <productname>Postgres</productname>.
+ <tip>
+ <para>
+ In the current release of <productname>Postgres</productname>
+ (v6.4), to create a temporary
+ table you must create and drop the table by explicit commands.
+ </para>
+ </tip>
+ </para>
+
<REFSECT3 ID="R3-SQL-UNIQUECLAUSE-1">
<REFSECT3INFO>
<DATE>1998-09-11</DATE>
</TITLE>
<PARA>
SQL92 specifies some additional capabilities for UNIQUE:
+ </para>
<para>
Table Constraint definition
</PARA>
</synopsis>
</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">
<REFSECT3INFO>
<DATE>1998-09-11</DATE>
SQL92 specifies some additional capabilities for NOT NULL:
</PARA>
<synopsis>
- [ CONSTRAINT name ] NOT NULL
- [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
- [ [ NOT ] DEFERRABLE ]
+ [ CONSTRAINT name ] NOT NULL
+ [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
+ [ [ NOT ] DEFERRABLE ]
</synopsis>
</REFSECT3>
<PARA>
SQL92 specifies some additional capabilities for constraints,
and also defines assertions and domain constraints.
- <note>
- <para>
- <productname>Postgres</productname> does not yet support
-either domains or assertions.
+ <note>
+ <para>
+ <productname>Postgres</productname> does not yet support
+ either domains or assertions.
+ </para>
+ </note>
</para>
- </note>
-
<PARA>
An assertion is a special type of integrity constraint and share
the same namespace as other constraints.
<REFPURPOSE>
Creates a new table
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-22</DATE>
<PARA>
A valid query statement. Refer to SELECT for a description of the
allowed syntax.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
+ </refsect2>
<REFSECT2 ID="R2-SQL-CREATETABLEAS-2">
<REFSECT2INFO>
Outputs
</TITLE>
<PARA>
- Refer to CREATE TABLE and SELECT for a summary of possible output
-messages.
-
- <REFSECT1 ID="R1-SQL-CREATETABLEAS-1">
- <REFSECT1INFO>
- <DATE>1998-09-22</DATE>
- </REFSECT1INFO>
- <TITLE>
- Description
- </TITLE>
+ Refer to CREATE TABLE and SELECT for a summary of possible output
+ messages.
+ </para>
+ </refsect2>
+ </refsynopsisdiv>
+
+ <REFSECT1 ID="R1-SQL-CREATETABLEAS-1">
+ <REFSECT1INFO>
+ <DATE>1998-09-22</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
<PARA>
CREATE TABLE AS enables a table to be created from the contents of
an existing table. It has functionality equivalent to SELECT TABLE INTO,
but with perhaps a more obvious syntax.
-
-</refsect1>
+ </para>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
<REFPURPOSE>
Creates a new trigger
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
<LISTITEM>
<PARA>
This message is returned if the trigger is successfully created.
-
- </VARIABLELIST>
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
<PARA>
Refer to <command>DROP TRIGGER</command> for information on how to
remove triggers.
- </PARA>
-
+ </PARA>
</REFSECT2>
-
+ </refsect1>
+
<REFSECT1 ID="R1-SQL-CREATETRIGGER-2">
<TITLE>
Usage
</TITLE>
<PARA>
- Check if the specified distributor code exists in the distributors
- table before appending or updating a row in the table films:
+ Check if the specified distributor code exists in the distributors
+ table before appending or updating a row in the table films:
</PARA>
<ProgramListing>
-CREATE TRIGGER if_dist_exists
- BEFORE INSERT OR UPDATE ON films FOR EACH ROW
- EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
+ CREATE TRIGGER if_dist_exists
+ BEFORE INSERT OR UPDATE ON films FOR EACH ROW
+ EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
</ProgramListing>
<PARA>
- Before cancelling a distributor or updating its code, remove every
- reference to the table films:
+ Before cancelling a distributor or updating its code, remove every
+ reference to the table films:
</PARA>
<ProgramListing>
-CREATE TRIGGER if_film_exists
- BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
- EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
+ CREATE TRIGGER if_film_exists
+ BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
+ EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
</ProgramListing>
</REFSECT1>
SQL92
</TITLE>
<PARA>
- There is no <command>CREATE TRIGGER</command> in <acronym>SQL92</acronym>.
+
There is no <command>CREATE TRIGGER</command> in <acronym>SQL92</acronym>.
</PARA>
<PARA>
The second example above may also be done by using a FOREIGN KEY
constraint as in:
</PARA>
<ProgramListing>
-CREATE TABLE distributors (
+ CREATE TABLE distributors (
did DECIMAL(3),
name VARCHAR(40),
CONSTRAINT if_film_exists
- FOREIGN KEY(did) REFERENCES films
- ON UPDATE CASCADE ON DELETE CASCADE
-);
- </ProgramListing>
+ FOREIGN KEY(did) REFERENCES films
+ ON UPDATE CASCADE ON DELETE CASCADE
+ );
+ </ProgramListing>
<PARA>
However, foreign keys are not yet implemented (as of version 6.4) in
<productname>Postgres</productname>.
</PARA>
+ </refsect2>
+ </refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
<REFPURPOSE>
Defines a new base data type
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
<LISTITEM>
<PARA>
Message returned if the type is successfully created.
-
+ </para>
+ </listitem>
+ </varlistentry>
</VARIABLELIST>
-
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
length. If you need a larger type you must create a Large
Object type. The interface for these types is discussed
at length in
-<comment>This section reference needs replacing</comment>
+ <comment>This section reference needs replacing</comment>
Section 7, the large object interface. The
length of all large object types is always VARIABLE.
+ </para>
</refsect2>
</refsect1>
+
<refsect1>
<title>Examples</title>
<para>
type in a class definition:
</para>
<programlisting>
- CREATE TYPE box (INTERNALLENGTH = 8,
- INPUT = my_procedure_1, OUTPUT = my_procedure_2)
-
- CREATE TABLE myboxes (id INT4, description box)
+ CREATE TYPE box (INTERNALLENGTH = 8,
+ INPUT = my_procedure_1, OUTPUT = my_procedure_2)
+
+ CREATE TABLE myboxes (id INT4, description box)
</programlisting>
<para>
This command creates a variable length array type with
with an underscore.
</para>
</refsect2>
+
<REFSECT2 ID="R2-SQL-CREATETYPE-3">
<REFSECT2INFO>
<DATE>1998-09-21</DATE>
</PARA>
<PARA>
See also <command>CREATE FUNCTION</command>,
- <command>CREATE OPERATOR</command> and the chapter on Large Objects
-in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
-</para>
+ <command>CREATE OPERATOR</command> and the chapter on Large Objects
+ in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
+ </para>
</REFSECT2>
</refsect1>
<TITLE>
Compatibility
</TITLE>
- <PARA>
<REFSECT2 ID="R2-SQL-CREATETYPE-4">
<REFSECT2INFO>
<command>CREATE TYPE</command> is an <acronym>SQL3</acronym> statement.
</PARA>
- </REFSECT2>
+ </REFSECT2>
+ </refsect1>
</REFENTRY>
<REFPURPOSE>
Creates account information for a new user
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
a NULL value is stored in "<filename>pg_shadow</filename>"
for this attribute,
and the login will be valid for all time.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </variablelist>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEUSER-2">
Message returned if the command completes successfully.
</PARA>
</LISTITEM>
- </VARLISTENTRY>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>ERROR: removeUser: user "<replaceable class="parameter">username</replaceable>" does not exist</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- if "<replaceable class="parameter">username</replaceable>" not found.
- </PARA>
- <comment>I don't understand this and I don't know how to get
-this error message.</comment>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: removeUser: user "<replaceable class="parameter">username</replaceable>" does not exist</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ if "<replaceable class="parameter">username</replaceable>" not found.
+ </PARA>
+ <comment>I don't understand this and I don't know how to get
+ this error message.</comment>
+ </listitem>
+ </varlistentry>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
+--------------------------+--------------------------+-------+
</programlisting>
</REFSECT2>
+ </refsect1>
<REFSECT1 ID="R1-SQL-CREATEUSER-2">
<TITLE>
SQL92
</TITLE>
<PARA>
- There is no CREATE USER statement in SQL92.
+ There is no CREATE USER statement in SQL92.
</PARA>
+ </refsect2>
+ </refsect1>
</REFENTRY>
<REFPURPOSE>
Constructs a virtual table
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-21</DATE>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
+ </para>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEVIEW-2">
<programlisting>
CREATE VIEW vista AS SELECT 'Hello World'::text
</programlisting>
-
- </VARIABLELIST>
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
Currently, views are read only.
</para>
</REFSECT2>
-
+ </refsect1>
+
<REFSECT1 ID="R1-SQL-CREATEVIEW-2">
<TITLE>
Usage
<REFENTRY ID="APP-CREATEDB">
-<REFMETA>
-<REFENTRYTITLE>
-<application>createdb</application>
-</REFENTRYTITLE>
-<REFMISCINFO>Application</REFMISCINFO>
-</REFMETA>
-<REFNAMEDIV>
-<REFNAME>
-<application>createdb</application>
-</REFNAME>
-<REFPURPOSE>
-Create a new <productname>Postgres</productname> database
-</REFPURPOSE>
-<REFSYNOPSISDIV>
-<REFSYNOPSISDIVINFO>
-<DATE>1998-10-02</DATE>
-</REFSYNOPSISDIVINFO>
-<SYNOPSIS>
-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> ]
- [ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
-</SYNOPSIS>
-
-<REFSECT2 ID="R2-APP-CREATEDB-1">
-<REFSECT2INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT2INFO>
-<TITLE>
-Inputs
-</TITLE>
-<PARA>
-
-<variablelist>
-<varlistentry>
-<term>
--h <replaceable class="parameter">host</replaceable>
-</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..
-
-<varlistentry>
-<term>
--p <replaceable class="parameter">port</replaceable>
-</term>
-<listitem>
-<para>
-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>
-environment variable (if set).
-
-<varlistentry>
-<term>
--u
-</term>
-<listitem>
-<para>
-Use password authentication.
-Prompts for
-<replaceable class="parameter">username</replaceable>
- and <replaceable class="parameter">password</replaceable>.
-
-<varlistentry>
-<term>
--D <replaceable class="parameter">datadir</replaceable>
-</term>
-<listitem>
-<para>
-Specifies the alternate database location for this database installation.
-This is the location of the installation system tables, not the location
-of this specific database, which may be different.
-
-<varlistentry>
-<term>
-<replaceable class="parameter">dbname</replaceable>
-</term>
-<listitem>
-<para>
-Specifies the name of the database to be created. The name must be
-unique among all <productname>Postgres</productname> databases in this installation.
-<replaceable class="parameter">dbname</replaceable>
-defaults to the value of the
-<envar>USER</envar>
-environment variable.
-
-</variablelist>
-
-<REFSECT2 ID="R2-APP-CREATEDB-2">
-<REFSECT2INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT2INFO>
-<TITLE>
-Outputs
-</TITLE>
-<PARA>
-<application>createdb</application> will create files in the
-<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
-data area for the new database.
-
-<variablelist>
-<varlistentry>
-<term>
-Connection to database 'template1' failed.
-connectDB() failed: Is the postmaster running and accepting connections
- at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
-createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
-<listitem>
-<para>
-<application>createdb</application> could not attach to the
-<application>postmaster</application>
-process on the specified host and port. If you see this message,
-ensure that the <application>postmaster</application>
-is running on the proper host and that you have specified the proper
-port. If your site uses an authentication system, ensure that you
-have obtained the required authentication credentials.
-
-<varlistentry>
-<term>
-Connection to database 'template1' failed.
-FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
-createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
-<listitem>
-<para>
-You do not have a valid entry in the relation <literal>pg_shadow</literal>
-and and will not be allowed to access <productname>Postgres</productname>.
-Contact your <productname>Postgres</productname> administrator.
-
-<varlistentry>
-<term>
-ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
-createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
-<listitem>
-<para>
-You do not have permission to create new databases.
-Contact your <productname>Postgres</productname> site administrator.
-
-<varlistentry>
-<term>
-ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
-createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
-<listitem>
-<para>
-The database already exists.
-
-<varlistentry>
-<term>
-createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
-<listitem>
-<para>
-An internal error occurred in <application>psql</application>
-or in the backend server. Ensure that your site administrator has
-properly installed <productname>Postgres</productname>and initialized the site with
-<application>initdb</application>.
-
-</variablelist>
-
-<note>
-<para>
-<application>createdb</application> internally runs
-CREATE DATABASE from <application>psql</application>
-while connected to the <literal>template1</literal> database.
-</note>
-
-<REFSECT1 ID="R1-APP-CREATEDB-1">
-<REFSECT1INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT1INFO>
-<TITLE>
-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
-person, other than the <productname>Postgres</productname> super-user,
- who can destroy it.
-
-<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">.
-
-<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:
-
-<programlisting>
-createdb demo
-</programlisting>
-
-To create the database <literal>demo</literal>
- using the postmaster on host eden, port 5000:
-
-<programlisting>
-createdb -p 5000 -h eden demo
-</programlisting>
+ <REFMETA>
+ <REFENTRYTITLE>
+ <application>createdb</application>
+ </REFENTRYTITLE>
+ <REFMISCINFO>Application</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ <application>createdb</application>
+ </REFNAME>
+ <REFPURPOSE>
+ Create a new <productname>Postgres</productname> database
+ </REFPURPOSE>
+ </refnamediv>
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-10-02</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ 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> ]
+ [ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-APP-CREATEDB-1">
+ <REFSECT2INFO>
+ <DATE>1998-10-02</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ -h <replaceable class="parameter">host</replaceable>
+ </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..
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ -p <replaceable class="parameter">port</replaceable>
+ </term>
+ <listitem>
+ <para>
+ 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>
+ environment variable (if set).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -u
+ </term>
+ <listitem>
+ <para>
+ Use password authentication.
+ Prompts for
+ <replaceable class="parameter">username</replaceable>
+ and <replaceable class="parameter">password</replaceable>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -D <replaceable class="parameter">datadir</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Specifies the alternate database location for this database installation.
+ This is the location of the installation system tables, not the location
+ of this specific database, which may be different.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <replaceable class="parameter">dbname</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Specifies the name of the database to be created. The name must be
+ unique among all <productname>Postgres</productname> databases in this installation.
+ <replaceable class="parameter">dbname</replaceable>
+ defaults to the value of the
+ <envar>USER</envar>
+ environment variable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect2>
+ <REFSECT2 ID="R2-APP-CREATEDB-2">
+ <REFSECT2INFO>
+ <DATE>1998-10-02</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ <application>createdb</application> will create files in the
+ <filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
+ data area for the new database.
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ Connection to database 'template1' failed.
+ connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+ createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+ </term>
+ <listitem>
+ <para>
+ <application>createdb</application> could not attach to the
+ <application>postmaster</application>
+ process on the specified host and port. If you see this message,
+ ensure that the <application>postmaster</application>
+ is running on the proper host and that you have specified the proper
+ port. If your site uses an authentication system, ensure that you
+ have obtained the required authentication credentials.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Connection to database 'template1' failed.
+ FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+ createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+ </term>
+ <listitem>
+ <para>
+ You do not have a valid entry in the relation <literal>pg_shadow</literal>
+ and and will not be allowed to access <productname>Postgres</productname>.
+ Contact your <productname>Postgres</productname> administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
+ createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+ </term>
+ <listitem>
+ <para>
+ You do not have permission to create new databases.
+ Contact your <productname>Postgres</productname> site administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
+ createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+ </term>
+ <listitem>
+ <para>
+ The database already exists.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+ </term>
+ <listitem>
+ <para>
+ An internal error occurred in <application>psql</application>
+ or in the backend server. Ensure that your site administrator has
+ properly installed <productname>Postgres</productname>and initialized the site with
+ <application>initdb</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </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>
+
+ <REFSECT1 ID="R1-APP-CREATEDB-1">
+ <REFSECT1INFO>
+ <DATE>1998-10-02</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ 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
+ person, other than the <productname>Postgres</productname> super-user,
+ 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>
+
+ <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:
+
+ <programlisting>
+ createdb demo
+ </programlisting>
+
+ To create the database <literal>demo</literal>
+ using the postmaster on host eden, port 5000:
+
+ <programlisting>
+ createdb -p 5000 -h eden demo
+ </programlisting>
+ </para>
+ </refsect1>
</REFENTRY>
<REFPURPOSE>
Create a new <productname>Postgres</productname> user
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
[ -d | -D ] [ -u | -U ] [ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS>
-<REFSECT2 ID="R2-APP-CREATEUSER-1">
-<REFSECT2INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT2INFO>
-<TITLE>
-Inputs
-</TITLE>
-<PARA>
-
-<variablelist>
-<varlistentry>
-<term>
--h <replaceable class="parameter">host</replaceable>
-</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..
-
-<varlistentry>
-<term>
--p <replaceable class="parameter">port</replaceable>
-</term>
-<listitem>
-<para>
-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>
-environment variable (if set).
-
-<varlistentry>
-<term>
--d
-</term>
-<listitem>
-<para>
-Allows the user to create databases.
-
-<varlistentry>
-<term>
--D
-</term>
-<listitem>
-<para>
-Forbids the user to create databases.
-
-<varlistentry>
-<term>
--i <replaceable class="parameter">userid</replaceable>
-</term>
-<listitem>
-<para>
-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
-to match the operating system UID.
-You will be prompted for an identifier if none is specified on the command line,
-and it will suggest an identifier matching the UID.
-
-<varlistentry>
-<term>
--u
-</term>
-<listitem>
-<para>
-Allows the user to create other users.
-
-<varlistentry>
-<term>
--U
-</term>
-<listitem>
-<para>
-Forbids the user to create other users.
-
-<varlistentry>
-<term>
-<replaceable class="parameter">username</replaceable>
-</term>
-<listitem>
-<para>
-Specifies the name of the <productname>Postgres</productname> user to be created.
-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.
-
-</variablelist>
-
-<REFSECT2 ID="R2-APP-CREATEUSER-2">
-<REFSECT2INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT2INFO>
-<TITLE>
-Outputs
-</TITLE>
-<PARA>
-<application>createuser</application> will add an entry in the
-<literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
-
-<variablelist>
-<varlistentry>
-<term>
-Connection to database 'template1' failed.
-connectDB() failed: Is the postmaster running and accepting connections
- at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
-createuser: database access failed.
-<listitem>
-<para>
-<application>createuser</application> could not attach to the
-<application>postmaster</application>
-process on the specified host and port. If you see this message,
-ensure that the <application>postmaster</application>
-is running on the proper host and that you have specified the proper
-port. If your site uses an authentication system, ensure that you
-have obtained the required authentication credentials.
-
-<varlistentry>
-<term>
-Connection to database 'template1' failed.
-FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
-createuser: database access failed.
-<listitem>
-<para>
-You do not have a valid entry in the relation <literal>pg_shadow</literal>
-and and will not be allowed to access <productname>Postgres</productname>. Contact your
-<productname>Postgres</productname> administrator.
-
-<varlistentry>
-<term>
-createuser: <replaceable class="parameter">username</replaceable> cannot create users.
-<listitem>
-<para>
-You do not have permission to create new users; contact your
-<productname>Postgres</productname> site administrator.
-
-<varlistentry>
-<term>
-createuser: user "<replaceable class="parameter">username</replaceable>" already exists
-<listitem>
-<para>
-The user to be added already has an entry in the <literal>pg_shadow</literal>
-class.
-
-<varlistentry>
-<term>
-database access failed
-<listitem>
-<para>
-An internal error occurred in <application>psql</application>
-or in the backend server. Ensure that your site administrator has
-properly installed <productname>Postgres</productname>and initialized the site with
-<application>initdb</application>.
-
-</variablelist>
-
-<note>
-<para>
-<application>createuser</application> internally runs
-CREATE USER from <application>psql</application>
-while connected to the <literal>template1</literal> database.
-</note>
-
-<REFSECT1 ID="R1-APP-CREATEUSER-1">
-<REFSECT1INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT1INFO>
-<TITLE>
-Description
-</TITLE>
-<PARA>
-<application>createuser</application> creates a
-new <productname>Postgres</productname> user.
-Only users with <literal>usesuper</literal> set in
-the <literal>pg_shadow</literal> class can create
-new <productname>Postgres</productname> users. As shipped,
-the user <literal>postgres</literal> can create users.
-
-<para>
-<application>createuser</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>createuser</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">.
-
-Once invoked, <application>createuser</application>
-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
-user identifier must be specified.
-
-<note>
-<para>
-The <productname>Postgres</productname> user identifier
-does not need to be the same as the user's Unix UID. However, typically
-they are assigned to be the same.
-</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.
+ <REFSECT2 ID="R2-APP-CREATEUSER-1">
+ <REFSECT2INFO>
+ <DATE>1998-10-02</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ -h <replaceable class="parameter">host</replaceable>
+ </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..
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -p <replaceable class="parameter">port</replaceable>
+ </term>
+ <listitem>
+ <para>
+ 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>
+ environment variable (if set).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -d
+ </term>
+ <listitem>
+ <para>
+ Allows the user to create databases.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -D
+ </term>
+ <listitem>
+ <para>
+ Forbids the user to create databases.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -i <replaceable class="parameter">userid</replaceable>
+ </term>
+ <listitem>
+ <para>
+ 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
+ to match the operating system UID.
+ You will be prompted for an identifier if none is specified on the command line,
+ and it will suggest an identifier matching the UID.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -u
+ </term>
+ <listitem>
+ <para>
+ Allows the user to create other users.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -U
+ </term>
+ <listitem>
+ <para>
+ Forbids the user to create other users.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <replaceable class="parameter">username</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Specifies the name of the <productname>Postgres</productname> user to be created.
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect2>
+ <REFSECT2 ID="R2-APP-CREATEUSER-2">
+ <REFSECT2INFO>
+ <DATE>1998-10-02</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ <application>createuser</application> will add an entry in the
+ <literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ Connection to database 'template1' failed.
+ connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+ createuser: database access failed.
+ </term>
+ <listitem>
+ <para>
+ <application>createuser</application> could not attach to the
+ <application>postmaster</application>
+ process on the specified host and port. If you see this message,
+ ensure that the <application>postmaster</application>
+ is running on the proper host and that you have specified the proper
+ port. If your site uses an authentication system, ensure that you
+ have obtained the required authentication credentials.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ Connection to database 'template1' failed.
+ FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+ createuser: database access failed.
+ </term>
+ <listitem>
+ <para>
+ You do not have a valid entry in the relation <literal>pg_shadow</literal>
+ and and will not be allowed to access <productname>Postgres</productname>. Contact your
+ <productname>Postgres</productname> administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ createuser: <replaceable class="parameter">username</replaceable> cannot create users.
+ </term>
+ <listitem>
+ <para>
+ You do not have permission to create new users; contact your
+ <productname>Postgres</productname> site administrator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ createuser: user "<replaceable class="parameter">username</replaceable>" already exists
+ </term>
+ <listitem>
+ <para>
+ The user to be added already has an entry in the <literal>pg_shadow</literal>
+ class.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ database access failed
+ </term>
+ <listitem>
+ <para>
+ An internal error occurred in <application>psql</application>
+ or in the backend server. Ensure that your site administrator has
+ properly installed <productname>Postgres</productname>and initialized the site with
+ <application>initdb</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+
+ <note>
+ <para>
+ <application>createuser</application> internally runs
+ CREATE USER from <application>psql</application>
+ while connected to the <literal>template1</literal> database.
+ </para>
+ </note>
+ </refsect2>
+ </refsynopsisdiv>
+
+ <REFSECT1 ID="R1-APP-CREATEUSER-1">
+ <REFSECT1INFO>
+ <DATE>1998-10-02</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ <application>createuser</application> creates a
+ new <productname>Postgres</productname> user.
+ Only users with <literal>usesuper</literal> set in
+ the <literal>pg_shadow</literal> class can create
+ new <productname>Postgres</productname> users. As shipped,
+ the user <literal>postgres</literal> can create users.
+ </para>
+ <para>
+ <application>createuser</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>createuser</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">.
+
+ Once invoked, <application>createuser</application>
+ 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
+ user identifier must be specified.
+ </para>
+ <note>
+ <para>
+ The <productname>Postgres</productname> user identifier
+ does not need to be the same as the user's Unix UID. However, typically
+ they are assigned to be the same.
+ </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>
+ </refsect1>
</REFENTRY>
<REFPURPOSE>
Defines a cursor for table access
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-04</DATE>
<LISTITEM>
<PARA>
This error occurs if the cursor is not declared within a transaction block.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
-
- </VARIABLELIST>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
</REFSYNOPSISDIV>
BINARY cursors give you back the data in the native binary
representation. So binary cursors will tend to be a
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,
you would get a string of '1' with a default cursor
whereas with a binary cursor you would get
a 4-byte value equal to control-A ('^A').
-
-<caution>
-<para>
-BINARY cursors should be used carefully. User applications such
-as <application>psql</application> are not aware of binary cursors
-and expect data to come back in a text format.
-</caution>
-
+ <caution>
+ <para>
+ BINARY cursors should be used carefully. User applications such
+ as <application>psql</application> are not aware of binary cursors
+ and expect data to come back in a text format.
+ </para>
+ </caution>
+ </para>
<PARA>
However, string representation is architecture-neutral whereas binary
representation can differ between different machine architectures.
representations (e.g. "big-endian" versus "little-endian"),
you will probably not want your data returned in
binary format.
-
-<tip>
-<para>
- If you intend to display the data in
- ASCII, getting it back in ASCII will save you some
- effort on the client side.
-</tip>
+
+ <tip>
+ <para>
+ If you intend to display the data in
+ ASCII, getting it back in ASCII will save you some
+ effort on the client side.
+ </para>
+ </tip>
</PARA>
<REFSECT2 ID="R2-SQL-DECLARE-3">
</PARA>
<PARA>
<productname>Postgres</productname>
- 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.
-
-<note>
-<para>
-In <acronym>SQL92</acronym> cursors are only available in
-embedded applications. <application>ecpg</application>, the
-embedded SQL preprocessor for <productname>Postgres</productname>,
-supports the <acronym>SQL92</acronym> conventions, including those
-involving DECLARE and OPEN statements.
-</note>
-
+
+ <note>
+ <para>
+ In <acronym>SQL92</acronym> cursors are only available in
+ embedded applications. <application>ecpg</application>, the
+ embedded SQL preprocessor for <productname>Postgres</productname>,
+ supports the <acronym>SQL92</acronym> conventions, including those
+ involving DECLARE and OPEN statements.
+ </para>
+ </note>
+
</PARA>
</REFSECT2>
</refsect1>
SQL92
</TITLE>
<PARA>
-<acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
-and in modules. <productname>Postgres</productname> permits cursors to be used
-interactively.
-<acronym>SQL92</acronym> allows embedded or modular cursors to
-update database information.
-All <productname>Postgres</productname> cursors are readonly.
-The BINARY keyword is a <productname>Postgres</productname> extension.
-
+ <acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
+ and in modules. <productname>Postgres</productname> permits cursors to be used
+ interactively.
+ <acronym>SQL92</acronym> allows embedded or modular cursors to
+ update database information.
+ All <productname>Postgres</productname> cursors are readonly.
+ The BINARY keyword is a <productname>Postgres</productname> extension.
+ </para>
+ </refsect2>
+ </refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
Deletes rows from a table
</REFPURPOSE>
-
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<PARA>
If <replaceable class="parameter">count</replaceable> is 0,
no rows were deleted.
-
- </VARIABLELIST>
+ </para>
+ </listitem>
+ </varlistentry>
+ </VARIABLELIST>
+ </para>
</REFSECT2>
-</REFSYNOPSISDIV>
+ </REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-DELETE-1">
<REFSECT1INFO>
Remove all films but musicals:
</PARA>
<ProgramListing>
-DELETE FROM films WHERE kind <> 'Musical';
+DETETE FROM films WHERE kind <> 'Musical';
SELECT * FROM films;
</synopsis>
<para>
where <replaceable class="parameter">cursor</replaceable> identifies an open cursor. Interactive cursors in <productname>Postgres</productname> are read-only.
-</para>
+ </para>
</refsect2>
</refsect1>
</REFENTRY>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
+ </refnamediv>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
[ -i ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
-<REFSECT2 ID="R2-APP-DESTROYDB-1">
-<REFSECT2INFO>
-<DATE>1998-10-02</DATE>
-</REFSECT2INFO>
-<TITLE>
-Inputs
-</TITLE>
-<PARA>
-
-<variablelist>
-<varlistentry>
-<term>
--h <replaceable class="parameter">host</replaceable>
-</term>
-<listitem>
-<para
projects / postgresql.git / commitdiff