Skip to content

P
Postgres FD Implementation
Commit 32cfa65e authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Rearrange and consolidate the Admin Guide. 

Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
 integrated with the User's Guide.
Break up the former chapter on pg_options
 into Admin and Programmer's Guides.
parent c3a4d8ed
Hide whitespace changes
Inline Side-by-side
Showing with 2196 additions and 2086 deletions
doc/src/sgml/admin.sgml
View file @ 32cfa65e
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.12 1999/05/12 07:32:42 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.13 1999/05/20 05:39:25 thomas Exp $
Postgres Administrator's Guide.
Derived from postgres.sgml.
- thomas 1998-10-27
$Log: admin.sgml,v $
Revision 1.13 1999/05/20 05:39:25 thomas
Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
integrated with the User's Guide.
Break up the former chapter on pg_options
into Admin and Programmer's Guides.
Revision 1.12 1999/05/12 07:32:42 thomas
Include mention of CASE, COALESCE, and IFNULL.
Add date/time parsing procedure (perhaps should be in appendix).
......@@ -46,7 +54,7 @@ Bigger updates to the installation instructions (install and config).
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity install SYSTEM "install.sgml">
<!entity installw SYSTEM "install-win32.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity layout SYSTEM "layout.sgml">
<!entity ports SYSTEM "ports.sgml">
<!entity recovery SYSTEM "recovery.sgml">
<!entity regress SYSTEM "regress.sgml">
......@@ -54,6 +62,7 @@ Bigger updates to the installation instructions (install and config).
<!entity runtime SYSTEM "runtime.sgml">
<!entity security SYSTEM "security.sgml">
<!entity start-ag SYSTEM "start-ag.sgml">
<!entity trouble SYSTEM "trouble.sgml">
<!entity biblio SYSTEM "biblio.sgml">
]>
......@@ -87,12 +96,12 @@ Bigger updates to the installation instructions (install and config).
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1999-04-08)</Date>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998-9
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
......@@ -131,12 +140,13 @@ Your name here...
&ports;
&config;
&layout;
&install;
&installw;
&runtime;
&security;
&options;
&start-ag;
&trouble;
&recovery;
&regress;
&release;
......@@ -155,7 +165,7 @@ Don't bother with an index until we get some index entries.
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
......
doc/src/sgml/datetime.sgml 0 → 100644
View file @ 32cfa65e
From - Mon May 10 15:59:27 1999
Received: from localhost (lockhart@localhost [127.0.0.1])
by localhost (8.8.7/8.8.7) with ESMTP id PAA24871
for <lockhart@localhost>; Wed, 14 Apr 1999 15:45:24 GMT
Received: from apop-server.alumni.caltech.edu
by localhost with POP3 (fetchmail-4.7.9)
for lockhart@localhost (single-drop); Wed, 14 Apr 1999 15:45:26 +0000 (UTC)
Received: from bologna.nettuno.it (bologna.nettuno.it [193.43.2.1])
by alumnus.caltech.edu (8.9.1/8.9.1) with ESMTP id IAA18386
for <lockhart@alumni.caltech.edu>; Wed, 14 Apr 1999 08:41:45 -0700 (PDT)
Received: from proxy.sferacarta.com (mail@sfcabop1.nettuno.it [193.207.10.213])
by bologna.nettuno.it (8.8.6/8.8.6/NETTuno 3.1) with ESMTP id RAA15888;
Wed, 14 Apr 1999 17:41:33 +0200 (MDT)
Received: from rosso.sferacarta.com (sferacarta.com) [10.20.30.5]
by proxy.sferacarta.com with esmtp (Exim 2.05 #1 (Debian))
id 10XTfQ-00083Z-00; Wed, 14 Apr 1999 17:41:40 +0000
Message-ID: <3714B6B6.F745D41D@sferacarta.com>
Date: Wed, 14 Apr 1999 17:39:34 +0200
From: José Soares <jose@sferacarta.com>
X-Mailer: Mozilla 4.5 [it] (Win95; I)
X-Accept-Language: it
MIME-Version: 1.0
To: Thomas Lockhart <lockhart@alumni.caltech.edu>
CC: hackers <pgsql-hackers@postgresql.org>,
general <pgsql-general@postgresql.org>
Subject: Re: [GENERAL] Re: [HACKERS] Gregorian Calendar
References: <3711B1E5.80213DF6@sferacarta.com> <37135951.88FDB948@alumni.caltech.edu>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=iso-8859-1
X-UIDL: 25f0580d2a532247ac6af3aee9737b7c
X-Mozilla-Status: 8011
X-Mozilla-Status2: 00000000
Hi Thomas,
Thomas Lockhart ha scritto:
> > I have a question about dates.
> > The Gregorian reform of calendar skiped 10 days on Oct, 1582.
> > This reform was accepted by Great Britain and Dominions (including
> > what is now the USA) only in 1752.
> > If I insert a date that doesn't exist PostgreSQL accepts it.
> > Should it be considered normal ?
>
> As Peter says, this is tricky.
>
> Date conventions before the 19th century make for interesting reading,
> but are not imho consistant enough to warrant coding into a date/time
> handler.
>
> As you probably have noticed, we use Julian date calculations for our
> date/time support.
I suppose you refer to Julian Day invented by the French scholar
Joseph Justus Scaliger (1540-1609)
that probably takes its name from the Scaliger's father,
the Italian scholar Julius Caesar Scaliger (1484-1558).
Astronomers have used the Julian period to assign a unique number to
every day since 1 January 4713 BC. This is the so-called Julian Day
(JD). JD 0 designates the 24 hours from noon UTC on 1 January 4713 BC
to noon UTC on 2 January 4713 BC.
Julian Day is different from Julian Date
The Julian calendar was introduced by Julius Caesar in 45 BC. It was
in common use until the 1582, when countries started changing to the
Gregorian calendar.
In the Julian calendar, the tropical year is approximated as 365 1/4
days = 365.25 days. This gives an error of 1 day in approximately 128
and this is why pope Gregory XIII in accordance with instructions
from the Council of Trent reformed the calendar to correct this error.
In the Gregorian calendar, the tropical year is approximated as
365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300
years for the tropical year to shift one day with respect to the
Gregorian calendar.
The approximation 365+97/400 is achieved by having 97 leap years
every 400 years.
The Gregorian calendar has 97 leap years every 400 years:
Every year divisible by 4 is a leap year.
However, every year divisible by 100 is not a leap year.
However, every year divisible by 400 is a leap year after all.
So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600,
2000, and 2400 are leap years.
instead in the Julian calendar only years divisible by 4 are leap years.
The papal bull of February 1582 decreed that 10 days should be dropped
from October 1582 so that 15 October should follow immediately after
4 October.
This was observed in Italy, Poland, Portugal, and Spain. Other Catholic
countries followed shortly after, but Protestant countries were
reluctant to change, and the Greek orthodox countries didn't change
until the start of this century.
The reform was observed by Great Britain and Dominions (including what is
now the USA)
in 1752.
The 2 Sep 1752 was followed by 14 Sep 1752.
This is why unix has the cal 9 1752 like this:
September 1752
S M Tu W Th F S
1 2 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
My question is:
^^^^^^^^^^^^
If SQL92 says:
(Second Informal Review Draft) ISO/IEC 9075:1992, Database
Language SQL- July 30, 1992
5.3 literals
22)Within the definition of a <datetime literal>, the <datetime
value>s are constrained by the natural rules for dates and
times
according to the Gregorian calendar.
^^^^^^^^^^^^^^^
Dates between 1752-09-03 and 1752-09-13.
Are they valid dates?
^^^^^^^^^^^^^^^^
> They have the nice property of correctly
> predicting/calculating any date more recent than something like 4013BC
> to far into the future, using the assumption that the length of the
> year is 365.25 days. This is a very recently adopted convention
> (sometime in the 1800s I had thought, but perhaps it was during the
> same "reform" in 1752).
>
> I've toyed with the idea of implementing a Chinese dynastic calendar,
> since it seems to be more predictable than historical European
> calendars.
People's Republic of China uses the Gregorian calendar
for civil purposes. Chinese calendar is used for determining
festivals.
The beginnings of the Chinese calendar can be traced back to the 14th
century BC. Legend has it that the Emperor Huangdi invented the
calendar in 2637 B
José
doc/src/sgml/install.sgml
View file @ 32cfa65e
<Chapter Id="install">
<Title>Installation</Title>
<Chapter Id="install">
<Title>Installation</Title>
<Abstract>
<Para>
Complete installation instructions for
<ProductName>Postgres</ProductName> v6.5.
</Para>
</Abstract>
<Para>
Before installing <ProductName>Postgres</ProductName>, you may wish to visit
<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
for up to date information, patches, etc.
</Para>
<Para>
These installation instructions assume:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
Commands are Unix-compatible. See note below.
</Para>
</ListItem>
<ListItem>
<Para>
Defaults are used except where noted.
</Para>
</ListItem>
<ListItem>
<Para>
User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
</Para>
</ListItem>
<ListItem>
<Para>
The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
<ListItem>
<Para>
The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
</ItemizedList>
</para>
<Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands
like <command>ps</command> and <command>tar</command> may vary wildly
between platforms on what options you should use.
<Emphasis>Use common sense</Emphasis> before typing in these commands.
</Para>
<Para>
Our Makefiles require GNU <Application>make</Application> (called
<Quote>gmake</Quote> in this document). They will <Emphasis>not</Emphasis>
work with non-GNU <Application>make</Application> programs. If you
have GNU <Application>make</Application> installed under the name
<Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
command <command>make</command> instead. That's OK, but
you need to have the GNU form of <Application>make</Application> to succeed with
an installation.
</Para>
<Sect1>
<Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
<Para>
Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/install.htm">
http://www.postgresql.org/docs/admin/install.htm</ulink>.
In general, most Unix-compatible
platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>.
</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
is as little as 8MB, there are noticable improvements in runtimes for the regression
tests when expanding memory up to 96MB on a relatively fast dual-processor system
running X-Windows.
The rule is you can never have too much memory.
</para>
<Para>
Check that you have sufficient disk space. You will need about
30 Mbytes for <filename>/usr/src/pgsql</filename>,
about 5 Mbytes for <filename>/usr/local/pgsql</filename>
(excluding your database) and 1 Mbyte for an empty database.
The database will temporarily grow to about 20 Mbytes during the
regression tests. You will also need about 3 Mbytes for the
distribution tar file.
</Para>
<Abstract>
<Para>
Complete installation instructions for
<ProductName>Postgres</ProductName> v6.5.
</Para>
</Abstract>
<Para>
Before installing <ProductName>Postgres</ProductName>, you may wish to visit
<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
for up to date information, patches, etc.
</Para>
<Para>
These installation instructions assume:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
Commands are Unix-compatible. See note below.
</Para>
</ListItem>
<ListItem>
<Para>
Defaults are used except where noted.
</Para>
</ListItem>
<ListItem>
<Para>
User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
</Para>
</ListItem>
<ListItem>
<Para>
The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
<ListItem>
<Para>
The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
</ItemizedList>
</para>
<Para>
Commands were tested on RedHat Linux version 5.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands
like <command>ps</command> and <command>tar</command> may vary wildly
between platforms on what options you should use.
<Emphasis>Use common sense</Emphasis> before typing in these commands.
</Para>
<Para>
Our Makefiles require GNU <Application>make</Application> (called
<Quote>gmake</Quote> in this document). They will <Emphasis>not</Emphasis>
work with non-GNU <Application>make</Application> programs. If you
have GNU <Application>make</Application> installed under the name
<Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
command <command>make</command> instead. That's OK, but
you need to have the GNU form of <Application>make</Application> to succeed with
an installation.
</Para>
<Sect1>
<Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
<Para>
Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/install.htm">
http://www.postgresql.org/docs/admin/install.htm</ulink>.
In general, most Unix-compatible
platforms with modern libraries should be able to run
<ProductName>Postgres</ProductName>.
</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
is as little as 8MB, there are noticable improvements in runtimes for the regression
tests when expanding memory up to 96MB on a relatively fast dual-processor system
running X-Windows.
The rule is you can never have too much memory.
</para>
<Para>
Check that you have sufficient disk space. You will need about
30 Mbytes for <filename>/usr/src/pgsql</filename>,
about 5 Mbytes for <filename>/usr/local/pgsql</filename>
(excluding your database) and 1 Mbyte for an empty database.
The database will temporarily grow to about 20 Mbytes during the
regression tests. You will also need about 3 Mbytes for the
distribution tar file.
</Para>
<Para>
We therefore recommend that during installation and testing you
have well over 20 Mbytes free under <filename>/usr/local</filename> and another 25 Mbytes
free on the disk partition containing your database. Once you
delete the source files, tar file and regression database, you
will need 2 Mbytes for <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty
database, plus about five times the space you would require to
store your database data in a flat file.
</Para>
<Para>
We therefore recommend that during installation and testing you
have well over 20 Mbytes free under <filename>/usr/local</filename> and another 25 Mbytes
free on the disk partition containing your database. Once you
delete the source files, tar file and regression database, you
will need 2 Mbytes for <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty
database, plus about five times the space you would require to
store your database data in a flat file.
</Para>
<Para>
To check for disk space, use
<programlisting>
<Para>
To check for disk space, use
<programlisting>
$ df -k
</programlisting>
</para>
</Sect1>
</programlisting>
</para>
</Sect1>
<Sect1>
<Title>Installation Procedure</Title>
......@@ -1300,95 +1302,30 @@ For more information on the various support mailing lists.
</Para>
</Sect1>
<Sect1>
<Title>Porting Notes</Title>
<Sect1>
<Title>Porting Notes</Title>
<Note>
<Para>
Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
the source distribution. For some ports, the notes below may be out of date.
</Para>
</Note>
<Sect2>
<Title>Ultrix4.x</Title>
<para>
<note>
<para>
There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
</para>
</note>
</para>
<para>
You need to install the libdl-1.1 package since Ultrix 4.x doesn't
have a dynamic loader. It's available in
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
<Para>
Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
the source distribution.
</Para>
</Sect2>
<Sect2>
<Title>Linux</Title>
<Sect3>
<Sect3Info>
<Author>
<FirstName>Thomas G.</FirstName>
<SurName>Lockhart</SurName>
</Author>
<Date>1998-02-19</Date>
</Sect3Info>
<Title>Linux ELF</Title>
<Para>
The regression test reference machine is
a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
The linux-elf port installs cleanly. See the Linux FAQ for more details.
</Para>
</Sect3>
<Sect3>
<Sect3Info>
<Date>1995-05-11</Date>
</Sect3Info>
<Title>Linux a.out</Title>
<Para>
For non-ELF Linux, the dld library MUST be obtained and installed on
the system. It enables dynamic link loading capability to the <ProductName>Postgres</ProductName>
port. The dld library can be obtained from the sunsite linux
distributions. The current name is dld-3.2.5.
<ULink url="sneaker@powergrid.electriciti.com">Jalon Q. Zimmerman</ULink>
</Para>
</Sect3>
</Sect2>
<Sect2>
<Title>BSD/OS</Title>
<Para>
For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
</Para>
</Sect2>
<Sect2>
<Title>NeXT</Title>
<Para>
The NeXT port for v1.09 was supplied by
<ULink url="mailto:tom@basil.icce.rug.nl">Tom R. Hageman</ULink>.
It requires a SysV IPC emulation library and header files for
shared libary and semaphore stuff. Tom just happens to sell such
a product so contact him for information. He has also indicated that
binary releases of <ProductName>Postgres</ProductName> for NEXTSTEP will be made available to
the general public. Contact Info@RnA.nl for information.
</para>
<Para>
We have no recent reports of successful NeXT installations (as of v6.2.1).
However, the client-side libraries should work even
if the backend is not supported.
</Para>
</Sect2>
</Sect1>
</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/layout.sgml 0 → 100644
View file @ 32cfa65e
<chapter id="layout">
<Title>System Layout</Title>
<Para>
<Figure Id="ADMIN-LAYOUT">
<Title><ProductName>Postgres</ProductName> file layout</Title>
<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic>
</Figure>
<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT">
shows how the <ProductName>Postgres</ProductName> distribution is laid
out when installed in the default way. For simplicity,
we will assume that <ProductName>Postgres</ProductName>
has been installed in the
directory <filename>/usr/local/pgsql</filename>. Therefore, wherever
you see the directory <filename>/usr/local/pgsql</filename> you should
substitute the name of the directory where
<ProductName>Postgres</ProductName> is
actually installed.
All <ProductName>Postgres</ProductName> commands are installed
in the directory
<filename>/usr/local/pgsql/bin</filename>. Therefore, you should add
this directory to your shell command path. If you use
a variant of the Berkeley C shell, such as csh or tcsh,
you would add
<ProgramListing>
set path = ( /usr/local/pgsql/bin path )
</ProgramListing>
in the .login file in your home directory. If you use
a variant of the Bourne shell, such as sh, ksh, or
bash, then you would add
<ProgramListing>
PATH=/usr/local/pgsql/bin:$PATH
export PATH
</ProgramListing>
to the .profile file in your home directory.
From now on, we will assume that you have added the
<ProductName>Postgres</ProductName> bin directory to your path.
In addition, we
will make frequent reference to "setting a shell
variable" or "setting an environment variable" throughout
this document. If you did not fully understand the
last paragraph on modifying your search path, you
should consult the UNIX manual pages that describe your
shell before going any further.
</Para>
<Para>
If you have not set things up in the
default way, you may have some more work to do.
For example, if the database server machine is a remote machine, you
will need to set the <envar>PGHOST</envar> environment variable to the name
of the database server machine. The environment variable
<envar>PGPORT</envar> may also have to be set. The bottom line is this: if
you try to start an application program and it complains
that it cannot connect to the <Application>postmaster</Application>,
you must go back and make sure that your
environment is properly set up.
</Para>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/pg_options.sgml
View file @ 32cfa65e
<Chapter Id="pg-options">
<DocInfo>
<AuthorGroup>
<Author>
<FirstName>Massimo</FirstName>
<Surname>Dal Zotto</Surname>
</Author>
</AuthorGroup>
<Date>Transcribed 1998-10-16</Date>
</DocInfo>
<Title>Using pg_options</Title>
<Para>
<Note>
<Para>
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
</Para>
</Note>
</para>
<Para>
The optional file <filename>data/pg_options</filename> contains runtime
options used by the backend to control trace messages and other backend
tunable parameters.
What makes this file interesting is the fact that it is re-read by a backend
when it receives a SIGHUP signal, making thus possible to change run-time
options on the fly without needing to restart
<productname>Postgres</productname>.
The options specified in this file may be debugging flags used by the trace
package (<filename>backend/utils/misc/trace.c</filename>) or numeric
parameters which can be used by the backend to control its behaviour.
New options and parameters must be defined in
<filename>backend/utils/misc/trace.c</filename> and
<filename>backend/include/utils/trace.h</filename>.
</para>
<Para>
For example suppose we want to add conditional trace messages and a tunable
numeric parameter to the code in file <filename>foo.c</filename>.
All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
<filename>backend/include/utils/trace.h</filename>:
<programlisting>
<Chapter Id="pg-options">
<DocInfo>
<AuthorGroup>
<Author>
<FirstName>Massimo</FirstName>
<Surname>Dal Zotto</Surname>
</Author>
</AuthorGroup>
<Date>Transcribed 1998-10-16</Date>
</DocInfo>
<Title>pg_options</Title>
<Para>
<Note>
<Para>
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
</Para>
</Note>
</para>
<Para>
The optional file <filename>data/pg_options</filename> contains runtime
options used by the backend to control trace messages and other backend
tunable parameters.
What makes this file interesting is the fact that it is re-read by a backend
when it receives a SIGHUP signal, making thus possible to change run-time
options on the fly without needing to restart
<productname>Postgres</productname>.
The options specified in this file may be debugging flags used by the trace
package (<filename>backend/utils/misc/trace.c</filename>) or numeric
parameters which can be used by the backend to control its behaviour.
New options and parameters must be defined in
<filename>backend/utils/misc/trace.c</filename> and
<filename>backend/include/utils/trace.h</filename>.
</para>
<Para>
For example suppose we want to add conditional trace messages and a tunable
numeric parameter to the code in file <filename>foo.c</filename>.
All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
<filename>backend/include/utils/trace.h</filename>:
<programlisting>
/* file trace.h */
enum pg_option_enum {
...
......@@ -48,23 +48,23 @@ enum pg_option_enum {
NUM_PG_OPTIONS /* must be the last item of enum */
};
</programlisting>
</programlisting>
and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
<programlisting>
<programlisting>
/* file trace.c */
static char *opt_names[] = {
...
"foo", /* trace foo functions */
"fooparam" /* foo tunable parameter */
};
</programlisting>
</programlisting>
Options in the two files must be specified in exactly the same order.
In the foo source files we can now reference the new flags with:
Options in the two files must be specified in exactly the same order.
In the foo source files we can now reference the new flags with:
<programlisting>
<programlisting>
/* file foo.c */
#include "trace.h"
#define foo_param pg_options[OPT_FOO_PARAM]
......@@ -77,54 +77,54 @@ foo_function(int x, int y)
do_more_foo(x, y);
}
}
</programlisting>
</para>
<para>
Existing files using private trace flags can be changed by simply adding
the following code:
</programlisting>
</para>
<para>
Existing files using private trace flags can be changed by simply adding
the following code:
<programlisting>
<programlisting>
#include "trace.h"
/* int my_own_flag = 0; -- removed */
#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
</programlisting>
</para>
<para>
All pg_options are initialized to zero at backend startup. If we need a
different default value we must add some initialization code at the beginning
of <function>PostgresMain</function>.
</programlisting>
</para>
<para>
All pg_options are initialized to zero at backend startup. If we need a
different default value we must add some initialization code at the beginning
of <function>PostgresMain</function>.
Now we can set the foo_param and enable foo trace by writing values into the
<filename>data/pg_options</filename> file:
Now we can set the foo_param and enable foo trace by writing values into the
<filename>data/pg_options</filename> file:
<programlisting>
<programlisting>
# file pg_options
...
foo=1
fooparam=17
</programlisting>
</para>
<para>
The new options will be read by all new backends when they are started.
To make effective the changes for all running backends we need to send a
SIGHUP to the postmaster. The signal will be automatically sent to all the
backends. We can also activate the changes only for a specific backend by
sending the SIGHUP directly to it.
</para>
<para>
pg_options can also be specified with the <option>-T</option> switch of
<productname>Postgres</productname>:
<programlisting>
</programlisting>
</para>
<para>
The new options will be read by all new backends when they are started.
To make effective the changes for all running backends we need to send a
SIGHUP to the postmaster. The signal will be automatically sent to all the
backends. We can also activate the changes only for a specific backend by
sending the SIGHUP directly to it.
</para>
<para>
pg_options can also be specified with the <option>-T</option> switch of
<productname>Postgres</productname>:
<programlisting>
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
</programlisting>
</para>
<Para>
The functions used for printing errors and debug messages can now make use
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
or stderr are prefixed by a timestamp containing also the backend pid:
<programlisting>
</programlisting>
</para>
<Para>
The functions used for printing errors and debug messages can now make use
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
or stderr are prefixed by a timestamp containing also the backend pid:
<programlisting>
#timestamp #pid #message
980127.17:52:14.173 [29271] StartTransactionCommand
980127.17:52:14.174 [29271] ProcessUtility: drop table t;
......@@ -134,518 +134,103 @@ or stderr are prefixed by a timestamp containing also the backend pid:
980127.19:52:14.292 [29286] Async_NotifyFrontEnd
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
980127.19:52:14.466 [29286] Async_NotifyHandler done
</programlisting>
</para>
<para>
This format improves readability of the logs and allows people to understand
exactly which backend is doing what and at which time. It also makes
easier to write simple awk or perl scripts which monitor the log to
detect database errors or problem, or to compute transaction time statistics.
</para>
<para>
Messages printed to syslog use the log facility LOG_LOCAL0.
The use of syslog can be controlled with the syslog pg_option.
Unfortunately many functions call directly <function>printf()</function>
to print their messages to stdout or stderr and this output can't be
redirected to syslog or have timestamps in it.
It would be advisable that all calls to printf would be replaced with the
PRINTF macro and output to stderr be changed to use EPRINTF instead so that
we can control all output in a uniform way.
</Para>
<Para>
The new pg_options mechanism is more convenient than defining new backend
option switches because:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
we don't have to define a different switch for each thing we want to control.
All options are defined as keywords in an external file stored in the data
directory.
</Para>
</ListItem>
<ListItem>
<Para>
we don't have to restart <productname>Postgres</productname> to change
the setting of some option.
Normally backend options are specified to the postmaster and passed to each
backend when it is started. Now they are read from a file.
</Para>
</ListItem>
<ListItem>
<Para>
we can change options on the fly while a backend is running. We can thus
investigate some problem by activating debug messages only when the problem
appears. We can also try different values for tunable parameters.
</Para>
</ListItem>
</ItemizedList>
The format of the <filename>pg_options</filename> file is as follows:
<programlisting>
</programlisting>
</para>
<para>
This format improves readability of the logs and allows people to understand
exactly which backend is doing what and at which time. It also makes
easier to write simple awk or perl scripts which monitor the log to
detect database errors or problem, or to compute transaction time statistics.
</para>
<para>
Messages printed to syslog use the log facility LOG_LOCAL0.
The use of syslog can be controlled with the syslog pg_option.
Unfortunately many functions call directly <function>printf()</function>
to print their messages to stdout or stderr and this output can't be
redirected to syslog or have timestamps in it.
It would be advisable that all calls to printf would be replaced with the
PRINTF macro and output to stderr be changed to use EPRINTF instead so that
we can control all output in a uniform way.
</Para>
<Para>
The new pg_options mechanism is more convenient than defining new backend
option switches because:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
we don't have to define a different switch for each thing we want to control.
All options are defined as keywords in an external file stored in the data
directory.
</Para>
</ListItem>
<ListItem>
<Para>
we don't have to restart <productname>Postgres</productname> to change
the setting of some option.
Normally backend options are specified to the postmaster and passed to each
backend when it is started. Now they are read from a file.
</Para>
</ListItem>
<ListItem>
<Para>
we can change options on the fly while a backend is running. We can thus
investigate some problem by activating debug messages only when the problem
appears. We can also try different values for tunable parameters.
</Para>
</ListItem>
</ItemizedList>
The format of the <filename>pg_options</filename> file is as follows:
<programlisting>
# <replaceable>comment</replaceable>
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable>
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0
</programlisting>
Note that <replaceable class="parameter">keyword</replaceable> can also be
an abbreviation of the option name defined in
<filename>backend/utils/misc/trace.c</filename>.
</Para>
<Para>
The options currently defined in
<filename>backend/utils/misc/trace.c</filename> are the following:
<variablelist>
<varlistentry>
<term>
all
</term>
<listitem>
<para>
Global trace flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
Trace messages enabled individually
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Enable all trace messages
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-1
</term>
<listitem>
<para>
Disable all trace messages
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
verbose
</term>
<listitem>
<para>
Verbosity flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
No messages. This is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Print information messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
2
</term>
<listitem>
<para>
Print more information messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
query
</term>
<listitem>
<para>
Query trace flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
Don't print query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Print a condensed query in one line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
4
</term>
<listitem>
<para>
Print the full query.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
plan
</term>
<listitem>
<para>
Print query plan.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
parse
</term>
<listitem>
<para>
Print parser output.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
rewritten
</term>
<listitem>
<para>
Print rewritten query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
parserstats
</term>
<listitem>
<para>
Print parser statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
plannerstats
</term>
<listitem>
<para>
Print planner statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
executorstats
</term>
<listitem>
<para>
Print executor statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
shortlocks
</term>
<listitem>
<para>
Currently unused but needed to enable features in the future.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
locks
</term>
<listitem>
<para>
Trace locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
userlocks
</term>
<listitem>
<para>
Trace user locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
spinlocks
</term>
<listitem>
<para>
Trace spin locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
notify
</term>
<listitem>
<para>
Trace notify functions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
malloc
</term>
<listitem>
<para>
Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
palloc
</term>
<listitem>
<para>
Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
lock_debug_oidmin
</term>
<listitem>
<para>
Minimum relation oid traced by locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
lock_debug_relid
</term>
<listitem>
<para>
oid, if not zero, of relation traced by locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
lock_read_priority
</term>
<listitem>
<para>
Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
deadlock_timeout
</term>
<listitem>
<para>
Deadlock check timer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
syslog
</term>
<listitem>
<para>
syslog flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
Messages to stdout/stderr.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Messages to stdout/stderr and syslog.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
2
</term>
<listitem>
<para>
Messages only to syslog.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
hostlookup
</term>
<listitem>
<para>
Enable hostname lookup in ps_status.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
showportnumber
</term>
<listitem>
<para>
Show port number in ps_status.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
notifyunlock
</term>
<listitem>
<para>
Unlock of pg_listener after notify.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
notifyhack
</term>
<listitem>
<para>
Remove duplicate tuples from pg_listener.
</para>
</listitem>
</varlistentry>
</variablelist>
For example my pg_options file contains the following values:
<programlisting>
verbose=2
query
hostlookup
showportnumber
</programlisting>
</Para>
<Para>
Some of the existing code using private variables and option switches has
been changed to make use of the pg_options feature, mainly in
<filename>postgres.c</filename>. It would be advisable to modify
all existing code
in this way, so that we can get rid of many of the switches on
the <productname>Postgres</productname> command line
and can have more tunable options
with a unique place to put option values.
</Para>
</Chapter>
</programlisting>
Note that <replaceable class="parameter">keyword</replaceable> can also be
an abbreviation of the option name defined in
<filename>backend/utils/misc/trace.c</filename>.
</Para>
<para>
Refer to <citetitle>The Administrator's Guide</citetitle> chapter
on runtime options for a complete list of currently supported
options.
</para>
<Para>
Some of the existing code using private variables and option switches has
been changed to make use of the pg_options feature, mainly in
<filename>postgres.c</filename>. It would be advisable to modify
all existing code
in this way, so that we can get rid of many of the switches on
the <productname>Postgres</productname> command line
and can have more tunable options
with a unique place to put option values.
</Para>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/pgaccess.sgml deleted 100644 → 0
View file @ c3a4d8ed
<Chapter Id="pgaccess">
<Title><Command>pgaccess</Command></Title>
<Para>
This section needs to be written. Volunteers?
</Para>
</Chapter>
doc/src/sgml/postgres.sgml
View file @ 32cfa65e
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.21 1999/05/04 02:19:20 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.22 1999/05/20 05:39:27 thomas Exp $
Postgres integrated documentation.
Other subset docs should be copied and shrunk from here.
thomas 1998-02-23
$Log: postgres.sgml,v $
Revision 1.22 1999/05/20 05:39:27 thomas
Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
integrated with the User's Guide.
Break up the former chapter on pg_options
into Admin and Programmer's Guides.
Revision 1.21 1999/05/04 02:19:20 thomas
Include chapters on security and an intro to SQL.
......@@ -105,7 +113,6 @@ Move SQL reference pages up into the User's Guide.
<!entity install SYSTEM "install.sgml">
<!entity installw SYSTEM "install-win32.sgml">
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity ports SYSTEM "ports.sgml">
<!entity runtime SYSTEM "runtime.sgml">
<!entity recovery SYSTEM "recovery.sgml">
......@@ -146,6 +153,7 @@ Move SQL reference pages up into the User's Guide.
<!entity contacts SYSTEM "contacts.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
<!entity signals SYSTEM "signals.sgml">
......@@ -157,7 +165,7 @@ Move SQL reference pages up into the User's Guide.
<Title>PostgreSQL</Title>
<BookInfo>
<ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
......@@ -180,7 +188,7 @@ Move SQL reference pages up into the User's Guide.
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
<Date>(last updated 1998-05-19)</Date>
</BookBiblio>
<LegalNotice>
......@@ -242,21 +250,18 @@ Your name here...
</Para>
</PartIntro>
&sql;
&environ;
&manage;
&syntax;
&sql;
&syntax;
&datatype;
&oper;
&func;
&typeconv;
&keys;
&keys;
&array;
&inherit;
&query-ug;
&environ;
&manage;
&storage;
&psql;
&pgaccess;
&commands;
</Part>
......@@ -274,7 +279,6 @@ Your name here...
&installw;
&runtime;
&security;
&options;
&start-ag;
&recovery;
&regress;
......@@ -331,6 +335,7 @@ Your name here...
</Para>
</PartIntro>
&arch-dev;
&options;
&geqo;
&protocol;
&signals;
......
doc/src/sgml/programmer.sgml
View file @ 32cfa65e
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.13 1999/04/08 13:28:22 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.14 1999/05/20 05:39:27 thomas Exp $
Postgres Programmer's Guide.
- thomas 1998-10-27
$Log: programmer.sgml,v $
Revision 1.14 1999/05/20 05:39:27 thomas
Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
integrated with the User's Guide.
Break up the former chapter on pg_options
into Admin and Programmer's Guides.
Revision 1.13 1999/04/08 13:28:22 thomas
Add emacs editor hints to bottom of file.
......@@ -80,6 +88,7 @@ Bigger updates to the installation instructions (install and config).
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!-- developer's guide -->
<!entity arch-dev SYSTEM "arch-dev.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity bki SYSTEM "bki.sgml">
......@@ -87,6 +96,7 @@ Bigger updates to the installation instructions (install and config).
<!entity contacts SYSTEM "contacts.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
<!entity signals SYSTEM "signals.sgml">
......@@ -96,23 +106,23 @@ Bigger updates to the installation instructions (install and config).
<!-- Title information -->
<Title>PostgreSQL Programmer's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<Title>PostgreSQL Programmer's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<!-- editor in authorgroup is not supported
<AuthorGroup>
-->
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<!--
</AuthorGroup>
-->
......@@ -121,17 +131,17 @@ Bigger updates to the installation instructions (install and config).
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-10-27)</Date>
</BookBiblio>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
by the Postgres Global Development Group.
</Para>
</LegalNotice>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
</BookInfo>
</BookInfo>
<!--
<TOC> </TOC>
......@@ -146,33 +156,33 @@ Your name here...
</Dedication>
-->
<Preface id="preface">
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain,
open source descendant of this original Berkeley code.
</Para>
</Preface>
&intro-pg;
&arch-pg;
&extend;
&xfunc;
&xtypes;
&xoper;
&xaggr;
&rules;
&xindex;
&gist;
&xplang;
&dfunc;
<Preface id="preface">
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain,
open source descendant of this original Berkeley code.
</Para>
</Preface>
&intro-pg;
&arch-pg;
&extend;
&xfunc;
&xtypes;
&xoper;
&xaggr;
&rules;
&xindex;
&gist;
&xplang;
&dfunc;
<!-- reference -->
......@@ -183,33 +193,34 @@ Disable it until we put in some info.
&func-ref;
-->
&trigger;
&spi;
&lobj;
&libpq;
&libpqpp;
&libpgtcl;
&ecpg;
&odbc;
&jdbc;
&trigger;
&spi;
&lobj;
&libpq;
&libpqpp;
&libpgtcl;
&ecpg;
&odbc;
&jdbc;
<!-- development -->
&arch-dev;
&geqo;
&protocol;
&signals;
&compiler;
&bki;
&page;
&arch-dev;
&options;
&geqo;
&protocol;
&signals;
&compiler;
&bki;
&page;
<!-- appendices -->
&docguide;
&docguide;
<!--
&contacts;
-->
&biblio;
&biblio;
<!--
<index id="index">
......
doc/src/sgml/psql.sgml deleted 100644 → 0
View file @ c3a4d8ed
<Chapter Id="psql">
<Title><Command>psql</Command></Title>
<Para>
This section needs to be converted from the original psql man page. Volunteers?
</Para>
<Tip>
<Para>
To change the paging behavior of your results, set/unset your PAGER environment variable.
</Para>
</Tip>
<Sect1>
<Title>Paging To Screen</Title>
<Note>
<Title>Author</Title>
<Para>
From Brett McCormick on the mailing list 1998-04-04.
</Para>
</Note>
<Para>
To affect the paging behavior of your <Command>psql</Command> output,
set or unset your PAGER environment variable. I always have to set mine
before it will pause. And of course you have to do this before
starting the program.
</para>
<Para>
In csh/tcsh or other C shells:
<ProgramListing>
unsetenv PAGER
</ProgramListing>
while in sh/bash or other Bourne shells:
<ProgramListing>
unset PAGER
</ProgramListing>
</para>
</sect1>
</Chapter>
doc/src/sgml/query-ug.sgml deleted 100644 → 0
View file @ c3a4d8ed
<Chapter Id="query-ug">
<TITLE>The Query Language</TITLE>
<Para>
<Note>
<Para>
This chapter must go into depth on each area of the query language.
Currently a copy of the tutorial.
- thomas 1998-01-12
</Para>
</Note>
</Para>
<Para>
The <ProductName>Postgres</ProductName> query language is a variant of
<Acronym>SQL3</Acronym>. It
has many extensions such as an extensible type system,
inheritance, functions and production rules. Those are
features carried over from the original <ProductName>Postgres</ProductName>
query
language, <ProductName>PostQuel</ProductName>.
This section provides an overview
of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym>
to perform simple operations.
This manual is only intended to give you an idea of our
flavor of <Acronym>SQL</Acronym> and is in no way a complete tutorial on
<Acronym>SQL</Acronym>. Numerous books have been written on <Acronym>SQL</Acronym>. For
instance, consult <xref linkend="MELT93" endterm="MELT93-full"> or
<xref linkend="DATE97" endterm="DATE97-full">. You should also
be aware that some features of <ProductName>Postgres</ProductName>
are not part of the <Acronym>ANSI</Acronym> standard.
</Para>
<Sect1>
<Title>Concepts</Title>
<Para>
The fundamental notion in <ProductName>Postgres</ProductName>
is that of a class,
which is a named collection of object instances. Each
instance has the same collection of named attributes,
and each attribute is of a specific type. Furthermore,
each instance has a permanent <FirstTerm>object
identifier</FirstTerm> (<Acronym>OID</Acronym>)
that is unique throughout the installation. Because
<Acronym>SQL</Acronym> syntax refers to tables, we will use the terms
<FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably.
Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an
<FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym>
<FirstTerm>columns</FirstTerm>
are <FirstTerm>attributes</FirstTerm>.
As previously discussed, classes are grouped into
databases, and a collection of databases managed by a
single <FileName>postmaster</FileName> process constitutes an installation
or site.
</Para>
</sect1>
<Sect1>
<Title>Creating a New Class</Title>
<Para>
You can create a new class by specifying the class
name, along with all attribute names and their types:
<ProgramListing>
CREATE TABLE weather (
city varchar(80),
temp_lo int, -- low temperature
temp_hi int, -- high temperature
prcp real, -- precipitation
date date
);
</ProgramListing>
</para>
<Para>
Note that keywords are case-insensitive and identifiers
are usually case-insensitive.
<Acronym>Postgres</Acronym> allows <Acronym>SQL92</Acronym> <FirstTerm>delimited identifiers</FirstTerm>
(identifiers surrounded by double-quotes) to include mixed-case and spaces, tabs, etc.
</para>
<Para>
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual
<Acronym>SQL</Acronym> types <Type>int</Type>,
<Type>float</Type>, <Type>real</Type>, <Type>smallint</Type>, <Type>char(N)</Type>,
<Type>varchar(N)</Type>, <Type>date</Type>, <Type>time</Type>,
and <Type>timestamp</Type>, as well as other types of general utility and
a rich set of geometric types. As we will
see later, <ProductName>Postgres</ProductName> can be customized with an
arbitrary number of
user-defined data types. Consequently, type names are
not syntactical keywords, except where required to support special cases in the <Acronym>SQL92</Acronym> standard.
So far, the <ProductName>Postgres</ProductName> create command looks exactly like
the command used to create a table in a traditional
relational system. However, we will presently see that
classes have properties that are extensions of the
relational model.
</Para>
</sect1>
<Sect1>
<Title>Populating a Class with Instances</Title>
<Para>
The <Command>insert</Command> statement is used to populate a class with
instances:
<ProgramListing>
INSERT INTO weather
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
</ProgramListing>
</para>
<Para>
You can also use the <Command>copy</Command> command to perform load large
amounts of data from flat (<Acronym>ASCII</Acronym>) files.
This is usually faster because the data is read (or written) as a single atomic
transaction directly to or from the target table. An example would be:
<ProgramListing>
COPY INTO weather FROM '/home/user/weather.txt'
USING DELIMITERS '|';
</ProgramListing>
where the path name for the source file must be available to the backend server
machine, not just the client.
</para>
</sect1>
<Sect1>
<Title>Querying a Class</Title>
<Para>
The weather class can be queried with normal relational
selection and projection queries. A <Acronym>SQL</Acronym> <Command>select</Command>
statement is used to do this. The statement is divided into
a target list (the part that lists the attributes to be
returned) and a qualification (the part that specifies
any restrictions). For example, to retrieve all the
rows of weather, type:
<ProgramListing>
SELECT * FROM WEATHER;
</ProgramListing>
and the output should be:
<ProgramListing>
+--------------+---------+---------+------+------------+
|city | temp_lo | temp_hi | prcp | date |
+--------------+---------+---------+------+------------+
|San Francisco | 46 | 50 | 0.25 | 11-27-1994 |
+--------------+---------+---------+------+------------+
|San Francisco | 43 | 57 | 0 | 11-29-1994 |
+--------------+---------+---------+------+------------+
|Hayward | 37 | 54 | | 11-29-1994 |
+--------------+---------+---------+------+------------+
</ProgramListing>
You may specify any arbitrary expressions in the target list. For example, you can do:
<ProgramListing>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</ProgramListing>
</para>
<Para>
Arbitrary Boolean operators
(<Command>and</Command>, <Command>or</Command> and <Command>not</Command>) are
allowed in the qualification of any query. For example,
<ProgramListing>
SELECT * FROM weather
WHERE city = 'San Francisco'
AND prcp > 0.0;
+--------------+---------+---------+------+------------+
|city | temp_lo | temp_hi | prcp | date |
+--------------+---------+---------+------+------------+
|San Francisco | 46 | 50 | 0.25 | 11-27-1994 |
+--------------+---------+---------+------+------------+
</ProgramListing>
</Para>
<Para>
As a final note, you can specify that the results of a
select can be returned in a <FirstTerm>sorted order</FirstTerm>
or with <FirstTerm>duplicate instances</FirstTerm> removed.
<ProgramListing>
SELECT DISTINCT city
FROM weather
ORDER BY city;
</ProgramListing>
</Para>
</sect1>
<Sect1>
<Title>Redirecting SELECT Queries</Title>
<Para>
Any select query can be redirected to a new class
<ProgramListing>
SELECT * INTO TABLE temp FROM weather;
</ProgramListing>
</para>
<Para>
This forms an implicit <Command>create</Command> command, creating a new
class temp with the attribute names and types specified
in the target list of the <Command>select into</Command> command. We can
then, of course, perform any operations on the resulting
class that we can perform on other classes.
</Para>
</sect1>
<Sect1>
<Title>Joins Between Classes</Title>
<Para>
Thus far, our queries have only accessed one class at a
time. Queries can access multiple classes at once, or
access the same class in such a way that multiple
instances of the class are being processed at the same
time. A query that accesses multiple instances of the
same or different classes at one time is called a join
query.
As an example, say we wish to find all the records that
are in the temperature range of other records. In
effect, we need to compare the temp_lo and temp_hi
attributes of each EMP instance to the temp_lo and
temp_hi attributes of all other EMP instances.
<Note>
<Para>
This is only a conceptual model. The actual join may
be performed in a more efficient manner, but this is invisible to the user.
</Para>
</Note>
We can do this with the following query:
<ProgramListing>
SELECT W1.city, W1.temp_lo, W1.temp_hi,
W2.city, W2.temp_lo, W2.temp_hi
FROM weather W1, weather W2
WHERE W1.temp_lo < W2.temp_lo
AND W1.temp_hi > W2.temp_hi;
+--------------+---------+---------+---------------+---------+---------+
|city | temp_lo | temp_hi | city | temp_lo | temp_hi |
+--------------+---------+---------+---------------+---------+---------+
|San Francisco | 43 | 57 | San Francisco | 46 | 50 |
+--------------+---------+---------+---------------+---------+---------+
|San Francisco | 37 | 54 | San Francisco | 46 | 50 |
+--------------+---------+---------+---------------+---------+---------+
</ProgramListing>
<Note>
<Para>
The semantics of such a join are
that the qualification
is a truth expression defined for the Cartesian product of
the classes indicated in the query. For those instances in
the Cartesian product for which the qualification is true,
<ProductName>Postgres</ProductName> computes and returns the values specified in the
target list. <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> does not assign any meaning to
duplicate values in such expressions. This means that <ProductName>Postgres</ProductName>
sometimes recomputes the same target list several times;
this frequently happens when Boolean expressions are connected
with an "or". To remove such duplicates, you must use
the <Command>select distinct</Command> statement.
</Para>
</Note>
</para>
<Para>
In this case, both W1 and W2 are surrogates for an
instance of the class weather, and both range over all
instances of the class. (In the terminology of most
database systems, W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.)
A query can contain an arbitrary number of
class names and surrogates.
</Para>
</sect1>
<Sect1>
<Title>Updates</Title>
<Para>
You can update existing instances using the update command.
Suppose you discover the temperature readings are
all off by 2 degrees as of Nov 28, you may update the
data as follow:
<ProgramListing>
UPDATE weather
SET temp_hi = temp_hi - 2, temp_lo = temp_lo - 2
WHERE date > '11/28/1994';
</ProgramListing>
</Para>
</sect1>
<Sect1>
<Title>Deletions</Title>
<Para>
Deletions are performed using the <Command>delete</Command> command:
<ProgramListing>
DELETE FROM weather WHERE city = 'Hayward';
</ProgramListing>
All weather recording belongs to Hayward is removed.
One should be wary of queries of the form
<ProgramListing>
DELETE FROM classname;
</ProgramListing>
Without a qualification, <Command>delete</Command> will simply
remove all instances of the given class, leaving it
empty. The system will not request confirmation before
doing this.
</Para>
</sect1>
<Sect1>
<Title>Using Aggregate Functions</Title>
<Para>
Like most other query languages, <ProductName>PostgreSQL</ProductName> supports
aggregate functions.
The current implementation of <ProductName>Postgres</ProductName> aggregate functions have some limitations.
Specifically, while there are aggregates to compute
such functions as the <Function>count</Function>, <Function>sum</Function>,
<Function>avg</Function> (average), <Function>max</Function> (maximum) and
<Function>min</Function> (minimum) over a set of instances, aggregates can only
appear in the target list of a query and not directly in the
qualification (the <FirstTerm>where</FirstTerm> clause). As an example,
<ProgramListing>
SELECT max(temp_lo) FROM weather;
</ProgramListing>
is allowed, while
<ProgramListing>
SELECT city FROM weather WHERE temp_lo = max(temp_lo);
</ProgramListing>
is not. However, as is often the case the query can be restated to accomplish
the intended result; here by using a <FirstTerm>subselect</FirstTerm>:
<ProgramListing>
SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
</ProgramListing>
</Para>
<Para>
Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
<ProgramListing>
SELECT city, max(temp_lo)
FROM weather
GROUP BY city;
</ProgramListing>
</Para>
</sect1>
</Chapter>
doc/src/sgml/query.sgml
View file @ 32cfa65e
<Chapter ID="query">
<TITLE>The Query Language</TITLE>
<Para>
The <ProductName>Postgres</ProductName> query language is a variant of
the <Acronym>SQL3</Acronym> draft next-generation standard. It
has many extensions such as an extensible type system,
inheritance, functions and production rules. These are
features carried over from the original <ProductName>Postgres</ProductName> query
language, <ProductName>PostQuel</ProductName>. This section provides an overview
of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> to perform simple operations.
This manual is only intended to give you an idea of our
flavor of <Acronym>SQL</Acronym> and is in no way a complete tutorial on
<Acronym>SQL</Acronym>. Numerous books have been written on <Acronym>SQL</Acronym>, including
<Chapter ID="query">
<TITLE>The Query Language</TITLE>
<Para>
The <ProductName>Postgres</ProductName> query language is a variant of
the <Acronym>SQL3</Acronym> draft next-generation standard. It
has many extensions such as an extensible type system,
inheritance, functions and production rules. These are
features carried over from the original <ProductName>Postgres</ProductName> query
language, <ProductName>PostQuel</ProductName>. This section provides an overview
of how to use <ProductName>Postgres</ProductName>
<Acronym>SQL</Acronym> to perform simple operations.
This manual is only intended to give you an idea of our
flavor of <Acronym>SQL</Acronym> and is in no way a complete tutorial on
<Acronym>SQL</Acronym>. Numerous books have been written on
<Acronym>SQL</Acronym>, including
<!--
<XRef LinkEnd="MELT93"> and <XRef LinkEnd="DATE97">.
-->
[MELT93] and [DATE97].
You should be aware that some language features
are not part of the <Acronym>ANSI</Acronym> standard.
</Para>
<Sect1>
<Title>Interactive Monitor</Title>
<Para>
In the examples that follow, we assume that you have
created the mydb database as described in the previous
subsection and have started <Application>psql</Application>.
Examples in this manual can also be found in
<FileName>/usr/local/pgsql/src/tutorial/</FileName>. Refer to the
<FileName>README</FileName> file in that directory for how to use them. To
start the tutorial, do the following:
<ProgramListing>
You should be aware that some language features
are extensions to the <Acronym>ANSI</Acronym> standard.
</Para>
<Sect1>
<Title>Interactive Monitor</Title>
<Para>
In the examples that follow, we assume that you have
created the mydb database as described in the previous
subsection and have started <Application>psql</Application>.
Examples in this manual can also be found in
<FileName>/usr/local/pgsql/src/tutorial/</FileName>. Refer to the
<FileName>README</FileName> file in that directory for how to use them. To
start the tutorial, do the following:
<ProgramListing>
% cd /usr/local/pgsql/src/tutorial
% psql -s mydb
Welcome to the POSTGRESQL interactive sql monitor:
......@@ -44,54 +46,55 @@ Welcome to the POSTGRESQL interactive sql monitor:
You are currently connected to the database: postgres
mydb=> \i basics.sql
</ProgramListing>
</Para>
<Para>
The <Literal>\i</Literal> command read in queries from the specified
files. The <Literal>-s</Literal> option puts you in single step mode which
pauses before sending a query to the backend. Queries
in this section are in the file <FileName>basics.sql</FileName>.
</Para>
<Para>
<Application>psql</Application>
has a variety of <Literal>\d</Literal> commands for showing system information.
Consult these commands for more details;
for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt.
</Para>
</sect1>
<Sect1>
<Title>Concepts</Title>
<Para>
The fundamental notion in <ProductName>Postgres</ProductName> is that of a class,
which is a named collection of object instances. Each
instance has the same collection of named attributes,
and each attribute is of a specific type. Furthermore,
each instance has a permanent <FirstTerm>object identifier</FirstTerm> (<Acronym>OID</Acronym>)
that is unique throughout the installation. Because
<Acronym>SQL</Acronym> syntax refers to tables, we will use the terms
<FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably.
Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an
<FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> <FirstTerm>columns</FirstTerm>
are <FirstTerm>attributes</FirstTerm>.
As previously discussed, classes are grouped into
databases, and a collection of databases managed by a
single <Application>postmaster</Application> process constitutes an installation
or site.
</Para>
</sect1>
<Sect1>
<Title>Creating a New Class</Title>
<Para>
You can create a new class by specifying the class
name, along with all attribute names and their types:
<ProgramListing>
</ProgramListing>
</Para>
<Para>
The <Literal>\i</Literal> command read in queries from the specified
files. The <Literal>-s</Literal> option puts you in single step mode which
pauses before sending a query to the backend. Queries
in this section are in the file <FileName>basics.sql</FileName>.
</Para>
<Para>
<Application>psql</Application>
has a variety of <Literal>\d</Literal> commands for showing system information.
Consult these commands for more details;
for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt.
</Para>
</sect1>
<Sect1>
<Title>Concepts</Title>
<Para>
The fundamental notion in <ProductName>Postgres</ProductName> is that of a class,
which is a named collection of object instances. Each
instance has the same collection of named attributes,
and each attribute is of a specific type. Furthermore,
each instance has a permanent <FirstTerm>object identifier</FirstTerm>
(<Acronym>OID</Acronym>)
that is unique throughout the installation. Because
<Acronym>SQL</Acronym> syntax refers to tables, we will use the terms
<FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably.
Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an
<FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> <FirstTerm>columns</FirstTerm>
are <FirstTerm>attributes</FirstTerm>.
As previously discussed, classes are grouped into
databases, and a collection of databases managed by a
single <Application>postmaster</Application> process constitutes an installation
or site.
</Para>
</sect1>
<Sect1>
<Title>Creating a New Class</Title>
<Para>
You can create a new class by specifying the class
name, along with all attribute names and their types:
<ProgramListing>
CREATE TABLE weather (
city varchar(80),
temp_lo int, -- low temperature
......@@ -99,66 +102,82 @@ CREATE TABLE weather (
prcp real, -- precipitation
date date
);
</ProgramListing>
</para>
<Para>
Note that both keywords and identifiers are case-insensitive; identifiers can become
case-sensitive by surrounding them with double-quotes as allowed by <Acronym>SQL92</Acronym>.
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual
<Acronym>SQL</Acronym> types <Type>int</Type>,
<Type>float</Type>, <Type>real</Type>, <Type>smallint</Type>, <Type>char(N)</Type>,
<Type>varchar(N)</Type>, <Type>date</Type>, <Type>time</Type>,
and <Type>timestamp</Type>, as well as other types of general utility and
a rich set of geometric types. As we will
see later, <ProductName>Postgres</ProductName> can be customized with an
arbitrary number of
user-defined data types. Consequently, type names are
not syntactical keywords, except where required to support special cases in the <Acronym>SQL92</Acronym> standard.
So far, the <ProductName>Postgres</ProductName> create command looks exactly like
the command used to create a table in a traditional
relational system. However, we will presently see that
classes have properties that are extensions of the
relational model.
</Para>
</sect1>
<Sect1>
<Title>Populating a Class with Instances</Title>
<Para>
The <Command>insert</Command> statement is used to populate a class with
instances:
<ProgramListing>
</ProgramListing>
</para>
<Para>
Note that both keywords and identifiers are case-insensitive; identifiers can become
case-sensitive by surrounding them with double-quotes as allowed
by <Acronym>SQL92</Acronym>.
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual
<Acronym>SQL</Acronym> types <Type>int</Type>,
<Type>float</Type>, <Type>real</Type>, <Type>smallint</Type>, <Type>char(N)</Type>,
<Type>varchar(N)</Type>, <Type>date</Type>, <Type>time</Type>,
and <Type>timestamp</Type>, as well as other types of general utility and
a rich set of geometric types. As we will
see later, <ProductName>Postgres</ProductName> can be customized with an
arbitrary number of
user-defined data types. Consequently, type names are
not syntactical keywords, except where required to support special
cases in the <Acronym>SQL92</Acronym> standard.
So far, the <ProductName>Postgres</ProductName> create command
looks exactly like
the command used to create a table in a traditional
relational system. However, we will presently see that
classes have properties that are extensions of the
relational model.
</Para>
</sect1>
<Sect1>
<Title>Populating a Class with Instances</Title>
<Para>
The <Command>insert</Command> statement is used to populate a class with
instances:
<ProgramListing>
INSERT INTO weather
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
</ProgramListing>
</Para>
<Para>
You can also use the <Command>copy</Command> command to perform load large
amounts of data from flat (<Acronym>ASCII</Acronym>) files.
</Para>
</sect1>
<Sect1>
<Title>Querying a Class</Title>
<Para>
The weather class can be queried with normal relational
selection and projection queries. A <Acronym>SQL</Acronym> <Command>select</Command>
statement is used to do this. The statement is divided into
a target list (the part that lists the attributes to be
returned) and a qualification (the part that specifies
any restrictions). For example, to retrieve all the
rows of weather, type:
<ProgramListing>
</ProgramListing>
</Para>
<Para>
You can also use the <Command>copy</Command> command to perform load large
amounts of data from flat (<Acronym>ASCII</Acronym>) files.
This is usually faster because the data is read (or written) as a single atomic
transaction directly to or from the target table. An example would be:
<ProgramListing>
COPY INTO weather FROM '/home/user/weather.txt'
USING DELIMITERS '|';
</ProgramListing>
where the path name for the source file must be available to the backend server
machine, not the client, since the backend server reads the file directly.
</para>
</sect1>
</Para>
</sect1>
<Sect1>
<Title>Querying a Class</Title>
<Para>
The weather class can be queried with normal relational
selection and projection queries. A <Acronym>SQL</Acronym> <Command>select</Command>
statement is used to do this. The statement is divided into
a target list (the part that lists the attributes to be
returned) and a qualification (the part that specifies
any restrictions). For example, to retrieve all the
rows of weather, type:
<ProgramListing>
SELECT * FROM WEATHER;
</ProgramListing>
</ProgramListing>
and the output should be:
<ProgramListing>
and the output should be:
<ProgramListing>
+--------------+---------+---------+------+------------+
|city | temp_lo | temp_hi | prcp | date |
+--------------+---------+---------+------+------------+
......@@ -168,89 +187,91 @@ SELECT * FROM WEATHER;
+--------------+---------+---------+------+------------+
|Hayward | 37 | 54 | | 11-29-1994 |
+--------------+---------+---------+------+------------+
</ProgramListing>
You may specify any arbitrary expressions in the target list. For example, you can do:
<ProgramListing>
</ProgramListing>
You may specify any arbitrary expressions in the target list. For example, you can do:
<ProgramListing>
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
</ProgramListing>
</Para>
</ProgramListing>
</Para>
<Para>
Arbitrary Boolean operators
(<Command>and</Command>, <Command>or</Command> and <Command>not</Command>) are
allowed in the qualification of any query. For example,
<Para>
Arbitrary Boolean operators
(<Command>and</Command>, <Command>or</Command> and <Command>not</Command>) are
allowed in the qualification of any query. For example,
<ProgramListing>
<ProgramListing>
SELECT * FROM weather
WHERE city = 'San Francisco'
AND prcp > 0.0;
</programlisting>
results in:
<programlisting>
+--------------+---------+---------+------+------------+
|city | temp_lo | temp_hi | prcp | date |
+--------------+---------+---------+------+------------+
|San Francisco | 46 | 50 | 0.25 | 11-27-1994 |
+--------------+---------+---------+------+------------+
</ProgramListing>
</Para>
</ProgramListing>
</Para>
<Para>
As a final note, you can specify that the results of a
select can be returned in a <FirstTerm>sorted order</FirstTerm>
or with <FirstTerm>duplicate instances</FirstTerm> removed.
<Para>
As a final note, you can specify that the results of a
select can be returned in a <FirstTerm>sorted order</FirstTerm>
or with <FirstTerm>duplicate instances</FirstTerm> removed.
<ProgramListing>
<ProgramListing>
SELECT DISTINCT city
FROM weather
ORDER BY city;
</ProgramListing>
</Para>
</sect1>
</ProgramListing>
</Para>
</sect1>
<Sect1>
<Title>Redirecting SELECT Queries</Title>
<Sect1>
<Title>Redirecting SELECT Queries</Title>
<Para>
Any select query can be redirected to a new class
<ProgramListing>
<Para>
Any select query can be redirected to a new class
<ProgramListing>
SELECT * INTO TABLE temp FROM weather;
</ProgramListing>
</Para>
<Para>
This forms an implicit <Command>create</Command> command, creating a new
class temp with the attribute names and types specified
in the target list of the <Command>select into</Command> command. We can
then, of course, perform any operations on the resulting
class that we can perform on other classes.
</Para>
</sect1>
<Sect1>
<Title>Joins Between Classes</Title>
<Para>
Thus far, our queries have only accessed one class at a
time. Queries can access multiple classes at once, or
access the same class in such a way that multiple
instances of the class are being processed at the same
time. A query that accesses multiple instances of the
same or different classes at one time is called a join
query.
As an example, say we wish to find all the records that
are in the temperature range of other records. In
effect, we need to compare the temp_lo and temp_hi
attributes of each EMP instance to the temp_lo and
temp_hi attributes of all other EMP instances.
<Note>
<Para>
This is only a conceptual model. The actual join may
be performed in a more efficient manner, but this is invisible to the user.
</Para>
</Note>
We can do this with the following query:
<ProgramListing>
</ProgramListing>
</Para>
<Para>
This forms an implicit <Command>create</Command> command, creating a new
class temp with the attribute names and types specified
in the target list of the <Command>select into</Command> command. We can
then, of course, perform any operations on the resulting
class that we can perform on other classes.
</Para>
</sect1>
<Sect1>
<Title>Joins Between Classes</Title>
<Para>
Thus far, our queries have only accessed one class at a
time. Queries can access multiple classes at once, or
access the same class in such a way that multiple
instances of the class are being processed at the same
time. A query that accesses multiple instances of the
same or different classes at one time is called a join
query.
As an example, say we wish to find all the records that
are in the temperature range of other records. In
effect, we need to compare the temp_lo and temp_hi
attributes of each EMP instance to the temp_lo and
temp_hi attributes of all other EMP instances.
<Note>
<Para>
This is only a conceptual model. The actual join may
be performed in a more efficient manner, but this is invisible to the user.
</Para>
</Note>
We can do this with the following query:
<ProgramListing>
SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
W2.city, W2.temp_lo AS low, W2.temp_hi AS high
FROM weather W1, weather W2
......@@ -264,113 +285,135 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
+--------------+-----+------+---------------+-----+------+
|San Francisco | 37 | 54 | San Francisco | 46 | 50 |
+--------------+-----+------+---------------+-----+------+
</ProgramListing>
<Note>
<Para>
The semantics of such a join are
that the qualification
is a truth expression defined for the Cartesian product of
the classes indicated in the query. For those instances in
the Cartesian product for which the qualification is true,
<ProductName>Postgres</ProductName> computes and returns the values specified in the
target list. <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> does not assign any meaning to
duplicate values in such expressions. This means that <ProductName>Postgres</ProductName>
sometimes recomputes the same target list several times;
this frequently happens when Boolean expressions are connected
with an "or". To remove such duplicates, you must use
the <Command>select distinct</Command> statement.
</Para>
</Note>
</para>
<Para>
In this case, both W1 and W2 are surrogates for an
instance of the class weather, and both range over all
instances of the class. (In the terminology of most
database systems, W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.)
A query can contain an arbitrary number of
class names and surrogates.
</Para>
</sect1>
<Sect1>
<Title>Updates</Title>
<Para>
You can update existing instances using the update command.
Suppose you discover the temperature readings are
all off by 2 degrees as of Nov 28, you may update the
data as follow:
<ProgramListing>
</ProgramListing>
<Note>
<Para>
The semantics of such a join are
that the qualification
is a truth expression defined for the Cartesian product of
the classes indicated in the query. For those instances in
the Cartesian product for which the qualification is true,
<ProductName>Postgres</ProductName> computes and returns the
values specified in the target list.
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym>
does not assign any meaning to
duplicate values in such expressions.
This means that <ProductName>Postgres</ProductName>
sometimes recomputes the same target list several times;
this frequently happens when Boolean expressions are connected
with an "or". To remove such duplicates, you must use
the <Command>select distinct</Command> statement.
</Para>
</Note>
</para>
<Para>
In this case, both W1 and W2 are surrogates for an
instance of the class weather, and both range over all
instances of the class. (In the terminology of most
database systems, W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.)
A query can contain an arbitrary number of
class names and surrogates.
</Para>
</sect1>
<Sect1>
<Title>Updates</Title>
<Para>
You can update existing instances using the update command.
Suppose you discover the temperature readings are
all off by 2 degrees as of Nov 28, you may update the
data as follow:
<ProgramListing>
UPDATE weather
SET temp_hi = temp_hi - 2, temp_lo = temp_lo - 2
WHERE date > '11/28/1994';
</ProgramListing>
</Para>
</sect1>
</ProgramListing>
</Para>
</sect1>
<Sect1>
<Title>Deletions</Title>
<Sect1>
<Title>Deletions</Title>
<Para>
Deletions are performed using the <Command>delete</Command> command:
<ProgramListing>
<Para>
Deletions are performed using the <Command>delete</Command> command:
<ProgramListing>
DELETE FROM weather WHERE city = 'Hayward';
</ProgramListing>
</ProgramListing>
All weather recording belongs to Hayward is removed.
One should be wary of queries of the form
<ProgramListing>
All weather recording belongs to Hayward is removed.
One should be wary of queries of the form
<ProgramListing>
DELETE FROM classname;
</ProgramListing>
Without a qualification, <Command>delete</Command> will simply
remove all instances of the given class, leaving it
empty. The system will not request confirmation before
doing this.
</Para>
</sect1>
<Sect1>
<Title>Using Aggregate Functions</Title>
<Para>
Like most other query languages, <ProductName>PostgreSQL</ProductName> supports
aggregate functions.
The current implementation of <ProductName>Postgres</ProductName> aggregate functions have some limitations.
Specifically, while there are aggregates to compute
such functions as the <Function>count</Function>, <Function>sum</Function>,
<Function>avg</Function> (average), <Function>max</Function> (maximum) and
<Function>min</Function> (minimum) over a set of instances, aggregates can only
appear in the target list of a query and not directly in the
qualification (the where clause). As an example,
<ProgramListing>
</ProgramListing>
Without a qualification, <Command>delete</Command> will simply
remove all instances of the given class, leaving it
empty. The system will not request confirmation before
doing this.
</Para>
</sect1>
<Sect1>
<Title>Using Aggregate Functions</Title>
<Para>
Like most other query languages,
<ProductName>PostgreSQL</ProductName> supports
aggregate functions.
The current implementation of
<ProductName>Postgres</ProductName> aggregate functions have some limitations.
Specifically, while there are aggregates to compute
such functions as the <Function>count</Function>, <Function>sum</Function>,
<Function>avg</Function> (average), <Function>max</Function> (maximum) and
<Function>min</Function> (minimum) over a set of instances, aggregates can only
appear in the target list of a query and not directly in the
qualification (the where clause). As an example,
<ProgramListing>
SELECT max(temp_lo) FROM weather;
</ProgramListing>
</ProgramListing>
is allowed, while
is allowed, while
<ProgramListing>
<ProgramListing>
SELECT city FROM weather WHERE temp_lo = max(temp_lo);
</ProgramListing>
</ProgramListing>
is not. However, as is often the case the query can be restated to accomplish
the intended result; here by using a <FirstTerm>subselect</FirstTerm>:
<ProgramListing>
is not. However, as is often the case the query can be restated to accomplish
the intended result; here by using a <FirstTerm>subselect</FirstTerm>:
<ProgramListing>
SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
</ProgramListing>
</Para>
</ProgramListing>
</Para>
<Para>
Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
<ProgramListing>
<Para>
Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
<ProgramListing>
SELECT city, max(temp_lo)
FROM weather
GROUP BY city;
</ProgramListing>
</Para>
</sect1>
</Chapter>
</ProgramListing>
</Para>
</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/runtime.sgml
View file @ 32cfa65e
<Chapter Id="runtime">
<Title>Runtime Environment</Title>
<Para>
This chapter outlines the interaction between <Productname>Postgres</Productname> and
the operating system.
</para>
<sect1>
<title>Using <Productname>Postgres</Productname> from Unix</title>
<para>
All <Productname>Postgres</Productname> commands that are executed
directly from a Unix shell are
found in the directory <quote>.../bin</quote>. Including this directory in
your search path will make executing the commands easier.
</para>
<para>
A collection of system catalogs exist at each site. These include a
class (<literal>pg_user</literal>) that contains an instance for each valid
<Productname>Postgres</Productname> user. The instance specifies a set of
<Productname>Postgres</Productname> privileges, such as
the ability to act as <Productname>Postgres</Productname> super-user,
the ability to create/destroy
databases, and the ability to update the system catalogs. A Unix
user cannot do anything with <Productname>Postgres</Productname>
until an appropriate instance is
installed in this class. Further information on the system catalogs
is available by running queries on the appropriate classes.
</para>
</sect1>
</chapter>
<chapter id="layout">
<Title>System Layout</Title>
<Para>
<Figure Id="ADMIN-LAYOUT">
<Title><ProductName>Postgres</ProductName> file layout</Title>
<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic>
</Figure>
<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT">
shows how the <ProductName>Postgres</ProductName> distribution is laid
out when installed in the default way. For simplicity,
we will assume that <ProductName>Postgres</ProductName>
has been installed in the
directory <filename>/usr/local/pgsql</filename>. Therefore, wherever
you see the directory <filename>/usr/local/pgsql</filename> you should
substitute the name of the directory where
<ProductName>Postgres</ProductName> is
actually installed.
All <ProductName>Postgres</ProductName> commands are installed
in the directory
<filename>/usr/local/pgsql/bin</filename>. Therefore, you should add
this directory to your shell command path. If you use
a variant of the Berkeley C shell, such as csh or tcsh,
you would add
<ProgramListing>
set path = ( /usr/local/pgsql/bin path )
</ProgramListing>
in the .login file in your home directory. If you use
a variant of the Bourne shell, such as sh, ksh, or
bash, then you would add
<ProgramListing>
PATH=/usr/local/pgsql/bin:$PATH
export PATH
</ProgramListing>
to the .profile file in your home directory.
From now on, we will assume that you have added the
<ProductName>Postgres</ProductName> bin directory to your path.
In addition, we
will make frequent reference to "setting a shell
variable" or "setting an environment variable" throughout
this document. If you did not fully understand the
last paragraph on modifying your search path, you
should consult the UNIX manual pages that describe your
shell before going any further.
</Para>
<Para>
If you have not set things up in the
default way, you may have some more work to do.
For example, if the database server machine is a remote machine, you
will need to set the <envar>PGHOST</envar> environment variable to the name
of the database server machine. The environment variable
<envar>PGPORT</envar> may also have to be set. The bottom line is this: if
you try to start an application program and it complains
that it cannot connect to the <Application>postmaster</Application>,
you must go back and make sure that your
environment is properly set up.
</Para>
<Chapter Id="runtime">
<Title>Runtime Environment</Title>
<Para>
This chapter outlines the interaction between <Productname>Postgres</Productname> and
the operating system.
</para>
<sect1>
<title>Using <Productname>Postgres</Productname> from Unix</title>
<para>
All <Productname>Postgres</Productname> commands that are executed
directly from a Unix shell are
found in the directory <quote>.../bin</quote>. Including this directory in
your search path will make executing the commands easier.
</para>
<para>
A collection of system catalogs exist at each site. These include a
class (<literal>pg_user</literal>) that contains an instance for each valid
<Productname>Postgres</Productname> user. The instance specifies a set of
<Productname>Postgres</Productname> privileges, such as
the ability to act as <Productname>Postgres</Productname> super-user,
the ability to create/destroy
databases, and the ability to update the system catalogs. A Unix
user cannot do anything with <Productname>Postgres</Productname>
until an appropriate instance is
installed in this class. Further information on the system catalogs
is available by running queries on the appropriate classes.
</para>
</sect1>
<sect1 Id="postmaster">
<Title>Starting <Application>postmaster</Application></Title>
<Para>
Nothing can happen to a database unless the
<Application>postmaster</Application>
process is running. As the site administrator, there
are a number of things you should remember before
starting the <Application>postmaster</Application>.
These are discussed in the installation and configuration sections
of this manual.
However, if <ProductName>Postgres</ProductName> has been installed by following
the installation instructions exactly as written, the
following simple command is all you should
need to start the <Application>postmaster</Application>:
<ProgramListing>
% postmaster
</ProgramListing>
</para>
<para>
The <Application>postmaster</Application> occasionally prints out
messages which
are often helpful during troubleshooting. If you wish
to view debugging messages from the <Application>postmaster</Application>,
you can
start it with the -d option and redirect the output to
the log file:
<ProgramListing>
% postmaster -d >& pm.log &
</ProgramListing>
If you do not wish to see these messages, you can type
<ProgramListing>
% postmaster -S
</ProgramListing>
and the <Application>postmaster</Application> will be "S"ilent.
Notice that there
is no ampersand ("&amp") at the end of the last example so
postmaster will be running in the foreground.
</Para>
</sect1>
<sect1 Id="pg-options">
<Title id="pg-options-title">Using pg_options</Title>
<Para>
<Note>
<Para>
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
</Para>
</Note>
</para>
<Para>
The optional file <filename>data/pg_options</filename> contains runtime
options used by the backend to control trace messages and other backend
tunable parameters.
The file is re-read by a backend
when it receives a SIGHUP signal, making thus possible to change run-time
options on the fly without needing to restart
<productname>Postgres</productname>.
The options specified in this file may be debugging flags used by the trace
package (<filename>backend/utils/misc/trace.c</filename>) or numeric
parameters which can be used by the backend to control its behaviour.
</para>
<para>
All pg_options are initialized to zero at backend startup.
New or modified options will be read by all new backends when they are started.
To make effective any changes for all running backends we need to send a
SIGHUP to the postmaster. The signal will be automatically sent to all the
backends. We can also activate the changes only for a specific backend by
sending the SIGHUP directly to it.
</para>
<para>
pg_options can also be specified with the <option>-T</option> switch of
<productname>Postgres</productname>:
<programlisting>
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
</programlisting>
</para>
<Para>
The functions used for printing errors and debug messages can now make use
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
or stderr are prefixed by a timestamp containing also the backend pid:
<programlisting>
#timestamp #pid #message
980127.17:52:14.173 [29271] StartTransactionCommand
980127.17:52:14.174 [29271] ProcessUtility: drop table t;
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
980127.17:52:14.186 [29286] Async_NotifyHandler
980127.17:52:14.186 [29286] Waking up sleeping backend process
980127.19:52:14.292 [29286] Async_NotifyFrontEnd
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
980127.19:52:14.466 [29286] Async_NotifyHandler done
</programlisting>
</para>
<para>
This format improves readability of the logs and allows people to understand
exactly which backend is doing what and at which time. It also makes
easier to write simple awk or perl scripts which monitor the log to
detect database errors or problem, or to compute transaction time statistics.
</para>
<para>
Messages printed to syslog use the log facility LOG_LOCAL0.
The use of syslog can be controlled with the syslog pg_option.
Unfortunately many functions call directly <function>printf()</function>
to print their messages to stdout or stderr and this output can't be
redirected to syslog or have timestamps in it.
It would be advisable that all calls to printf would be replaced with the
PRINTF macro and output to stderr be changed to use EPRINTF instead so that
we can control all output in a uniform way.
</Para>
<para>
The format of the <filename>pg_options</filename> file is as follows:
<programlisting>
# <replaceable>comment</replaceable>
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable>
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0
</programlisting>
Note that <replaceable class="parameter">keyword</replaceable> can also be
an abbreviation of the option name defined in
<filename>backend/utils/misc/trace.c</filename>.
<example>
<title>pg_options File</title>
<para>
For example my pg_options file contains the following values:
<programlisting>
verbose=2
query
hostlookup
showportnumber
</programlisting>
</para>
</example>
</para>
<sect2>
<title>Recognized Options</title>
<Para>
The options currently defined are:
<variablelist>
<varlistentry>
<term>
all
</term>
<listitem>
<para>
Global trace flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
Trace messages enabled individually
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Enable all trace messages
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-1
</term>
<listitem>
<para>
Disable all trace messages
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
verbose
</term>
<listitem>
<para>
Verbosity flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
No messages. This is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Print information messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
2
</term>
<listitem>
<para>
Print more information messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
query
</term>
<listitem>
<para>
Query trace flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
Don't print query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Print a condensed query in one line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
4
</term>
<listitem>
<para>
Print the full query.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
plan
</term>
<listitem>
<para>
Print query plan.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
parse
</term>
<listitem>
<para>
Print parser output.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
rewritten
</term>
<listitem>
<para>
Print rewritten query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
parserstats
</term>
<listitem>
<para>
Print parser statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
plannerstats
</term>
<listitem>
<para>
Print planner statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
executorstats
</term>
<listitem>
<para>
Print executor statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
shortlocks
</term>
<listitem>
<para>
Currently unused but needed to enable features in the future.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
locks
</term>
<listitem>
<para>
Trace locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
userlocks
</term>
<listitem>
<para>
Trace user locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
spinlocks
</term>
<listitem>
<para>
Trace spin locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
notify
</term>
<listitem>
<para>
Trace notify functions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
malloc
</term>
<listitem>
<para>
Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
palloc
</term>
<listitem>
<para>
Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
lock_debug_oidmin
</term>
<listitem>
<para>
Minimum relation oid traced by locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
lock_debug_relid
</term>
<listitem>
<para>
oid, if not zero, of relation traced by locks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
lock_read_priority
</term>
<listitem>
<para>
Currently unused.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
deadlock_timeout
</term>
<listitem>
<para>
Deadlock check timer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
syslog
</term>
<listitem>
<para>
syslog flag. Allowed values are:
</para>
<variablelist>
<varlistentry>
<term>
0
</term>
<listitem>
<para>
Messages to stdout/stderr.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
1
</term>
<listitem>
<para>
Messages to stdout/stderr and syslog.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
2
</term>
<listitem>
<para>
Messages only to syslog.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
hostlookup
</term>
<listitem>
<para>
Enable hostname lookup in ps_status.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
showportnumber
</term>
<listitem>
<para>
Show port number in ps_status.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
notifyunlock
</term>
<listitem>
<para>
Unlock of pg_listener after notify.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
notifyhack
</term>
<listitem>
<para>
Remove duplicate tuples from pg_listener.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/security.sgml
View file @ 32cfa65e
......@@ -183,6 +183,9 @@
two exceptions: manual system catalog updates are not permitted if the
user does not have <literal>pg_user.usecatupd</literal> set, and destruction of
system catalogs (or modification of their schemas) is never allowed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
......
doc/src/sgml/sql.sgml
View file @ 32cfa65e
......@@ -288,7 +288,7 @@ attributes are taken from. We often write a relation scheme as
<parameter>D<subscript>i</subscript></parameter>,
for each attribute
<parameter>A<subscript>i</subscript></parameter>,
1 &le; <literal>i</literal> &le; <literal>k</literal>,
1 &lt;&equal; <literal>i</literal> &lt;&equal; <literal>k</literal>,
where the values of the attributes are taken from. We often write
a relation scheme as
<literal>R(<parameter>A<subscript>1</subscript></parameter>,
......@@ -325,10 +325,12 @@ attributes are taken from. We often write a relation scheme as
integers. We define this by assigning a data type to each
attribute. The type of <classname>SNAME</classname> will be
<type>VARCHAR(20)</type> (this is the <acronym>SQL</acronym> type
for character strings of length &le; 20), the type of <classname>SNO</classname> will be
for character strings of length &lt;&equal; 20),
the type of <classname>SNO</classname> will be
<type>INTEGER</type>. With the assignment of a data type we also have selected
a domain for an attribute. The domain of <classname>SNAME</classname> is the set of all
character strings of length &le; 20, the domain of <classname>SNO</classname> is the set of
character strings of length &lt;&equal; 20,
the domain of <classname>SNO</classname> is the set of
all integer numbers.
</para>
</sect2>
......@@ -339,7 +341,7 @@ attributes are taken from. We often write a relation scheme as
Model</title>
<para>
In section <xref linkend="formal-notion" endterm="formal-notion">
In <xref linkend="formal-notion" endterm="formal-notion">
we defined the mathematical notion of
the relational model. Now we know how the data can be stored using a
relational data model but we do not know what to do with all these
......@@ -481,19 +483,23 @@ attributes are taken from. We often write a relation scheme as
projecting out the duplicate column.
</para>
<para id="join-example">
Let's have a look at the tables that are produced by evaluating the steps
necessary for a join.
Let the following two tables be given:
<example id="join-example">
<title>An Inner Join</title>
<programlisting>
<para>
Let's have a look at the tables that are produced by evaluating the steps
necessary for a join.
Let the following two tables be given:
<programlisting>
R A | B | C S C | D | E
---+---+--- ---+---+---
1 | 2 | 3 3 | a | b
4 | 5 | 6 6 | c | d
7 | 8 | 9
</programlisting>
</para>
</programlisting>
</para>
</example>
<para>
First we calculate the Cartesian product
......
doc/src/sgml/start-ag.sgml
View file @ 32cfa65e
......@@ -4,251 +4,194 @@
- - thomas 1998-02-24
-->
<Chapter Id="postmaster">
<Title>Starting <Application>postmaster</Application></Title>
<Para>
Nothing can happen to a database unless the
<Application>postmaster</Application>
process is running. As the site administrator, there
are a number of things you should remember before
starting the <Application>postmaster</Application>.
These are discussed in the installation and configuration sections
of this manual.
However, if <ProductName>Postgres</ProductName> has been installed by following
the installation instructions exactly as written, the
following simple command is all you should
need to start the <Application>postmaster</Application>:
<ProgramListing>
% postmaster
</ProgramListing>
The <Application>postmaster</Application> occasionally prints out
messages which
are often helpful during troubleshooting. If you wish
to view debugging messages from the <Application>postmaster</Application>,
you can
start it with the -d option and redirect the output to
the log file:
<ProgramListing>
% postmaster -d >& pm.log &
</ProgramListing>
If you do not wish to see these messages, you can type
<ProgramListing>
% postmaster -S
</ProgramListing>
and the <Application>postmaster</Application> will be "S"ilent.
Notice that there
is no ampersand ("&amp") at the end of the last example.
</Para>
</Chapter>
<Chapter Id="newuser">
<Title>Adding and Deleting Users</Title>
<Para>
<Application>createuser</Application> enables specific users to access
<ProductName>Postgres</ProductName>.
<Application>destroyuser</Application> removes users and
prevents them from accessing <ProductName>Postgres</ProductName>.
Note that these
commands only affect users with respect to
<ProductName>Postgres</ProductName>;
they have no effect on users other privileges or status with regards
to the underlying
operating system.
</Para>
</Chapter>
<Chapter Id="disk">
<Title>Disk Management</Title>
<Para>
</Para>
<Sect1>
<Title>Alternate Locations</Title>
<Para>
It is possible to create a database in a location other than the default
location for the installation. Remember that all database access actually
occurs through the database backend, so that any location specified must
be accessible by the backend.
</para>
<Para>
Alternate database locations are created and referenced by an environment variable
which gives the absolute path to the intended storage location.
This environment variable must have been defined before the backend was started
and must be writable by the postgres administrator account.
Any valid environment variable name may be used to reference an alternate
location, although using variable name with a prefix of PGDATA is recommended
to avoid confusion and conflict with other variables.
</para>
<Note>
<Para>
In previous versions of <ProductName>Postgres</ProductName>,
it was also permissable to use an absolute path name to specify an alternate storage location.
The environment variable style of specification
is to be preferred since it allows the site administrator more flexibility in
managing disk storage.
If you prefer using absolute paths, you may do so by defining
"ALLOW_ABSOLUTE_DBPATHS" and recompiling <ProductName>Postgres</ProductName>
To do this, either add this line
<ProgramListing>
<Chapter Id="newuser">
<Title>Adding and Deleting Users</Title>
<Para>
<Application>createuser</Application> enables specific users to access
<ProductName>Postgres</ProductName>.
<Application>destroyuser</Application> removes users and
prevents them from accessing <ProductName>Postgres</ProductName>.
Note that these
commands only affect users with respect to
<ProductName>Postgres</ProductName>;
they have no effect on users other privileges or status with regards
to the underlying
operating system.
</Para>
</Chapter>
<Chapter Id="disk">
<Title>Disk Management</Title>
<Sect1>
<Title>Alternate Locations</Title>
<Para>
It is possible to create a database in a location other than the default
location for the installation. Remember that all database access actually
occurs through the database backend, so that any location specified must
be accessible by the backend.
</para>
<Para>
Alternate database locations are created and referenced by an environment variable
which gives the absolute path to the intended storage location.
This environment variable must have been defined before the backend was started
and must be writable by the postgres administrator account.
Any valid environment variable name may be used to reference an alternate
location, although using variable name with a prefix of PGDATA is recommended
to avoid confusion and conflict with other variables.
</para>
<Note>
<Para>
In previous versions of <ProductName>Postgres</ProductName>,
it was also permissable to use an absolute path name
to specify an alternate storage location.
The environment variable style of specification
is to be preferred since it allows the site administrator more flexibility in
managing disk storage.
If you prefer using absolute paths, you may do so by defining
"ALLOW_ABSOLUTE_DBPATHS" and recompiling <ProductName>Postgres</ProductName>
To do this, either add this line
<ProgramListing>
#define ALLOW_ABSOLUTE_DBPATHS 1
</ProgramListing>
to the file <filename>src/include/config.h</filename>, or by specifying
<ProgramListing>
</ProgramListing>
to the file <filename>src/include/config.h</filename>, or by specifying
<ProgramListing>
CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS
</ProgramListing>
in your <filename>Makefile.custom</filename>.
</Para>
</Note>
<Para>
Remember that database creation is actually performed by the database backend.
Therefore, any environment variable specifying an alternate location must have
been defined before the backend was started. To define an alternate location
PGDATA2 pointing to <filename>/home/postgres/data</filename>, first type
<ProgramListing>
</ProgramListing>
in your <filename>Makefile.custom</filename>.
</Para>
</Note>
<Para>
Remember that database creation is actually performed by the database backend.
Therefore, any environment variable specifying an alternate location must have
been defined before the backend was started. To define an alternate location
PGDATA2 pointing to <filename>/home/postgres/data</filename>, first type
<ProgramListing>
% setenv PGDATA2 /home/postgres/data
</ProgramListing>
to define the environment variable to be used with subsequent commands.
Usually, you will want to define this variable in the
<ProductName>Postgres</ProductName> superuser's
<filename>.profile</filename>
or
<filename>.cshrc</filename>
initialization file to ensure that it is defined upon system startup.
Any environment variable can be used to reference alternate location,
although it is preferred that the variables be prefixed with "PGDATA"
to eliminate confusion and the possibility of conflicting with or
overwriting other variables.
</para>
<Para>
To create a data storage area in PGDATA2, ensure
that <filename>/home/postgres</filename> already exists and is writable
by the postgres administrator.
Then from the command line, type
<ProgramListing>
</ProgramListing>
to define the environment variable to be used with subsequent commands.
Usually, you will want to define this variable in the
<ProductName>Postgres</ProductName> superuser's
<filename>.profile</filename>
or
<filename>.cshrc</filename>
initialization file to ensure that it is defined upon system startup.
Any environment variable can be used to reference alternate location,
although it is preferred that the variables be prefixed with "PGDATA"
to eliminate confusion and the possibility of conflicting with or
overwriting other variables.
</para>
<Para>
To create a data storage area in PGDATA2, ensure
that <filename>/home/postgres</filename> already exists and is writable
by the postgres administrator.
Then from the command line, type
<ProgramListing>
% setenv PGDATA2 /home/postgres/data
% initlocation $PGDATA2
Creating Postgres database system directory /home/postgres/data
Creating Postgres database system directory /home/postgres/data/base
</ProgramListing>
</para>
<Para>
To test the new location, create a database <Database>test</Database> by typing
<ProgramListing>
</ProgramListing>
</para>
<Para>
To test the new location, create a database <Database>test</Database> by typing
<ProgramListing>
% createdb -D PGDATA2 test
% destroydb test
</ProgramListing>
</para>
</Sect1>
</Chapter>
<Chapter Id="trouble">
<Title>Troubleshooting</Title>
<Para>
Assuming that your site administrator has properly
started the <Application>postmaster</Application> process
and authorized you to use the database, you (as a user) may begin to start up
applications. As previously mentioned, you should add
<filename>/usr/local/pgsql/bin</filename> to your shell search path.
In most cases, this is all you should have to do in
terms of preparation.
</para>
<Para>
If you get the following error message from a
<ProductName>Postgres</ProductName>
command (such as <Application>psql</Application> or
<Application>createdb</Application>):
<ProgramListing>
connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
</ProgramListing>
it is usually because either the <Application>postmaster</Application> is not running,
or you are attempting to connect to the wrong server host.
If you get the following error message:
<ProgramListing>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
</ProgramListing>
it means that the site administrator started the <Application>postmaster</Application>
as the wrong user. Tell him to restart it as
the <ProductName>Postgres</ProductName> superuser.
</Para>
</Chapter>
<Chapter Id="manage-ag">
<Title>Managing a Database</Title>
<Para>
Now that <ProductName>Postgres</ProductName> is up and running we can create
some databases to experiment with. Here, we describe the
basic commands for managing a database.
</Para>
<Sect1>
<Title>Creating a Database</Title>
<Para>
Let's say you want to create a database named mydb.
You can do this with the following command:
<ProgramListing>
</ProgramListing>
</para>
</Sect1>
</Chapter>
<Chapter Id="manage-ag">
<Title>Managing a Database</Title>
<Para>
Now that <ProductName>Postgres</ProductName> is up and running we can create
some databases to experiment with. Here, we describe the
basic commands for managing a database.
</Para>
<Sect1>
<Title>Creating a Database</Title>
<Para>
Let's say you want to create a database named mydb.
You can do this with the following command:
<ProgramListing>
% createdb mydb
</ProgramListing>
<ProductName>Postgres</ProductName> allows you to create
any number of databases
at a given site and you automatically become the
database administrator of the database you just created.
Database names must have an alphabetic first
character and are limited to 16 characters in length.
Not every user has authorization to become a database
administrator. If <ProductName>Postgres</ProductName>
refuses to create databases
for you, then the site administrator needs to grant you
permission to create databases. Consult your site
administrator if this occurs.
</Para>
</Sect1>
<Sect1>
<Title>Accessing a Database</Title>
<Para>
Once you have constructed a database, you can access it
by:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
running the <ProductName>Postgres</ProductName> terminal monitor program
(<Application>psql</Application>) which allows you to interactively
enter, edit, and execute <Acronym>SQL</Acronym> commands.
</Para>
</ListItem>
<ListItem>
<Para>
writing a C program using the <literal>libpq</literal> subroutine
library. This allows you to submit <Acronym>SQL</Acronym> commands
from C and get answers and status messages back to
your program. This interface is discussed further
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</Para>
</ListItem>
</ItemizedList>
You might want to start up <Application>psql</Application>,
to try out the examples in this manual. It can be activated for the mydb
database by typing the command:
<ProgramListing>
</ProgramListing>
<ProductName>Postgres</ProductName> allows you to create
any number of databases
at a given site and you automatically become the
database administrator of the database you just created.
Database names must have an alphabetic first
character and are limited to 16 characters in length.
Not every user has authorization to become a database
administrator. If <ProductName>Postgres</ProductName>
refuses to create databases
for you, then the site administrator needs to grant you
permission to create databases. Consult your site
administrator if this occurs.
</Para>
</Sect1>
<Sect1>
<Title>Accessing a Database</Title>
<Para>
Once you have constructed a database, you can access it
by:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
running the <ProductName>Postgres</ProductName> terminal monitor program
(<Application>psql</Application>) which allows you to interactively
enter, edit, and execute <Acronym>SQL</Acronym> commands.
</Para>
</ListItem>
<ListItem>
<Para>
writing a C program using the <literal>libpq</literal> subroutine
library. This allows you to submit <Acronym>SQL</Acronym> commands
from C and get answers and status messages back to
your program. This interface is discussed further
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</Para>
</ListItem>
</ItemizedList>
You might want to start up <Application>psql</Application>,
to try out the examples in this manual. It can be activated for the mydb
database by typing the command:
<ProgramListing>
% psql mydb
</ProgramListing>
</ProgramListing>
You will be greeted with the following message:
<ProgramListing>
You will be greeted with the following message:
<ProgramListing>
Welcome to the Postgres interactive sql monitor:
type \? for help on slash commands
......@@ -257,70 +200,94 @@ Welcome to the Postgres interactive sql monitor:
You are currently connected to the database: mydb
mydb=>
</ProgramListing>
</Para>
<Para>
This prompt indicates that the terminal monitor is listening
to you and that you can type <Acronym>SQL</Acronym> queries into a
workspace maintained by the terminal monitor.
The <Application>psql</Application> program responds to escape
codes that begin
with the backslash character, "\". For example, you
can get help on the syntax of various
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
<ProgramListing>
</ProgramListing>
</Para>
<Para>
This prompt indicates that the terminal monitor is listening
to you and that you can type <Acronym>SQL</Acronym> queries into a
workspace maintained by the terminal monitor.
The <Application>psql</Application> program responds to escape
codes that begin
with the backslash character, "\". For example, you
can get help on the syntax of various
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
<ProgramListing>
mydb=> \h
</ProgramListing>
</ProgramListing>
Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace
to the <ProductName>Postgres</ProductName> server by typing:
<ProgramListing>
Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace
to the <ProductName>Postgres</ProductName> server by typing:
<ProgramListing>
mydb=> \g
</ProgramListing>
This tells the server to process the query. If you
terminate your query with a semicolon, the backslash-g is not
necessary. <Application>psql</Application> will automatically
process semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
<ProgramListing>
</ProgramListing>
This tells the server to process the query. If you
terminate your query with a semicolon, the backslash-g is not
necessary. <Application>psql</Application> will automatically
process semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
<ProgramListing>
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
</ProgramListing>
and <Application>psql</Application> will quit and return
you to your command
shell. (For more escape codes, type backslash-h at the monitor
prompt.)
White space (i.e., spaces, tabs and newlines) may be
used freely in <Acronym>SQL</Acronym> queries.
Single-line comments are denoted by
<Quote>--</Quote>. Everything after the dashes up to the end of the
line is ignored. Multiple-line comments, and comments within a line,
are denoted by <Quote>/* ... */</Quote>
</Para>
</Sect1>
</ProgramListing>
and <Application>psql</Application> will quit and return
you to your command
shell. (For more escape codes, type backslash-h at the monitor
prompt.)
White space (i.e., spaces, tabs and newlines) may be
used freely in <Acronym>SQL</Acronym> queries.
Single-line comments are denoted by two dashes
(<Quote>--</Quote>). Everything after the dashes up to the end of the
line is ignored. Multiple-line comments, and comments within a line,
are denoted by <Quote>/* ... */</Quote>, a convention borrowed
from <productname>Ingres</productname>.
</Para>
</Sect1>
<Sect1>
<Title>Destroying a Database</Title>
<Sect1>
<Title>Destroying a Database</Title>
<Para>
If you are the database administrator for the database
mydb, you can destroy it using the following UNIX command:
<ProgramListing>
<Para>
If you are the database administrator for the database
mydb, you can destroy it using the following UNIX command:
<ProgramListing>
% destroydb mydb
</ProgramListing>
This action physically removes all of the UNIX files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</Para>
</Sect1>
</Chapter>
</ProgramListing>
This action physically removes all of the UNIX files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</Para>
</Sect1>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/trouble.sgml 0 → 100644
View file @ 32cfa65e
<Chapter Id="trouble">
<Title>Troubleshooting</Title>
<sect1>
<title>Client Connections</title>
<Para>
If you get the following error message from a
<ProductName>Postgres</ProductName>
command (such as <Application>psql</Application> or
<Application>createdb</Application>):
<ProgramListing>
connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
</ProgramListing>
it is usually because either the <Application>postmaster</Application> is not running,
or you are attempting to connect to the wrong server host.
If you get the following error message:
<ProgramListing>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
</ProgramListing>
it means that the site administrator started the <Application>postmaster</Application>
as the wrong user. Tell him to restart it as
the <ProductName>Postgres</ProductName> superuser.
</Para>
</sect1>
<sect1>
<title>Debugging Messages</title>
<para>
The <Application>postmaster</Application> occasionally prints out
messages which
are often helpful during troubleshooting. If you wish
to view debugging messages from the <Application>postmaster</Application>,
you can
start it with the -d option and redirect the output to
the log file:
<ProgramListing>
% postmaster -d >& pm.log &
</ProgramListing>
If you do not wish to see these messages, you can type
<ProgramListing>
% postmaster -S
</ProgramListing>
and the <Application>postmaster</Application> will be "S"ilent.
Notice that there
is no ampersand ("&amp") at the end of the last example so
postmaster will be running in the foreground.
</Para>
<sect2 Id="pg-options-trouble">
<Title>pg_options</Title>
<Para>
<Note>
<Para>
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
</Para>
</Note>
</para>
<Para>
The optional file <filename>data/pg_options</filename> contains runtime
options used by the backend to control trace messages and other backend
tunable parameters.
What makes this file interesting is the fact that it is re-read by a backend
when it receives a SIGHUP signal, making thus possible to change run-time
options on the fly without needing to restart
<productname>Postgres</productname>.
The options specified in this file may be debugging flags used by the trace
package (<filename>backend/utils/misc/trace.c</filename>) or numeric
parameters which can be used by the backend to control its behaviour.
New options and parameters must be defined in
<filename>backend/utils/misc/trace.c</filename> and
<filename>backend/include/utils/trace.h</filename>.
</para>
<para>
pg_options can also be specified with the <option>-T</option> switch of
<productname>Postgres</productname>:
<programlisting>
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
</programlisting>
</para>
<Para>
The functions used for printing errors and debug messages can now make use
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
or stderr are prefixed by a timestamp containing also the backend pid:
<programlisting>
#timestamp #pid #message
980127.17:52:14.173 [29271] StartTransactionCommand
980127.17:52:14.174 [29271] ProcessUtility: drop table t;
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
980127.17:52:14.186 [29286] Async_NotifyHandler
980127.17:52:14.186 [29286] Waking up sleeping backend process
980127.19:52:14.292 [29286] Async_NotifyFrontEnd
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
980127.19:52:14.466 [29286] Async_NotifyHandler done
</programlisting>
</para>
<para>
This format improves readability of the logs and allows people to understand
exactly which backend is doing what and at which time. It also makes
easier to write simple awk or perl scripts which monitor the log to
detect database errors or problem, or to compute transaction time statistics.
</para>
<para>
Messages printed to syslog use the log facility LOG_LOCAL0.
The use of syslog can be controlled with the syslog pg_option.
Unfortunately many functions call directly <function>printf()</function>
to print their messages to stdout or stderr and this output can't be
redirected to syslog or have timestamps in it.
It would be advisable that all calls to printf would be replaced with the
PRINTF macro and output to stderr be changed to use EPRINTF instead so that
we can control all output in a uniform way.
</Para>
<para>
The format of the <filename>pg_options</filename> file is as follows:
<programlisting>
# <replaceable>comment</replaceable>
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable>
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0
</programlisting>
Note that <replaceable class="parameter">keyword</replaceable> can also be
an abbreviation of the option name defined in
<filename>backend/utils/misc/trace.c</filename>.
</Para>
<Para>
Refer to <xref linkend="pg-options-title" endterm="pg-options-title">
for a complete list of option keywords and possible values.
</para>
</sect2>
</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/tutorial.sgml
View file @ 32cfa65e
......@@ -24,23 +24,23 @@
<!-- Title information -->
<Title>PostgreSQL Tutorial</Title>
<BookInfo>
<ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<Title>PostgreSQL Tutorial</Title>
<BookInfo>
<ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<!-- editor in authorgroup is not supported
<AuthorGroup>
-->
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<!--
</AuthorGroup>
-->
......@@ -49,16 +49,17 @@
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
</BookBiblio>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
</Para>
</LegalNotice>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
</BookInfo>
</BookInfo>
<!--
<TOC> </TOC>
......@@ -73,30 +74,48 @@ Your name here...
</Dedication>
-->
<Preface>
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
of this original Berkeley code.
</Para>
</Preface>
&intro;
&arch;
&start;
&query;
&advanced;
&biblio;
<Preface>
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
of this original Berkeley code.
</Para>
</Preface>
&intro;
&arch;
&start;
&query;
&advanced;
&biblio;
<!--
<INDEX> </INDEX>
-->
</Book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/user.sgml
View file @ 32cfa65e
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.8 1999/05/04 02:26:06 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.9 1999/05/20 05:39:29 thomas Exp $
Postgres User's Manual.
Derived from postgres.sgml.
thomas 1998-02-24
$Log: user.sgml,v $
Revision 1.9 1999/05/20 05:39:29 thomas
Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
integrated with the User's Guide.
Break up the former chapter on pg_options
into Admin and Programmer's Guides.
Revision 1.8 1999/05/04 02:26:06 thomas
Include new introductory chapter on SQL from Stefan S.
Should this be in the tutorial instead?
......@@ -48,9 +56,6 @@ Move SQL reference pages up into the User's Guide.
<!entity keys SYSTEM "keys.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity pgaccess SYSTEM "pgaccess.sgml">
<!entity psql SYSTEM "psql.sgml">
<!entity query-ug SYSTEM "query-ug.sgml">
<!entity sql SYSTEM "sql.sgml">
<!entity storage SYSTEM "storage.sgml">
<!entity syntax SYSTEM "syntax.sgml">
......@@ -65,42 +70,42 @@ Move SQL reference pages up into the User's Guide.
<!-- Title information -->
<Title>PostgreSQL User's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<Title>PostgreSQL User's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<!-- editor in authorgroup is not supported
<AuthorGroup>
<AuthorGroup>
-->
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<!--
</AuthorGroup>
</AuthorGroup>
-->
<!--
<AuthorInitials>TGL</AuthorInitials>
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
</BookBiblio>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
by the Postgres Global Development Group.
</Para>
</LegalNotice>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
</BookInfo>
</BookInfo>
<!--
<TOC> </TOC>
......@@ -115,42 +120,39 @@ Your name here...
</Dedication>
-->
<preface id="preface">
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
of this original Berkeley code.
</Para>
</Preface>
&intro;
<preface id="preface">
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
of this original Berkeley code.
</Para>
</Preface>
&intro;
&sql;
&environ;
&manage;
&syntax;
&datatype;
&oper;
&func;
&typeconv;
&datatype;
&oper;
&func;
&typeconv;
&keys;
&array;
&inherit;
&query-ug;
&storage;
&psql;
&pgaccess;
&commands;
<!--
&contacts;
-->
&array;
&inherit;
&environ;
&manage;
&storage;
&commands;
<!--
&contacts;
-->
&biblio;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment