From 30e355fc80996db0334e9d8d28b05dc299500a3e Mon Sep 17 00:00:00 2001
From: "Thomas G. Lockhart" <lockhart@fourpalms.org>
Date: Fri, 7 Apr 2000 13:30:58 +0000
Subject: [PATCH] Fix path to initdb in installation instructions. General
cleanup for 7.0.
---
doc/src/sgml/advanced.sgml | 60 +-
doc/src/sgml/func.sgml | 106 +++-
doc/src/sgml/install.sgml | 1134 +++++++++++++++++++-----------------
doc/src/sgml/intro.sgml | 24 +-
doc/src/sgml/legal.sgml | 14 +-
doc/src/sgml/notation.sgml | 27 +-
doc/src/sgml/ports.sgml | 53 +-
doc/src/sgml/query.sgml | 121 ++--
doc/src/sgml/sql.sgml | 142 +++--
doc/src/sgml/start.sgml | 583 ++++++++++--------
doc/src/sgml/y2k.sgml | 7 +-
11 files changed, 1304 insertions(+), 967 deletions(-)
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 3142c32739b..af7030e392a 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.9 2000/03/31 03:27:40 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="advanced">
@@ -106,10 +106,10 @@ SELECT c.name, c.altitude
Here the <quote>*</quote> after cities indicates that the query should
be run over cities and all classes below cities in the
inheritance hierarchy. Many of the commands that we
- have already discussed (<command>select</command>,
- <command>update</command> and <command>delete</command>)
+ have already discussed (<command>SELECT</command>,
+ <command>UPDATE</command> and <command>DELETE</command>)
support this <quote>*</quote> notation, as do others, like
- <command>alter</command>.
+ <command>ALTER</command>.
</para>
</sect1>
@@ -118,7 +118,8 @@ SELECT c.name, c.altitude
<para>
One of the tenets of the relational model is that the
- attributes of a relation are atomic. <productname>Postgres</productname> does not
+ attributes of a relation are atomic.
+ <productname>Postgres</productname> does not
have this restriction; attributes can themselves contain
sub-values that can be accessed from the query
language. For example, you can create attributes that
@@ -129,7 +130,8 @@ SELECT c.name, c.altitude
<title>Arrays</title>
<para>
- <productname>Postgres</productname> allows attributes of an instance to be defined
+ <productname>Postgres</productname> allows attributes of an
+ instance to be defined
as fixed-length or variable-length multi-dimensional
arrays. Arrays of any base type or user-defined type
can be created. To illustrate their use, we first create a
@@ -149,11 +151,14 @@ CREATE TABLE SAL_EMP (
a <firstterm>text</firstterm> string (name), a one-dimensional
array of <firstterm>int4</firstterm>
(pay_by_quarter), which represents the employee's
- salary by quarter and a two-dimensional array of <firstterm>text</firstterm>
+ salary by quarter and a two-dimensional array of
+ <firstterm>text</firstterm>
(schedule), which represents the employee's weekly
- schedule. Now we do some <firstterm>INSERTS</firstterm>s; note that when
+ schedule. Now we do some <firstterm>INSERTS</firstterm>s;
+ note that when
appending to an array, we enclose the values within
- braces and separate them by commas. If you know <firstterm>C</firstterm>,
+ braces and separate them by commas. If you know
+ <firstterm>C</firstterm>,
this is not unlike the syntax for initializing structures.
<programlisting>
@@ -168,7 +173,8 @@ INSERT INTO SAL_EMP
'{{"talk", "consult"}, {"meeting"}}');
</programlisting>
- By default, <productname>Postgres</productname> uses the "one-based" numbering
+ By default, <productname>Postgres</productname> uses the
+ "one-based" numbering
convention for arrays -- that is, an array of n elements
starts with array[1] and ends with array[n].
Now, we can run some queries on SAL_EMP. First, we
@@ -228,6 +234,11 @@ SELECT SAL_EMP.schedule[1:2][1:1]
</sect2>
</sect1>
+<!--
+
+We haven't had Time Travel for two or three years, so let's stop
+mentioning it. - thomas 2000-04-02
+
<sect1>
<title>Time Travel</title>
@@ -240,21 +251,27 @@ SELECT SAL_EMP.schedule[1:2][1:1]
</para>
<para>
- New features such as triggers allow one to mimic the behavior of time travel when desired, without
- incurring the overhead when it is not needed (for most users, this is most of the time).
- See examples in the <filename>contrib</filename> directory for more information.
+ New features such as triggers allow one to mimic the behavior of
+ time travel when desired, without
+ incurring the overhead when it is not needed (for most users, this
+ is most of the time).
+ See examples in the <filename>contrib</filename> directory for
+ more information.
</para>
<note>
<title>Time travel is deprecated</title>
<para>
- The remaining text in this section is retained only until it can be rewritten in the context
- of new techniques to accomplish the same purpose. Volunteers? - thomas 1998-01-12
+ The remaining text in this section is retained only until it can
+ be rewritten in the context
+ of new techniques to accomplish the same purpose.
+ Volunteers? - thomas 1998-01-12
</para>
</note>
<para>
- <productname>Postgres</productname> supports the notion of time travel. This feature
+ <productname>Postgres</productname> supports the notion of time
+ travel. This feature
allows a user to run historical queries. For
example, to find the current population of Mariposa
city, one would query:
@@ -269,7 +286,8 @@ SELECT * FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+
</programlisting>
- <productname>Postgres</productname> will automatically find the version of Mariposa's
+ <productname>Postgres</productname> will automatically find the
+ version of Mariposa's
record valid at the current time.
One can also give a time range. For example to see the
past and present populations of Mariposa, one would
@@ -313,18 +331,22 @@ SELECT name, population
abbreviated as ``[,].''
</para>
</sect1>
+-->
<sect1>
<title>More Advanced Features</title>
<para>
- <productname>Postgres</productname> has many features not touched upon in this
+ <productname>Postgres</productname> has many features not touched
+ upon in this
tutorial introduction, which has been oriented toward newer users of
<acronym>SQL</acronym>.
- These are discussed in more detail in both the User's and Programmer's Guides.
+ These are discussed in more detail in both the User's and
+ Programmer's Guides.
</para>
</sect1>
+
</chapter>
<!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ec84abeb92f..9e2c2458329 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -88,10 +88,10 @@
<entry>abs(-17.4)</entry>
</row>
<row>
- <entry>sqrt(float8)</entry>
+ <entry>degrees(float8)</entry>
<entry>float8</entry>
- <entry>square root</entry>
- <entry>sqrt(2.0)</entry>
+ <entry>radians to degrees</entry>
+ <entry>degrees(0.5)</entry>
</row>
<row>
<entry>exp(float8)</entry>
@@ -111,18 +111,36 @@
<entry>base 10 logarithm</entry>
<entry>log(2.0)</entry>
</row>
+ <row>
+ <entry>pi()</entry>
+ <entry>float8</entry>
+ <entry>fundamental constant</entry>
+ <entry>pi()</entry>
+ </row>
<row>
<entry>pow(float8,float8)</entry>
<entry>float8</entry>
<entry>raise a number to the specified exponent</entry>
<entry>pow(2.0, 16.0)</entry>
</row>
+ <row>
+ <entry>radians(float8)</entry>
+ <entry>float8</entry>
+ <entry>degrees to radians</entry>
+ <entry>radians(45.0)</entry>
+ </row>
<row>
<entry>round(float8)</entry>
<entry>float8</entry>
<entry>round to nearest integer</entry>
<entry>round(42.4)</entry>
</row>
+ <row>
+ <entry>sqrt(float8)</entry>
+ <entry>float8</entry>
+ <entry>square root</entry>
+ <entry>sqrt(2.0)</entry>
+ </row>
<row>
<entry>trunc(float8)</entry>
<entry>float8</entry>
@@ -156,6 +174,88 @@
Most of the functions listed for FLOAT8 are also available for
type NUMERIC.
</para>
+
+ <para>
+ <table tocentry="1">
+ <title>Transcendental Mathematical Functions</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Function</entry>
+ <entry>Returns</entry>
+ <entry>Description</entry>
+ <entry>Example</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>acos(float8)</entry>
+ <entry>float8</entry>
+ <entry>arccosine</entry>
+ <entry>acos(10.0)</entry>
+ </row>
+ <row>
+ <entry>asin(float8)</entry>
+ <entry>float8</entry>
+ <entry>arcsine</entry>
+ <entry>asin(10.0)</entry>
+ </row>
+ <row>
+ <entry>atan(float8)</entry>
+ <entry>float8</entry>
+ <entry>arctangent</entry>
+ <entry>atan(10.0)</entry>
+ </row>
+ <row>
+ <entry>atan2(float8,float8)</entry>
+ <entry>float8</entry>
+ <entry>arctangent</entry>
+ <entry>atan3(10.0,20.0)</entry>
+ </row>
+ <row>
+ <entry>cos(float8)</entry>
+ <entry>float8</entry>
+ <entry>cosine</entry>
+ <entry>cos(0.4)</entry>
+ </row>
+ <row>
+ <entry>cot(float8)</entry>
+ <entry>float8</entry>
+ <entry>cotangent</entry>
+ <entry>cot(20.0)</entry>
+ </row>
+ <row>
+ <entry>sin(float8)</entry>
+ <entry>float8</entry>
+ <entry>sine</entry>
+ <entry>cos(0.4)</entry>
+ </row>
+ <row>
+ <entry>cos(float8)</entry>
+ <entry>float8</entry>
+ <entry>cosine</entry>
+ <entry>cos(0.4)</entry>
+ </row>
+ <row>
+ <entry>cos(float8)</entry>
+ <entry>float8</entry>
+ <entry>cosine</entry>
+ <entry>cos(0.4)</entry>
+ </row>
+ <row>
+ <entry>cos(float8)</entry>
+ <entry>float8</entry>
+ <entry>cosine</entry>
+ <entry>cos(0.4)</entry>
+ </row>
+ <row>
+ <entry>cos(float8)</entry>
+ <entry>float8</entry>
+ <entry>cosine</entry>
+ <entry>cos(0.4)</entry>
+ </row>
+
+
</sect1>
<sect1>
diff --git a/doc/src/sgml/install.sgml b/doc/src/sgml/install.sgml
index c7b441a671a..210b98b8cfa 100644
--- a/doc/src/sgml/install.sgml
+++ b/doc/src/sgml/install.sgml
@@ -1,548 +1,581 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/install.sgml,v 1.38 2000/03/31 15:00:14 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/install.sgml,v 1.39 2000/04/07 13:30:58 thomas Exp $
-->
- <Chapter Id="install">
- <Title>Installation</Title>
+ <chapter id="install">
+ <title>Installation</title>
- <Abstract>
- <Para>
+ <abstract>
+ <para>
Installation instructions for
- <ProductName>PostgreSQL</ProductName> 7.0.
- </Para>
- </Abstract>
+ <productname>PostgreSQL</productname> 7.0.
+ </para>
+ </abstract>
- <Para>
- If you haven't gotten the <ProductName>PostgreSQL</ProductName> distribution,
- get it from <ULink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ULink>,
+ <para>
+ If you haven't gotten the <productname>PostgreSQL</productname> distribution,
+ get it from <ulink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ulink>,
then unpack it:
- <ProgramListing>
-gunzip postgresql-7.0.tar.gz
-tar -xf postgresql-7.0.tar
-mv postgresql-7.0 /usr/src
- </ProgramListing>
- </Para>
-
- <Sect1>
- <Title>Before you start</Title>
-
- <Para>
- Building <Productname>PostgreSQL</Productname> requires <acronym>GNU</acronym>
- <Application>make</Application>. It will <Emphasis>not</Emphasis>
- work with other <Application>make</Application> programs. On GNU/Linux systems
+
+ <programlisting>
+> gunzip postgresql-7.0.tar.gz
+> tar -xf postgresql-7.0.tar
+> mv postgresql-7.0 /usr/src
+ </programlisting>
+ </para>
+
+ <sect1>
+ <title>Before you start</title>
+
+ <para>
+ Building <productname>PostgreSQL</productname> requires <acronym>GNU</acronym>
+ <application>make</application>. It will <emphasis>not</emphasis>
+ work with other <application>make</application> programs. On GNU/Linux systems
GNU make is the default tool, on other systems you may find that
- GNU <Application>make</Application> is installed under the name <Quote>gmake</Quote>.
+ GNU <application>make</application> is installed under the name
+ <quote>gmake</quote>.
We will use that name from now on to indicate <acronym>GNU</acronym>
- <Application>make</Application>, no matter what name it has on your system.
- To test for <acronym>GNU</acronym> <Application>make</Application> enter
+ <application>make</application>, no matter what name it has on your system.
+ To test for <acronym>GNU</acronym> <application>make</application> enter
<programlisting>
-<userinput>gmake --version</userinput>
+> <userinput>gmake --version</userinput>
</programlisting>
- If you need to get <acronym>GNU</acronym> <Application>make</Application>, you can
- find it at <ULink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ULink>.
- </Para>
+ If you need to get <acronym>GNU</acronym>
+ <application>make</application>, you can
+ find it at <ulink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
+ </para>
- <Para>
+ <para>
Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/ports.htm">
http://www.postgresql.org/docs/admin/ports.htm</ulink>.
- In general, most Unix-compatible platforms with modern libraries should be able to run
- <ProductName>PostgreSQL</ProductName>. In the <filename>doc</filename> subdirectory
+ In general, most Unix-compatible platforms with modern libraries
+ should be able to run
+ <productname>PostgreSQL</productname>. In the
+ <filename>doc</filename> subdirectory
of the distribution are several platform-specific FAQ and README documents you
might wish to consult if you are having trouble.
</para>
<para>
- Although the minimum required memory for running <ProductName>PostgreSQL</ProductName>
- can be as little as 8MB, there are noticeable speed improvements when expanding memory
+ Although the minimum required memory for running
+ <productname>PostgreSQL</productname>
+ can be as little as 8MB, there are noticeable speed improvements
+ when expanding memory
up to 96MB or beyond. The rule is you can never have too much memory.
</para>
- <Para>
+ <para>
Check that you have sufficient disk space. You will need about
30 Mbytes for the source tree during compilation and about 5 Mbytes for
the installation directory. An empty database takes about 1 Mbyte, otherwise
they take about five times the amount of space that a flat text file with the
same data would take. If you run the regression tests you will temporarily need
an extra 20MB.
- </Para>
+ </para>
- <Para>
+ <para>
To check for disk space, use
<programlisting>
-df -k
+> df -k
</programlisting>
</para>
<para>
- Considering today's prices for hard disks, getting a large and fast hard disk should
+ Considering today's prices for hard disks, getting a large and
+ fast hard disk should
probably be in your plans before putting a database into production use.
</para>
- </Sect1>
-
-<Sect1>
-<Title>Installation Procedure</Title>
-
-<Procedure>
-<Title><ProductName>PostgreSQL</ProductName> Installation</Title>
-
-<Para>
-For a fresh install or upgrading from previous releases of
-<ProductName>PostgreSQL</ProductName>:
-</Para>
-
-<Step Performance="optional">
-<Para>
-Create the <ProductName>PostgreSQL</ProductName> superuser account.
-This is the user the server will run as. For production use you
-should create a separate, unprivileged account (<literal>postgres</literal> is
-commonly used). If you do not have root access or just want to play around,
-your own user account is enough.
-</para>
-<para>
-Running <ProductName>PostgreSQL</ProductName> as <literal>root</literal>, <literal>bin</literal>,
-or any other account with special access rights is a security risk;
-<emphasis>don't do it</emphasis>. The postmaster will in fact refuse
-to start as root.
-</para>
-<Para>
-You need not do the building and installation itself under this account
-(although you can). You will be told when you need to login as the
-database superuser.
-</Para>
-</Step>
-
-<Step Performance="required">
-<Para>
-Configure the source code for your system. It is this step at which
-you can specify your actual installation path for the build process
-and make choices about what gets installed. Change into the <filename>src</filename>
-subdirectory and type:
-<ProgramListing>
-./configure
-</ProgramListing>
-followed by any options you might want to give it. For a first installation
-you should be able to do fine without any.
-For a complete list of options, type:
-<ProgramListing>
-./configure --help
-</ProgramListing>
- Some of the more commonly used ones are:
-<VariableList>
- <varlistentry>
- <term>--prefix=BASEDIR</term>
- <listitem>
- <para>
- Selects a different base directory for the installation of
- <ProductName>PostgreSQL</ProductName>. The default is <filename>/usr/local/pgsql</filename>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--enable-locale</term>
- <listitem>
- <para>
- If you want to use locales.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--enable-multibyte</term>
- <listitem>
- <para>
- Allows the use of multibyte character encodings. This is primarily for
- languages like Japanese, Korean, or Chinese.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--with-perl</term>
- <listitem>
- <para>
- Builds the Perl interface and plperl extension language.
- Please note that the Perl interface needs to be
- installed into the usual place for Perl modules (typically under
- <filename>/usr/lib/perl</filename>), so you must have root access
- to perform the installation step. (It is often easiest to leave out
- <option>--with-perl</option> initially, and then build and install the
- Perl interface after completing the installation of PostgreSQL
- itself.)
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--with-odbc</term>
- <listitem>
- <para>
- Builds the ODBC driver package.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--with-tcl</term>
- <listitem>
- <para>
- Builds interface libraries and programs requiring
- Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
- </para>
- </listitem>
- </varlistentry>
-</VariableList>
-
-</Para>
-</step>
-
-<Step Performance="required">
-<Para>
-Compile the program. Type
-<ProgramListing>
-gmake
-</ProgramListing>
-The compilation process can take anywhere from 10 minutes to an hour.
-Your mileage will most certainly vary. Remember to use GNU make.
-</Para>
-
-<Para>
-The last line displayed will hopefully be
-<programlisting>
+ </sect1>
+
+ <sect1>
+ <title>Installation Procedure</title>
+
+ <procedure>
+ <title><productname>PostgreSQL</productname> Installation</title>
+
+ <para>
+ For a fresh install or upgrading from previous releases of
+ <productname>PostgreSQL</productname>:
+ </para>
+
+ <step performance="optional">
+ <para>
+ Create the <productname>PostgreSQL</productname> superuser account.
+ This is the user the server will run as. For production use you
+ should create a separate, unprivileged account
+ (<literal>postgres</literal> is
+ commonly used). If you do not have root access or just want to play around,
+ your own user account is enough.
+ </para>
+ <para>
+ Running <productname>PostgreSQL</productname> as
+ <literal>tera</literal>teral>, <literal>bin</literal>,
+ or any other account with special access rights is a security risk;
+ <emphasis>don't do it</emphasis>. The postmaster will in fact refuse
+ to start as root.
+ </para>
+ <para>
+ You need not do the building and installation itself under this account
+ (although you can). You will be told when you need to login as the
+ database superuser.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Configure the source code for your system. It is this step at which
+ you can specify your actual installation path for the build process
+ and make choices about what gets installed. Change into the
+ <filename>src</filename>
+ subdirectory and type:
+ <programlisting>
+> ./configure
+ </programlisting>
+ followed by any options you might want to give it. For a first installation
+ you should be able to do fine without any.
+ For a complete list of options, type:
+ <programlisting>
+> ./configure --help
+ </programlisting>
+ Some of the more commonly used ones are:
+ <variablelist>
+ <varlistentry>
+ <term>--prefix=BASEDIR</term>
+ <listitem>
+ <para>
+ Selects a different base directory for the installation of
+ <productname>PostgreSQL</productname>. The default is
+ <filename>/usr/local/pgsql</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--enable-locale</term>
+ <listitem>
+ <para>
+ If you want to use locales.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--enable-multibyte</term>
+ <listitem>
+ <para>
+ Allows the use of multibyte character encodings. This is primarily for
+ languages like Japanese, Korean, or Chinese.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-perl</term>
+ <listitem>
+ <para>
+ Builds the Perl interface and plperl extension language.
+ Please note that the Perl interface needs to be
+ installed into the usual place for Perl modules (typically under
+ <filename>/usr/lib/perl</filename>), so you must have root access
+ to perform the installation step. (It is often easiest to leave out
+ <option>--with-perl</option> initially, and then build and install the
+ Perl interface after completing the installation of PostgreSQL
+ itself.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-odbc</term>
+ <listitem>
+ <para>
+ Builds the ODBC driver package.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-tcl</term>
+ <listitem>
+ <para>
+ Builds interface libraries and programs requiring
+ Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Compile the program. Type
+ <programlisting>
+> gmake
+ </programlisting>
+ The compilation process can take anywhere from 10 minutes to an hour.
+ Your mileage will most certainly vary. Remember to use GNU make.
+ </para>
+
+ <para>
+ The last line displayed will hopefully be
+ <programlisting>
All of PostgreSQL is successfully made. Ready to install.
-</programlisting>
-</Para>
-</Step>
-
-<Step Performance="optional">
-<Para>
-If you want to test the newly built server before you install it,
-you can run the regression tests at this point. The regression tests
-are a test suite to verify that <ProductName>PostgreSQL</ProductName>
-runs on your machine in the way the developers expected it to.
-For detailed instructions see <xref linkend="regress" endterm="regress-title">.
-(Be sure to use the "parallel regress test" method, since the sequential
-method only works with an already-installed server.)
-</Para>
-</Step>
-
-<Step Performance="required">
-<Para>
-If you are not upgrading an existing system then skip to
-<xref linkend="continue">.
-</Para>
-
-<Para>
-You now need to back up your existing database.
-To dump your fairly recent post-6.0 database installation, type
-<programlisting>
-pg_dumpall > db.out
-</programlisting>
-If you wish to preserve object id's (oids), then use the -o
-option when running <application>pg_dumpall</application>.
-However, unless you have a
-special reason for doing this (such as using OIDs as keys
-in tables), don't do it.
-</Para>
-
-<Para>
-Make sure to use the <application>pg_dumpall</application>
-command from the version you are currently running.
-7.0's <application>pg_dumpall</application> will not work on older databases.
-However, if you are still using 6.0, do not use the
-<application>pg_dumpall</application> script from 6.0 or everything will be
-owned by the <ProductName>PostgreSQL</ProductName> superuser after you
-reload. In that case
-you should grab <application>pg_dumpall</application> from a later
-6.x.x release.
-If you are upgrading from a version prior to
-<ProductName>Postgres95</ProductName> v1.09 then you must back up your database,
-install <ProductName>Postgres95</ProductName> v1.09, restore your database,
-then back it up again.
-</Para>
-
-<caution>
-<Para>
- You must make sure that your database is not updated in the middle of
- your backup. If necessary, bring down postmaster, edit the permissions
- in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
- to allow only you on, then
- bring <application>postmaster</application> back up.
-</Para>
-</caution>
-</Step>
-
-<Step Performance="required">
-<Para>
-If you are upgrading an existing system then kill the database server now. Type
-<ProgramListing>
-ps ax | grep postmaster
-</ProgramListing>
-or
-<ProgramListing>
-ps -e | grep postmaster
-</ProgramListing>
-(It depends on your system which one of these two works. No harm can be done
-by typing the wrong one.)
-This should list the process numbers for a number of processes, similar
-to this:
-<ProgramListing>
+ </programlisting>
+ </para>
+ </step>
+
+ <step performance="optional">
+ <para>
+ If you want to test the newly built server before you install it,
+ you can run the regression tests at this point. The regression tests
+ are a test suite to verify that <productname>PostgreSQL</productname>
+ runs on your machine in the way the developers expected it to.
+ For detailed instructions see <xref endterm="regress-title"
+ linkend="regress">.
+ (Be sure to use the "parallel regress test" method, since the sequential
+ method only works with an already-installed server.)
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ If you are not upgrading an existing system then skip to
+ <xref linkend="continue">.
+ </para>
+
+ <para>
+ You now need to back up your existing database.
+ To dump your fairly recent post-6.0 database installation, type
+ <programlisting>
+> pg_dumpall > db.out
+ </programlisting>
+ If you wish to preserve object id's (oids), then use the -o
+ option when running <application>pg_dumpall</application>.
+ However, unless you have a
+ special reason for doing this (such as using OIDs as keys
+ in tables), don't do it.
+ </para>
+
+ <para>
+ Make sure to use the <application>pg_dumpall</application>
+ command from the version you are currently running.
+ 7.0's <application>pg_dumpall</application> will not work on older databases.
+ However, if you are still using 6.0, do not use the
+ <application>pg_dumpall</application> script from 6.0 or everything will be
+ owned by the <productname>PostgreSQL</productname> superuser after you
+ reload. In that case
+ you should grab <application>pg_dumpall</application> from a later
+ 6.x.x release.
+ If you are upgrading from a version prior to
+ <productname>Postgres95</productname> v1.09 then you must back
+ up your database,
+ install <productname>Postgres95</productname> v1.09, restore your database,
+ then back it up again.
+ </para>
+
+ <caution>
+ <para>
+ You must make sure that your database is not updated in the middle of
+ your backup. If necessary, bring down postmaster, edit the permissions
+ in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
+ to allow only you on, then
+ bring <application>postmaster</application> back up.
+ </para>
+ </caution>
+ </step>
+
+ <step performance="required">
+ <para>
+ If you are upgrading an existing system then kill the database
+ server now. Type
+ <programlisting>
+> ps ax | grep postmaster
+ </programlisting>
+ or
+ <programlisting>
+> ps -e | grep postmaster
+ </programlisting>
+ (It depends on your system which one of these two works. No harm can be done
+ by typing the wrong one.)
+ This should list the process numbers for a number of processes, similar
+ to this:
+ <programlisting>
263 ? SW 0:00 (postmaster)
777 p1 S 0:00 grep postmaster
-</ProgramListing>
-Type the following line, with <replaceable>pid</replaceable>
-replaced by the process id for process <literal>postmaster</literal>
-(263 in the above case). (Do not use the id for the process "grep postmaster".)
-<programlisting>
-kill <replaceable>pid</replaceable>
-</programlisting>
-</Para>
-
-<tip>
-<para>
-On systems which have <productname>PostgreSQL</productname> started at boot time, there
-is probably a startup file that will accomplish the same thing. For example, on a
-Redhat Linux system one might find that
-<programlisting>
-/etc/rc.d/init.d/postgres.init stop
-</programlisting>
-works.
-</para>
-</tip>
-
-<Para>
-Also move the old directories out of the way. Type the following:
-<programlisting>
-mv /usr/local/pgsql /usr/local/pgsql.old
-</programlisting>
-(substitute your particular paths).
-</Para>
-
-</Step>
-
-<Step Performance="required" id="continue">
-<Para>
-Install the <ProductName>PostgreSQL</ProductName> executable files and
-libraries. Type
-<ProgramListing>
-gmake install
-</ProgramListing>
-</Para>
-<Para>
-You should do this step as the user that you want the installed executables
-to be owned by. This does not have to be the same as the database superuser;
-some people prefer to have the installed files be owned by root.
-</Para>
-</Step>
-
-<Step Performance="required">
-<Para>
-If necessary, tell your system how to find the new shared libraries.
-How to do this varies between platforms. The most widely usable method
-is to set the environment variable
-<envar>LD_LIBRARY_PATH</envar>:
-<programlisting>
-LD_LIBRARY_PATH=/usr/local/pgsql/lib
-export LD_LIBRARY_PATH
-</programlisting>
-on sh, ksh, bash, zsh or
-<programlisting>
-setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
-</programlisting>
-on csh or tcsh.
-You might want to put this into a shell startup file such as
-<filename>/etc/profile</filename>.
-</Para>
-
-<Para>
-On some systems the following is the preferred method, but you must have root
-access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
-<programlisting>
-<FileName>/usr/local/pgsql/lib</FileName>
-</programlisting>
-Then run command <Command>/sbin/ldconfig</Command>.
-</Para>
-
-<Para>
-If in doubt, refer to the manual pages of your system. If you later on get
-a message like
-<programlisting>
+ </programlisting>
+ Type the following line, with <replaceable>pid</replaceable>
+ replaced by the process id for process <literal>postmaster</literal>
+ (263 in the above case). (Do not use the id for the process
+ "grep postmaster".)
+ <programlisting>
+> kill <replaceable>pid</replaceable>
+ </programlisting>
+ </para>
+
+ <tip>
+ <para>
+ On systems which have <productname>PostgreSQL</productname>
+ started at boot time, there
+ is probably a startup file that will accomplish the same
+ thing. For example, on a
+ Redhat Linux system one might find that
+ <programlisting>
+> /etc/rc.d/init.d/postgres.init stop
+ </programlisting>
+ works.
+ </para>
+ </tip>
+
+ <para>
+ Also move the old directories out of the way. Type the following:
+ <programlisting>
+> mv /usr/local/pgsql /usr/local/pgsql.old
+ </programlisting>
+ (substitute your particular paths).
+ </para>
+
+ </step>
+
+ <step performance="required" id="continue">
+ <para>
+ Install the <productname>PostgreSQL</productname> executable files and
+ libraries. Type
+ <programlisting>
+> gmake install
+ </programlisting>
+ </para>
+ <para>
+ You should do this step as the user that you want the installed executables
+ to be owned by. This does not have to be the same as the database superuser;
+ some people prefer to have the installed files be owned by root.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ If necessary, tell your system how to find the new shared libraries.
+ How to do this varies between platforms. The most widely usable method
+ is to set the environment variable
+ <envar>LD_LIBRARY_PATH</envar>:
+ <programlisting>
+> LD_LIBRARY_PATH=/usr/local/pgsql/lib
+> export LD_LIBRARY_PATH
+ </programlisting>
+ on sh, ksh, bash, zsh or
+ <programlisting>
+> setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
+ </programlisting>
+ on csh or tcsh.
+ You might want to put this into a shell startup file such as
+ <filename>/etc/profile</filename>.
+ </para>
+
+ <para>
+ On some systems the following is the preferred method, but you must have root
+ access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
+ <programlisting>
+<filename>/usr/local/pgsql/lib</filename>
+ </programlisting>
+ Then run command <command>/sbin/ldconfig</command>.
+ </para>
+
+ <para>
+ If in doubt, refer to the manual pages of your system. If you later on get
+ a message like
+ <programlisting>
psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory
-</programlisting>
-then the above was necessary. Simply do this step then.
-</Para>
-</Step>
-
-<Step Performance="required">
-<Para>
-Create the database installation (the working data files).
-To do this you must log in to your
-<ProductName>PostgreSQL</ProductName> superuser account. It will not
-work as root.
-<ProgramListing>
-mkdir /usr/local/pgsql/data
-chown postgres /usr/local/pgsql/data
-su - postgres
-/usr/local/pgsql/initdb -D /usr/local/pgsql/data
-</ProgramListing>
-</Para>
-<Para>
-The <option>-D</option> option specifies the location where the data will be
-stored. You can use any path you want, it does not have to be under
-the installation directory. Just make sure that the superuser account
-can write to the directory (or create it, if it doesn't already exist)
-before starting <command>initdb</command>.
-(If you have already been doing the installation up to now as the <productname>PostgreSQL</productname>
-superuser, you may have to log in as root temporarily to create the data
-directory underneath a root-owned directory.)
-</Para>
-</Step>
-
-<Step Performance="required">
-<Para>
-The previous step should have told you how to start up the database server.
-Do so now. The command should look something like
-<programlisting>
-/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
-</programlisting>
-This will start the server in the foreground. To make it detach to
-the background, you can use the <option>-S</option> option, but then you won't
-see any log messages the server produces. A better way to put the server
-in the background is
-<programlisting>
-nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
+ </programlisting>
+ then the above was necessary. Simply do this step then.
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ Create the database installation (the working data files).
+ To do this you must log in to your
+ <productname>PostgreSQL</productname> superuser account. It will not
+ work as root.
+ <programlisting>
+> mkdir /usr/local/pgsql/data
+> chown postgres /usr/local/pgsql/data
+> su - postgres
+> /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+ </programlisting>
+ </para>
+ <para>
+ The <option>-D</option> option specifies the location where the data will be
+ stored. You can use any path you want, it does not have to be under
+ the installation directory. Just make sure that the superuser account
+ can write to the directory (or create it, if it doesn't already exist)
+ before starting <command>initdb</command>.
+ (If you have already been doing the installation up to now as the
+ <productname>PostgreSQL</productname>
+ superuser, you may have to log in as root temporarily to create the data
+ directory underneath a root-owned directory.)
+ </para>
+ </step>
+
+ <step performance="required">
+ <para>
+ The previous step should have told you how to start up the database server.
+ Do so now. The command should look something like
+ <programlisting>
+> /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
+ </programlisting>
+ This will start the server in the foreground. To make it detach to
+ the background, you can use the <option>-S</option> option, but then you won't
+ see any log messages the server produces. A better way to put the server
+ in the background is
+ <programlisting>
+> nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
</dev/null >>server.log 2>>1 &
-</programlisting>
-</Para>
-</Step>
+ </programlisting>
+ </para>
+ </step>
+
+ <step performance="optional">
+ <para>
+ If you are upgrading from an existing installation, dump your data back in:
+ <programlisting>
+> /usr/local/pgsql/bin/psql -d template1 -f db.out
+ </programlisting>
+ You also might want to copy over the old <filename>pg_hba.conf</filename>
+ file and any other files you might have had set up for authentication, such
+ as password files.
+ </para>
+ </step>
+ </procedure>
-<Step Performance="optional">
-<para>
-If you are upgrading from an existing installation, dump your data back in:
-<programlisting>
-/usr/local/pgsql/bin/psql -d template1 -f db.out
-</programlisting>
-You also might want to copy over the old <filename>pg_hba.conf</filename>
-file and any other files you might have had set up for authentication, such
-as password files.
-</Para>
-</Step>
-</Procedure>
-
-<para>
-This concludes the installation proper. To make your life more productive and enjoyable
-you should look at the following optional steps and suggestions.
-</para>
-
-<itemizedlist>
-<listitem>
-<Para>
-Life will be more convenient if you set up some environment variables. First of all
-you probably want to include <filename>/usr/local/pgsql/bin</filename> (or equivalent)
-into your <envar>PATH</envar>. To do this, add the following to your shell startup
-file, such as <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>,
-if you want it to affect every user):
-<programlisting>
-PATH=$PATH:/usr/local/pgsql/bin
-</programlisting>
-</Para>
-<Para>
-Furthermore, if you set <envar>PGDATA</envar> in the environment of the PostgreSQL
-superuser, you can omit the <option>-D</option> for <filename>postmaster</filename>
-and <filename>initdb</filename>.
-</Para>
-</listitem>
-
-<listitem>
-<Para>
-You probably want to install the <application>man</application> and
-<acronym>HTML</acronym> documentation. Type
-<ProgramListing>
-cd /usr/src/pgsql/postgresql-7.0/doc
-gmake install
-</ProgramListing>
-This will install files under <filename>/usr/local/pgsql/doc</filename>
-and <filename>/usr/local/pgsql/man</filename>. To enable your system
-to find the <application>man</application> documentation, you need to
-add a line like the following to a shell startup file:
-<ProgramListing>
-MANPATH=$MANPATH:/usr/local/pgsql/man
-</ProgramListing>
-</para>
-
-<para>
-The documentation is also available in Postscript format. If you have
-a Postscript printer, or have your machine already set up to accept
-Postscript files using a print filter, then to print the User's Guide
-simply type
-<programlisting>
-cd /usr/local/pgsql/doc
-gunzip -c user.ps.tz | lpr
-</programlisting>
-Here is how you might do it if you have Ghostscript on your system and are
-writing to a laserjet printer.
-<programlisting>
-gunzip -c user.ps.gz | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- | lpr
-</programlisting>
-Printer setups can vary wildly from system to system.
-If in doubt, consult your manuals or your local expert.
-</para>
-
-<para>
-The Adminstrator's Guide should probably be your first reading if you
-are completely new to <productname>PostgreSQL</productname>, as it contains
-information about how to set up database users and authentication.
-</para>
-</listitem>
-
-<listitem>
-<Para>
-Usually, you will want to modify your computer so that it will automatically
-start the database server whenever it boots.
-This is not required; the <ProductName>PostgreSQL</ProductName> server can
-be run successfully from non-privileged accounts without root intervention.
-</para>
-<para>
-Different systems have different conventions for starting up daemons at boot time,
-so you are advised to familiarize yourself with them.
-Most systems have a file <filename>/etc/rc.local</filename> or
-<filename>/etc/rc.d/rc.local</filename> which is almost certainly no bad place
-to put such a command.
-Whatever you do, postmaster must be run by the <ProductName>PostgreSQL</ProductName>
-superuser (<literal>postgres</literal>) <emphasis>and not by root</emphasis> or
-any other user. Therefore you probably always want to form your command lines
-along the lines of <literal>su -c '...' postgres</literal>.
-</para>
-<para>
-It might be advisable to keep a log of the server output. To start the server that way
-try:
-<ProgramListing>
-nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
-</ProgramListing>
-</para>
-
-<para>
-Here are a few more operating system specific suggestions.
-
-<itemizedlist>
-<listitem>
-<para>
-Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
- 2.5.1 to contain the following single line:
-<programlisting>
-su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
-</programlisting>
-</para>
-</listitem>
-
-<listitem>
-<para>
-In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
- contain the following lines and make it chmod 755 and chown
- root:bin.
+ <para>
+ This concludes the installation proper. To make your life more
+ productive and enjoyable
+ you should look at the following optional steps and suggestions.
+ </para>
-<programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Life will be more convenient if you set up some environment
+ variables. First of all
+ you probably want to include
+ <filename>/usr/local/pgsql/bin</filename> (or equivalent)
+ into your <envar>PATH</envar>. To do this, add the following to
+ your shell startup
+ file, such as <filename>~/.bash_profile</filename> (or
+ <filename>/etc/profile</filename>,
+ if you want it to affect every user):
+ <programlisting>
+> PATH=$PATH:/usr/local/pgsql/bin
+ </programlisting>
+ </para>
+ <para>
+ Furthermore, if you set <envar>PGDATA</envar> in the environment
+ of the PostgreSQL
+ superuser, you can omit the <option>-D</option> for
+ <filename>postmaster</filename>
+ and <filename>initdb</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ You probably want to install the <application>man</application> and
+ <acronym>HTML</acronym> documentation. Type
+ <programlisting>
+> cd /usr/src/pgsql/postgresql-7.0/doc
+> gmake install
+ </programlisting>
+ This will install files under <filename>/usr/local/pgsql/doc</filename>
+ and <filename>/usr/local/pgsql/man</filename>. To enable your system
+ to find the <application>man</application> documentation, you need to
+ add a line like the following to a shell startup file:
+ <programlisting>
+> MANPATH=$MANPATH:/usr/local/pgsql/man
+ </programlisting>
+ </para>
+
+ <para>
+ The documentation is also available in Postscript format. If you have
+ a Postscript printer, or have your machine already set up to accept
+ Postscript files using a print filter, then to print the User's Guide
+ simply type
+ <programlisting>
+> cd /usr/local/pgsql/doc
+> gunzip -c user.ps.tz | lpr
+ </programlisting>
+ Here is how you might do it if you have Ghostscript on your system and are
+ writing to a laserjet printer.
+ <programlisting>
+> gunzip -c user.ps.gz \
+ | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
+ | lpr
+ </programlisting>
+ Printer setups can vary wildly from system to system.
+ If in doubt, consult your manuals or your local expert.
+ </para>
+
+ <para>
+ The Adminstrator's Guide should probably be your first reading if you
+ are completely new to <productname>PostgreSQL</productname>, as it contains
+ information about how to set up database users and authentication.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Usually, you will want to modify your computer so that it will automatically
+ start the database server whenever it boots.
+ This is not required; the <productname>PostgreSQL</productname> server can
+ be run successfully from non-privileged accounts without root intervention.
+ </para>
+ <para>
+ Different systems have different conventions for starting up
+ daemons at boot time,
+ so you are advised to familiarize yourself with them.
+ Most systems have a file <filename>/etc/rc.local</filename> or
+ <filename>/etc/rc.d/rc.local</filename> which is almost
+ certainly no bad place
+ to put such a command.
+ Whatever you do, postmaster must be run by the
+ <productname>PostgreSQL</productname>
+ superuser (<literal>postgres</literal>) <emphasis>and not by
+ root</emphasis> or
+ any other user. Therefore you probably always want to form your command lines
+ along the lines of <literal>su -c '...' postgres</literal>.
+ </para>
+ <para>
+ It might be advisable to keep a log of the server output. To
+ start the server that way
+ try:
+ <programlisting>
+> nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
+ </programlisting>
+ </para>
+
+ <para>
+ Here are a few more operating system specific suggestions.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
+ 2.5.1 to contain the following single line:
+ <programlisting>
+> su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
+ </programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
+ contain the following lines and make it chmod 755 and chown
+ root:bin.
+
+ <programlisting>
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
@@ -550,57 +583,58 @@ In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
-S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql'
}
-</programlisting>
+ </programlisting>
+
+ You may put the line breaks as shown above. The shell is smart
+ 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>
+ In RedHat Linux add a file
+ <filename>/etc/rc.d/init.d/postgres.init</filename>
+ which is based on the example in <filename>contrib/linux/</filename>.
+ Then make a softlink to this file from
+ <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Run the regression tests against the installed server (using the sequential
+ test method). If you didn't run the tests before installation, you should
+ definitely do it now.
+ For detailed instructions see <xref endterm="regress-title"
+ linkend="regress">.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ To start <quote>playing around</quote>, set up the paths as explained above
+ and start the server. To create a database, type
+ <programlisting>
+> createdb testdb
+ </programlisting>
+ Then enter
+ <programlisting>
+> psql testdb
+ </programlisting>
+ to connect to that database. At the prompt you can enter SQL commands
+ and start experimenting.
+ </para>
- You may put the line breaks as shown above. The shell is smart
- 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>
-In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
-which is based on the example in <filename>contrib/linux/</filename>.
-Then make a softlink to this file from
- <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
-</para>
-</listitem>
-
-</itemizedlist>
-
-</Para>
-</listitem>
-
-<listitem>
-<Para>
-Run the regression tests against the installed server (using the sequential
-test method). If you didn't run the tests before installation, you should
-definitely do it now.
-For detailed instructions see <xref linkend="regress" endterm="regress-title">.
-</Para>
-</listitem>
-
-</itemizedlist>
-
-<Para>
-To start <quote>playing around</quote>, set up the paths as explained above
-and start the server. To create a database, type
-<ProgramListing>
-createdb testdb
-</ProgramListing>
-Then enter
-<ProgramListing>
-psql testdb
-</ProgramListing>
-to connect to that database. At the prompt you can enter SQL commands
-and start experimenting.
-</Para>
-
-</Sect1>
-
-</Chapter>
+ </sect1>
+ </chapter>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml
index 0acf9a2689c..1d6de96d8bf 100644
--- a/doc/src/sgml/intro.sgml
+++ b/doc/src/sgml/intro.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.11 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="intro">
@@ -16,7 +16,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
<productname>Postgres release 4.2</productname></ulink>.
The <productname>Postgres</productname> project,
led by Professor Michael Stonebraker, was sponsored by the
- Defense Advanced Research Projects Agency (<acronym>DARPA</acronym>), the
+ Defense Advanced Research Projects Agency
+ (<acronym>DARPA</acronym>), the
Army Research Office (<acronym>ARO</acronym>), the National Science
Foundation (<acronym>NSF</acronym>), and ESL, Inc.
</para>
@@ -37,7 +38,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
models in part because of its "Spartan simplicity".
However, as mentioned, this simplicity often makes the
implementation of certain applications very difficult.
- <productname>Postgres</productname> offers substantial additional
+ <productname>Postgres</productname> offers substantial additional
power by incorporating the following four additional
basic concepts in such a way that users can easily
extend the system:
@@ -62,13 +63,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
</para>
<para>
- These features put <productname>Postgres</productname> into the category of databases
- referred to as <firstterm>object-relational</firstterm>. Note that this is distinct
- from those referred to as <firstterm>object-oriented</firstterm>, which in general
- are not as well suited to supporting the traditional relational database languages.
- 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>.
+ These features put <productname>Postgres</productname> into the
+ category of databases referred to as
+ <firstterm>object-relational</firstterm>. Note that this is distinct
+ from those referred to as <firstterm>object-oriented</firstterm>,
+ which in general are not as well suited to supporting the
+ traditional relational database languages.
+ 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>
diff --git a/doc/src/sgml/legal.sgml b/doc/src/sgml/legal.sgml
index 02da480b496..41436347ee6 100644
--- a/doc/src/sgml/legal.sgml
+++ b/doc/src/sgml/legal.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.8 2000/04/07 13:30:58 thomas Exp $
-->
<sect1 id="copyright">
@@ -7,7 +7,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas
<para>
<productname>PostgreSQL</productname> is Copyright © 1996-2000
- by the PostgreSQL Inc.
+ by PostgreSQL Inc.
and is distributed under the terms of the Berkeley license.
</para>
@@ -35,14 +35,22 @@ $Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas
maintainance, support, updates, enhancements, or modifications.
</para>
+<!--
+How to keep track of all the trademarks? I'll try the strategy used at
+www.qnx.com - thomas
<para>
<acronym>Unix</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
and Solaris are trademarks of Sun Microsystems, Inc. DEC,
- DECstation, Alpha AXP and ULTRIX are trademarks of Digital
+ DECstation, Alpha AXP and ULTRIX are trademarks of Compaq, formerly Digital
Equipment Corp. PA-RISC and HP-UX are trademarks of
Hewlett-Packard Co. OSF/1 is a trademark of the Open
Software Foundation.
</para>
+-->
+
+ <para>
+ All trademarks are the property of their respective owners.
+ </para>
</sect1>
<!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml
index 053857c96e1..31153c8a1f0 100644
--- a/doc/src/sgml/notation.sgml
+++ b/doc/src/sgml/notation.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.9 2000/04/07 13:30:58 thomas Exp $
-->
<sect1 id="terminology">
@@ -25,13 +25,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho
binaries and database files. As the database superuser, all
protection mechanisms may be bypassed and any data accessed
arbitrarily.
- In addition, the <Productname>Postgres</Productname> superuser is allowed to execute
+ In addition, the <Productname>Postgres</Productname> superuser is
+ allowed to execute
some support programs which are generally not available to all users.
Note that the <Productname>Postgres</Productname> superuser is
<emphasis>not</emphasis>
- 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.
+ 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>
@@ -82,18 +84,21 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho
In a command synopsis, brackets
(<quote>[</quote> and <quote>]</quote>) indicate an optional phrase or keyword.
Anything in braces
- (<quote>{</quote> and <quote>}</quote>) and containing vertical bars (<quote>|</quote>)
+ (<quote>{</quote> and <quote>}</quote>) and containing vertical bars
+ (<quote>|</quote>)
indicates that you must choose one.
</para>
<para>
- In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean
+ In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are
+ used to group boolean
expressions. <quote>|</quote> is the boolean operator OR.
</para>
<para>
Examples will show commands executed from various accounts and programs.
- Commands executed from the root account will be preceeded with <quote>></quote>.
+ Commands executed from the root account will be preceeded with
+ <quote>></quote>.
Commands executed from the <Productname>Postgres</Productname>
superuser account will be preceeded with <quote>%</quote>, while commands
executed from an unprivileged user's account will be preceeded with
@@ -104,8 +109,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho
<note>
<para>
- At the time of writing (<Productname>Postgres</Productname> v6.5) the notation for
- flagging commands is not universally consistant throughout the documentation set.
+ At the time of writing (<Productname>Postgres</Productname> v7.0)
+ the notation for
+ 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>
diff --git a/doc/src/sgml/ports.sgml b/doc/src/sgml/ports.sgml
index c90eb4cc417..ee2b760ba33 100644
--- a/doc/src/sgml/ports.sgml
+++ b/doc/src/sgml/ports.sgml
@@ -32,15 +32,15 @@
<row>
<entry>AIX 4.3.2</entry>
<entry>RS6000</entry>
- <entry>v6.5</entry>
- <entry>1999-05-26</entry>
+ <entry>v7.0</entry>
+ <entry>2000-04-05</entry>
<entry>(<ulink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ulink>)</entry>
</row>
<row>
- <entry>BSDI</entry>
+ <entry>BSDI 4.01</entry>
<entry>x86</entry>
- <entry>v6.5</entry>
- <entry>1999-05-25</entry>
+ <entry>v7.0</entry>
+ <entry>2000-04-04</entry>
<entry>(<ulink url="mailto:maillist@candle.pha.pa.us">Bruce Momjian</ulink></entry>
</row>
<row>
@@ -60,12 +60,11 @@
(<ulink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ulink>)</entry>
</row>
<row>
- <entry>FreeBSD 2.2.x-4.0</entry>
+ <entry>FreeBSD 4.0</entry>
<entry>x86</entry>
- <entry>v6.5</entry>
- <entry>1999-05-25</entry>
- <entry>(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>,
- <ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink>)</entry>
+ <entry>v7.0</entry>
+ <entry>2000-04-04</entry>
+ <entry>(<ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink>)</entry>
</row>
<row>
<entry>HPUX</entry>
@@ -136,17 +135,17 @@
(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry>
</row>
<row>
- <entry>Linux 2.0.x</entry>
+ <entry>Linux 2.2.5</entry>
<entry>Sparc</entry>
- <entry>v6.4</entry>
- <entry>1998-10-25</entry>
+ <entry>v7.0</entry>
+ <entry>2000-04-02</entry>
<entry>(<ulink url="mailto:szybist@boxhill.com">Tom Szybist</ulink>)</entry>
</row>
<row>
- <entry>LinuxPPC R4 2.2.1/libc5</entry>
+ <entry>LinuxPPC R4</entry>
<entry>PPC603e</entry>
<entry>v7.0</entry>
- <entry>2000-03-26</entry>
+ <entry>2000-04-04</entry>
<entry>Powerbook 2400c
(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry>
</row>
@@ -250,20 +249,20 @@
(<ulink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ulink>)</entry>
</row>
<row>
- <entry>Windows</entry>
+ <entry>Windows/Win32</entry>
<entry>x86</entry>
- <entry>v6.4</entry>
- <entry>1999-01-06</entry>
- <entry>Client-side libraries or ODBC/JDBC. No server yet.
+ <entry>v7.0</entry>
+ <entry>2000-04-02</entry>
+ <entry>Client-side libraries or ODBC/JDBC. No server-side.
(<ulink url="mha@sollentuna.net">Magnus Hagander</ulink></entry>
</row>
<row>
- <entry>Windows NT</entry>
+ <entry>WinNT/Cygwin</entry>
<entry>x86</entry>
- <entry>v6.5</entry>
- <entry>1999-05-26</entry>
+ <entry>v7.0</entry>
+ <entry>2000-03-30</entry>
<entry>Working with the Cygwin library.
- (<ulink url="mailto:Dan.Horak@email.cz">Daniel Horak</ulink>) </entry>
+ (<ulink url="mailto:horak@sit.plzen-city.cz">Daniel Horak</ulink>) </entry>
</row>
</tbody>
</tgroup>
@@ -273,8 +272,9 @@
<note>
<para>
For <productname>Windows NT</productname>,
- the server-side port of <productname>Postgres</productname> has recently been
- accomplished. The Cygnus library is required to compile it.
+ the server-side port of <productname>Postgres</productname> uses
+ the RedHat/Cygnus <productname>Cygwin</productname> library and
+ toolset.
</para>
</note>
</sect1>
@@ -289,7 +289,8 @@
</para>
<para>
- At the time of publication, the following platforms have been tested:
+ At the time of publication, the following platforms have not been
+ tested for v7.0:
<table tocentry="1">
<title>Obsolete Platforms</title>
diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index 11b603f6523..971be248387 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.9 2000/03/31 03:27:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="query">
@@ -8,20 +8,21 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.9 2000/03/31 03:27:41 thomas
<para>
The <productname>Postgres</productname> query language is a variant of
the <acronym>SQL3</acronym> draft next-generation standard. It
- has many extensions such as an extensible type system,
+ has many extensions to <acronym>SQL92</acronym> such as an
+ extensible type system,
inheritance, functions and production rules. These are
- features carried over from the original <productname>Postgres</productname> query
- language, <productname>PostQuel</productname>. This section provides an overview
+ features carried over from the original
+ <productname>Postgres</productname> query
+ language, <productname>PostQuel</productname>.
+ This section provides an overview
of how to use <productname>Postgres</productname>
<acronym>SQL</acronym> to perform simple operations.
This manual is only intended to give you an idea of our
flavor of <acronym>SQL</acronym> and is in no way a complete tutorial on
<acronym>SQL</acronym>. Numerous books have been written on
- <acronym>SQL</acronym>, including
-<!--
-<XRef LinkEnd="MELT93"> and <XRef LinkEnd="DATE97">.
--->
-[MELT93] and [DATE97].
+ <acronym>SQL92</acronym>, including
+ <xref linkend="MELT93" endterm="MELT93-title"> and
+ <xref linkend="DATE97" endterm="DATE97-title">.
You should be aware that some language features
are extensions to the <acronym>ANSI</acronym> standard.
</para>
@@ -111,22 +112,26 @@ CREATE TABLE weather (
</para>
<para>
- Note that both keywords and identifiers are case-insensitive; identifiers can become
- case-sensitive by surrounding them with double-quotes as allowed
+ Note that both keywords and identifiers are case-insensitive;
+ identifiers can preserve case by surrounding them with
+ double-quotes as allowed
by <acronym>SQL92</acronym>.
- <productname>Postgres</productname> <acronym>SQL</acronym> supports the usual
+ <productname>Postgres</productname> <acronym>SQL</acronym>
+ supports the usual
<acronym>SQL</acronym> types <type>int</type>,
<type>float</type>, <type>real</type>, <type>smallint</type>,
<type>char(N)</type>,
<type>varchar(N)</type>, <type>date</type>, <type>time</type>,
and <type>timestamp</type>, as well as other types of general utility and
a rich set of geometric types. As we will
- see later, <productname>Postgres</productname> can be customized with an
+ see later, <productname>Postgres</productname> can be customized
+ with an
arbitrary number of
user-defined data types. Consequently, type names are
not syntactical keywords, except where required to support special
cases in the <acronym>SQL92</acronym> standard.
- So far, the <productname>Postgres</productname> <command>CREATE</command> command
+ So far, the <productname>Postgres</productname>
+ <command>CREATE</command> command
looks exactly like
the command used to create a table in a traditional
relational system. However, we will presently see that
@@ -139,7 +144,7 @@ CREATE TABLE weather (
<title>Populating a Class with Instances</title>
<para>
- The <command>insert</command> statement is used to populate a class with
+ The <command>INSERT</command> statement is used to populate a class with
instances:
<programlisting>
@@ -149,9 +154,10 @@ INSERT INTO weather
</para>
<para>
- You can also use the <command>copy</command> command to perform load large
+ You can also use the <command>COPY</command> command to perform load large
amounts of data from flat (<acronym>ASCII</acronym>) files.
- This is usually faster because the data is read (or written) as a single atomic
+ This is usually faster because the data is read (or written) as a
+ single atomic
transaction directly to or from the target table. An example would be:
<programlisting>
@@ -159,7 +165,8 @@ COPY weather FROM '/home/user/weather.txt'
USING DELIMITERS '|';
</programlisting>
- where the path name for the source file must be available to the backend server
+ where the path name for the source file must be available to the
+ backend server
machine, not the client, since the backend server reads the file directly.
</para>
</sect1>
@@ -170,7 +177,7 @@ COPY weather FROM '/home/user/weather.txt'
<para>
The weather class can be queried with normal relational
selection and projection queries. A <acronym>SQL</acronym>
- <command>select</command>
+ <command>SELECT</command>
statement is used to do this. The statement is divided into
a target list (the part that lists the attributes to be
returned) and a qualification (the part that specifies
@@ -192,7 +199,8 @@ SELECT * FROM weather;
|Hayward | 37 | 54 | | 11-29-1994 |
+--------------+---------+---------+------+------------+
</programlisting>
- You may specify any arbitrary expressions in the target list. For example, you can do:
+ You may specify any arbitrary expressions in the target list. For
+ example, you can do:
<programlisting>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</programlisting>
@@ -200,7 +208,8 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
<para>
Arbitrary Boolean operators
- (<command>and</command>, <command>or</command> and <command>not</command>) are
+ (<command>AND</command>, <command>OR</command> and
+ <command>NOT</command>) are
allowed in the qualification of any query. For example,
<programlisting>
@@ -235,16 +244,16 @@ SELECT DISTINCT city
<title>Redirecting SELECT Queries</title>
<para>
- Any select query can be redirected to a new class
+ Any <command>SELECT</command> query can be redirected to a new class
<programlisting>
SELECT * INTO TABLE temp FROM weather;
</programlisting>
</para>
<para>
- This forms an implicit <command>create</command> command, creating a new
+ This forms an implicit <command>CREATE</command> command, creating a new
class temp with the attribute names and types specified
- in the target list of the <command>select into</command> command. We can
+ in the target list of the <command>SELECT INTO</command> command. We can
then, of course, perform any operations on the resulting
class that we can perform on other classes.
</para>
@@ -269,7 +278,8 @@ SELECT * INTO TABLE temp FROM weather;
<note>
<para>
This is only a conceptual model. The actual join may
- be performed in a more efficient manner, but this is invisible to the user.
+ be performed in a more efficient manner, but this is invisible
+ to the user.
</para>
</note>
@@ -307,16 +317,18 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
sometimes recomputes the same target list several times;
this frequently happens when Boolean expressions are connected
with an "or". To remove such duplicates, you must use
- the <command>select distinct</command> statement.
+ the <command>SELECT DISTINCT</command> statement.
</para>
</note>
</para>
<para>
- In this case, both W1 and W2 are surrogates for an
+ In this case, both <literal>W1</literal> and
+ <literal>W2</literal> are surrogates for an
instance of the class weather, and both range over all
instances of the class. (In the terminology of most
- database systems, W1 and W2 are known as <firstterm>range variables</firstterm>.)
+ database systems, <literal>W1</literal> and <literal>W2</literal>
+ are known as <firstterm>range variables</firstterm>.)
A query can contain an arbitrary number of
class names and surrogates.
</para>
@@ -326,7 +338,8 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
<title>Updates</title>
<para>
- You can update existing instances using the update command.
+ You can update existing instances using the
+ <command>UPDATE</command> command.
Suppose you discover the temperature readings are
all off by 2 degrees as of Nov 28, you may update the
data as follow:
@@ -343,7 +356,7 @@ UPDATE weather
<title>Deletions</title>
<para>
- Deletions are performed using the <command>delete</command> command:
+ Deletions are performed using the <command>DELETE</command> command:
<programlisting>
DELETE FROM weather WHERE city = 'Hayward';
</programlisting>
@@ -354,7 +367,7 @@ DELETE FROM weather WHERE city = 'Hayward';
DELETE FROM classname;
</programlisting>
- Without a qualification, <command>delete</command> will simply
+ Without a qualification, <command>DELETE</command> will simply
remove all instances of the given class, leaving it
empty. The system will not request confirmation before
doing this.
@@ -365,7 +378,7 @@ DELETE FROM classname;
<title>Using Aggregate Functions</title>
<para>
- Like most other query languages,
+ Like most other relational database products,
<productname>PostgreSQL</productname> supports
aggregate functions.
An aggregate function computes a single result from multiple input rows.
@@ -377,20 +390,20 @@ DELETE FROM classname;
<para>
It is important to understand the interaction between aggregates and
- SQL's <command>where</command> and <command>having</command> clauses.
- The fundamental difference between <command>where</command> and
- <command>having</command> is this: <command>where</command> selects
+ SQL's <command>WHERE</command> and <command>HAVING</command> clauses.
+ The fundamental difference between <command>WHERE</command> and
+ <command>HAVING</command> is this: <command>WHERE</command> selects
input rows before groups and aggregates are computed (thus, it controls
which rows go into the aggregate computation), whereas
- <command>having</command> selects group rows after groups and
+ <command>HAVING</command> selects group rows after groups and
aggregates are computed. Thus, the
- <command>where</command> clause may not contain aggregate functions;
+ <command>WHERE</command> clause may not contain aggregate functions;
it makes no sense to try to use an aggregate to determine which rows
will be inputs to the aggregates. On the other hand,
- <command>having</command> clauses always contain aggregate functions.
- (Strictly speaking, you are allowed to write a <command>having</command>
+ <command>HAVING</command> clauses always contain aggregate functions.
+ (Strictly speaking, you are allowed to write a <command>HAVING</command>
clause that doesn't use aggregates, but it's wasteful; the same condition
- could be used more efficiently at the <command>where</command> stage.)
+ could be used more efficiently at the <command>WHERE</command> stage.)
</para>
<para>
@@ -408,13 +421,17 @@ SELECT max(temp_lo) FROM weather;
SELECT city FROM weather WHERE temp_lo = max(temp_lo);
</programlisting>
- but this will not work since the aggregate max() can't be used in
- <command>where</command>. However, as is often the case the query can be
+ but this will not work since the aggregate
+ <function>max</function> can't be used in
+ <command>WHERE</command>. However, as is often the case the query can be
restated to accomplish the intended result; here by using a
<firstterm>subselect</firstterm>:
+
<programlisting>
-SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
+SELECT city FROM weather
+ WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
</programlisting>
+
This is OK because the sub-select is an independent computation that
computes its own aggregate separately from what's happening in the outer
select.
@@ -422,24 +439,29 @@ SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
<para>
Aggregates are also very useful in combination with
- <firstterm>group by</firstterm> clauses. For example, we can get the
+ <command>GROUP BY</command> clauses. For example, we can get the
maximum low temperature observed in each city with
+
<programlisting>
SELECT city, max(temp_lo)
FROM weather
GROUP BY city;
</programlisting>
+
which gives us one output row per city. We can filter these grouped
- rows using <command>having</command>:
+ rows using <command>HAVING</command>:
+
<programlisting>
SELECT city, max(temp_lo)
FROM weather
GROUP BY city
HAVING min(temp_lo) < 0;
</programlisting>
+
which gives us the same results for only the cities that have some
below-zero readings. Finally, if we only care about cities whose
- names begin with 'P', we might do
+ names begin with "<literal>P</literal>", we might do
+
<programlisting>
SELECT city, max(temp_lo)
FROM weather
@@ -447,11 +469,12 @@ SELECT city, max(temp_lo)
GROUP BY city
HAVING min(temp_lo) < 0;
</programlisting>
+
Note that we can apply the city-name restriction in
- <command>where</command>, since it needs no aggregate. This is
- more efficient than adding the restriction to <command>having</command>,
+ <command>WHERE</command>, since it needs no aggregate. This is
+ more efficient than adding the restriction to <command>HAVING</command>,
because we avoid doing the grouping and aggregate calculations
- for all rows that fail the <command>where</command> check.
+ for all rows that fail the <command>WHERE</command> check.
</para>
</sect1>
</chapter>
diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml
index 1df0a41c8aa..e030d4dbf84 100644
--- a/doc/src/sgml/sql.sgml
+++ b/doc/src/sgml/sql.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.8 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="sql">
@@ -7,18 +7,28 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<abstract>
<para>
- This chapter originally appeared as a part of
+ This chapter introduces the mathematical concepts behind
+ relational databases. It is not required reading, so if you bog
+ down or want to get straight to some simple examples feel free to
+ jump ahead to the next chapter and come back when you have more
+ time and patience. This stuff is supposed to be fun!
+ </para>
+
+ <para>
+ This material originally appeared as a part of
Stefan Simkovics' Master's Thesis
(<xref linkend="SIM98" endterm="SIM98">).
</para>
</abstract>
<para>
- <acronym>SQL</acronym> has become the most popular relational query language.
+ <acronym>SQL</acronym> has become the most popular relational query
+ language.
The name <quote><acronym>SQL</acronym></quote> is an abbreviation for
<firstterm>Structured Query Language</firstterm>.
In 1974 Donald Chamberlin and others defined the
- language SEQUEL (<firstterm>Structured English Query Language</firstterm>) at IBM
+ language SEQUEL (<firstterm>Structured English Query
+ Language</firstterm>) at IBM
Research. This language was first implemented in an IBM
prototype called SEQUEL-XRM in 1974-75. In 1976-77 a revised version
of SEQUEL called SEQUEL/2 was defined and the name was changed to
@@ -28,13 +38,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<para>
A new prototype called System R was developed by IBM in 1977. System R
- implemented a large subset of SEQUEL/2 (now <acronym>SQL</acronym>) and a number of
+ implemented a large subset of SEQUEL/2 (now <acronym>SQL</acronym>)
+ and a number of
changes were made to <acronym>SQL</acronym> during the project.
System R was installed in
a number of user sites, both internal IBM sites and also some selected
customer sites. Thanks to the success and acceptance of System R at
those user sites IBM started to develop commercial products that
- implemented the <acronym>SQL</acronym> language based on the System R technology.
+ implemented the <acronym>SQL</acronym> language based on the System
+ R technology.
</para>
<para>
@@ -48,16 +60,20 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
</para>
<para>
- <acronym>SQL</acronym> is also an official standard now. In 1982 the American National
- Standards Institute (<acronym>ANSI</acronym>) chartered its Database Committee X3H2 to
+ <acronym>SQL</acronym> is also an official standard now. In 1982
+ the American National
+ Standards Institute (<acronym>ANSI</acronym>) chartered its
+ Database Committee X3H2 to
develop a proposal for a standard relational language. This proposal
was ratified in 1986 and consisted essentially of the IBM dialect of
<acronym>SQL</acronym>. In 1987 this <acronym>ANSI</acronym>
standard was also accepted as an international
standard by the International Organization for Standardization
(<acronym>ISO</acronym>).
- This original standard version of <acronym>SQL</acronym> is often referred to,
- informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original standard was extended
+ This original standard version of <acronym>SQL</acronym> is often
+ referred to,
+ informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original
+ standard was extended
and this new standard is often, again informally, referred to as
"<abbrev>SQL/89</abbrev>". Also in 1989, a related standard called
<firstterm>Database Language Embedded <acronym>SQL</acronym></firstterm>
@@ -73,12 +89,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
ratified standard - "International Standard ISO/IEC 9075:1992,
Database Language <acronym>SQL</acronym>" - in late 1992.
<acronym>SQL/92</acronym> is the version
- normally meant when people refer to "the <acronym>SQL</acronym> standard". A detailed
+ normally meant when people refer to "the <acronym>SQL</acronym>
+ standard". A detailed
description of <acronym>SQL/92</acronym> is given in
<xref linkend="DATE97" endterm="DATE97">. At the time of
writing this document a new standard informally referred to
as <firstterm><acronym>SQL3</acronym></firstterm>
- is under development. It is planned to make <acronym>SQL</acronym> a Turing-complete
+ is under development. It is planned to make <acronym>SQL</acronym>
+ a Turing-complete
language, i.e. all computable queries (e.g. recursive queries) will be
possible. This is a very complex task and therefore the completion of
the new standard can not be expected before 1999.
@@ -100,8 +118,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
</para>
<para>
- A <firstterm>relational database</firstterm> is a database that is perceived by its
- users as a <firstterm>collection of tables</firstterm> (and nothing else but tables).
+ A <firstterm>relational database</firstterm> is a database that is
+ perceived by its
+ users as a <firstterm>collection of tables</firstterm> (and
+ nothing else but tables).
A table consists of rows and columns where each row represents a
record and each column represents an attribute of the records
contained in the table.
@@ -154,13 +174,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
</para>
<para>
- The tables PART and SUPPLIER may be regarded as <firstterm>entities</firstterm> and
- SELLS may be regarded as a <firstterm>relationship</firstterm> between a particular
+ The tables PART and SUPPLIER may be regarded as
+ <firstterm>entities</firstterm> and
+ SELLS may be regarded as a <firstterm>relationship</firstterm>
+ between a particular
part and a particular supplier.
</para>
<para>
- As we will see later, <acronym>SQL</acronym> operates on tables like the ones just
+ As we will see later, <acronym>SQL</acronym> operates on tables
+ like the ones just
defined but before that we will study the theory of the relational
model.
</para>
@@ -171,7 +194,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<para>
The mathematical concept underlying the relational model is the
- set-theoretic <firstterm>relation</firstterm> which is a subset of the Cartesian
+ set-theoretic <firstterm>relation</firstterm> which is a subset of
+ the Cartesian
product of a list of domains. This set-theoretic relation gives
the model its name (do not confuse it with the relationship from the
<firstterm>Entity-Relationship model</firstterm>).
@@ -184,7 +208,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<para>
<!--
\begin{definition}
-The <firstterm>Cartesian product</firstterm> of domains $D_{1}, D_{2},\ldots, D_{k}$ written
+The <firstterm>Cartesian product</firstterm> of domains $D_{1},
+ D_{2},\ldots, D_{k}$ written
\mbox{$D_{1} \times D_{2} \times \ldots \times D_{k}$} is the set of
all $k$-tuples $(v_{1},v_{2},\ldots,v_{k})$ such that \mbox{$v_{1} \in
D_{1}, v_{2} \in D_{2}, \ldots, v_{k} \in D_{k}$}.
@@ -304,8 +329,10 @@ attributes are taken from. We often write a relation scheme as
<note>
<para>
A <firstterm>relation scheme</firstterm> is just a kind of template
- whereas a <firstterm>relation</firstterm> is an instance of a <firstterm>relation
- scheme</firstterm>. The relation consists of tuples (and can therefore be
+ whereas a <firstterm>relation</firstterm> is an instance of a
+ <firstterm>relation
+ scheme</firstterm>. The relation consists of tuples (and can
+ therefore be
viewed as a table); not so the relation scheme.
</para>
</note>
@@ -332,8 +359,10 @@ attributes are taken from. We often write a relation scheme as
<type>VARCHAR(20)</type> (this is the <acronym>SQL</acronym> type
for character strings of length <= 20),
the type of <classname>SNO</classname> will be
- <type>INTEGER</type>. With the assignment of a data type we also have selected
- a domain for an attribute. The domain of <classname>SNAME</classname> is the set of all
+ <type>INTEGER</type>. With the assignment of a data type we also
+ have selected
+ a domain for an attribute. The domain of
+ <classname>SNAME</classname> is the set of all
character strings of length <= 20,
the domain of <classname>SNO</classname> is the set of
all integer numbers.
@@ -345,7 +374,8 @@ attributes are taken from. We often write a relation scheme as
<title id="operations">Operations in the Relational Data Model</title>
<para>
- In the previous section (<xref linkend="formal-notion" endterm="formal-notion">)
+ In the previous section
+ (<xref linkend="formal-notion" endterm="formal-notion">)
we defined the mathematical notion of
the relational model. Now we know how the data can be stored using a
relational data model but we do not know what to do with all these
@@ -357,7 +387,8 @@ attributes are taken from. We often write a relation scheme as
<itemizedlist>
<listitem>
<para>
- The <firstterm>Relational Algebra</firstterm> which is an algebraic notation,
+ The <firstterm>Relational Algebra</firstterm> which is an
+ algebraic notation,
where queries are expressed by applying specialized operators to the
relations.
</para>
@@ -365,7 +396,8 @@ attributes are taken from. We often write a relation scheme as
<listitem>
<para>
- The <firstterm>Relational Calculus</firstterm> which is a logical notation,
+ The <firstterm>Relational Calculus</firstterm> which is a
+ logical notation,
where queries are expressed by formulating some logical restrictions
that the tuples in the answer must satisfy.
</para>
@@ -383,7 +415,8 @@ attributes are taken from. We often write a relation scheme as
<itemizedlist>
<listitem>
<para>
- SELECT (σ): extracts <firstterm>tuples</firstterm> from a relation that
+ SELECT (σ): extracts <firstterm>tuples</firstterm> from
+ a relation that
satisfy a given restriction. Let <parameter>R</parameter> be a
table that contains an attribute
<parameter>A</parameter>.
@@ -441,10 +474,12 @@ attributes are taken from. We often write a relation scheme as
INTERSECT (∩): builds the set-theoretic intersection of two
tables. Given the tables <classname>R</classname> and
<classname>S</classname>,
- <classname>R</classname> ∪ <classname>S</classname> is the set of tuples
+ <classname>R</classname> ∪ <classname>S</classname> is the
+ set of tuples
that are in <classname>R</classname> and in
<classname>S</classname>.
- We again require that <classname>R</classname> and <classname>S</classname> have the
+ We again require that <classname>R</classname> and
+ <classname>S</classname> have the
same arity.
</para>
</listitem>
@@ -455,7 +490,8 @@ attributes are taken from. We often write a relation scheme as
two tables. Let <classname>R</classname> and <classname>S</classname>
again be two tables with the same
arity. <classname>R</classname> - <classname>S</classname>
- is the set of tuples in <classname>R</classname> but not in <classname>S</classname>.
+ is the set of tuples in <classname>R</classname> but not in
+ <classname>S</classname>.
</para>
</listitem>
@@ -672,9 +708,9 @@ t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>
the one underlying the most relational languages. For a detailed
discussion on <acronym>DRC</acronym> (and also
<acronym>TRC</acronym>) see
- [<xref linkend="DATE94" endterm="DATE94">]
+ <xref linkend="DATE94" endterm="DATE94">
or
- [<xref linkend="ULL88" endterm="ULL88">].
+ <xref linkend="ULL88" endterm="ULL88">.
</para>
</sect2>
@@ -727,9 +763,9 @@ t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>
algorithm</quote>) by which an arbitrary expression of the relational
calculus can be reduced to a semantically equivalent expression of
relational algebra. For a more detailed discussion on that refer to
- [<xref linkend="DATE94" endterm="DATE94">]
+ <xref linkend="DATE94" endterm="DATE94">
and
- [<xref linkend="ULL88" endterm="ULL88">].
+ <xref linkend="ULL88" endterm="ULL88">.
</para>
<para>
@@ -750,9 +786,11 @@ t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>
<acronym>SQL</acronym> is based on the tuple
relational calculus. As a result every query that can be formulated
using the tuple relational calculus (or equivalently, relational
- algebra) can also be formulated using <acronym>SQL</acronym>. There are, however,
+ algebra) can also be formulated using
+ <acronym>SQL</acronym>. There are, however,
capabilities beyond the scope of relational algebra or calculus. Here
- is a list of some additional features provided by <acronym>SQL</acronym> that are not
+ is a list of some additional features provided by
+ <acronym>SQL</acronym> that are not
part of relational algebra or calculus:
<itemizedlist>
@@ -764,7 +802,8 @@ t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>
<listitem>
<para>
- Arithmetic capability: In <acronym>SQL</acronym> it is possible to involve
+ Arithmetic capability: In <acronym>SQL</acronym> it is possible
+ to involve
arithmetic operations as well as comparisons, e.g.
A < B + 3.
@@ -787,7 +826,8 @@ t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>
<para>
Aggregate Functions: Operations such as
<firstterm>average</firstterm>, <firstterm>sum</firstterm>,
- <firstterm>max</firstterm>, etc. can be applied to columns of a relation to
+ <firstterm>max</firstterm>, etc. can be applied to columns of a
+ relation to
obtain a single quantity.
</para>
</listitem>
@@ -918,7 +958,8 @@ t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>
Note that the word DOUBLE after the keyword AS is the new title of the
second column. This technique can be used for every element of the
- target list to assign a new title to the resulting column. This new title
+ target list to assign a new title to the resulting
+ column. This new title
is often referred to as alias. The alias cannot be used throughout the
rest of the query.
</para>
@@ -1508,8 +1549,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para>
A view may be regarded as a <firstterm>virtual table</firstterm>,
i.e. a table that
- does not <emphasis>physically</emphasis> exist in the database but looks to the user
- as if it does. By contrast, when we talk of a <firstterm>base table</firstterm> there is
+ does not <emphasis>physically</emphasis> exist in the database
+ but looks to the user
+ as if it does. By contrast, when we talk of a
+ <firstterm>base table</firstterm> there is
really a physically stored counterpart of each row of the table
somewhere in the physical storage.
</para>
@@ -1550,7 +1593,8 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para>
Let the following view definition be given (we use
- the tables from <xref linkend="supplier-fig" endterm="supplier-fig"> again):
+ the tables from
+ <xref linkend="supplier-fig" endterm="supplier-fig"> again):
<programlisting>
CREATE VIEW London_Suppliers
@@ -1587,7 +1631,8 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<emphasis>hidden</emphasis>
access to the base tables SUPPLIER, SELLS and PART first. It
does so by executing the query given in the view definition against
- those base tables. After that the additional qualifications (given in the
+ those base tables. After that the additional qualifications
+ (given in the
query against the view) can be applied to obtain the resulting
table.
</para>
@@ -1746,11 +1791,12 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<!--
section
<xref linkend="view-impl" endterm="view-impl">.
+ <citetitle>SIM98</citetitle>
-->
- <citetitle>SIM98</citetitle>
+ <xref linkend="SIM98" endterm="SIM98">
for a more detailed
description). For more information about system catalogs refer to
- <citetitle>DATE</citetitle>.
+ <xref linkend="DATE94" endterm="DATE94">.
</para>
</sect2>
@@ -1815,10 +1861,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para>
For a detailed discussion on embedded <acronym>SQL</acronym>
refer to
- [<xref linkend="DATE97" endterm="DATE97">],
- [<xref linkend="DATE94" endterm="DATE94">],
+ <xref linkend="DATE97" endterm="DATE97">,
+ <xref linkend="DATE94" endterm="DATE94">,
or
- [<xref linkend="ULL88" endterm="ULL88">].
+ <xref linkend="ULL88" endterm="ULL88">.
</para>
</sect2>
</sect1>
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 5589eca7f34..ccb43fbb0f8 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -1,250 +1,333 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.9 2000/03/31 03:27:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
-<Chapter Id="start">
-<Title>Getting Started</Title>
-
-<Abstract>
-<Para>
-How to begin work with <ProductName>Postgres</ProductName> for a new user.
-</Para>
-</Abstract>
-
-<Para>
- Some of the steps required to use <ProductName>Postgres</ProductName>
- can be performed by any Postgres user, and some must be done by
- the site database administrator. This site administrator
- is the person who installed the software, created
- the database directories and started the <Application>postmaster</Application>
- process. This person does not have to be the Unix
- superuser (<Quote>root</Quote>)
- or the computer system administrator; a person can install and use
-<ProductName>Postgres</ProductName> without any special accounts or privileges.
-</Para>
-
-<Para>
-If you are installing <ProductName>Postgres</ProductName> yourself, then
-refer to the Administrator's Guide for instructions on installation, and return
-to this guide when the installation is complete.
-</Para>
-
-<Para>
- Throughout this manual, any examples that begin with
- the character <Quote>%</Quote> are commands that should be typed
- at the Unix shell prompt. Examples that begin with the
- character <Quote>*</Quote> are commands in the Postgres query
- language, Postgres <Acronym>SQL</Acronym>.
-</Para>
-
-<Sect1>
-<Title>Setting Up Your Environment</Title>
-
-<Para>
- This section discusses how to set up
- your own environment so that you can use frontend
- applications. We assume <ProductName>Postgres</ProductName> has already been
- successfully installed and started; refer to the Administrator's Guide
-and the installation notes
- for how to install Postgres.
-</Para>
-
-<Para>
-<ProductName>Postgres</ProductName> is a client/server application. As a user,
-you only need access to the client portions of the installation (an example
-of a client application is the interactive monitor <Application>psql</Application>).
- For simplicity,
- we will assume that <ProductName>Postgres</ProductName> has been installed in the
- directory <FileName>/usr/local/pgsql</FileName>. Therefore, wherever
- you see the directory <FileName>/usr/local/pgsql</FileName> you should
- substitute the name of the directory where <ProductName>Postgres</ProductName> is
- actually installed.
- All <ProductName>Postgres</ProductName> commands are installed in the directory
- <FileName>/usr/local/pgsql/bin</FileName>. Therefore, you should add
- this directory to your shell command path. If you use
- a variant of the Berkeley C shell, such as csh or tcsh,
- you would add
-<ProgramListing>
+ <chapter id="start">
+ <title>Getting Started</title>
+
+ <abstract>
+ <para>
+ How to begin work with <productname>Postgres</productname> for a new user.
+ </para>
+ </abstract>
+
+ <para>
+ Some of the steps required to use <productname>Postgres</productname>
+ can be performed by any Postgres user, and some must be done by
+ the site database administrator. This site administrator
+ is the person who installed the software, created
+ the database directories and started the
+ <application>postmaster</application>
+ process. This person does not have to be the Unix
+ superuser (<quote>root</quote>)
+ or the computer system administrator; a person can install and use
+ <productname>Postgres</productname> without any special accounts or
+ privileges.
+ </para>
+
+ <para>
+ If you are installing <productname>Postgres</productname> yourself, then
+ refer to the Administrator's Guide for instructions on
+ installation, and return
+ to this guide when the installation is complete.
+ </para>
+
+ <para>
+ Throughout this manual, any examples that begin with
+ the character <quote>%</quote> are commands that should be typed
+ at the Unix shell prompt. Examples that begin with the
+ character <quote>*</quote> are commands in the Postgres query
+ language, Postgres <acronym>SQL</acronym>.
+ </para>
+
+ <sect1>
+ <title>Setting Up Your Environment</title>
+
+ <para>
+ This section discusses how to set up
+ your own environment so that you can use frontend
+ applications. We assume <productname>Postgres</productname> has
+ already been
+ successfully installed and started; refer to the Administrator's Guide
+ and the installation notes
+ for how to install Postgres.
+ </para>
+
+ <para>
+ <productname>Postgres</productname> is a client/server
+ application. As a user,
+ you only need access to the client portions of the installation
+ (an example
+ of a client application is the interactive monitor
+ <application>psql</application>).
+ For simplicity,
+ we will assume that <productname>Postgres</productname> has been
+ installed in the
+ directory <filename>/usr/local/pgsql</filename>. Therefore, wherever
+ you see the directory <filename>/usr/local/pgsql</filename> you should
+ substitute the name of the directory where
+ <productname>Postgres</productname> is
+ actually installed.
+ All <productname>Postgres</productname> commands are installed in
+ the directory
+ <filename>/usr/local/pgsql/bin</filename>. Therefore, you should add
+ this directory to your shell command path. If you use
+ a variant of the Berkeley C shell, such as csh or tcsh,
+ you would add
+
+ <programlisting>
% set path = ( /usr/local/pgsql/bin path )
-</ProgramListing>
- in the <FileName>.login</FileName> file in your home directory. If you use
- a variant of the Bourne shell, such as sh, ksh, or
- bash, then you would add
-<ProgramListing>
+ </programlisting>
+
+ in the <filename>.login</filename> file in your home directory.
+ If you use
+ a variant of the Bourne shell, such as sh, ksh, or
+ bash, then you would add
+
+ <programlisting>
% PATH=/usr/local/pgsql/bin:$PATH
% export PATH
-</ProgramListing>
- to the .profile file in your home directory.
- From now on, we will assume that you have added the
- <ProductName>Postgres</ProductName> bin directory to your path. In addition, we
- will make frequent reference to <Quote>setting a shell
- variable</Quote> or <Quote>setting an environment variable</Quote> throughout
- this document. If you did not fully understand the
- last paragraph on modifying your search path, you
- should consult the Unix manual pages that describe your
- shell before going any further.
-</Para>
-
-<Para>
-If your site administrator has not set things up in the
-default way, you may have some more work to do. For example, if the database
- server machine is a remote machine, you
-will need to set the <Acronym>PGHOST</Acronym> environment variable to the name
-of the database server machine. The environment variable
-<Acronym>PGPORT</Acronym> may also have to be set. The bottom line is this: if
-you try to start an application program and it complains
-that it cannot connect to the <Application>postmaster</Application>,
- you should immediately consult your site administrator to make sure that your
-environment is properly set up.
-</Para>
-
-</Sect1>
-
-<Sect1>
-<Title>Starting the Interactive Monitor (psql)</Title>
-
-<Para>
- Assuming that your site administrator has properly
- started the <Application>postmaster</Application> process and authorized you to
- use the database, you (as a user) may begin to start up
- applications. As previously mentioned, you should add
- <FileName>/usr/local/pgsql/bin</FileName> to your shell search path.
- In most cases, this is all you should have to do in
- terms of preparation.
-</Para>
-
-<Para>
-As of <ProductName>Postgres</ProductName> v6.3, two different styles of connections
-are supported. The site administrator will have chosen to allow TCP/IP network connections
-or will have restricted database access to local (same-machine) socket connections only.
-These choices become significant if you encounter problems in connecting to a database.
-</Para>
-
-<Para>
- If you get the following error message from a <ProductName>Postgres</ProductName>
- command (such as <Application>psql</Application> or <Application>createdb</Application>):
-
-<ProgramListing>
+ </programlisting>
+
+ to the .profile file in your home directory.
+ From now on, we will assume that you have added the
+ <productname>Postgres</productname> bin directory to your path.
+ In addition, we
+ will make frequent reference to <quote>setting a shell
+ variable</quote> or <quote>setting an environment
+ variable</quote> throughout
+ this document. If you did not fully understand the
+ last paragraph on modifying your search path, you
+ should consult the Unix manual pages that describe your
+ shell before going any further.
+ </para>
+
+ <para>
+ If your site administrator has not set things up in the
+ default way, you may have some more work to do. For example, if
+ the database
+ server machine is a remote machine, you
+ will need to set the <acronym>PGHOST</acronym> environment
+ variable to the name
+ of the database server machine. The environment variable
+ <acronym>PGPORT</acronym> may also have to be set. The bottom
+ line is this: if
+ you try to start an application program and it complains
+ that it cannot connect to the <application>postmaster</application>,
+ you should immediately consult your site administrator to make
+ sure that your
+ environment is properly set up.
+ </para>
+
+ </sect1>
+
+ <sect1>
+ <title>Starting the Interactive Monitor (psql)</title>
+
+ <para>
+ Assuming that your site administrator has properly
+ started the <application>postmaster</application> process and
+ authorized you to
+ use the database, you (as a user) may begin to start up
+ applications. As previously mentioned, you should add
+ <filename>/usr/local/pgsql/bin</filename> to your shell search path.
+ In most cases, this is all you should have to do in
+ terms of preparation.
+ </para>
+
+ <para>
+ Two different styles of connections
+ are supported. The site administrator will have chosen to allow
+ TCP/IP network connections
+ or will have restricted database access to local (same-machine)
+ socket connections only.
+ These choices become significant if you encounter problems in
+ connecting to a database, since you will want to confirm that you
+ are choosing an allowed connection option.
+ </para>
+
+ <para>
+ If you get the following error message from a
+ <productname>Postgres</productname>
+ command (such as <application>psql</application> or
+ <application>createdb</application>):
+
+ <programlisting>
% psql template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '5432'?
-</ProgramListing>
+ </programlisting>
-or
+ or
-<ProgramListing>
+ <programlisting>
% psql -h localhost template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting TCP/IP
(with -i) connections at 'localhost' on port '5432'?
-</ProgramListing>
-
- it is usually because (1) the <Application>postmaster</Application> is not running,
- or (2) you are attempting to connect to the wrong server host.
- If you get the following error message:
-
-<ProgramListing>
+ </programlisting>
+
+ it is usually because
+
+ <itemizedlist mark="bullet" spacing="compact">
+ <listitem>
+ <para>
+ the <application>postmaster</application> is not running,
+ or
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ you are attempting to connect to the wrong server host.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If you get the following error message:
+
+ <programlisting>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
-</ProgramListing>
-
- it means that the site administrator started the <Application>postmaster</Application>
- as the wrong user. Tell him to restart it as
- the <ProductName>Postgres</ProductName> superuser.
-</Para>
-</Sect1>
-
-<Sect1>
-<Title>Managing a Database</Title>
-
-<Para>
- Now that <ProductName>Postgres</ProductName> is up and running we can create some
- databases to experiment with. Here, we describe the
- basic commands for managing a database.
-</Para>
-
-<Para>
-Most <ProductName>Postgres</ProductName>
-applications assume that the database name, if not specified, is the same as the name on your computer
-account.
-</Para>
-
-<Para>
-If your database administrator has set up your account without database creation privileges,
-then she should have told you what the name of your database is. If this is the case, then you
-can skip the sections on creating and destroying databases.
-</Para>
-
-<Sect2>
-<Title>Creating a Database</Title>
-
-<Para>
- Let's say you want to create a database named <Database>mydb</Database>.
+ </programlisting>
+
+ it means that the site administrator started the
+ <application>postmaster</application>
+ as the wrong user. Tell him to restart it as
+ the <productname>Postgres</productname> superuser.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Managing a Database</title>
+
+ <para>
+ Now that <productname>Postgres</productname> is up and running we
+ can create some
+ databases to experiment with. Here, we describe the
+ basic commands for managing a database.
+ </para>
+
+ <para>
+ Most <productname>Postgres</productname>
+ applications assume that the database name, if not specified, is
+ the same as the name on your computer
+ account.
+ </para>
+
+ <para>
+ If your database administrator has set up your account without
+ database creation privileges,
+ then she should have told you what the name of your database is. If
+ this is the case, then you
+ can skip the sections on creating and destroying databases.
+ </para>
+
+ <sect2>
+ <title>Creating a Database</title>
+
+ <para>
+ Let's say you want to create a database named
+ <database>mydb</database>.
You can do this with the following command:
-<ProgramListing>
+ <programlisting>
% createdb mydb
-</ProgramListing>
-</Para>
-
-<Para>
-If you do not have the privileges required to create a database, you will see
-the following:
-<ProgramListing>
+ </programlisting>
+ </para>
+
+ <para>
+ If you do not have the privileges required to create a database,
+ you will see
+ the following:
+ <programlisting>
% createdb mydb
WARN:user "your username" is not allowed to create/destroy databases
createdb: database creation failed on mydb.
-</ProgramListing>
-</Para>
+ </programlisting>
+ </para>
-<Para>
- <ProductName>Postgres</ProductName> allows you to create any number of databases
+ <para>
+ <productname>Postgres</productname> allows you to create any
+ number of databases
at a given site and you automatically become the
- database administrator of the database you just created. Database names must have an alphabetic first
+ database administrator of the database you just created.
+ Database names must have an alphabetic first
character and are limited to 32 characters in length.
Not every user has authorization to become a database
- administrator. If <ProductName>Postgres</ProductName> refuses to create databases
+ administrator. If <productname>Postgres</productname> refuses to
+ create databases
for you, then the site administrator needs to grant you
permission to create databases. Consult your site
administrator if this occurs.
-</Para>
-</Sect2>
+ </para>
+ </sect2>
-<Sect2>
-<Title>Accessing a Database</Title>
+ <sect2>
+ <title>Accessing a Database</title>
-<Para>
+ <para>
Once you have constructed a database, you can access it
by:
-<ItemizedList Mark="bullet" Spacing="compact">
-<ListItem>
-<Para>
-running the <ProductName>Postgres</ProductName> terminal monitor programs
- (e.g. <Application>psql</Application>) which allows you to interactively
- enter, edit, and execute <Acronym>SQL</Acronym> commands.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
- writing a <Acronym>C</Acronym> program using the LIBPQ subroutine
- library. This allows you to submit <Acronym>SQL</Acronym> commands
- from <Acronym>C</Acronym> and get answers and status messages back to
+ <itemizedlist spacing="compact" mark="bullet">
+ <listitem>
+ <para>
+ Running the <productname>Postgres</productname> terminal
+ monitor programs
+ (e.g. <application>psql</application>) which allows you to
+ interactively
+ enter, edit, and execute <acronym>SQL</acronym> commands.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Using an existing native frontend tool like
+ <application>pgaccess</application> or
+ <application>ApplixWare</application> (via
+ <acronym>ODBC</acronym>) to create and manipulate a
+ database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Using a language like perl or tcl which has a supported
+ interface for <productname>Postgres</productname>. Some of
+ these languages also have convenient and powerful GUI toolkits
+ which can help you construct custom
+ applications. <application>pgaccess</application>, mentioned
+ above, is one such application written in tk/tcl and can be
+ used as an example.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Writing a <acronym>C</acronym> program using
+ the LIBPQ subroutine
+ library. This allows you to submit
+ <acronym>SQL</acronym> commands
+ from <acronym>C</acronym> and get answers and
+ status messages back to
your program. This interface is discussed further
in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
-</Para>
-</ListItem>
-</ItemizedList>
+ </para>
+ </listitem>
+ </itemizedlist>
-You might want to start up <Application>psql</Application>,
-to try out the examples in this manual.
- It can be activated for the <Database>mydb</Database>
+ You might want to start up <application>psql</application>,
+ to try out the examples in this manual.
+ It can be activated for the <database>mydb</database>
database by typing the command:
-<ProgramListing>
+ <programlisting>
% psql mydb
-</ProgramListing>
+ </programlisting>
You will be greeted with the following message:
-<ProgramListing>
+ <programlisting>
Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
@@ -254,71 +337,79 @@ Welcome to the POSTGRESQL interactive sql monitor:
You are currently connected to the database: template1
mydb=>
-</ProgramListing>
-</Para>
+ </programlisting>
+ </para>
-<Para>
-This prompt indicates that the terminal monitor is listening
- to you and that you can type <Acronym>SQL</Acronym> queries into a
+ <para>
+ This prompt indicates that the terminal monitor is listening
+ to you and that you can type <acronym>SQL</acronym> queries into a
workspace maintained by the terminal monitor.
- The <Application>psql</Application> program responds to escape codes that begin
- with the backslash character, <Quote>\</Quote> For example, you
+ The <application>psql</application> program responds to escape
+ codes that begin
+ with the backslash character, <quote>\</quote> For example, you
can get help on the syntax of various
- <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
-<ProgramListing>
+ <productname>Postgres</productname> <acronym>SQL</acronym>
+ commands by typing:
+ <programlisting>
mydb=> \h
-</ProgramListing>
+ </programlisting>
+ </para>
+ <para>
Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace
- to the <ProductName>Postgres</ProductName> server by typing:
-<ProgramListing>
+ to the <productname>Postgres</productname> server by typing:
+ <programlisting>
mydb=> \g
-</ProgramListing>
+ </programlisting>
This tells the server to process the query. If you
- terminate your query with a semicolon, the <Quote>\g</Quote> is not
+ terminate your query with a semicolon, the <quote>\g</quote> is not
necessary.
- <Application>psql</Application> will automatically process semicolon terminated queries.
+ <application>psql</application> will automatically process
+ semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
-<ProgramListing>
+ <programlisting>
mydb=> \i fileName
-</ProgramListing>
+ </programlisting>
- To get out of <Application>psql</Application> and return to Unix, type
-<ProgramListing>
+ To get out of <application>psql</application> and return to Unix, type
+ <programlisting>
mydb=> \q
-</ProgramListing>
+ </programlisting>
- and <Application>psql</Application> will quit and return you to your command
- shell. (For more escape codes, type <Command>\h</Command> at the monitor
- prompt.)
+ and <application>psql</application> will quit and return
+ you to your command
+ shell. (For more escape codes, type <command>\h</command> at the
+ monitor prompt.)
White space (i.e., spaces, tabs and newlines) may be
- used freely in <Acronym>SQL</Acronym> queries. Single-line comments are denoted by
- <Quote>--</Quote>. Everything after the dashes up to the end of the
+ used freely in <acronym>SQL</acronym> queries. Single-line
+ comments are denoted by
+ <quote>--</quote>. Everything after the dashes up to the end of the
line is ignored. Multiple-line comments, and comments within a line,
- are denoted by <Quote>/* ... */</Quote>
-</Para>
-</Sect2>
-
-<Sect2>
-<Title>Destroying a Database</Title>
-
-<Para>
+ are denoted by <quote>/* ... */</quote>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Destroying a Database</title>
+
+ <para>
If you are the database administrator for the database
- <Database>mydb</Database>, you can destroy it using the following Unix command:
-<ProgramListing>
+ <database>mydb</database>, you can destroy it using the
+ following Unix command:
+ <programlisting>
% dropdb mydb
-</ProgramListing>
+ </programlisting>
This action physically removes all of the Unix files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
-</Para>
-</Sect2>
-</Sect1>
+ </para>
+ </sect2>
+ </sect1>
-</Chapter>
+ </chapter>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/doc/src/sgml/y2k.sgml b/doc/src/sgml/y2k.sgml
index 895a3d40ef9..75257cbc23c 100644
--- a/doc/src/sgml/y2k.sgml
+++ b/doc/src/sgml/y2k.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.6 2000/04/07 13:30:58 thomas Exp $
-->
<sect1 id="y2k">
@@ -11,7 +11,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 th
<para>
Written by
<ulink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ulink>
- on 1998-10-22.
+ on 1998-10-22. Updated 2000-03-31.
</para>
</note>
@@ -25,7 +25,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 th
<itemizedlist>
<listitem>
<para>
- The author of this statement, a volunteer on the <productname>Postgres</productname>
+ The author of this statement, a volunteer on the
+ <productname>Postgres</productname>
support team since November, 1996, is not aware of
any problems in the <productname>Postgres</productname> code base related
to time transitions around Jan 1, 2000 (Y2K).
--
GitLab