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.
<!--
-$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).
<!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">
<!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">
]>
<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 (©) 1998-9
by the Postgres Global Development Group.
</Para>
</LegalNotice>
&ports;
&config;
+ &layout;
&install;
&installw;
&runtime;
&security;
- &options;
&start-ag;
+ &trouble;
&recovery;
®ress;
&release;
<!-- 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
--- /dev/null
+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é
+
+
+
-<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>
+ 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>
+ To check for disk space, use
$ df -k
-</programlisting>
-</para>
-</Sect1>
+ </programlisting>
+ </para>
+ </Sect1>
<Sect1>
<Title>Installation Procedure</Title>
</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:
+-->
--- /dev/null
+<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:
+-->
-<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>
+ <FirstName>Massimo</FirstName>
+ <Surname>Dal Zotto</Surname>
+ </Author>
+ </AuthorGroup>
+ <Date>Transcribed 1998-10-16</Date>
+ </DocInfo>
+
+ <Title>pg_options</Title>
+
+ <Note>
+
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
+ </Para>
+ </Note>
+ </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>
+ 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>:
+
/* file trace.h */
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>
/* 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>
/* file foo.c */
#include "trace.h"
#define foo_param pg_options[OPT_FOO_PARAM]
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>
+ Existing files using private trace flags can be changed by simply adding
+ the following code:
-<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>
+ 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>
# 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>
+ 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>
+ pg_options can also be specified with the <option>-T</option> switch of
+
<productname>Postgres</productname>:
+
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>
+ 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:
+
#timestamp #pid #message
980127.17:52:14.173 [29271] StartTransactionCommand
980127.17:52:14.174 [29271] ProcessUtility: drop table t;
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>
+ 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>
+ 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>
+
+ The new pg_options mechanism is more convenient than defining new backend
+ option switches because:
+
+ <ItemizedList Mark="bullet" Spacing="compact">
+ <ListItem>
+ 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>
+
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>
+ 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:
+
# <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:
+-->
+++ /dev/null
-<Chapter Id="pgaccess">
-<Title><Command>pgaccess</Command></Title>
-
-<Para>
-This section needs to be written. Volunteers?
-</Para>
-
-</Chapter>
<!--
-$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.
<!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">
<!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">
<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>
<AuthorInitials>TGL</AuthorInitials>
-->
- <Date>(last updated 1998-02-23)</Date>
+ <Date>(last updated 1998-05-19)</Date>
</BookBiblio>
<LegalNotice>
</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>
&installw;
&runtime;
&security;
- &options;
&start-ag;
&recovery;
®ress;
</Para>
</PartIntro>
&arch-dev;
+ &options;
&geqo;
&protocol;
&signals;
<!--
-$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.
<!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">
<!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">
<!-- Title information -->
-<Title>PostgreSQL Programmer's Guide</Title>
-<BookInfo>
- <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
- <BookBiblio>
- <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>
- <OrgName>Caltech/JPL</OrgName>
- </Affiliation>
- </Editor>
+ <Editor>
+ <FirstName>Thomas</FirstName>
+ <SurName>Lockhart</SurName>
+ <Affiliation>
+ <OrgName>Caltech/JPL</OrgName>
+ </Affiliation>
+ </Editor>
<!--
</AuthorGroup>
-->
<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>
+ <ProductName>PostgreSQL</ProductName> is copyright (©) 1998-9
+ by the Postgres Global Development Group.
+ </Para>
+ </LegalNotice>
-</BookInfo>
+ </BookInfo>
<!--
<TOC> </TOC>
</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;
+ <Title>Summary</Title>
+
+
<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 -->
&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">
+++ /dev/null
-<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>
+++ /dev/null
-<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>
-<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>
+
+ 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:
+
% cd /usr/local/pgsql/src/tutorial
% psql -s mydb
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
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:
+--------------+---------+---------+------+------------+
|city | temp_lo | temp_hi | prcp | date |
+--------------+---------+---------+------+------------+
+--------------+---------+---------+------+------------+
|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:
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,
+ 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;
-
+ </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.
+ 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>
+ </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>
+ Any select query can be redirected to a new class
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>
+
+ 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>
+
+ 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>
+ 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:
+
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
+--------------+-----+------+---------------+-----+------+
|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>
+ Deletions are performed using the <Command>delete</Command> command:
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
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>
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>:
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>
+ Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
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:
+-->
-<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 ("&") 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:
+-->
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>
<parameter>D<subscript>i</subscript></parameter>,
for each attribute
<parameter>A<subscript>i</subscript></parameter>,
- 1 ≤ <literal>i</literal> ≤ <literal>k</literal>,
+ 1 <&equal; <literal>i</literal> <&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>,
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 ≤ 20), the type of <classname>SNO</classname> will be
+ for character strings of length <&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 ≤ 20, the domain of <classname>SNO</classname> is the set of
+ character strings of length <&equal; 20,
+ the domain of <classname>SNO</classname> is the set of
all integer numbers.
</para>
</sect2>
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
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
- - 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 ("&") 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:
Welcome to the Postgres interactive sql monitor:
type \? for help on slash commands
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:
+-->
--- /dev/null
+ <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 ("&") 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:
+-->
<!-- Title information -->
-<Title>PostgreSQL Tutorial</Title>
-<BookInfo>
- <ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
- <BookBiblio>
- <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>
- <OrgName>Caltech/JPL</OrgName>
- </Affiliation>
- </Editor>
+ <Editor>
+ <FirstName>Thomas</FirstName>
+ <SurName>Lockhart</SurName>
+ <Affiliation>
+ <OrgName>Caltech/JPL</OrgName>
+ </Affiliation>
+ </Editor>
<!--
</AuthorGroup>
-->
<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 (©) 1998-9
+ by the Postgres Global Development Group.
+ </Para>
+ </LegalNotice>
-</BookInfo>
+ </BookInfo>
<!--
<TOC> </TOC>
</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;
+ <Title>Summary</Title>
+
+
<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:
+-->
<!--
-$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?
<!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">
<!-- Title information -->
-<Title>PostgreSQL User's Guide</Title>
-<BookInfo>
- <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
- <BookBiblio>
- <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>
-->
- <Editor>
- <FirstName>Thomas</FirstName>
- <SurName>Lockhart</SurName>
- <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>
+ <ProductName>PostgreSQL</ProductName> is copyright (©) 1998-9
+ by the Postgres Global Development Group.
+ </Para>
+ </LegalNotice>
-</BookInfo>
+ </BookInfo>
<!--
<TOC> </TOC>
</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;
+ <Title>Summary</Title>
+
+
<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;
projects / postgresql / commitdiff