mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix path to initdb in installation instructions.

Browse Source 
General cleanup for 7.0.
This commit is contained in:
Thomas G. Lockhart 2000-04-07 13:30:58 +00:00
parent b2096a5512
commit 30e355fc80
11 changed files with 1233 additions and 896 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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"> <chapter id="advanced">
@ -106,10 +106,10 @@ SELECT c.name, c.altitude
Here the <quote>*</quote> after cities indicates that the query should Here the <quote>*</quote> after cities indicates that the query should
be run over cities and all classes below cities in the be run over cities and all classes below cities in the
inheritance hierarchy. Many of the commands that we inheritance hierarchy. Many of the commands that we
have already discussed (<command>select</command>, have already discussed (<command>SELECT</command>,
<command>update</command> and <command>delete</command>) <command>UPDATE</command> and <command>DELETE</command>)
support this <quote>*</quote> notation, as do others, like support this <quote>*</quote> notation, as do others, like
<command>alter</command>. <command>ALTER</command>.
</para> </para>
</sect1> </sect1>
@ -118,7 +118,8 @@ SELECT c.name, c.altitude
<para> <para>
One of the tenets of the relational model is that the 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 have this restriction; attributes can themselves contain
sub-values that can be accessed from the query sub-values that can be accessed from the query
language. For example, you can create attributes that language. For example, you can create attributes that
@ -129,7 +130,8 @@ SELECT c.name, c.altitude
<title>Arrays</title> <title>Arrays</title>
<para> <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 as fixed-length or variable-length multi-dimensional
arrays. Arrays of any base type or user-defined type arrays. Arrays of any base type or user-defined type
can be created. To illustrate their use, we first create a 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 a <firstterm>text</firstterm> string (name), a one-dimensional
array of <firstterm>int4</firstterm> array of <firstterm>int4</firstterm>
(pay_by_quarter), which represents the employee's (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), 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 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. this is not unlike the syntax for initializing structures.
<programlisting> <programlisting>
@ -168,7 +173,8 @@ INSERT INTO SAL_EMP
'{{"talk", "consult"}, {"meeting"}}'); '{{"talk", "consult"}, {"meeting"}}');
</programlisting> </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 convention for arrays -- that is, an array of n elements
starts with array[1] and ends with array[n]. starts with array[1] and ends with array[n].
Now, we can run some queries on SAL_EMP. First, we Now, we can run some queries on SAL_EMP. First, we
@ -228,6 +234,11 @@ SELECT SAL_EMP.schedule[1:2][1:1]
</sect2> </sect2>
</sect1> </sect1>
<!--
We haven't had Time Travel for two or three years, so let's stop
mentioning it. - thomas 2000-04-02
<sect1> <sect1>
<title>Time Travel</title> <title>Time Travel</title>
@ -240,21 +251,27 @@ SELECT SAL_EMP.schedule[1:2][1:1]
</para> </para>
<para> <para>
New features such as triggers allow one to mimic the behavior of time travel when desired, without New features such as triggers allow one to mimic the behavior of
incurring the overhead when it is not needed (for most users, this is most of the time). time travel when desired, without
See examples in the <filename>contrib</filename> directory for more information. 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> </para>
<note> <note>
<title>Time travel is deprecated</title> <title>Time travel is deprecated</title>
<para> <para>
The remaining text in this section is retained only until it can be rewritten in the context The remaining text in this section is retained only until it can
of new techniques to accomplish the same purpose. Volunteers? - thomas 1998-01-12 be rewritten in the context
of new techniques to accomplish the same purpose.
Volunteers? - thomas 1998-01-12
</para> </para>
</note> </note>
<para> <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 allows a user to run historical queries. For
example, to find the current population of Mariposa example, to find the current population of Mariposa
city, one would query: city, one would query:
@ -269,7 +286,8 @@ SELECT * FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+ +---------+------------+----------+
</programlisting> </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. record valid at the current time.
One can also give a time range. For example to see the One can also give a time range. For example to see the
past and present populations of Mariposa, one would past and present populations of Mariposa, one would
@ -313,18 +331,22 @@ SELECT name, population
abbreviated as ``[,].'' abbreviated as ``[,].''
</para> </para>
</sect1> </sect1>
-->
<sect1> <sect1>
<title>More Advanced Features</title> <title>More Advanced Features</title>
<para> <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 tutorial introduction, which has been oriented toward newer users of
<acronym>SQL</acronym>. <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> </para>
</sect1> </sect1>
</chapter> </chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

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

@ -88,10 +88,10 @@
<entry>abs(-17.4)</entry> <entry>abs(-17.4)</entry>
</row> </row>
<row> <row>
<entry>sqrt(float8)</entry> <entry>degrees(float8)</entry>
<entry>float8</entry> <entry>float8</entry>
<entry>square root</entry> <entry>radians to degrees</entry>
<entry>sqrt(2.0)</entry> <entry>degrees(0.5)</entry>
</row> </row>
<row> <row>
<entry>exp(float8)</entry> <entry>exp(float8)</entry>
@ -111,18 +111,36 @@
<entry>base 10 logarithm</entry> <entry>base 10 logarithm</entry>
<entry>log(2.0)</entry> <entry>log(2.0)</entry>
</row> </row>
<row>
<entry>pi()</entry>
<entry>float8</entry>
<entry>fundamental constant</entry>
<entry>pi()</entry>
</row>
<row> <row>
<entry>pow(float8,float8)</entry> <entry>pow(float8,float8)</entry>
<entry>float8</entry> <entry>float8</entry>
<entry>raise a number to the specified exponent</entry> <entry>raise a number to the specified exponent</entry>
<entry>pow(2.0, 16.0)</entry> <entry>pow(2.0, 16.0)</entry>
</row> </row>
<row>
<entry>radians(float8)</entry>
<entry>float8</entry>
<entry>degrees to radians</entry>
<entry>radians(45.0)</entry>
</row>
<row> <row>
<entry>round(float8)</entry> <entry>round(float8)</entry>
<entry>float8</entry> <entry>float8</entry>
<entry>round to nearest integer</entry> <entry>round to nearest integer</entry>
<entry>round(42.4)</entry> <entry>round(42.4)</entry>
</row> </row>
<row>
<entry>sqrt(float8)</entry>
<entry>float8</entry>
<entry>square root</entry>
<entry>sqrt(2.0)</entry>
</row>
<row> <row>
<entry>trunc(float8)</entry> <entry>trunc(float8)</entry>
<entry>float8</entry> <entry>float8</entry>
@ -156,6 +174,88 @@
Most of the functions listed for FLOAT8 are also available for Most of the functions listed for FLOAT8 are also available for
type NUMERIC. type NUMERIC.
</para> </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>
<sect1> <sect1>

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

@ -1,139 +1,151 @@
<!-- <!--
$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"> <chapter id="install">
<Title>Installation</Title> <title>Installation</title>
<Abstract> <abstract>
<Para> <para>
Installation instructions for Installation instructions for
<ProductName>PostgreSQL</ProductName> 7.0. <productname>PostgreSQL</productname> 7.0.
</Para> </para>
</Abstract> </abstract>
<Para> <para>
If you haven't gotten the <ProductName>PostgreSQL</ProductName> distribution, If you haven't gotten the <productname>PostgreSQL</productname> distribution,
get it from <ULink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ULink>, get it from <ulink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ulink>,
then unpack it: 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
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>.
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
<programlisting> <programlisting>
<userinput>gmake --version</userinput> &gt; gunzip postgresql-7.0.tar.gz
&gt; tar -xf postgresql-7.0.tar
&gt; mv postgresql-7.0 /usr/src
</programlisting> </programlisting>
If you need to get <acronym>GNU</acronym> <Application>make</Application>, you can </para>
find it at <ULink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ULink>.
</Para>
<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>.
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
<programlisting>
&gt; <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>
<para>
Up to date information on supported platforms is at Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/ports.htm"> <ulink url="http://www.postgresql.org/docs/admin/ports.htm">
http://www.postgresql.org/docs/admin/ports.htm</ulink>. http://www.postgresql.org/docs/admin/ports.htm</ulink>.
In general, most Unix-compatible platforms with modern libraries should be able to run In general, most Unix-compatible platforms with modern libraries
<ProductName>PostgreSQL</ProductName>. In the <filename>doc</filename> subdirectory 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 of the distribution are several platform-specific FAQ and README documents you
might wish to consult if you are having trouble. might wish to consult if you are having trouble.
</para> </para>
<para> <para>
Although the minimum required memory for running <ProductName>PostgreSQL</ProductName> Although the minimum required memory for running
can be as little as 8MB, there are noticeable speed improvements when expanding memory <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. up to 96MB or beyond. The rule is you can never have too much memory.
</para> </para>
<Para> <para>
Check that you have sufficient disk space. You will need about Check that you have sufficient disk space. You will need about
30 Mbytes for the source tree during compilation and about 5 Mbytes for 30 Mbytes for the source tree during compilation and about 5 Mbytes for
the installation directory. An empty database takes about 1 Mbyte, otherwise 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 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 same data would take. If you run the regression tests you will temporarily need
an extra 20MB. an extra 20MB.
</Para> </para>
<Para> <para>
To check for disk space, use To check for disk space, use
<programlisting> <programlisting>
df -k &gt; df -k
</programlisting> </programlisting>
</para> </para>
<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. probably be in your plans before putting a database into production use.
</para> </para>
</Sect1> </sect1>
<Sect1> <sect1>
<Title>Installation Procedure</Title> <title>Installation Procedure</title>
<Procedure> <procedure>
<Title><ProductName>PostgreSQL</ProductName> Installation</Title> <title><productname>PostgreSQL</productname> Installation</title>
<Para> <para>
For a fresh install or upgrading from previous releases of For a fresh install or upgrading from previous releases of
<ProductName>PostgreSQL</ProductName>: <productname>PostgreSQL</productname>:
</Para> </para>
<Step Performance="optional"> <step performance="optional">
<Para> <para>
Create the <ProductName>PostgreSQL</ProductName> superuser account. Create the <productname>PostgreSQL</productname> superuser account.
This is the user the server will run as. For production use you This is the user the server will run as. For production use you
should create a separate, unprivileged account (<literal>postgres</literal> is 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, commonly used). If you do not have root access or just want to play around,
your own user account is enough. your own user account is enough.
</para> </para>
<para> <para>
Running <ProductName>PostgreSQL</ProductName> as <literal>root</literal>, <literal>bin</literal>, Running <productname>PostgreSQL</productname> as
<literal>tera</literal>teral>, <literal>bin</literal>,
or any other account with special access rights is a security risk; or any other account with special access rights is a security risk;
<emphasis>don't do it</emphasis>. The postmaster will in fact refuse <emphasis>don't do it</emphasis>. The postmaster will in fact refuse
to start as root. to start as root.
</para> </para>
<Para> <para>
You need not do the building and installation itself under this account 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 (although you can). You will be told when you need to login as the
database superuser. database superuser.
</Para> </para>
</Step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
Configure the source code for your system. It is this step at which Configure the source code for your system. It is this step at which
you can specify your actual installation path for the build process you can specify your actual installation path for the build process
and make choices about what gets installed. Change into the <filename>src</filename> and make choices about what gets installed. Change into the
<filename>src</filename>
subdirectory and type: subdirectory and type:
<ProgramListing> <programlisting>
./configure &gt; ./configure
</ProgramListing> </programlisting>
followed by any options you might want to give it. For a first installation followed by any options you might want to give it. For a first installation
you should be able to do fine without any. you should be able to do fine without any.
For a complete list of options, type: For a complete list of options, type:
<ProgramListing> <programlisting>
./configure --help &gt; ./configure --help
</ProgramListing> </programlisting>
Some of the more commonly used ones are: Some of the more commonly used ones are:
<VariableList> <variablelist>
<varlistentry> <varlistentry>
<term>--prefix=BASEDIR</term> <term>--prefix=BASEDIR</term>
<listitem> <listitem>
<para> <para>
Selects a different base directory for the installation of Selects a different base directory for the installation of
<ProductName>PostgreSQL</ProductName>. The default is <filename>/usr/local/pgsql</filename>. <productname>PostgreSQL</productname>. The default is
<filename>/usr/local/pgsql</filename>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -191,179 +203,185 @@ For a complete list of options, type:
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</VariableList> </variablelist>
</Para> </para>
</step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
Compile the program. Type Compile the program. Type
<ProgramListing> <programlisting>
gmake &gt; gmake
</ProgramListing> </programlisting>
The compilation process can take anywhere from 10 minutes to an hour. The compilation process can take anywhere from 10 minutes to an hour.
Your mileage will most certainly vary. Remember to use GNU make. Your mileage will most certainly vary. Remember to use GNU make.
</Para> </para>
<Para> <para>
The last line displayed will hopefully be The last line displayed will hopefully be
<programlisting> <programlisting>
All of PostgreSQL is successfully made. Ready to install. All of PostgreSQL is successfully made. Ready to install.
</programlisting> </programlisting>
</Para> </para>
</Step> </step>
<Step Performance="optional"> <step performance="optional">
<Para> <para>
If you want to test the newly built server before you install it, 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 you can run the regression tests at this point. The regression tests
are a test suite to verify that <ProductName>PostgreSQL</ProductName> are a test suite to verify that <productname>PostgreSQL</productname>
runs on your machine in the way the developers expected it to. runs on your machine in the way the developers expected it to.
For detailed instructions see <xref linkend="regress" endterm="regress-title">. For detailed instructions see <xref endterm="regress-title"
linkend="regress">.
(Be sure to use the "parallel regress test" method, since the sequential (Be sure to use the "parallel regress test" method, since the sequential
method only works with an already-installed server.) method only works with an already-installed server.)
</Para> </para>
</Step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
If you are not upgrading an existing system then skip to If you are not upgrading an existing system then skip to
<xref linkend="continue">. <xref linkend="continue">.
</Para> </para>
<Para> <para>
You now need to back up your existing database. You now need to back up your existing database.
To dump your fairly recent post-6.0 database installation, type To dump your fairly recent post-6.0 database installation, type
<programlisting> <programlisting>
pg_dumpall > db.out &gt; pg_dumpall > db.out
</programlisting> </programlisting>
If you wish to preserve object id's (oids), then use the -o If you wish to preserve object id's (oids), then use the -o
option when running <application>pg_dumpall</application>. option when running <application>pg_dumpall</application>.
However, unless you have a However, unless you have a
special reason for doing this (such as using OIDs as keys special reason for doing this (such as using OIDs as keys
in tables), don't do it. in tables), don't do it.
</Para> </para>
<Para> <para>
Make sure to use the <application>pg_dumpall</application> Make sure to use the <application>pg_dumpall</application>
command from the version you are currently running. command from the version you are currently running.
7.0's <application>pg_dumpall</application> will not work on older databases. 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 However, if you are still using 6.0, do not use the
<application>pg_dumpall</application> script from 6.0 or everything will be <application>pg_dumpall</application> script from 6.0 or everything will be
owned by the <ProductName>PostgreSQL</ProductName> superuser after you owned by the <productname>PostgreSQL</productname> superuser after you
reload. In that case reload. In that case
you should grab <application>pg_dumpall</application> from a later you should grab <application>pg_dumpall</application> from a later
6.x.x release. 6.x.x release.
If you are upgrading from a version prior to If you are upgrading from a version prior to
<ProductName>Postgres95</ProductName> v1.09 then you must back up your database, <productname>Postgres95</productname> v1.09 then you must back
install <ProductName>Postgres95</ProductName> v1.09, restore your database, up your database,
install <productname>Postgres95</productname> v1.09, restore your database,
then back it up again. then back it up again.
</Para> </para>
<caution> <caution>
<Para> <para>
You must make sure that your database is not updated in the middle of You must make sure that your database is not updated in the middle of
your backup. If necessary, bring down postmaster, edit the permissions your backup. If necessary, bring down postmaster, edit the permissions
in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename> in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
to allow only you on, then to allow only you on, then
bring <application>postmaster</application> back up. bring <application>postmaster</application> back up.
</Para> </para>
</caution> </caution>
</Step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
If you are upgrading an existing system then kill the database server now. Type If you are upgrading an existing system then kill the database
<ProgramListing> server now. Type
ps ax | grep postmaster <programlisting>
</ProgramListing> &gt; ps ax | grep postmaster
</programlisting>
or or
<ProgramListing> <programlisting>
ps -e | grep postmaster &gt; ps -e | grep postmaster
</ProgramListing> </programlisting>
(It depends on your system which one of these two works. No harm can be done (It depends on your system which one of these two works. No harm can be done
by typing the wrong one.) by typing the wrong one.)
This should list the process numbers for a number of processes, similar This should list the process numbers for a number of processes, similar
to this: to this:
<ProgramListing> <programlisting>
263 ? SW 0:00 (postmaster) 263 ? SW 0:00 (postmaster)
777 p1 S 0:00 grep postmaster 777 p1 S 0:00 grep postmaster
</ProgramListing> </programlisting>
Type the following line, with <replaceable>pid</replaceable> Type the following line, with <replaceable>pid</replaceable>
replaced by the process id for process <literal>postmaster</literal> 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".) (263 in the above case). (Do not use the id for the process
"grep postmaster".)
<programlisting> <programlisting>
kill <replaceable>pid</replaceable> &gt; kill <replaceable>pid</replaceable>
</programlisting> </programlisting>
</Para> </para>
<tip> <tip>
<para> <para>
On systems which have <productname>PostgreSQL</productname> started at boot time, there On systems which have <productname>PostgreSQL</productname>
is probably a startup file that will accomplish the same thing. For example, on a 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 Redhat Linux system one might find that
<programlisting> <programlisting>
/etc/rc.d/init.d/postgres.init stop &gt; /etc/rc.d/init.d/postgres.init stop
</programlisting> </programlisting>
works. works.
</para> </para>
</tip> </tip>
<Para> <para>
Also move the old directories out of the way. Type the following: Also move the old directories out of the way. Type the following:
<programlisting> <programlisting>
mv /usr/local/pgsql /usr/local/pgsql.old &gt; mv /usr/local/pgsql /usr/local/pgsql.old
</programlisting> </programlisting>
(substitute your particular paths). (substitute your particular paths).
</Para> </para>
</Step> </step>
<Step Performance="required" id="continue"> <step performance="required" id="continue">
<Para> <para>
Install the <ProductName>PostgreSQL</ProductName> executable files and Install the <productname>PostgreSQL</productname> executable files and
libraries. Type libraries. Type
<ProgramListing> <programlisting>
gmake install &gt; gmake install
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
You should do this step as the user that you want the installed executables 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; 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. some people prefer to have the installed files be owned by root.
</Para> </para>
</Step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
If necessary, tell your system how to find the new shared libraries. If necessary, tell your system how to find the new shared libraries.
How to do this varies between platforms. The most widely usable method How to do this varies between platforms. The most widely usable method
is to set the environment variable is to set the environment variable
<envar>LD_LIBRARY_PATH</envar>: <envar>LD_LIBRARY_PATH</envar>:
<programlisting> <programlisting>
LD_LIBRARY_PATH=/usr/local/pgsql/lib &gt; LD_LIBRARY_PATH=/usr/local/pgsql/lib
export LD_LIBRARY_PATH &gt; export LD_LIBRARY_PATH
</programlisting> </programlisting>
on sh, ksh, bash, zsh or on sh, ksh, bash, zsh or
<programlisting> <programlisting>
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib &gt; setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</programlisting> </programlisting>
on csh or tcsh. on csh or tcsh.
You might want to put this into a shell startup file such as You might want to put this into a shell startup file such as
<filename>/etc/profile</filename>. <filename>/etc/profile</filename>.
</Para> </para>
<Para> <para>
On some systems the following is the preferred method, but you must have root 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 access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
<programlisting> <programlisting>
<FileName>/usr/local/pgsql/lib</FileName> <filename>/usr/local/pgsql/lib</filename>
</programlisting> </programlisting>
Then run command <Command>/sbin/ldconfig</Command>. Then run command <command>/sbin/ldconfig</command>.
</Para> </para>
<Para> <para>
If in doubt, refer to the manual pages of your system. If you later on get If in doubt, refer to the manual pages of your system. If you later on get
a message like a message like
<programlisting> <programlisting>
@ -371,104 +389,112 @@ psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory libpq.so.2.1: cannot open shared object file: No such file or directory
</programlisting> </programlisting>
then the above was necessary. Simply do this step then. then the above was necessary. Simply do this step then.
</Para> </para>
</Step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
Create the database installation (the working data files). Create the database installation (the working data files).
To do this you must log in to your To do this you must log in to your
<ProductName>PostgreSQL</ProductName> superuser account. It will not <productname>PostgreSQL</productname> superuser account. It will not
work as root. work as root.
<ProgramListing> <programlisting>
mkdir /usr/local/pgsql/data &gt; mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data &gt; chown postgres /usr/local/pgsql/data
su - postgres &gt; su - postgres
/usr/local/pgsql/initdb -D /usr/local/pgsql/data &gt; /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
The <option>-D</option> option specifies the location where the data will be 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 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 the installation directory. Just make sure that the superuser account
can write to the directory (or create it, if it doesn't already exist) can write to the directory (or create it, if it doesn't already exist)
before starting <command>initdb</command>. before starting <command>initdb</command>.
(If you have already been doing the installation up to now as the <productname>PostgreSQL</productname> (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 superuser, you may have to log in as root temporarily to create the data
directory underneath a root-owned directory.) directory underneath a root-owned directory.)
</Para> </para>
</Step> </step>
<Step Performance="required"> <step performance="required">
<Para> <para>
The previous step should have told you how to start up the database server. The previous step should have told you how to start up the database server.
Do so now. The command should look something like Do so now. The command should look something like
<programlisting> <programlisting>
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data &gt; /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
</programlisting> </programlisting>
This will start the server in the foreground. To make it detach to 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 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 see any log messages the server produces. A better way to put the server
in the background is in the background is
<programlisting> <programlisting>
nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \ &gt; nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
&lt;/dev/null &gt;>server.log 2&gt;>1 &amp; &lt;/dev/null &gt;>server.log 2&gt;>1 &amp;
</programlisting> </programlisting>
</Para> </para>
</Step> </step>
<Step Performance="optional"> <step performance="optional">
<para> <para>
If you are upgrading from an existing installation, dump your data back in: If you are upgrading from an existing installation, dump your data back in:
<programlisting> <programlisting>
/usr/local/pgsql/bin/psql -d template1 -f db.out &gt; /usr/local/pgsql/bin/psql -d template1 -f db.out
</programlisting> </programlisting>
You also might want to copy over the old <filename>pg_hba.conf</filename> 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 file and any other files you might have had set up for authentication, such
as password files. as password files.
</Para> </para>
</Step> </step>
</Procedure> </procedure>
<para> <para>
This concludes the installation proper. To make your life more productive and enjoyable This concludes the installation proper. To make your life more
productive and enjoyable
you should look at the following optional steps and suggestions. you should look at the following optional steps and suggestions.
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<Para> <para>
Life will be more convenient if you set up some environment variables. First of all Life will be more convenient if you set up some environment
you probably want to include <filename>/usr/local/pgsql/bin</filename> (or equivalent) variables. First of all
into your <envar>PATH</envar>. To do this, add the following to your shell startup you probably want to include
file, such as <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>, <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): if you want it to affect every user):
<programlisting> <programlisting>
PATH=$PATH:/usr/local/pgsql/bin &gt; PATH=$PATH:/usr/local/pgsql/bin
</programlisting> </programlisting>
</Para> </para>
<Para> <para>
Furthermore, if you set <envar>PGDATA</envar> in the environment of the PostgreSQL Furthermore, if you set <envar>PGDATA</envar> in the environment
superuser, you can omit the <option>-D</option> for <filename>postmaster</filename> of the PostgreSQL
superuser, you can omit the <option>-D</option> for
<filename>postmaster</filename>
and <filename>initdb</filename>. and <filename>initdb</filename>.
</Para> </para>
</listitem> </listitem>
<listitem> <listitem>
<Para> <para>
You probably want to install the <application>man</application> and You probably want to install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type <acronym>HTML</acronym> documentation. Type
<ProgramListing> <programlisting>
cd /usr/src/pgsql/postgresql-7.0/doc &gt; cd /usr/src/pgsql/postgresql-7.0/doc
gmake install &gt; gmake install
</ProgramListing> </programlisting>
This will install files under <filename>/usr/local/pgsql/doc</filename> This will install files under <filename>/usr/local/pgsql/doc</filename>
and <filename>/usr/local/pgsql/man</filename>. To enable your system and <filename>/usr/local/pgsql/man</filename>. To enable your system
to find the <application>man</application> documentation, you need to to find the <application>man</application> documentation, you need to
add a line like the following to a shell startup file: add a line like the following to a shell startup file:
<ProgramListing> <programlisting>
MANPATH=$MANPATH:/usr/local/pgsql/man &gt; MANPATH=$MANPATH:/usr/local/pgsql/man
</ProgramListing> </programlisting>
</para> </para>
<para> <para>
@ -477,13 +503,15 @@ 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 Postscript files using a print filter, then to print the User's Guide
simply type simply type
<programlisting> <programlisting>
cd /usr/local/pgsql/doc &gt; cd /usr/local/pgsql/doc
gunzip -c user.ps.tz | lpr &gt; gunzip -c user.ps.tz | lpr
</programlisting> </programlisting>
Here is how you might do it if you have Ghostscript on your system and are Here is how you might do it if you have Ghostscript on your system and are
writing to a laserjet printer. writing to a laserjet printer.
<programlisting> <programlisting>
gunzip -c user.ps.gz | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- | lpr &gt; gunzip -c user.ps.gz \
| gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
| lpr
</programlisting> </programlisting>
Printer setups can vary wildly from system to system. Printer setups can vary wildly from system to system.
If in doubt, consult your manuals or your local expert. If in doubt, consult your manuals or your local expert.
@ -497,29 +525,34 @@ information about how to set up database users and authentication.
</listitem> </listitem>
<listitem> <listitem>
<Para> <para>
Usually, you will want to modify your computer so that it will automatically Usually, you will want to modify your computer so that it will automatically
start the database server whenever it boots. start the database server whenever it boots.
This is not required; the <ProductName>PostgreSQL</ProductName> server can This is not required; the <productname>PostgreSQL</productname> server can
be run successfully from non-privileged accounts without root intervention. be run successfully from non-privileged accounts without root intervention.
</para> </para>
<para> <para>
Different systems have different conventions for starting up daemons at boot time, Different systems have different conventions for starting up
daemons at boot time,
so you are advised to familiarize yourself with them. so you are advised to familiarize yourself with them.
Most systems have a file <filename>/etc/rc.local</filename> or 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 <filename>/etc/rc.d/rc.local</filename> which is almost
certainly no bad place
to put such a command. to put such a command.
Whatever you do, postmaster must be run by the <ProductName>PostgreSQL</ProductName> Whatever you do, postmaster must be run by the
superuser (<literal>postgres</literal>) <emphasis>and not by root</emphasis> or <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 any other user. Therefore you probably always want to form your command lines
along the lines of <literal>su -c '...' postgres</literal>. along the lines of <literal>su -c '...' postgres</literal>.
</para> </para>
<para> <para>
It might be advisable to keep a log of the server output. To start the server that way It might be advisable to keep a log of the server output. To
start the server that way
try: try:
<ProgramListing> <programlisting>
nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres & &gt; nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
</ProgramListing> </programlisting>
</para> </para>
<para> <para>
@ -531,7 +564,7 @@ Here are a few more operating system specific suggestions.
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
2.5.1 to contain the following single line: 2.5.1 to contain the following single line:
<programlisting> <programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" &gt; su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting> </programlisting>
</para> </para>
</listitem> </listitem>
@ -561,7 +594,8 @@ In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
<listitem> <listitem>
<para> <para>
In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename> In RedHat Linux add a file
<filename>/etc/rc.d/init.d/postgres.init</filename>
which is based on the example in <filename>contrib/linux/</filename>. which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from Then make a softlink to this file from
<filename>/etc/rc.d/rc5.d/S98postgres.init</filename>. <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
@ -570,37 +604,37 @@ Then make a softlink to this file from
</itemizedlist> </itemizedlist>
</Para> </para>
</listitem> </listitem>
<listitem> <listitem>
<Para> <para>
Run the regression tests against the installed server (using the sequential Run the regression tests against the installed server (using the sequential
test method). If you didn't run the tests before installation, you should test method). If you didn't run the tests before installation, you should
definitely do it now. definitely do it now.
For detailed instructions see <xref linkend="regress" endterm="regress-title">. For detailed instructions see <xref endterm="regress-title"
</Para> linkend="regress">.
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<Para> <para>
To start <quote>playing around</quote>, set up the paths as explained above To start <quote>playing around</quote>, set up the paths as explained above
and start the server. To create a database, type and start the server. To create a database, type
<ProgramListing> <programlisting>
createdb testdb &gt; createdb testdb
</ProgramListing> </programlisting>
Then enter Then enter
<ProgramListing> <programlisting>
psql testdb &gt; psql testdb
</ProgramListing> </programlisting>
to connect to that database. At the prompt you can enter SQL commands to connect to that database. At the prompt you can enter SQL commands
and start experimenting. and start experimenting.
</Para> </para>
</Sect1> </sect1>
</chapter>
</Chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:

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

@ -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"> <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>. <productname>Postgres release 4.2</productname></ulink>.
The <productname>Postgres</productname> project, The <productname>Postgres</productname> project,
led by Professor Michael Stonebraker, was sponsored by the 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 Army Research Office (<acronym>ARO</acronym>), the National Science
Foundation (<acronym>NSF</acronym>), and ESL, Inc. Foundation (<acronym>NSF</acronym>), and ESL, Inc.
</para> </para>
@ -62,13 +63,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
</para> </para>
<para> <para>
These features put <productname>Postgres</productname> into the category of databases These features put <productname>Postgres</productname> into the
referred to as <firstterm>object-relational</firstterm>. Note that this is distinct category of databases referred to as
from those referred to as <firstterm>object-oriented</firstterm>, which in general <firstterm>object-relational</firstterm>. Note that this is distinct
are not as well suited to supporting the traditional relational database languages. from those referred to as <firstterm>object-oriented</firstterm>,
So, although <productname>Postgres</productname> has some object-oriented features, which in general are not as well suited to supporting the
it is firmly in the relational database world. In fact, some commercial databases traditional relational database languages.
have recently incorporated features pioneered by <productname>Postgres</productname>. 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> </para>
</sect1> </sect1>

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

@ -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"> <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> <para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2000 <productname>PostgreSQL</productname> is Copyright &copy; 1996-2000
by the PostgreSQL Inc. by PostgreSQL Inc.
and is distributed under the terms of the Berkeley license. and is distributed under the terms of the Berkeley license.
</para> </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. maintainance, support, updates, enhancements, or modifications.
</para> </para>
<!--
How to keep track of all the trademarks? I'll try the strategy used at
www.qnx.com - thomas
<para> <para>
<acronym>Unix</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS <acronym>Unix</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
and Solaris are trademarks of Sun Microsystems, Inc. DEC, 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 Equipment Corp. PA-RISC and HP-UX are trademarks of
Hewlett-Packard Co. OSF/1 is a trademark of the Open Hewlett-Packard Co. OSF/1 is a trademark of the Open
Software Foundation. Software Foundation.
</para> </para>
-->
<para>
All trademarks are the property of their respective owners.
</para>
</sect1> </sect1>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

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

@ -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"> <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 binaries and database files. As the database superuser, all
protection mechanisms may be bypassed and any data accessed protection mechanisms may be bypassed and any data accessed
arbitrarily. 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. some support programs which are generally not available to all users.
Note that the <Productname>Postgres</Productname> superuser is Note that the <Productname>Postgres</Productname> superuser is
<emphasis>not</emphasis> <emphasis>not</emphasis>
the same as the Unix superuser (which will be referred to as <firstterm>root</firstterm>). the same as the Unix superuser (which will be referred to as
The superuser should have a non-zero user identifier (<firstterm>UID</firstterm>) <firstterm>root</firstterm>).
for security reasons. The superuser should have a non-zero user identifier
(<firstterm>UID</firstterm>) for security reasons.
</para> </para>
<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 In a command synopsis, brackets
(<quote>[</quote> and <quote>]</quote>) indicate an optional phrase or keyword. (<quote>[</quote> and <quote>]</quote>) indicate an optional phrase or keyword.
Anything in braces Anything in braces
(<quote>{</quote> and <quote>}</quote>) and containing vertical bars (<quote>|</quote>) (<quote>{</quote> and <quote>}</quote>) and containing vertical bars
(<quote>|</quote>)
indicates that you must choose one. indicates that you must choose one.
</para> </para>
<para> <para>
In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are
used to group boolean
expressions. <quote>|</quote> is the boolean operator OR. expressions. <quote>|</quote> is the boolean operator OR.
</para> </para>
<para> <para>
Examples will show commands executed from various accounts and programs. Examples will show commands executed from various accounts and programs.
Commands executed from the root account will be preceeded with <quote>&gt;</quote>. Commands executed from the root account will be preceeded with
<quote>&gt;</quote>.
Commands executed from the <Productname>Postgres</Productname> Commands executed from the <Productname>Postgres</Productname>
superuser account will be preceeded with <quote>%</quote>, while commands superuser account will be preceeded with <quote>%</quote>, while commands
executed from an unprivileged user's account will be preceeded with 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> <note>
<para> <para>
At the time of writing (<Productname>Postgres</Productname> v6.5) the notation for At the time of writing (<Productname>Postgres</Productname> v7.0)
flagging commands is not universally consistant throughout the documentation set. the notation for
flagging commands is not universally consistant throughout the
documentation set.
Please report problems to Please report problems to
<ulink url="mailto:docs@postgresql.org">the Documentation Mailing List</ulink>. <ulink url="mailto:docs@postgresql.org">the Documentation Mailing List</ulink>.
</para> </para>

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

@ -32,15 +32,15 @@
<row> <row>
<entry>AIX 4.3.2</entry> <entry>AIX 4.3.2</entry>
<entry>RS6000</entry> <entry>RS6000</entry>
<entry>v6.5</entry> <entry>v7.0</entry>
<entry>1999-05-26</entry> <entry>2000-04-05</entry>
<entry>(<ulink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ulink>)</entry> <entry>(<ulink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ulink>)</entry>
</row> </row>
<row> <row>
<entry>BSDI</entry> <entry>BSDI 4.01</entry>
<entry>x86</entry> <entry>x86</entry>
<entry>v6.5</entry> <entry>v7.0</entry>
<entry>1999-05-25</entry> <entry>2000-04-04</entry>
<entry>(<ulink url="mailto:maillist@candle.pha.pa.us">Bruce Momjian</ulink></entry> <entry>(<ulink url="mailto:maillist@candle.pha.pa.us">Bruce Momjian</ulink></entry>
</row> </row>
<row> <row>
@ -60,12 +60,11 @@
(<ulink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ulink>)</entry> (<ulink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ulink>)</entry>
</row> </row>
<row> <row>
<entry>FreeBSD 2.2.x-4.0</entry> <entry>FreeBSD 4.0</entry>
<entry>x86</entry> <entry>x86</entry>
<entry>v6.5</entry> <entry>v7.0</entry>
<entry>1999-05-25</entry> <entry>2000-04-04</entry>
<entry>(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>, <entry>(<ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink>)</entry>
<ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink>)</entry>
</row> </row>
<row> <row>
<entry>HPUX</entry> <entry>HPUX</entry>
@ -136,17 +135,17 @@
(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry> (<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry>
</row> </row>
<row> <row>
<entry>Linux 2.0.x</entry> <entry>Linux 2.2.5</entry>
<entry>Sparc</entry> <entry>Sparc</entry>
<entry>v6.4</entry> <entry>v7.0</entry>
<entry>1998-10-25</entry> <entry>2000-04-02</entry>
<entry>(<ulink url="mailto:szybist@boxhill.com">Tom Szybist</ulink>)</entry> <entry>(<ulink url="mailto:szybist@boxhill.com">Tom Szybist</ulink>)</entry>
</row> </row>
<row> <row>
<entry>LinuxPPC R4 2.2.1/libc5</entry> <entry>LinuxPPC R4</entry>
<entry>PPC603e</entry> <entry>PPC603e</entry>
<entry>v7.0</entry> <entry>v7.0</entry>
<entry>2000-03-26</entry> <entry>2000-04-04</entry>
<entry>Powerbook 2400c <entry>Powerbook 2400c
(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry> (<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry>
</row> </row>
@ -250,20 +249,20 @@
(<ulink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ulink>)</entry> (<ulink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ulink>)</entry>
</row> </row>
<row> <row>
<entry>Windows</entry> <entry>Windows/Win32</entry>
<entry>x86</entry> <entry>x86</entry>
<entry>v6.4</entry> <entry>v7.0</entry>
<entry>1999-01-06</entry> <entry>2000-04-02</entry>
<entry>Client-side libraries or ODBC/JDBC. No server yet. <entry>Client-side libraries or ODBC/JDBC. No server-side.
(<ulink url="mha@sollentuna.net">Magnus Hagander</ulink></entry> (<ulink url="mha@sollentuna.net">Magnus Hagander</ulink></entry>
</row> </row>
<row> <row>
<entry>Windows NT</entry> <entry>WinNT/Cygwin</entry>
<entry>x86</entry> <entry>x86</entry>
<entry>v6.5</entry> <entry>v7.0</entry>
<entry>1999-05-26</entry> <entry>2000-03-30</entry>
<entry>Working with the Cygwin library. <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> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -273,8 +272,9 @@
<note> <note>
<para> <para>
For <productname>Windows NT</productname>, For <productname>Windows NT</productname>,
the server-side port of <productname>Postgres</productname> has recently been the server-side port of <productname>Postgres</productname> uses
accomplished. The Cygnus library is required to compile it. the RedHat/Cygnus <productname>Cygwin</productname> library and
toolset.
</para> </para>
</note> </note>
</sect1> </sect1>
@ -289,7 +289,8 @@
</para> </para>
<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"> <table tocentry="1">
<title>Obsolete Platforms</title> <title>Obsolete Platforms</title>

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

@ -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"> <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> <para>
The <productname>Postgres</productname> query language is a variant of The <productname>Postgres</productname> query language is a variant of
the <acronym>SQL3</acronym> draft next-generation standard. It 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 inheritance, functions and production rules. These are
features carried over from the original <productname>Postgres</productname> query features carried over from the original
language, <productname>PostQuel</productname>. This section provides an overview <productname>Postgres</productname> query
language, <productname>PostQuel</productname>.
This section provides an overview
of how to use <productname>Postgres</productname> of how to use <productname>Postgres</productname>
<acronym>SQL</acronym> to perform simple operations. <acronym>SQL</acronym> to perform simple operations.
This manual is only intended to give you an idea of our 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 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>. Numerous books have been written on
<acronym>SQL</acronym>, including <acronym>SQL92</acronym>, including
<!-- <xref linkend="MELT93" endterm="MELT93-title"> and
<XRef LinkEnd="MELT93"> and <XRef LinkEnd="DATE97">. <xref linkend="DATE97" endterm="DATE97-title">.
-->
[MELT93] and [DATE97].
You should be aware that some language features You should be aware that some language features
are extensions to the <acronym>ANSI</acronym> standard. are extensions to the <acronym>ANSI</acronym> standard.
</para> </para>
@ -111,22 +112,26 @@ CREATE TABLE weather (
</para> </para>
<para> <para>
Note that both keywords and identifiers are case-insensitive; identifiers can become Note that both keywords and identifiers are case-insensitive;
case-sensitive by surrounding them with double-quotes as allowed identifiers can preserve case by surrounding them with
double-quotes as allowed
by <acronym>SQL92</acronym>. 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>, <acronym>SQL</acronym> types <type>int</type>,
<type>float</type>, <type>real</type>, <type>smallint</type>, <type>float</type>, <type>real</type>, <type>smallint</type>,
<type>char(N)</type>, <type>char(N)</type>,
<type>varchar(N)</type>, <type>date</type>, <type>time</type>, <type>varchar(N)</type>, <type>date</type>, <type>time</type>,
and <type>timestamp</type>, as well as other types of general utility and and <type>timestamp</type>, as well as other types of general utility and
a rich set of geometric types. As we will 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 arbitrary number of
user-defined data types. Consequently, type names are user-defined data types. Consequently, type names are
not syntactical keywords, except where required to support special not syntactical keywords, except where required to support special
cases in the <acronym>SQL92</acronym> standard. 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 looks exactly like
the command used to create a table in a traditional the command used to create a table in a traditional
relational system. However, we will presently see that relational system. However, we will presently see that
@ -139,7 +144,7 @@ CREATE TABLE weather (
<title>Populating a Class with Instances</title> <title>Populating a Class with Instances</title>
<para> <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: instances:
<programlisting> <programlisting>
@ -149,9 +154,10 @@ INSERT INTO weather
</para> </para>
<para> <para>
You can also use the <command>copy</command> command to perform load large You can also use the <command>COPY</command> command to perform load large
amounts of data from flat (<acronym>ASCII</acronym>) files. amounts of data from flat (<acronym>ASCII</acronym>) files.
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: transaction directly to or from the target table. An example would be:
<programlisting> <programlisting>
@ -159,7 +165,8 @@ COPY weather FROM '/home/user/weather.txt'
USING DELIMITERS '|'; USING DELIMITERS '|';
</programlisting> </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. machine, not the client, since the backend server reads the file directly.
</para> </para>
</sect1> </sect1>
@ -170,7 +177,7 @@ COPY weather FROM '/home/user/weather.txt'
<para> <para>
The weather class can be queried with normal relational The weather class can be queried with normal relational
selection and projection queries. A <acronym>SQL</acronym> 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 statement is used to do this. The statement is divided into
a target list (the part that lists the attributes to be a target list (the part that lists the attributes to be
returned) and a qualification (the part that specifies returned) and a qualification (the part that specifies
@ -192,7 +199,8 @@ SELECT * FROM weather;
|Hayward | 37 | 54 | | 11-29-1994 | |Hayward | 37 | 54 | | 11-29-1994 |
+--------------+---------+---------+------+------------+ +--------------+---------+---------+------+------------+
</programlisting> </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> <programlisting>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather; SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</programlisting> </programlisting>
@ -200,7 +208,8 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
<para> <para>
Arbitrary Boolean operators 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, allowed in the qualification of any query. For example,
<programlisting> <programlisting>
@ -235,16 +244,16 @@ SELECT DISTINCT city
<title>Redirecting SELECT Queries</title> <title>Redirecting SELECT Queries</title>
<para> <para>
Any select query can be redirected to a new class Any <command>SELECT</command> query can be redirected to a new class
<programlisting> <programlisting>
SELECT * INTO TABLE temp FROM weather; SELECT * INTO TABLE temp FROM weather;
</programlisting> </programlisting>
</para> </para>
<para> <para>
This forms an implicit <command>create</command> command, creating a new This forms an implicit <command>CREATE</command> command, creating a new
class temp with the attribute names and types specified 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 then, of course, perform any operations on the resulting
class that we can perform on other classes. class that we can perform on other classes.
</para> </para>
@ -269,7 +278,8 @@ SELECT * INTO TABLE temp FROM weather;
<note> <note>
<para> <para>
This is only a conceptual model. The actual join may 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> </para>
</note> </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; sometimes recomputes the same target list several times;
this frequently happens when Boolean expressions are connected this frequently happens when Boolean expressions are connected
with an "or". To remove such duplicates, you must use with an "or". To remove such duplicates, you must use
the <command>select distinct</command> statement. the <command>SELECT DISTINCT</command> statement.
</para> </para>
</note> </note>
</para> </para>
<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 instance of the class weather, and both range over all
instances of the class. (In the terminology of most 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 A query can contain an arbitrary number of
class names and surrogates. class names and surrogates.
</para> </para>
@ -326,7 +338,8 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
<title>Updates</title> <title>Updates</title>
<para> <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 Suppose you discover the temperature readings are
all off by 2 degrees as of Nov 28, you may update the all off by 2 degrees as of Nov 28, you may update the
data as follow: data as follow:
@ -343,7 +356,7 @@ UPDATE weather
<title>Deletions</title> <title>Deletions</title>
<para> <para>
Deletions are performed using the <command>delete</command> command: Deletions are performed using the <command>DELETE</command> command:
<programlisting> <programlisting>
DELETE FROM weather WHERE city = 'Hayward'; DELETE FROM weather WHERE city = 'Hayward';
</programlisting> </programlisting>
@ -354,7 +367,7 @@ DELETE FROM weather WHERE city = 'Hayward';
DELETE FROM classname; DELETE FROM classname;
</programlisting> </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 remove all instances of the given class, leaving it
empty. The system will not request confirmation before empty. The system will not request confirmation before
doing this. doing this.
@ -365,7 +378,7 @@ DELETE FROM classname;
<title>Using Aggregate Functions</title> <title>Using Aggregate Functions</title>
<para> <para>
Like most other query languages, Like most other relational database products,
<productname>PostgreSQL</productname> supports <productname>PostgreSQL</productname> supports
aggregate functions. aggregate functions.
An aggregate function computes a single result from multiple input rows. An aggregate function computes a single result from multiple input rows.
@ -377,20 +390,20 @@ DELETE FROM classname;
<para> <para>
It is important to understand the interaction between aggregates and It is important to understand the interaction between aggregates and
SQL's <command>where</command> and <command>having</command> clauses. SQL's <command>WHERE</command> and <command>HAVING</command> clauses.
The fundamental difference between <command>where</command> and The fundamental difference between <command>WHERE</command> and
<command>having</command> is this: <command>where</command> selects <command>HAVING</command> is this: <command>WHERE</command> selects
input rows before groups and aggregates are computed (thus, it controls input rows before groups and aggregates are computed (thus, it controls
which rows go into the aggregate computation), whereas 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 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 it makes no sense to try to use an aggregate to determine which rows
will be inputs to the aggregates. On the other hand, will be inputs to the aggregates. On the other hand,
<command>having</command> clauses always contain aggregate functions. <command>HAVING</command> clauses always contain aggregate functions.
(Strictly speaking, you are allowed to write a <command>having</command> (Strictly speaking, you are allowed to write a <command>HAVING</command>
clause that doesn't use aggregates, but it's wasteful; the same condition 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>
<para> <para>
@ -408,13 +421,17 @@ SELECT max(temp_lo) FROM weather;
SELECT city FROM weather WHERE temp_lo = max(temp_lo); SELECT city FROM weather WHERE temp_lo = max(temp_lo);
</programlisting> </programlisting>
but this will not work since the aggregate max() can't be used in but this will not work since the aggregate
<command>where</command>. However, as is often the case the query can be <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 restated to accomplish the intended result; here by using a
<firstterm>subselect</firstterm>: <firstterm>subselect</firstterm>:
<programlisting> <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> </programlisting>
This is OK because the sub-select is an independent computation that This is OK because the sub-select is an independent computation that
computes its own aggregate separately from what's happening in the outer computes its own aggregate separately from what's happening in the outer
select. select.
@ -422,24 +439,29 @@ SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
<para> <para>
Aggregates are also very useful in combination with 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 maximum low temperature observed in each city with
<programlisting> <programlisting>
SELECT city, max(temp_lo) SELECT city, max(temp_lo)
FROM weather FROM weather
GROUP BY city; GROUP BY city;
</programlisting> </programlisting>
which gives us one output row per city. We can filter these grouped which gives us one output row per city. We can filter these grouped
rows using <command>having</command>: rows using <command>HAVING</command>:
<programlisting> <programlisting>
SELECT city, max(temp_lo) SELECT city, max(temp_lo)
FROM weather FROM weather
GROUP BY city GROUP BY city
HAVING min(temp_lo) < 0; HAVING min(temp_lo) < 0;
</programlisting> </programlisting>
which gives us the same results for only the cities that have some which gives us the same results for only the cities that have some
below-zero readings. Finally, if we only care about cities whose 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> <programlisting>
SELECT city, max(temp_lo) SELECT city, max(temp_lo)
FROM weather FROM weather
@ -447,11 +469,12 @@ SELECT city, max(temp_lo)
GROUP BY city GROUP BY city
HAVING min(temp_lo) < 0; HAVING min(temp_lo) < 0;
</programlisting> </programlisting>
Note that we can apply the city-name restriction in Note that we can apply the city-name restriction in
<command>where</command>, since it needs no aggregate. This is <command>WHERE</command>, since it needs no aggregate. This is
more efficient than adding the restriction to <command>having</command>, more efficient than adding the restriction to <command>HAVING</command>,
because we avoid doing the grouping and aggregate calculations 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> </para>
</sect1> </sect1>
</chapter> </chapter>

142
doc/src/sgml/sql.sgml
View File

@ -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"> <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> <abstract>
<para> <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 Stefan Simkovics' Master's Thesis
(<xref linkend="SIM98" endterm="SIM98">). (<xref linkend="SIM98" endterm="SIM98">).
</para> </para>
</abstract> </abstract>
<para> <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 The name <quote><acronym>SQL</acronym></quote> is an abbreviation for
<firstterm>Structured Query Language</firstterm>. <firstterm>Structured Query Language</firstterm>.
In 1974 Donald Chamberlin and others defined the 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 Research. This language was first implemented in an IBM
prototype called SEQUEL-XRM in 1974-75. In 1976-77 a revised version 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 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> <para>
A new prototype called System R was developed by IBM in 1977. System R 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. changes were made to <acronym>SQL</acronym> during the project.
System R was installed in System R was installed in
a number of user sites, both internal IBM sites and also some selected 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 customer sites. Thanks to the success and acceptance of System R at
those user sites IBM started to develop commercial products that 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>
<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>
<para> <para>
<acronym>SQL</acronym> is also an official standard now. In 1982 the American National <acronym>SQL</acronym> is also an official standard now. In 1982
Standards Institute (<acronym>ANSI</acronym>) chartered its Database Committee X3H2 to the American National
Standards Institute (<acronym>ANSI</acronym>) chartered its
Database Committee X3H2 to
develop a proposal for a standard relational language. This proposal develop a proposal for a standard relational language. This proposal
was ratified in 1986 and consisted essentially of the IBM dialect of was ratified in 1986 and consisted essentially of the IBM dialect of
<acronym>SQL</acronym>. In 1987 this <acronym>ANSI</acronym> <acronym>SQL</acronym>. In 1987 this <acronym>ANSI</acronym>
standard was also accepted as an international standard was also accepted as an international
standard by the International Organization for Standardization standard by the International Organization for Standardization
(<acronym>ISO</acronym>). (<acronym>ISO</acronym>).
This original standard version of <acronym>SQL</acronym> is often referred to, This original standard version of <acronym>SQL</acronym> is often
informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original standard was extended 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 and this new standard is often, again informally, referred to as
"<abbrev>SQL/89</abbrev>". Also in 1989, a related standard called "<abbrev>SQL/89</abbrev>". Also in 1989, a related standard called
<firstterm>Database Language Embedded <acronym>SQL</acronym></firstterm> <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, ratified standard - "International Standard ISO/IEC 9075:1992,
Database Language <acronym>SQL</acronym>" - in late 1992. Database Language <acronym>SQL</acronym>" - in late 1992.
<acronym>SQL/92</acronym> is the version <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 description of <acronym>SQL/92</acronym> is given in
<xref linkend="DATE97" endterm="DATE97">. At the time of <xref linkend="DATE97" endterm="DATE97">. At the time of
writing this document a new standard informally referred to writing this document a new standard informally referred to
as <firstterm><acronym>SQL3</acronym></firstterm> 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 language, i.e. all computable queries (e.g. recursive queries) will be
possible. This is a very complex task and therefore the completion of possible. This is a very complex task and therefore the completion of
the new standard can not be expected before 1999. 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>
<para> <para>
A <firstterm>relational database</firstterm> is a database that is perceived by its A <firstterm>relational database</firstterm> is a database that is
users as a <firstterm>collection of tables</firstterm> (and nothing else but tables). 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 A table consists of rows and columns where each row represents a
record and each column represents an attribute of the records record and each column represents an attribute of the records
contained in the table. 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>
<para> <para>
The tables PART and SUPPLIER may be regarded as <firstterm>entities</firstterm> and The tables PART and SUPPLIER may be regarded as
SELLS may be regarded as a <firstterm>relationship</firstterm> between a particular <firstterm>entities</firstterm> and
SELLS may be regarded as a <firstterm>relationship</firstterm>
between a particular
part and a particular supplier. part and a particular supplier.
</para> </para>
<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 defined but before that we will study the theory of the relational
model. model.
</para> </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> <para>
The mathematical concept underlying the relational model is the 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 product of a list of domains. This set-theoretic relation gives
the model its name (do not confuse it with the relationship from the the model its name (do not confuse it with the relationship from the
<firstterm>Entity-Relationship model</firstterm>). <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> <para>
<!-- <!--
\begin{definition} \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 \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 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}$}. 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> <note>
<para> <para>
A <firstterm>relation scheme</firstterm> is just a kind of template A <firstterm>relation scheme</firstterm> is just a kind of template
whereas a <firstterm>relation</firstterm> is an instance of a <firstterm>relation whereas a <firstterm>relation</firstterm> is an instance of a
scheme</firstterm>. The relation consists of tuples (and can therefore be <firstterm>relation
scheme</firstterm>. The relation consists of tuples (and can
therefore be
viewed as a table); not so the relation scheme. viewed as a table); not so the relation scheme.
</para> </para>
</note> </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 <type>VARCHAR(20)</type> (this is the <acronym>SQL</acronym> type
for character strings of length &lt;= 20), for character strings of length &lt;= 20),
the type of <classname>SNO</classname> will be the type of <classname>SNO</classname> will be
<type>INTEGER</type>. With the assignment of a data type we also have selected <type>INTEGER</type>. With the assignment of a data type we also
a domain for an attribute. The domain of <classname>SNAME</classname> is the set of all have selected
a domain for an attribute. The domain of
<classname>SNAME</classname> is the set of all
character strings of length &lt;= 20, character strings of length &lt;= 20,
the domain of <classname>SNO</classname> is the set of the domain of <classname>SNO</classname> is the set of
all integer numbers. 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> <title id="operations">Operations in the Relational Data Model</title>
<para> <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 we defined the mathematical notion of
the relational model. Now we know how the data can be stored using a 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 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> <itemizedlist>
<listitem> <listitem>
<para> <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 where queries are expressed by applying specialized operators to the
relations. relations.
</para> </para>
@ -365,7 +396,8 @@ attributes are taken from. We often write a relation scheme as
<listitem> <listitem>
<para> <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 where queries are expressed by formulating some logical restrictions
that the tuples in the answer must satisfy. that the tuples in the answer must satisfy.
</para> </para>
@ -383,7 +415,8 @@ attributes are taken from. We often write a relation scheme as
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
SELECT (&sigma;): extracts <firstterm>tuples</firstterm> from a relation that SELECT (&sigma;): extracts <firstterm>tuples</firstterm> from
a relation that
satisfy a given restriction. Let <parameter>R</parameter> be a satisfy a given restriction. Let <parameter>R</parameter> be a
table that contains an attribute table that contains an attribute
<parameter>A</parameter>. <parameter>A</parameter>.
@ -441,10 +474,12 @@ attributes are taken from. We often write a relation scheme as
INTERSECT (&cap;): builds the set-theoretic intersection of two INTERSECT (&cap;): builds the set-theoretic intersection of two
tables. Given the tables <classname>R</classname> and tables. Given the tables <classname>R</classname> and
<classname>S</classname>, <classname>S</classname>,
<classname>R</classname> &cup; <classname>S</classname> is the set of tuples <classname>R</classname> &cup; <classname>S</classname> is the
set of tuples
that are in <classname>R</classname> and in that are in <classname>R</classname> and in
<classname>S</classname>. <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. same arity.
</para> </para>
</listitem> </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> two tables. Let <classname>R</classname> and <classname>S</classname>
again be two tables with the same again be two tables with the same
arity. <classname>R</classname> - <classname>S</classname> 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> </para>
</listitem> </listitem>
@ -672,9 +708,9 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
the one underlying the most relational languages. For a detailed the one underlying the most relational languages. For a detailed
discussion on <acronym>DRC</acronym> (and also discussion on <acronym>DRC</acronym> (and also
<acronym>TRC</acronym>) see <acronym>TRC</acronym>) see
[<xref linkend="DATE94" endterm="DATE94">] <xref linkend="DATE94" endterm="DATE94">
or or
[<xref linkend="ULL88" endterm="ULL88">]. <xref linkend="ULL88" endterm="ULL88">.
</para> </para>
</sect2> </sect2>
@ -727,9 +763,9 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
algorithm</quote>) by which an arbitrary expression of the relational algorithm</quote>) by which an arbitrary expression of the relational
calculus can be reduced to a semantically equivalent expression of calculus can be reduced to a semantically equivalent expression of
relational algebra. For a more detailed discussion on that refer to relational algebra. For a more detailed discussion on that refer to
[<xref linkend="DATE94" endterm="DATE94">] <xref linkend="DATE94" endterm="DATE94">
and and
[<xref linkend="ULL88" endterm="ULL88">]. <xref linkend="ULL88" endterm="ULL88">.
</para> </para>
<para> <para>
@ -750,9 +786,11 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
<acronym>SQL</acronym> is based on the tuple <acronym>SQL</acronym> is based on the tuple
relational calculus. As a result every query that can be formulated relational calculus. As a result every query that can be formulated
using the tuple relational calculus (or equivalently, relational 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 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: part of relational algebra or calculus:
<itemizedlist> <itemizedlist>
@ -764,7 +802,8 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
<listitem> <listitem>
<para> <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. arithmetic operations as well as comparisons, e.g.
A &lt; B + 3. A &lt; B + 3.
@ -787,7 +826,8 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
<para> <para>
Aggregate Functions: Operations such as Aggregate Functions: Operations such as
<firstterm>average</firstterm>, <firstterm>sum</firstterm>, <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. obtain a single quantity.
</para> </para>
</listitem> </listitem>
@ -918,7 +958,8 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
Note that the word DOUBLE after the keyword AS is the new title of the 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 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 is often referred to as alias. The alias cannot be used throughout the
rest of the query. rest of the query.
</para> </para>
@ -1508,8 +1549,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para> <para>
A view may be regarded as a <firstterm>virtual table</firstterm>, A view may be regarded as a <firstterm>virtual table</firstterm>,
i.e. a table that i.e. a table that
does not <emphasis>physically</emphasis> exist in the database but looks to the user does not <emphasis>physically</emphasis> exist in the database
as if it does. By contrast, when we talk of a <firstterm>base table</firstterm> there is 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 really a physically stored counterpart of each row of the table
somewhere in the physical storage. somewhere in the physical storage.
</para> </para>
@ -1550,7 +1593,8 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para> <para>
Let the following view definition be given (we use 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> <programlisting>
CREATE VIEW London_Suppliers 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> <emphasis>hidden</emphasis>
access to the base tables SUPPLIER, SELLS and PART first. It access to the base tables SUPPLIER, SELLS and PART first. It
does so by executing the query given in the view definition against 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 query against the view) can be applied to obtain the resulting
table. table.
</para> </para>
@ -1746,11 +1791,12 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<!-- <!--
section section
<xref linkend="view-impl" endterm="view-impl">. <xref linkend="view-impl" endterm="view-impl">.
-->
<citetitle>SIM98</citetitle> <citetitle>SIM98</citetitle>
-->
<xref linkend="SIM98" endterm="SIM98">
for a more detailed for a more detailed
description). For more information about system catalogs refer to description). For more information about system catalogs refer to
<citetitle>DATE</citetitle>. <xref linkend="DATE94" endterm="DATE94">.
</para> </para>
</sect2> </sect2>
@ -1815,10 +1861,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para> <para>
For a detailed discussion on embedded <acronym>SQL</acronym> For a detailed discussion on embedded <acronym>SQL</acronym>
refer to refer to
[<xref linkend="DATE97" endterm="DATE97">], <xref linkend="DATE97" endterm="DATE97">,
[<xref linkend="DATE94" endterm="DATE94">], <xref linkend="DATE94" endterm="DATE94">,
or or
[<xref linkend="ULL88" endterm="ULL88">]. <xref linkend="ULL88" endterm="ULL88">.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>

439
doc/src/sgml/start.sgml
View File

@ -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"> <chapter id="start">
<Title>Getting Started</Title> <title>Getting Started</title>
<Abstract> <abstract>
<Para> <para>
How to begin work with <ProductName>Postgres</ProductName> for a new user. How to begin work with <productname>Postgres</productname> for a new user.
</Para> </para>
</Abstract> </abstract>
<Para> <para>
Some of the steps required to use <ProductName>Postgres</ProductName> Some of the steps required to use <productname>Postgres</productname>
can be performed by any Postgres user, and some must be done by can be performed by any Postgres user, and some must be done by
the site database administrator. This site administrator the site database administrator. This site administrator
is the person who installed the software, created is the person who installed the software, created
the database directories and started the <Application>postmaster</Application> the database directories and started the
<application>postmaster</application>
process. This person does not have to be the Unix process. This person does not have to be the Unix
superuser (<Quote>root</Quote>) superuser (<quote>root</quote>)
or the computer system administrator; a person can install and use or the computer system administrator; a person can install and use
<ProductName>Postgres</ProductName> without any special accounts or privileges. <productname>Postgres</productname> without any special accounts or
</Para> privileges.
</para>
<Para> <para>
If you are installing <ProductName>Postgres</ProductName> yourself, then If you are installing <productname>Postgres</productname> yourself, then
refer to the Administrator's Guide for instructions on installation, and return refer to the Administrator's Guide for instructions on
installation, and return
to this guide when the installation is complete. to this guide when the installation is complete.
</Para> </para>
<Para> <para>
Throughout this manual, any examples that begin with Throughout this manual, any examples that begin with
the character <Quote>%</Quote> are commands that should be typed the character <quote>%</quote> are commands that should be typed
at the Unix shell prompt. Examples that begin with the at the Unix shell prompt. Examples that begin with the
character <Quote>*</Quote> are commands in the Postgres query character <quote>*</quote> are commands in the Postgres query
language, Postgres <Acronym>SQL</Acronym>. language, Postgres <acronym>SQL</acronym>.
</Para> </para>
<Sect1> <sect1>
<Title>Setting Up Your Environment</Title> <title>Setting Up Your Environment</title>
<Para> <para>
This section discusses how to set up This section discusses how to set up
your own environment so that you can use frontend your own environment so that you can use frontend
applications. We assume <ProductName>Postgres</ProductName> has already been applications. We assume <productname>Postgres</productname> has
already been
successfully installed and started; refer to the Administrator's Guide successfully installed and started; refer to the Administrator's Guide
and the installation notes and the installation notes
for how to install Postgres. for how to install Postgres.
</Para> </para>
<Para> <para>
<ProductName>Postgres</ProductName> is a client/server application. As a user, <productname>Postgres</productname> is a client/server
you only need access to the client portions of the installation (an example application. As a user,
of a client application is the interactive monitor <Application>psql</Application>). 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, For simplicity,
we will assume that <ProductName>Postgres</ProductName> has been installed in the we will assume that <productname>Postgres</productname> has been
directory <FileName>/usr/local/pgsql</FileName>. Therefore, wherever installed in the
you see the directory <FileName>/usr/local/pgsql</FileName> you should directory <filename>/usr/local/pgsql</filename>. Therefore, wherever
substitute the name of the directory where <ProductName>Postgres</ProductName> is you see the directory <filename>/usr/local/pgsql</filename> you should
substitute the name of the directory where
<productname>Postgres</productname> is
actually installed. actually installed.
All <ProductName>Postgres</ProductName> commands are installed in the directory All <productname>Postgres</productname> commands are installed in
<FileName>/usr/local/pgsql/bin</FileName>. Therefore, you should add the directory
<filename>/usr/local/pgsql/bin</filename>. Therefore, you should add
this directory to your shell command path. If you use this directory to your shell command path. If you use
a variant of the Berkeley C shell, such as csh or tcsh, a variant of the Berkeley C shell, such as csh or tcsh,
you would add you would add
<ProgramListing>
<programlisting>
% set path = ( /usr/local/pgsql/bin path ) % set path = ( /usr/local/pgsql/bin path )
</ProgramListing> </programlisting>
in the <FileName>.login</FileName> file in your home directory. If you use
in the <filename>.login</filename> file in your home directory.
If you use
a variant of the Bourne shell, such as sh, ksh, or a variant of the Bourne shell, such as sh, ksh, or
bash, then you would add bash, then you would add
<ProgramListing>
<programlisting>
% PATH=/usr/local/pgsql/bin:$PATH % PATH=/usr/local/pgsql/bin:$PATH
% export PATH % export PATH
</ProgramListing> </programlisting>
to the .profile file in your home directory. to the .profile file in your home directory.
From now on, we will assume that you have added the From now on, we will assume that you have added the
<ProductName>Postgres</ProductName> bin directory to your path. In addition, we <productname>Postgres</productname> bin directory to your path.
will make frequent reference to <Quote>setting a shell In addition, we
variable</Quote> or <Quote>setting an environment variable</Quote> throughout 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 this document. If you did not fully understand the
last paragraph on modifying your search path, you last paragraph on modifying your search path, you
should consult the Unix manual pages that describe your should consult the Unix manual pages that describe your
shell before going any further. shell before going any further.
</Para> </para>
<Para> <para>
If your site administrator has not set things up in the 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 default way, you may have some more work to do. For example, if
the database
server machine is a remote machine, you server machine is a remote machine, you
will need to set the <Acronym>PGHOST</Acronym> environment variable to the name will need to set the <acronym>PGHOST</acronym> environment
variable to the name
of the database server machine. The environment variable of the database server machine. The environment variable
<Acronym>PGPORT</Acronym> may also have to be set. The bottom line is this: if <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 you try to start an application program and it complains
that it cannot connect to the <Application>postmaster</Application>, that it cannot connect to the <application>postmaster</application>,
you should immediately consult your site administrator to make sure that your you should immediately consult your site administrator to make
sure that your
environment is properly set up. environment is properly set up.
</Para> </para>
</Sect1> </sect1>
<Sect1> <sect1>
<Title>Starting the Interactive Monitor (psql)</Title> <title>Starting the Interactive Monitor (psql)</title>
<Para> <para>
Assuming that your site administrator has properly Assuming that your site administrator has properly
started the <Application>postmaster</Application> process and authorized you to started the <application>postmaster</application> process and
authorized you to
use the database, you (as a user) may begin to start up use the database, you (as a user) may begin to start up
applications. As previously mentioned, you should add applications. As previously mentioned, you should add
<FileName>/usr/local/pgsql/bin</FileName> to your shell search path. <filename>/usr/local/pgsql/bin</filename> to your shell search path.
In most cases, this is all you should have to do in In most cases, this is all you should have to do in
terms of preparation. terms of preparation.
</Para> </para>
<Para> <para>
As of <ProductName>Postgres</ProductName> v6.3, two different styles of connections Two different styles of connections
are supported. The site administrator will have chosen to allow TCP/IP network connections are supported. The site administrator will have chosen to allow
or will have restricted database access to local (same-machine) socket connections only. TCP/IP network connections
These choices become significant if you encounter problems in connecting to a database. or will have restricted database access to local (same-machine)
</Para> 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> <para>
If you get the following error message from a <ProductName>Postgres</ProductName> If you get the following error message from a
command (such as <Application>psql</Application> or <Application>createdb</Application>): <productname>Postgres</productname>
command (such as <application>psql</application> or
<application>createdb</application>):
<ProgramListing> <programlisting>
% psql template1 % psql template1
Connection to database 'postgres' failed. Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting connections connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '5432'? at 'UNIX Socket' on port '5432'?
</ProgramListing> </programlisting>
or or
<ProgramListing> <programlisting>
% psql -h localhost template1 % psql -h localhost template1
Connection to database 'postgres' failed. Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting TCP/IP connectDB() failed: Is the postmaster running and accepting TCP/IP
(with -i) connections at 'localhost' on port '5432'? (with -i) connections at 'localhost' on port '5432'?
</ProgramListing> </programlisting>
it is usually because (1) the <Application>postmaster</Application> is not running, it is usually because
or (2) you are attempting to connect to the wrong server host.
<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: If you get the following error message:
<ProgramListing> <programlisting>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
</ProgramListing> </programlisting>
it means that the site administrator started the <Application>postmaster</Application> it means that the site administrator started the
<application>postmaster</application>
as the wrong user. Tell him to restart it as as the wrong user. Tell him to restart it as
the <ProductName>Postgres</ProductName> superuser. the <productname>Postgres</productname> superuser.
</Para> </para>
</Sect1> </sect1>
<Sect1> <sect1>
<Title>Managing a Database</Title> <title>Managing a Database</title>
<Para> <para>
Now that <ProductName>Postgres</ProductName> is up and running we can create some Now that <productname>Postgres</productname> is up and running we
can create some
databases to experiment with. Here, we describe the databases to experiment with. Here, we describe the
basic commands for managing a database. basic commands for managing a database.
</Para> </para>
<Para> <para>
Most <ProductName>Postgres</ProductName> Most <productname>Postgres</productname>
applications assume that the database name, if not specified, is the same as the name on your computer applications assume that the database name, if not specified, is
the same as the name on your computer
account. account.
</Para> </para>
<Para> <para>
If your database administrator has set up your account without database creation privileges, If your database administrator has set up your account without
then she should have told you what the name of your database is. If this is the case, then you 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. can skip the sections on creating and destroying databases.
</Para> </para>
<Sect2> <sect2>
<Title>Creating a Database</Title> <title>Creating a Database</title>
<Para> <para>
Let's say you want to create a database named <Database>mydb</Database>. Let's say you want to create a database named
<database>mydb</database>.
You can do this with the following command: You can do this with the following command:
<ProgramListing> <programlisting>
% createdb mydb % createdb mydb
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
If you do not have the privileges required to create a database, you will see If you do not have the privileges required to create a database,
you will see
the following: the following:
<ProgramListing> <programlisting>
% createdb mydb % createdb mydb
WARN:user "your username" is not allowed to create/destroy databases WARN:user "your username" is not allowed to create/destroy databases
createdb: database creation failed on mydb. createdb: database creation failed on mydb.
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
<ProductName>Postgres</ProductName> allows you to create any number of databases <productname>Postgres</productname> allows you to create any
number of databases
at a given site and you automatically become the 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. character and are limited to 32 characters in length.
Not every user has authorization to become a database 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 for you, then the site administrator needs to grant you
permission to create databases. Consult your site permission to create databases. Consult your site
administrator if this occurs. administrator if this occurs.
</Para> </para>
</Sect2> </sect2>
<Sect2> <sect2>
<Title>Accessing a Database</Title> <title>Accessing a Database</title>
<Para> <para>
Once you have constructed a database, you can access it Once you have constructed a database, you can access it
by: by:
<ItemizedList Mark="bullet" Spacing="compact"> <itemizedlist spacing="compact" mark="bullet">
<ListItem> <listitem>
<Para> <para>
running the <ProductName>Postgres</ProductName> terminal monitor programs Running the <productname>Postgres</productname> terminal
(e.g. <Application>psql</Application>) which allows you to interactively monitor programs
enter, edit, and execute <Acronym>SQL</Acronym> commands. (e.g. <application>psql</application>) which allows you to
</Para> interactively
</ListItem> enter, edit, and execute <acronym>SQL</acronym> commands.
<ListItem> </para>
<Para> </listitem>
writing a <Acronym>C</Acronym> program using the LIBPQ subroutine
library. This allows you to submit <Acronym>SQL</Acronym> commands <listitem>
from <Acronym>C</Acronym> and get answers and status messages back to <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 your program. This interface is discussed further
in <citetitle>The PostgreSQL Programmer's Guide</citetitle>. in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
</Para> </para>
</ListItem> </listitem>
</ItemizedList> </itemizedlist>
You might want to start up <Application>psql</Application>, You might want to start up <application>psql</application>,
to try out the examples in this manual. to try out the examples in this manual.
It can be activated for the <Database>mydb</Database> It can be activated for the <database>mydb</database>
database by typing the command: database by typing the command:
<ProgramListing> <programlisting>
% psql mydb % psql mydb
</ProgramListing> </programlisting>
You will be greeted with the following message: You will be greeted with the following message:
<ProgramListing> <programlisting>
Welcome to the POSTGRESQL interactive sql monitor: Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL Please read the file COPYRIGHT for copyright terms of POSTGRESQL
@ -254,71 +337,79 @@ Welcome to the POSTGRESQL interactive sql monitor:
You are currently connected to the database: template1 You are currently connected to the database: template1
mydb=> mydb=>
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
This prompt indicates that the terminal monitor is listening This prompt indicates that the terminal monitor is listening
to you and that you can type <Acronym>SQL</Acronym> queries into a to you and that you can type <acronym>SQL</acronym> queries into a
workspace maintained by the terminal monitor. workspace maintained by the terminal monitor.
The <Application>psql</Application> program responds to escape codes that begin The <application>psql</application> program responds to escape
with the backslash character, <Quote>\</Quote> For example, you codes that begin
with the backslash character, <quote>\</quote> For example, you
can get help on the syntax of various can get help on the syntax of various
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing: <productname>Postgres</productname> <acronym>SQL</acronym>
<ProgramListing> commands by typing:
<programlisting>
mydb=> \h mydb=> \h
</ProgramListing> </programlisting>
</para>
<para>
Once you have finished entering your queries into the Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace workspace, you can pass the contents of the workspace
to the <ProductName>Postgres</ProductName> server by typing: to the <productname>Postgres</productname> server by typing:
<ProgramListing> <programlisting>
mydb=> \g mydb=> \g
</ProgramListing> </programlisting>
This tells the server to process the query. If you 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. 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 To read queries from a file, say myFile, instead of
entering them interactively, type: entering them interactively, type:
<ProgramListing> <programlisting>
mydb=> \i fileName mydb=> \i fileName
</ProgramListing> </programlisting>
To get out of <Application>psql</Application> and return to Unix, type To get out of <application>psql</application> and return to Unix, type
<ProgramListing> <programlisting>
mydb=> \q mydb=> \q
</ProgramListing> </programlisting>
and <Application>psql</Application> will quit and return you to your command and <application>psql</application> will quit and return
shell. (For more escape codes, type <Command>\h</Command> at the monitor you to your command
prompt.) shell. (For more escape codes, type <command>\h</command> at the
monitor prompt.)
White space (i.e., spaces, tabs and newlines) may be White space (i.e., spaces, tabs and newlines) may be
used freely in <Acronym>SQL</Acronym> queries. Single-line comments are denoted by used freely in <acronym>SQL</acronym> queries. Single-line
<Quote>--</Quote>. Everything after the dashes up to the end of the 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, line is ignored. Multiple-line comments, and comments within a line,
are denoted by <Quote>/* ... */</Quote> are denoted by <quote>/* ... */</quote>
</Para> </para>
</Sect2> </sect2>
<Sect2> <sect2>
<Title>Destroying a Database</Title> <title>Destroying a Database</title>
<Para> <para>
If you are the database administrator for the database If you are the database administrator for the database
<Database>mydb</Database>, you can destroy it using the following Unix command: <database>mydb</database>, you can destroy it using the
<ProgramListing> following Unix command:
<programlisting>
% dropdb mydb % dropdb mydb
</ProgramListing> </programlisting>
This action physically removes all of the Unix files This action physically removes all of the Unix files
associated with the database and cannot be undone, so associated with the database and cannot be undone, so
this should only be done with a great deal of forethought. this should only be done with a great deal of forethought.
</Para> </para>
</Sect2> </sect2>
</Sect1> </sect1>
</Chapter> </chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:

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

@ -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"> <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> <para>
Written by Written by
<ulink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ulink> <ulink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ulink>
on 1998-10-22. on 1998-10-22. Updated 2000-03-31.
</para> </para>
</note> </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> <itemizedlist>
<listitem> <listitem>
<para> <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 support team since November, 1996, is not aware of
any problems in the <productname>Postgres</productname> code base related any problems in the <productname>Postgres</productname> code base related
to time transitions around Jan 1, 2000 (Y2K). to time transitions around Jan 1, 2000 (Y2K).