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

Rearrange and consolidate the Admin Guide.

Browse Source 
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.
This commit is contained in:
Thomas G. Lockhart 1999-05-20 05:39:29 +00:00
parent c3a4d8ed54
commit 32cfa65e49
18 changed files with 2107 additions and 1997 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,11 +1,19 @@
<!--
$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

155
doc/src/sgml/datetime.sgml Normal file
View File

@ -0,0 +1,155 @@
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é

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

@ -45,8 +45,9 @@ The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possi
</ListItem>
</ItemizedList>
</para>
<Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
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.
@ -73,7 +74,8 @@ Up to date information on supported platforms is at
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>.
platforms with modern libraries should be able to run
<ProductName>Postgres</ProductName>.
</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
@ -1303,92 +1305,27 @@ For more information on the various support mailing lists.
<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.
the source distribution.
</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>
</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:
-->

78
doc/src/sgml/layout.sgml Normal file
View File

@ -0,0 +1,78 @@
<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:
-->

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

@ -9,7 +9,7 @@
<Date>Transcribed 1998-10-16</Date>
</DocInfo>
<Title>Using pg_options</Title>
<Title>pg_options</Title>
<Para>
<Note>
@ -199,444 +199,12 @@ 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:
Refer to <citetitle>The Administrator's Guide</citetitle> chapter
on runtime options for a complete list of currently supported
options.
</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
@ -649,3 +217,20 @@ 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:
-->

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

@ -1,8 +0,0 @@
<Chapter Id="pgaccess">
<Title><Command>pgaccess</Command></Title>
<Para>
This section needs to be written. Volunteers?
</Para>
</Chapter>

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

@ -1,11 +1,19 @@
<!--
$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>
@ -243,8 +251,6 @@ Your name here...
</PartIntro>
&sql;
&environ;
&manage;
&syntax;
&datatype;
&oper;
@ -253,10 +259,9 @@ Your name here...
&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;

19
doc/src/sgml/programmer.sgml
View File

@ -1,10 +1,18 @@
<!--
$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">
@ -98,7 +108,7 @@ Bigger updates to the installation instructions (install and config).
<Title>PostgreSQL Programmer's Guide</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>
@ -121,12 +131,12 @@ Bigger updates to the installation instructions (install and config).
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-10-27)</Date>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
@ -196,6 +206,7 @@ Disable it until we put in some info.
<!-- development -->
&arch-dev;
&options;
&geqo;
&protocol;
&signals;

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

@ -1,45 +0,0 @@
<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>

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

@ -1,363 +0,0 @@
<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>

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

@ -8,16 +8,18 @@ the <Acronym>SQL3</Acronym> draft next-generation standard. It
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.
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
<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.
are extensions to the <Acronym>ANSI</Acronym> standard.
</Para>
<Sect1>
@ -70,7 +72,8 @@ for a listing, type <Literal>\?</Literal> at the <Application>psql</Application>
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>)
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.
@ -104,7 +107,8 @@ CREATE TABLE weather (
<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>.
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>,
@ -114,8 +118,10 @@ 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
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
@ -139,6 +145,19 @@ INSERT INTO weather
<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>
@ -184,7 +203,9 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
SELECT * FROM weather
WHERE city = 'San Francisco'
AND prcp > 0.0;
</programlisting>
results in:
<programlisting>
+--------------+---------+---------+------+------------+
|city | temp_lo | temp_hi | prcp | date |
+--------------+---------+---------+------+------------+
@ -273,9 +294,12 @@ The semantics of such a join are
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>
<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
@ -337,9 +361,11 @@ DELETE FROM classname;
<Title>Using Aggregate Functions</Title>
<Para>
Like most other query languages, <ProductName>PostgreSQL</ProductName> supports
Like most other query languages,
<ProductName>PostgreSQL</ProductName> supports
aggregate functions.
The current implementation of <ProductName>Postgres</ProductName> aggregate functions have some limitations.
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
@ -374,3 +400,20 @@ SELECT city, max(temp_lo)
</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:
-->

637
doc/src/sgml/runtime.sgml
View File

@ -5,6 +5,7 @@
This chapter outlines the interaction between <Productname>Postgres</Productname> and
the operating system.
</para>
<sect1>
<title>Using <Productname>Postgres</Productname> from Unix</title>
@ -14,6 +15,7 @@ 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
@ -28,66 +30,603 @@ 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>
<sect1 Id="postmaster">
<Title>Starting <Application>postmaster</Application></Title>
<Para>
<Figure Id="ADMIN-LAYOUT">
<Title><ProductName>Postgres</ProductName> file layout</Title>
<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic>
</Figure>
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>:
<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 )
% postmaster
</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
</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>
PATH=/usr/local/pgsql/bin:$PATH
export PATH
% postmaster -d >& pm.log &
</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.
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>
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.
<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:
-->

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

@ -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>

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

@ -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,7 +483,10 @@ attributes are taken from. We often write a relation scheme as
projecting out the duplicate column.
</para>
<para id="join-example">
<example id="join-example">
<title>An Inner Join</title>
<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:
@ -494,6 +499,7 @@ attributes are taken from. We often write a relation scheme as
7 | 8 | 9
</programlisting>
</para>
</example>
<para>
First we calculate the Cartesian product

121
doc/src/sgml/start-ag.sgml
View File

@ -4,44 +4,6 @@
- - 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>
@ -62,9 +24,6 @@ to the underlying
<Chapter Id="disk">
<Title>Disk Management</Title>
<Para>
</Para>
<Sect1>
<Title>Alternate Locations</Title>
@ -74,6 +33,7 @@ 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.
@ -83,23 +43,29 @@ 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.
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>
CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS
</ProgramListing>
in your <filename>Makefile.custom</filename>.
</Para>
</Note>
@ -109,9 +75,11 @@ 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
@ -124,11 +92,13 @@ 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
@ -137,49 +107,20 @@ 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>
% 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>
@ -195,6 +136,7 @@ FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
<Para>
Let's say you want to create a database named mydb.
You can do this with the following command:
<ProgramListing>
% createdb mydb
</ProgramListing>
@ -243,6 +185,7 @@ running the <ProductName>Postgres</ProductName> terminal monitor program
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>
@ -269,6 +212,7 @@ to you and that you can type <Acronym>SQL</Acronym> queries into a
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>
@ -276,6 +220,7 @@ mydb=> \h
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>
@ -286,11 +231,13 @@ mydb=> \g
process semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
<ProgramListing>
mydb=> \i fileName
</ProgramListing>
To get out of <Application>psql</Application> and return to UNIX, type
<ProgramListing>
mydb=> \q
</ProgramListing>
@ -301,10 +248,11 @@ you to your command
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
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>
are denoted by <Quote>/* ... */</Quote>, a convention borrowed
from <productname>Ingres</productname>.
</Para>
</Sect1>
@ -314,9 +262,11 @@ Single-line comments are denoted by
<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.
@ -324,3 +274,20 @@ Single-line comments are denoted by
</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:
-->

166
doc/src/sgml/trouble.sgml Normal file
View File

@ -0,0 +1,166 @@
<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:
-->

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

@ -26,7 +26,7 @@
<Title>PostgreSQL Tutorial</Title>
<BookInfo>
<ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
<ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@ -49,12 +49,13 @@
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
@ -96,7 +97,25 @@ It provides SQL92/SQL3 language support,
&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:
-->

26
doc/src/sgml/user.sgml
View File

@ -1,11 +1,19 @@
<!--
$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">
@ -67,7 +72,7 @@ Move SQL reference pages up into the User's Guide.
<Title>PostgreSQL User's Guide</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>
@ -90,12 +95,12 @@ Move SQL reference pages up into the User's Guide.
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
<Date>(last updated 1999-05-19)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
<ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
@ -132,8 +137,6 @@ It provides SQL92/SQL3 language support,
&intro;
&sql;
&environ;
&manage;
&syntax;
&datatype;
&oper;
@ -142,10 +145,9 @@ It provides SQL92/SQL3 language support,
&keys;
&array;
&inherit;
&query-ug;
&environ;
&manage;
&storage;
&psql;
&pgaccess;
&commands;
<!--