<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.30 2002/10/24 17:48:54 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.30.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="tutorial-advanced">
<firstterm>view</firstterm> over the query, which gives a name to
the query that you can refer to like an ordinary table.
+<programlisting>
CREATE VIEW myview AS
SELECT city, temp_lo, temp_hi, prcp, date, location
FROM weather, cities
WHERE city = name;
SELECT * FROM myview;
- </programlisting>
+</programlisting>
</para>
<para>
<para>
The new declaration of the tables would look like this:
+<programlisting>
CREATE TABLE cities (
city varchar(80) primary key,
location point
prcp real,
date date
);
- </programlisting>
+</programlisting>
Now try inserting an invalid record:
+<programlisting>
INSERT INTO weather VALUES ('Berkeley', 45, 53, 0.0, '1994-11-28');
- </programlisting>
+</programlisting>
- <screen>
+<screen>
ERROR: <unnamed> referential integrity violation - key referenced from weather not found in cities
- </screen>
+</screen>
</para>
<para>
The behavior of foreign keys can be finely tuned to your
application. We will not go beyond this simple example in this
- tutorial, but just refer you to the &cite-reference;
+ tutorial, but just refer you to the &cite-user;
for more information. Making correct use of
foreign keys will definitely improve the quality of your database
applications, so you are strongly encouraged to learn about them.
to Bob's account. Simplifying outrageously, the SQL commands for this
might look like
+<programlisting>
UPDATE accounts SET balance = balance - 100.00
WHERE name = 'Alice';
UPDATE branches SET balance = balance - 100.00
WHERE name = 'Bob';
UPDATE branches SET balance = balance + 100.00
WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Bob');
- </programlisting>
+</programlisting>
</para>
<para>
<command>BEGIN</> and <command>COMMIT</> commands. So our banking
transaction would actually look like
+<programlisting>
BEGIN;
UPDATE accounts SET balance = balance - 100.00
WHERE name = 'Alice';
-- etc etc
COMMIT;
- </programlisting>
+</programlisting>
</para>
<para>
implicitly when you list all cities. If you're really clever you
might invent some scheme like this:
+<programlisting>
CREATE TABLE capitals (
name text,
population real,
SELECT name, population, altitude FROM capitals
UNION
SELECT name, population, altitude FROM non_capitals;
- </programlisting>
+</programlisting>
This works OK as far as querying goes, but it gets ugly when you
need to update several rows, to name one thing.
<para>
A better solution is this:
+<programlisting>
CREATE TABLE cities (
name text,
population real,
CREATE TABLE capitals (
state char(2)
) INHERITS (cities);
- </programlisting>
+</programlisting>
</para>
<para>
including state capitals, that are located at an altitude
over 500 ft.:
+<programlisting>
SELECT name, altitude
FROM cities
WHERE altitude > 500;
- </programlisting>
+</programlisting>
which returns:
all the cities that are not state capitals and
are situated at an altitude of 500 ft. or higher:
+<programlisting>
SELECT name, altitude
FROM ONLY cities
WHERE altitude > 500;
- </programlisting>
+</programlisting>
<screen>
name | altitude
<classname>cities</classname> table, and not tables below
<classname>cities</classname> in the inheritance hierarchy. Many
of the commands that we have already discussed --
- <command>SELECT</command>, <command>UPDATE</command> and
+ <command>SELECT</command>, <command>UPDATE</command>, and
<command>DELETE</command> -- support this <literal>ONLY</literal>
notation.
</para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.23 2002/10/21 02:11:37 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.23.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="backup">
<title>Backup and Restore</title>
<para>
As any other <productname>PostgreSQL</> client application,
<application>pg_dump</> will by default connect with the database
- user name that is equal to the current Unix user name. To override
+ user name that is equal to the current operating system user name. To override
this, either specify the <option>-U</option> option or set the
environment variable <envar>PGUSER</envar>. Remember that
<application>pg_dump</> connections are subject to the normal
</synopsis>
where <replaceable class="parameter">infile</replaceable> is what
you used as <replaceable class="parameter">outfile</replaceable>
- for the pg_dump command. The database <replaceable
+ for the <command>pg_dump</> command. The database <replaceable
class="parameter">dbname</replaceable> will not be created by this
- command, you must create it yourself from template0 before executing
+ command, you must create it yourself from <literal>template0</> before executing
<application>psql</> (e.g., with <literal>createdb -T template0
<replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</>
The ability of <application>pg_dump</> and <application>psql</> to
write to or read from pipes makes it possible to dump a database
directly from one server to another, for example
- <informalexample>
<programlisting>
pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</>
</programlisting>
- </informalexample>
</para>
-
- <important>
- <para>
- The dumps produced by pg_dump are relative to template0. This means
- that any languages, procedures, etc. added to template1 will also be
- dumped by <application>pg_dump</>. As a result, when restoring, if
- you are using a customized template1, you must create the empty
- database from template0, as in the example above.
- </para>
- </important>
+ <important>
+ <para>
+ The dumps produced by <application>pg_dump</> are relative to
+ <literal>template0</>. This means that any languages, procedures,
+ etc. added to <literal>template1</> will also be dumped by
+ <application>pg_dump</>. As a result, when restoring, if you are
+ using a customized <literal>template1</>, you must create the
+ empty database from <literal>template0</>, as in the example
+ above.
+ </para>
+ </important>
</sect2>
acceptable in size to the underlying file system. For example, to
make chunks of 1 megabyte:
- <informalexample>
<programlisting>
pg_dump <replaceable class="parameter">dbname</replaceable> | split -b 1m - <replaceable class="parameter">filename</replaceable>
</programlisting>
- </informalexample>
Reload with
- <informalexample>
<programlisting>
createdb <replaceable class="parameter">dbname</replaceable>
cat <replaceable class="parameter">filename</replaceable>* | psql <replaceable class="parameter">dbname</replaceable>
</programlisting>
- </informalexample>
</para>
</formalpara>
restored selectively. The following command dumps a database using the
custom dump format:
- <informalexample>
<programlisting>
pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceable class="parameter">filename</replaceable>
</programlisting>
- </informalexample>
See the <application>pg_dump</> and <application>pg_restore</> reference pages for details.
-
</para>
</formalpara>
<para>
For reasons of backward compatibility, <application>pg_dump</> does
not dump large objects by default. To dump large objects you must use
- either the custom or the TAR output format, and use the -b option in
+ either the custom or the TAR output format, and use the <option>-b</> option in
<application>pg_dump</>. See the reference pages for details.
The directory <filename>contrib/pg_dumplo</> of the
<productname>PostgreSQL</> source tree also contains a program that can
are located, but you have probably found them already if you are
interested in this method. You can use whatever method you prefer
for doing usual file system backups, for example
- <informalexample>
+
<programlisting>
tar -cf backup.tar /usr/local/pgsql/data
</programlisting>
- </informalexample>
</para>
<para>
The least downtime can be achieved by installing the new server in
a different directory and running both the old and the new servers
in parallel, on different ports. Then you can use something like
-<informalexample>
+
<programlisting>
pg_dumpall -p 5432 | psql -d template1 -p 6543
</programlisting>
-</informalexample>
+
to transfer your data, or use an intermediate file if you want.
Then you can shut down the old server and start the new server at
the port the old one was running at. You should make sure that the
do the back up step before installing the new version, bring down
the server, move the old version out of the way, install the new
version, start the new server, restore the data. For example:
-<informalexample>
+
<programlisting>
pg_dumpall > backup
pg_ctl stop
postmaster -D /usr/local/pgsql/data
psql template1 < backup
</programlisting>
-</informalexample>
+
See <xref linkend="runtime"> about ways to start and stop the
server and other details. The installation instructions will advise
you of strategic places to perform these steps.
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.39 2002/09/21 18:32:52 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.39.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="client-authentication">
</para>
<para>
- The general format of the <filename>pg_hba.conf</filename> file is of
+ The general format of the <filename>pg_hba.conf</filename> file is
a set of records, one per line. Blank lines are ignored, as is any
text after the <quote>#</quote> comment character. A record is made
up of a number of fields which are separated by spaces and/or tabs.
<para>
If you use the map <literal>sameuser</literal>, the user
names are assumed to be identical. If not, the map name is
- looked up in the <literal>$PGDATA/pg_ident.conf</literal>
- file. The connection is accepted if that file contains an
+ looked up in the file <filename>pg_ident.conf</filename>
+ in the same directory as <filename>pg_hba.conf</filename>.
+ The connection is accepted if that file contains an
entry for this map name with the ident-supplied user name
and the requested <productname>PostgreSQL</productname> user
name.
<para>
When <literal>trust</> authentication is specified,
<productname>PostgreSQL</productname> assumes that anyone who can
- connect to the postmaster is authorized to access the database as
+ connect to the server is authorized to access the database as
whatever database user he specifies (including the database superuser).
This method should only be used when there is adequate system-level
protection on connections to the postmaster port.
<para>
<literal>trust</> authentication is only suitable for TCP connections
if you trust every user on every machine that is allowed to connect
- to the postmaster by the <filename>pg_hba.conf</> lines that specify
+ to the server by the <filename>pg_hba.conf</> lines that specify
<literal>trust</>. It is seldom reasonable to use <literal>trust</>
for any TCP connections other than those from <systemitem>localhost</> (127.0.0.1).
</para>
<para>
<productname>PostgreSQL</productname> database passwords are
- separate from operating system user passwords. Ordinarily, the
- password for each database user is stored in the pg_shadow system
+ separate from operating system user passwords. The password for
+ each database user is stored in the <literal>pg_shadow</> system
catalog table. Passwords can be managed with the query language
commands <command>CREATE USER</command> and <command>ALTER
USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
- 'secret';</userinput>. By default, that is, if no password has been
- set up, the stored password is <literal>NULL</literal> and password
- authentication will always fail for that user.
+ 'secret';</userinput>. By default, that is, if no password has
+ been set up, the stored password is null and
+ password authentication will always fail for that user.
</para>
<para>
file. The file should contain user names separated by commas or one
user name per line, and be in the same directory as
<filename>pg_hba.conf</>. Mention the (base) name of the file
- preceded with <literal>@</>in the <literal>USER</> column. The
- <literal>DATABASE</> column can similarly accept a list of values or
+ preceded with <literal>@</> in the user column. The
+ database column can similarly accept a list of values or
a file name. You can also specify group names by preceding the group
name with <literal>+</>.
</para>
Unix-domain sockets (currently <systemitem
class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,
<systemitem class="osname">NetBSD</>, and <systemitem
- class="osname">BSD/OS</>, ident authentication can also be applied
+ class="osname">BSD/OS</>), ident authentication can also be applied
to local connections. In this case, no security risk is added by
using ident authentication; indeed it is a preferable choice for
local connections on such systems.
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.6 2002/10/16 22:06:33 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.6.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="diskusage">
<para>
You can monitor disk space from three places: from
<application>psql</> using <command>VACUUM</> information, from
- <application>psql</> using <application>contrib/dbsize</>, and from
+ <application>psql</> using <filename>contrib/dbsize</>, and from
the command line using <application>contrib/oid2name</>. Using
<application>psql</> on a recently vacuumed (or analyzed) database,
you can issue queries to see the disk usage of any table:
</para>
<para>
- <application>dbsize</> loads functions into your database that allow
+ <filename>contrib/dbsize</> loads functions into your database that allow
you to find the size of a table or database from inside
<application>psql</> without the need for <command>VACUUM/ANALYZE.</>
</para>
+
<para>
- You can also use <application>oid2name</> to show disk usage. See
- <filename>README.oid2name</> for examples. It includes a script
+ You can also use <filename>contrib/oid2name</> to show disk usage. See
+ <filename>README.oid2name</> for examples. It includes a script that
shows disk usage for each database.
</para>
</sect1>
<secondary>on Windows</secondary>
</indexterm>
- <abstract>
- <para>
- Build, installation, and use instructions for
- <productname>PostgreSQL</productname> client libraries on
- <productname>Windows</productname>
- </para>
- </abstract>
-
<para>
Although <productname>PostgreSQL</productname> is written for
Unix-like operating systems, the C client library
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.103.2.5 2002/11/05 19:01:43 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.103.2.6 2002/11/06 23:30:39 petere Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
<primary>installation</primary>
</indexterm>
+ <para>
+ This <![%standalone-include;[document.]]>
+ <![%standalone-ignore;[chapter.]]> describes the installation of
+ <productname>PostgreSQL</productname> from the source code
+ distribution.
+ </para>
+
<sect1 id="install-short">
<title>Short Version</title>
<para>
To build the server programming language PL/Perl you need a full
Perl installation, including the <filename>libperl</filename>
- library and the header files. Since PL/Perl is a shared
+ library and the header files. Since PL/Perl will be a shared
library, the <indexterm><primary>libperl</primary></indexterm>
<filename>libperl</filename> library must be a shared library
- also on most platforms. At the time of this writing, this is
- almost never the case in prebuilt Perl packages.
+ also on most platforms. This appears to be the default in
+ recent Perl versions, but it was not in earlier versions, and in
+ general it is the choice of whomever installed Perl at your
+ site.
</para>
<para>
- If this difficulty arises in your situation, a message like this
- will appear during the build to point out this fact:
+ If you don't have the shared library but you need one, a message
+ like this will appear during the build to point out this fact:
<screen>
*** Cannot build PL/Perl because libperl is not a shared library.
*** You might have to rebuild your Perl installation. Refer to
*** the documentation for details.
</screen>
(If you don't follow the on-screen output you will merely notice
- the the PL/Perl library object will not be installed.) If you
- see this, you will have to re-build and install
- <productname>Perl</productname> manually to be able to build
- PL/Perl. During the configuration process for
- <productname>Perl</productname>, request a shared library.
+ that the PL/Perl library object, <filename>plperl.so</filename>
+ or similar, will not be installed.) If you see this, you will
+ have to rebuild and install <productname>Perl</productname>
+ manually to be able to build PL/Perl. During the configuration
+ process for <productname>Perl</productname>, request a shared
+ library.
</para>
</listitem>
To build the Python interface module or the PL/Python server
programming language, you need a Python installation, including
the header files.
- </para>
-
- <para>
- Since PL/Python is a shared library, the
+ Since PL/Python will be a shared library, the
<indexterm><primary>libpython</primary></indexterm>
<filename>libpython</filename> library must be a shared library
also on most platforms. This is not the case in a default
- Python installation. If after building and installing you have
- a file called <filename>plpython.so</filename> (possibly a
- different extension), then everything went well. Otherwise you
- should have seen a notice like this flying by:
+ Python installation.
+ </para>
+
+ <para>
+ If after building and installing you have a file called
+ <filename>plpython.so</filename> (possibly a different
+ extension), then everything went well. Otherwise you should
+ have seen a notice like this flying by:
<screen>
*** Cannot build PL/Python because libpython is not a shared library.
*** You might have to rebuild your Python installation. Refer to
<primary>yacc</primary>
</indexterm>
- <a
cronym>GNU</> <application>Flex</> and <application>Bison</>
+ <application>Flex</> and <application>Bison</>
are needed to build a CVS checkout or if you changed the actual
scanner and parser definition files. If you need them, be sure
to get <application>Flex</> 2.5.4 or later and
<primary>pg_dumpall</primary>
</indexterm>
- To dump your database installation, type:
+ To back up your database installation, type:
<screen>
<userinput>pg_dumpall > <replaceable>outputfile</></userinput>
</screen>
</para>
<para>
- Make sure that you use the <command>pg_dumpall</> command
- from the version you are currently running. &version;'s
- <command>pg_dumpall</> should not be used on older databases.
+ To make the backup, you can use the <command>pg_dumpall</command>
+ command from the version you are currently running. For best
+ results, however, try to use the <command>pg_dumpall</command>
+ command from PostgreSQL &version;, since this version contains
+ bug fixes and improvements over older versions. While this
+ advice might seem idiosyncratic since you haven't installed the
+ new version yet, it is advisable to follow it if you plan to
+ install the new version in parallel with the old version. In
+ that case you can complete the installation normally and transfer
+ the data later. This will also decrease the downtime.
</para>
</step>
</para>
<para>
- You can also install the new version in parallel with the old one
- to decrease the downtime. These topics are discussed at length in
- <![%standalone-include[the <citetitle>Administrator's Guide</>,]]>
- <![%standalone-ignore[<xref linkend="migration">,]]>
- which you are encouraged
- to read in any case.
+ These topics are discussed at length in <![%standalone-include[the
+ <citetitle>Administrator's Guide</>,]]> <![%standalone-ignore[<xref
+ linkend="migration">,]]> which you are encouraged to read in any
+ case.
</para>
</sect1>
server-side language. You need to have root access to be able
to install the Python module at its default place
(<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>).
- To be able to use this option, you must have Python installed
- and your system needs to support shared libraries. If you
- instead want to build a new complete interpreter binary, you
- will have to do it manually.
</para>
</listitem>
</varlistentry>
<term><option>--with-tcl</option></term>
<listitem>
<para>
- Builds components that require Tcl/Tk, which are
+ Build components that require Tcl/Tk, which are
<application>libpgtcl</>, <application>pgtclsh</>,
<application>pgtksh</application>,
and <application>PL/Tcl</>. But see below about
</procedure>
<formalpara>
- <title>Uninstall:</title>
+ <title>Uninstallation:</title>
<para>
To undo the installation use the command <command>gmake
uninstall</>. However, this will not remove any created directories.
<para>
On <systemitem class="osname">Cygwin</systemitem>, put the library
- directory on the <envar>PATH</envar> or move the
+ directory in the <envar>PATH</envar> or move the
<filename>.dll</filename> files into the <filename>bin/</filename>
directory.
</para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.98 2002/11/03 01:30:46 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.98.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="libpq">
<primary>password</primary>
<secondary>.pgpass</secondary>
</indexterm>
-<filename>$HOME/.pgpass</filename> is a file that can contain passwords
-to be used if the connection requires a password. This file should have the
-format:
-<screen>
+The file <filename>.pgpass</filename> in the home directory is a file
+that can contain passwords to be used if the connection requires a
+password. This file should have the format:
+<synopsis>
<replaceable>hostname</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>username</replaceable>:<replaceable>password</replaceable>
-</screen>
+</synopsis>
Any of these may be a literal name, or <literal>*</literal>, which matches
anything. The first match will be used so put more specific entries first.
Entries with <literal>:</literal> or <literal>\</literal> should be escaped
with <literal>\</literal>.
</para>
<para>
-The permissions on <filename>$HOME/.pgpass</filename> must disallow any
+The permissions on <filename>.pgpass</filename> must disallow any
access to world or group; achieve this by the command
-<command>chmod 0600 $HOME/.pgaccess</command>.
+<command>chmod 0600 .pgaccess</command>.
If the permissions are less strict than this, the file will be ignored.
+</para>
</sect1>
<sect1 id="libpq-threading">
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="maintenance">
a regular basis to keep a <productname>PostgreSQL</productname>
installation running smoothly. The tasks discussed here are repetitive
in nature and can easily be automated using standard Unix tools such
- as <filename>cron</filename> scripts. But it is the database
+ as <application>cron</application> scripts. But it is the database
administrator's responsibility to set up appropriate scripts, and to
check that they execute successfully.
</para>
<command>UPDATE</> or <command>DELETE</> of a row does not
immediately remove the old <firstterm>tuple</> (version of the row).
This approach is necessary to gain the benefits of multiversion
- concurrency control (see the <citetitle>User's Guide</>): the tuple
+ concurrency control (see the &cite-user;): the tuple
must not be deleted while it is still potentially visible to other
transactions. But eventually, an outdated or deleted tuple is no
longer of interest to any transaction. The space it occupies must be
Although per-column tweaking of <command>ANALYZE</> frequency may not be
very productive, you may well find it worthwhile to do per-column
adjustment of the level of detail of the statistics collected by
- <command>ANALYZE</>. Columns that are heavily used in WHERE clauses
+ <command>ANALYZE</>. Columns that are heavily used in <literal>WHERE</> clauses
and have highly irregular data distributions may require a finer-grain
data histogram than other columns. See <command>ALTER TABLE SET
STATISTICS</>.
is exactly one billion transactions: if you wait longer, it's possible
that a tuple that was not quite old enough to be reassigned last time
is now more than two billion transactions old and has wrapped around
- into the future --- ie, is lost to you. (Of course, it'll reappear
+ into the future --- i.e., is lost to you. (Of course, it'll reappear
after another two billion transactions, but that's no help.)
</para>
statistics in the system table <filename>pg_database</>. In particular,
the <filename>datfrozenxid</> field of a database's
<filename>pg_database</> row is updated at the completion of any
- database-wide vacuum operation (ie, <command>VACUUM</> that does not
+ database-wide vacuum operation (i.e., <command>VACUUM</> that does not
name a specific table). The value stored in this field is the freeze
cutoff XID that was used by that <command>VACUUM</> command. All normal
XIDs older than this cutoff XID are guaranteed to have been replaced by
<literal>FrozenXID</> within that database. A convenient way to
examine this information is to execute the query
- <informalexample>
+
<programlisting>
SELECT datname, age(datfrozenxid) FROM pg_database;
</programlisting>
- </informalexample>
+
The <literal>age</> column measures the number of transactions from the
cutoff XID to the current transaction's XID.
</para>
each database-wide <command>VACUUM</> automatically delivers a warning
if there are any <filename>pg_database</> entries showing an
<literal>age</> of more than 1.5 billion transactions, for example:
- <informalexample>
+
<programlisting>
play=# vacuum;
WARNING: Some databases have not been vacuumed in 1613770184 transactions.
or you may have a wraparound failure.
VACUUM
</programlisting>
- </informalexample>
</para>
<para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.22 2002/10/24 17:48:54 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.22.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="managing-databases">
database within the installation.) More accurately, a database is
a collection of schemas and the schemas contain the tables,
functions, etc. So the full hierarchy is:
- server-database-schema-table (or something else instead of a
+ server, database, schema, table (or something else instead of a
table).
</para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.14 2002/09/21 18:32:53 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.14.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="monitoring">
<title>Monitoring Database Activity</title>
<para>
- A database administrator frequently wonders <quote>what is the system
+ A database administrator frequently wonders, <quote>What is the system
doing right now?</quote>
This chapter discusses how to find that out.
</para>
<command>ps</> and <command>top</>. Also, once one has identified a
poorly-performing query, further investigation may be needed using
<productname>PostgreSQL</productname>'s <command>EXPLAIN</> command.
- The <citetitle>User's Guide</citetitle> discusses <command>EXPLAIN</>
+ The &cite-user; discusses <command>EXPLAIN</>
and other methods for understanding the behavior of an individual
query.
</para>
The user, database, and connection source host items remain the same for
the life of the client connection, but the activity indicator changes.
- The activity may be <literal>idle</> (ie, waiting for a client command),
- <literal>idle in transaction</> (waiting for client inside a BEGIN block),
+ The activity may be <literal>idle</> (i.e., waiting for a client command),
+ <literal>idle in transaction</> (waiting for client inside a <command>BEGIN</> block),
or a command type name such as <literal>SELECT</>. Also,
<literal>waiting</> is attached if the server is presently waiting
on a lock held by another server process. In the above example we can infer
<varname>STATS_BLOCK_LEVEL</varname>,
and <varname>STATS_ROW_LEVEL</varname>
default to <literal>false</>, no statistics are actually collected
- in the default configuration! You must turn one or more of them on
+ in the default configuration. You must turn one or more of them on
before you will get useful results from the statistical display
functions.
</para>
<para>
Several predefined views are available to show the results of
- statistics collection. Alternatively, one can build custom views
- using the underlying statistics functions.
+ statistics collection, listed in <xref
+ linkend="monitoring-stats-views-table">. Alternatively, one can
+ build custom views using the underlying statistics functions.
</para>
<para>
Each individual server process transmits new access counts to the collector
just before waiting for another client command; so a query still in
progress does not affect the displayed totals. Also, the collector itself
- emits new totals at most once per <varname>pgstat_stat_interval</varname> (500 milliseconds
- by default). So the displayed totals lag behind actual activity.
+ emits new totals at most once per <varname>pgstat_stat_interval</varname> milliseconds
+ (500 by default). So the displayed totals lag behind actual activity.
</para>
<para>
block.
</para>
- <table>
+ <table id="monitoring-stats-views-table">
<title>Standard Statistics Views</title>
<tgroup cols="2">
<tbody>
<row>
<entry><structname>pg_stat_activity</></entry>
- <entry>One row per server process, showing process <acronym>PID</>, database,
+ <entry>One row per server process, showing process <acronym>ID</>, database,
user, and current query. The current query column is only available
- to superusers; for others it reads as NULL. (Note that because of
+ to superusers; for others it reads as null. (Note that because of
the collector's reporting delay, current query will only be up-to-date
for long-running queries.)</entry>
</row>
<entry><structname>pg_stat_database</></entry>
<entry>One row per database, showing number of active backends,
total transactions committed and total rolled back in that database,
- total disk blocks read, and total number of buffer hits (ie, block
+ total disk blocks read, and total number of buffer hits (i.e., block
read requests avoided by finding the block already in buffer cache).
</entry>
</row>
<row>
<entry><structname>pg_stat_sys_tables</></entry>
- <entry>Same as pg_stat_all_tables, except that only system tables
+ <entry>Same as <structname>pg_stat_all_tables</>, except that only system tables
are shown.</entry>
</row>
<row>
<entry><structname>pg_stat_user_tables</></entry>
- <entry>Same as pg_stat_all_tables, except that only user tables
+ <entry>Same as <structname>pg_stat_all_tables</>, except that only user tables
are shown.</entry>
</row>
<entry><structname>pg_stat_all_indexes</></entry>
<entry>For each index in the current database, the total number
of index scans that have used that index, the number of index tuples
- read, and the number of successfully fetched heap tuples (this may
- be less when there are index entries pointing to expired heap tuples).
+ read, and the number of successfully fetched heap tuples. (This may
+ be less when there are index entries pointing to expired heap tuples.)
</entry>
</row>
<row>
<entry><structname>pg_stat_sys_indexes</></entry>
- <entry>Same as pg_stat_all_indexes, except that only indexes on
+ <entry>Same as <structname>pg_stat_all_indexes</>, except that only indexes on
system tables are shown.</entry>
</row>
<row>
<entry><structname>pg_stat_user_indexes</></entry>
- <entry>Same as pg_stat_all_indexes, except that only indexes on
+ <entry>Same as <structname>pg_stat_all_indexes</>, except that only indexes on
user tables are shown.</entry>
</row>
</para>
<para>
- Other ways of looking at the statistics can be set up by writing queries
- that use the same underlying statistics access functions as these standard
- views do. The per-database access functions accept a database OID to
- identify which database to report on. The per-table and per-index
- functions accept a table or index OID (note that only tables and indexes
- in the current
+ Other ways of looking at the statistics can be set up by writing
+ queries that use the same underlying statistics access functions as
+ these standard views do. These functions are listed in <xref
+ linkend="monitoring-stats-funcs-table">. The per-database access
+ functions accept a database OID to identify which database to
+ report on. The per-table and per-index functions accept a table or
+ index OID (note that only tables and indexes in the current
database can be seen with these functions). The per-backend access
- functions accept a backend ID number, which ranges from one to the number
- of currently active backends.
+ functions accept a backend ID number, which ranges from one to the
+ number of currently active backends.
</para>
- <table>
+ <table id="monitoring-stats-funcs-table">
<title>Statistics Access Functions</title>
<tgroup cols="3">
</tgroup>
</table>
- <para>
- Note: blocks_fetched minus blocks_hit gives the number of kernel read()
- calls issued for the table, index, or database; but the actual number of
- physical reads is usually lower due to kernel-level buffering.
- </para>
+ <note>
+ <para>
+ Blocks_fetched minus blocks_hit gives the number of kernel
+ <function>read()</> calls issued for the table, index, or
+ database; but the actual number of physical reads is usually
+ lower due to kernel-level buffering.
+ </para>
+ </note>
<para>
The function <function>pg_stat_get_backend_idset</function> provides
</sect2>
</sect1>
- <sect1 id="monitoring-locks">
- <title>Viewing Locks</title>
+ <sect1 id="monitoring-locks">
+ <title>Viewing Locks</title>
+
+ <para>
+ Another useful tool for monitoring database activity is the
+ <literal>pg_locks</literal> system catalog. This allows the
+ database administrator to view information about the outstanding
+ locks in the lock manager. For example, this capability can be used
+ to:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ View all the locks currently outstanding, all the locks on
+ relations in a particular database, all the locks on a
+ particular relation, or all the locks held by a particular
+ <productname>PostgreSQL</productname> session.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ View the relation in the current database with the most
+ ungranted locks (which might be a source of contention among
+ database clients).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Determine the effect of lock contention on overall database
+ performance, as well as the extent to which contention varies
+ with overall database traffic.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ For more information on locking and managing concurrency with
+ <productname>PostgreSQL</productname>, refer to the &cite-user;.
+ </para>
+ <note>
<para>
- Another useful tool for monitoring database activity is the
- <literal>pg_locks</literal> system catalog. This allows the
- database administrator to view information about the outstanding
- locks in the lock manager. For example, this capability can be
- used to:
- <itemizedlist>
- <listitem>
- <para>
- View all the locks currently outstanding, all the locks on
- relations in a particular database, all the locks on a
- particular relation, or all the locks held by a particular
- <productname>PostgreSQL</productname> backend.
- </para>
- </listitem>
- <listitem>
- <para>
- View the relation in the current database with the most
- un-granted locks (which might be a source of contention among
- database clients).
- </para>
- </listitem>
- <listitem>
- <para>
- Determine the effect of lock contention on overall database
- performance, as well as the extent to which contention varies
- with overall database traffic.
- </para>
- </listitem>
- </itemizedlist>
-
- For more information on locking and managing concurrency with
- <productname>PostgreSQL</productname>, refer to the
- <citetitle>Administrator's Guide</citetitle>.
+ When the <literal>pg_locks</literal> view is accessed, the
+ internal lock manager data structures are momentarily locked, and
+ a copy is made for the view to display. This ensures that the
+ view produces a consistent set of results, while not blocking
+ normal lock manager operations longer than necessary. Nonetheless
+ there could be some impact on database performance if this view is
+ examined often.
</para>
+ </note>
- <note>
- <para>
- When the <literal>pg_locks</literal> view is accessed, the
- internal lock manager data structures are momentarily locked,
- and a copy is made for the view to display. This ensures that
- the view produces a consistent set of results, while not blocking
- normal lock manager operations longer than necessary. Nonetheless
- there could be some impact on database performance if this view is
- examined often.
- </para>
- </note>
+ <para>
+ <xref linkend="monitoring-locks-table"> shows the definition of the
+ <literal>pg_locks</literal> columns. The
+ <literal>pg_locks</literal> view contains one row per lockable
+ object and requested lock mode. Thus, the same lockable object may
+ appear many times, if multiple transactions are holding or waiting
+ for locks on it. A lockable object is either a relation or a
+ transaction ID. (Note that this view includes only table-level
+ locks, not row-level ones. If a transaction is waiting for a
+ row-level lock, it will appear in the view as waiting for the
+ transaction ID of the current holder of that row lock.)
+ </para>
- <para>
- The <literal>pg_locks</literal> view contains one row per lockable
- object and requested lock mode. Thus, the same lockable object
- may appear many times, if multiple transactions are holding or
- waiting for locks on it. A lockable object is either a relation
- or a transaction ID. (Note that this view includes only table-level
- locks, not row-level ones. If a transaction is waiting for a
- row-level lock, it will appear in the view as waiting for the
- transaction ID of the current holder of that row lock.)
- </para>
+ <table id="monitoring-locks-table">
+ <title>Lock Status System View</title>
- <table>
- <title>Lock Status System View</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Column Name</entry>
- <entry>Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><structfield>relation</structfield></entry>
- <entry><type>oid</type></entry>
- <entry>The OID of the locked relation, or NULL if the lockable
- object is a transaction ID. This column can be joined
- with the <literal>pg_class</literal> system catalog to get more
- information on the locked relation. Note however that this will
- only work for relations in the current database (those for which
- the <structfield>database</structfield> column is either the
- current database's OID or zero).
- </entry>
- </row>
-
- <row>
- <entry><structfield>database</structfield></entry>
- <entry><type>oid</type></entry>
- <entry>The OID of the database in which the locked relation
- exists, or NULL if the lockable object is a transaction ID.
- If the lock is on a globally-shared table, this field will be
- zero. This
- column can be joined with the <literal>pg_database</literal>
- system catalog to get more information on the locked object's
- database.
- </entry>
- </row>
-
- <row>
- <entry><structfield>transaction</structfield></entry>
- <entry><type>xid</type></entry>
- <entry>The ID of a transaction, or NULL if the lockable object
- is a relation. Every transaction holds an exclusive lock on its
- transaction ID for its entire duration. If one transaction finds
- it necessary to wait specifically for another transaction, it
- does so by attempting to acquire share lock on the other transaction
- ID. That will succeed only when the other transaction terminates
- and releases its locks.
- </entry>
- </row>
-
- <row>
- <entry><structfield>pid</structfield></entry>
- <entry><type>int4</type></entry>
- <entry>The process ID of the
- <productname>PostgreSQL</productname> backend that has
- acquired or is attempting to acquire the lock. If you have
- enabled the statistics collector, this column can be joined
- with the <literal>pg_stat_activity</literal> view to get
- more information on the backend holding or waiting to hold the
- lock.</entry>
- </row>
-
- <row>
- <entry><structfield>mode</structfield></entry>
- <entry><type>text</type></entry>
- <entry>The mode of the requested or held lock on the lockable
- object. For more information on the
- different lock modes available in
- <productname>PostgreSQL</productname>, refer to the
- <citetitle>User's Guide</citetitle>.</entry>
- </row>
-
- <row>
- <entry><structfield>isgranted</structfield></entry>
- <entry><type>bool</type></entry>
- <entry>True if this lock has been granted (is held by this
- backend). False indicates that this backend is currently
- waiting to acquire this lock, which implies that some other
- backend is holding a conflicting lock mode on the same lockable
- object. This backend will sleep until the other lock is released
- (or a deadlock situation is detected). A single backend can be
- waiting to acquire at most one lock at a time.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect1>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Column Name</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><structfield>relation</structfield></entry>
+ <entry><type>oid</type></entry>
+ <entry>
+ The OID of the locked relation, or null if the lockable object
+ is a transaction ID. This column can be joined with the
+ <literal>pg_class</literal> system catalog to get more
+ information on the locked relation. Note however that this
+ will only work for relations in the current database (those for
+ which the <structfield>database</structfield> column is either
+ the current database's OID or zero).
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>database</structfield></entry>
+ <entry><type>oid</type></entry>
+ <entry>
+ The OID of the database in which the locked relation exists, or
+ null if the lockable object is a transaction ID. If the lock
+ is on a globally-shared table, this field will be zero. This
+ column can be joined with the <literal>pg_database</literal>
+ system catalog to get more information on the locked object's
+ database.
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>transaction</structfield></entry>
+ <entry><type>xid</type></entry>
+ <entry>
+ The ID of a transaction, or null if the lockable object is a
+ relation. Every transaction holds an exclusive lock on its
+ transaction ID for its entire duration. If one transaction
+ finds it necessary to wait specifically for another
+ transaction, it does so by attempting to acquire share lock on
+ the other transaction ID. That will succeed only when the
+ other transaction terminates and releases its locks.
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>pid</structfield></entry>
+ <entry><type>integer</type></entry>
+ <entry>
+ The process ID of the <productname>PostgreSQL</productname>
+ backend belonging to the session that has acquired or is
+ attempting to acquire the lock. If you have enabled the
+ statistics collector, this column can be joined with the
+ <literal>pg_stat_activity</literal> view to get more
+ information on the backend holding or waiting to hold the
+ lock.
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>mode</structfield></entry>
+ <entry><type>text</type></entry>
+ <entry>
+ The mode of the requested or held lock on the lockable
+ object. For more information on the different lock modes
+ available in <productname>PostgreSQL</productname>, refer to
+ the &cite-user;.
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>isgranted</structfield></entry>
+ <entry><type>boolean</type></entry>
+ <entry>
+ True if this lock has been granted (is held by this session).
+ False indicates that this session is currently waiting to
+ acquire this lock, which implies that some other session is
+ holding a conflicting lock mode on the same lockable object.
+ This backend will sleep until the other lock is released (or a
+ deadlock situation is detected). A single backend can be
+ waiting to acquire at most one lock at a time.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
</chapter>
<!-- Keep this comment at the end of the file
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27 2002/10/24 17:48:54 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="tutorial-sql">
<acronym>SQL</acronym> to perform simple operations. This
tutorial is only intended to give you an introduction and is in no
way a complete tutorial on <acronym>SQL</acronym>. Numerous books
- have been written on <acronym>SQL92</acronym>, including <xref
+ have been written on <acronym>SQL</acronym>, including <xref
linkend="MELT93"> and <xref linkend="DATE97">.
You should be aware that some <productname>PostgreSQL</productname>
language features are extensions to the standard.
The <literal>\i</literal> command reads in commands from the
specified file. The <literal>-s</literal> option puts you in
- single step mode which pauses before sending each query to the
+ single step mode which pauses before sending each statement to the
server. The commands used in this section are in the file
<filename>basics.sql</filename>.
</para>
join operator will have each of its rows in the output at least
once, whereas the table on the right will only have those rows
output that match some row of the left table. When outputting a
- left-table row for which there is no right-table match, empty (NULL)
+ left-table row for which there is no right-table match, empty (null)
values are substituted for the right-table columns.
</para>
<para>
<indexterm><primary>subquery</primary></indexterm>
- If we want to know what city (or cities) that reading occurred in,
+ If we wanted to know what city (or cities) that reading occurred in,
we might try
<programlisting>
go into the aggregation stage; so it has to be evaluated before
aggregate functions are computed.)
However, as is often the case
- the query can be restated to accomplish the intended result; here
+ the query can be restated to accomplish the intended result, here
by using a <firstterm>subquery</firstterm>:
<programlisting>
(1 row)
</screen>
- This is OK because the sub-select is an independent computation
+ This is OK because the subquery is an independent computation
that computes its own aggregate separately from what is happening
- in the outer select.
+ in the outer query.
</para>
<para>
<programlisting>
SELECT city, max(temp_lo)
FROM weather
- WHERE city LIKE 'S%'
+ WHERE city LIKE 'S%'<co id="co.tutorial-agg-like">
GROUP BY city
HAVING max(temp_lo) < 40;
</programlisting>
+ <calloutlist>
+ <callout arearefs="co.tutorial-agg-like">
+ <para>
+ The <literal>LIKE</literal> operator does pattern matching and
+ is explained in the &cite-user;.
+ </para>
+ </callout>
+ </calloutlist>
</para>
<para>
You can update existing rows using the
<command>UPDATE</command> command.
Suppose you discover the temperature readings are
- all off by 2 degrees as of November 28, you may update the
+ all off by 2 degrees as of November 28. You may update the
data as follows:
<programlisting>
</indexterm>
<para>
- Suppose you are no longer interested in the weather of Hayward,
- then you can do the following to delete those rows from the table.
+ Suppose you are no longer interested in the weather of Hayward.
+ Then you can do the following to delete those rows from the table.
Deletions are performed using the <command>DELETE</command>
command:
<programlisting>
</para>
<para>
- One should be wary of queries of the form
+ One should be wary of statements of the form
<synopsis>
DELETE FROM <replaceable>tablename</replaceable>;
</synopsis>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.147.2.1 2002/11/05 23:17:45 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.147.2.2 2002/11/06 23:30:39 petere Exp $
-->
<Chapter Id="runtime">
</para>
<sect1 id="postgres-user">
- <title>The <productname>PostgreSQL</productname> user account</title>
+ <title>The <productname>PostgreSQL</productname> User Account</title>
<indexterm>
<primary>postgres user</primary>
</sect1>
<sect1 id="creating-cluster">
- <title>Creating a database cluster</title>
+ <title>Creating a Database Cluster</title>
<indexterm>
<primary>database cluster</primary>
</screen>
This is intended to warn you that the currently selected locale
will cause indexes to be sorted in an order that prevents them from
- being used for LIKE and regular-expression searches. If you need
+ being used for <literal>LIKE</> and regular-expression searches. If you need
good performance in such searches, you should set your current
locale to <literal>C</> and re-run <command>initdb</command>, e.g.,
by running <literal>initdb --lc-collate=C</literal>. The sort
</sect1>
<sect1 id="postmaster-start">
- <title>Starting the database server</title>
+ <title>Starting the Database Server</title>
<para>
<indexterm>
<para>
Normally, you will want to start the database server when the
- computer boots. Auto-start scripts are operating-system specific.
+ computer boots. Autostart scripts are operating system-specific.
There are a few distributed with
<productname>PostgreSQL</productname> in the
<filename>/contrib/start-scripts</> directory. This may require root
means your kernel's limit on the number of System V semaphores is
smaller than the number <productname>PostgreSQL</productname> wants
to create. As above, you may be able to work around the problem by
- starting the postmaster with a reduced number of backend processes
+ starting the postmaster with a reduced number of allowed connections
(<option>-N</option> switch), but you'll eventually want to
increase the kernel limit.
</para>
<para>
- If you get an <quote>illegal system call</> error, it is likely
+ If you get an <quote>illegal system call</> error, it is likely that
shared memory or semaphores are not supported in your kernel at
all. In that case your only option is to reconfigure the kernel to
enable these features.
</sect1>
<sect1 id="runtime-config">
- <Title>Run-time configuration</Title>
+ <Title>Run-time Configuration</Title>
<indexterm>
<primary>configuration</primary>
<title>pg_settings</title>
<para>
- <structname>pg_settings</structname> virtual table allows display and update
+ The <structname>pg_settings</structname> virtual table allows display and update
of current session run-time parameters. There is one entry for each of the
available parameters provided by <command>SHOW ALL</command>. But it is
in a form that allows it to be joined with other relations and have a
<table>
<title>pg_settings Columns</title>
- <tgroup cols=4>
+ <tgroup cols=3>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
- <entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
- <entry>name</entry>
+ <entry><literal>name</literal></entry>
<entry><type>text</type></entry>
- <entry></entry>
<entry>The name of a current session run-time parameter</entry>
</row>
<row>
- <entry>setting</entry>
+ <entry><literal>setting</literal></entry>
<entry><type>text</type></entry>
- <entry></entry>
<entry>The value of a current session run-time parameter</entry>
</row>
</tbody>
<listitem>
<para>
Sets the optimizer's estimate of the cost of processing each
- operator in a WHERE clause. This is measured as a fraction of
+ operator in a <literal>WHERE</> clause. This is measured as a fraction of
the cost of a sequential page fetch.
</para>
</listitem>
<term><varname>SERVER_MIN_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
- This controls how much detail is written to the server logs. The
- default is <literal>NOTICE</>. Valid values are <literal>DEBUG5</>,
+ This controls how much message detail is written to the server
+ logs. Valid values are <literal>DEBUG5</>,
<literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
<literal>DEBUG1</>, <literal>INFO</>, <literal>NOTICE</>,
- <literal>WARNING</>, <literal>ERROR</>, <literal>LOG</>,
- <literal>FATAL</>, and <literal>PANIC</>. Later values send less
- detail to the logs. <literal>LOG</> has a different precedence
- here than in <literal>CLIENT_MIN_MESSAGES</>.
+ <literal>WARNING</>, <literal>ERROR</>, <literal>LOG</>,
+ <literal>FATAL</>, and <literal>PANIC</>. Later values send
+ less detail to the logs. The default is <literal>NOTICE</>.
+ Note that <literal>LOG</> has a different precedence here than
+ in <literal>CLIENT_MIN_MESSAGES</>.
</para>
+
<para>
Here is a summary of the various message types:
<variablelist>
<varlistentry>
- <term><varname>DEBUG[1-5]</varname></term>
+ <term><literal>DEBUG[1-5]</literal></term>
<listitem>
<para>
- This provides information for use by developers.
+ Provides information for use by developers.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><varname>INFO</varname></term>
+ <term><literal>INFO</literal></term>
<listitem>
<para>
- This provides information requested by the user, e.g.
- <command>SET</>.
+ Provides information implicitly requested by the user,
+ e.g., during <command>VACUUM VERBOSE</>.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><varname>NOTICE</varname></term>
+ <term><literal>NOTICE</literal></term>
<listitem>
<para>
- This provides information that may be helpful to users, e.g.
- truncation of long identifiers, sequence creation as part of
- <command>SERIAL</>.
+ Provides information that may be helpful to users, e.g.,
+ truncation of long identifiers and index creation as part
+ of primary keys.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><varname>WARNING</varname></term>
+ <term><literal>WARNING</literal></term>
<listitem>
<para>
- This provides warnings to the user, e.g. <command>COMMIT</>
+ Provides warnings to the user, e.g., <command>COMMIT</>
outside a transaction.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><varname>ERROR</varname></term>
+ <term><literal>ERROR</literal></term>
<listitem>
<para>
- Reports the error that caused the transaction to abort.
+ Reports the error that caused a transaction to abort.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>LOG</varname></term>
+ <term><literal>LOG</literal></term>
<listitem>
<para>
- This reports information of interest to administrators, e.g.
+ Reports information of interest to administrators, e.g.,
checkpoint activity.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><varname>FATAL</varname></term>
+ <term><literal>FATAL</literal></term>
<listitem>
<para>
- This reports why the backend session terminated.
+ Reports why a backend session terminated.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><varname>PANIC</varname></term>
+ <term><literal>PANIC</literal></term>
<listitem>
<para>
- This reports why all backends restarted.
+ Reports why all backend sessions restarted.
</para>
</listitem>
</varlistentry>
<term><varname>CLIENT_MIN_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
- This controls how much detail is written to the client. The
- default is <literal>NOTICE</>. Valid values are
- <literal>DEBUG5</>, <literal>DEBUG4</>, <literal>DEBUG3</>,
- <literal>DEBUG2</>, <literal>DEBUG1</>, <literal>LOG</>,
- <literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
- Later values send less information to the user. <literal>LOG</>
- has a different precedence here than in
- <literal>SERVER_MIN_MESSAGES</>. Also see that section for an
- explanation of the various values.
+ This controls how much message detail is written to the
+ client. Valid values are <literal>DEBUG5</>,
+ <literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
+ <literal>DEBUG1</>, <literal>LOG</>, <literal>NOTICE</>,
+ <literal>WARNING</>, and <literal>ERROR</>. Later values send
+ less information to the client. The default is
+ <literal>NOTICE</>. Note that <literal>LOG</> has a different
+ precedence here than in <literal>SERVER_MIN_MESSAGES</>. Also
+ see that section for an explanation of the various values.
</para>
</listitem>
</varlistentry>
to turn this on, as it might expose programming mistakes. To use
this option, the macro <literal>USE_ASSERT_CHECKING</literal>
must be defined when <productname>PostgreSQL</productname> is
- built (accomplished by the configure option
+ built (accomplished by the <command>configure</command> option
<option>--enable-cassert</option>). Note that
<literal>DEBUG_ASSERTIONS</literal> defaults to on if
<productname>PostgreSQL</productname> has been built with
<listitem>
<para>
These flags enable various debugging output to be sent to the
- server log. For each executed query, prints either the query text,
+ server log. For each executed query, print either the query text,
the resulting parse tree, the query rewriter output, or the execution
plan. <option>DEBUG_PRETTY_PRINT</option> indents these displays
to produce a more readable but much longer output format.
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>LOG_DURATION</varname> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Causes the duration of every completed statement to be logged.
+ To use this option, enable <varname>LOG_STATEMENT</> and
+ <varname>LOG_PID</> so you can link the statement to the
+ duration using the process ID.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>LOG_MIN_ERROR_STATEMENT</varname> (<type>string</type>)</term>
<listitem>
<para>
- This controls which message types output the original query to
- the server logs. All queries matching the setting or higher are
- logged. The default is <literal>PANIC</literal> (effectively
- "off"). Valid values are <literal>DEBUG5</literal>,
- <literal>DEBUG4</literal>, <literal>DEBUG3</literal>,
- <literal>DEBUG2</literal>, <literal>DEBUG1</literal>,
- <literal>INFO</literal>, <literal>NOTICE</literal>,
- <literal>WARNING</literal>, <literal>ERROR</literal>,
- <literal>FATAL</literal>, and <literal>PANIC</literal>.
+ This controls for which message levels the SQL statement
+ causing that message is to be recorded in the server log. All
+ statements causing a message of the level of the setting or
+ higher are logged. The default is <literal>PANIC</literal>
+ (effectively turning this feature off). Valid values are
+ <literal>DEBUG5</literal>, <literal>DEBUG4</literal>,
+ <literal>DEBUG3</literal>, <literal>DEBUG2</literal>,
+ <literal>DEBUG1</literal>, <literal>INFO</literal>,
+ <literal>NOTICE</literal>, <literal>WARNING</literal>,
+ <literal>ERROR</literal>, <literal>FATAL</literal>, and
+ <literal>PANIC</literal>. For example, if you set this to
+ <literal>ERROR</literal> then all SQL statements causing
+ errors, fatal errors, or panics will be logged.
</para>
+
<para>
- It is recommended you enable <literal>LOG_PID</literal> as well
+ It is recommended you enable <varname>LOG_PID</varname> as well
so you can more easily match the error statement with the error
message.
</para>
<term><varname>LOG_STATEMENT</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- Prints each query received.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>LOG_DURATION</varname> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Prints the duration of every completed query. To use this option,
- enable <literal>LOG_STATEMENT</> and <literal>LOG_PID</> so you
- can link the original query to the duration using the process id.
+ Causes each SQL statement to be logged.
</para>
</listitem>
</varlistentry>
This option determines the <application>syslog</application>
<quote>facility</quote> to be used when
<application>syslog</application> is enabled. You may choose
- from LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6,
- LOCAL7; the default is LOCAL0. See also the documentation of
- your system's <application>syslog</application>.
+ from <literal>LOCAL0</>, <literal>LOCAL1</>,
+ <literal>LOCAL2</>, <literal>LOCAL3</>, <literal>LOCAL4</>,
+ <literal>LOCAL5</>, <literal>LOCAL6</>, <literal>LOCAL7</>;
+ the default is <literal>LOCAL0</>. See also the
+ documentation of your system's
+ <application>syslog</application>.
</para>
</listitem>
</varlistentry>
</sect2>
<sect2 id="runtime-config-general">
- <title>General operation</title>
+ <title>General Operation</title>
<para>
<variablelist>
<varlistentry>
- <term><varname>AUTOCOMMIT</varname> (<type>bool</type>)</term>
+ <term><varname>AUTOCOMMIT</varname> (<type>boolean</type>)</term>
<indexterm><primary>autocommit</></>
<listitem>
<para>
Once another command is issued, a transaction block
begins and any <command>SET</>, <command>SHOW</>, or
<command>RESET</> commands are considered to be part of the
- transaction, i.e. they are committed or rolled back depending
+ transaction, i.e., they are committed or rolled back depending
on the completion status of the transaction. To execute a
<command>SET</>, <command>SHOW</>, or <command>RESET</>
command at the start of a transaction block, use <command>BEGIN</>
</varlistentry>
<varlistentry>
- <term><varname>AUSTRALIAN_TIMEZONES</varname> (<type>bool</type>)</term>
+ <term><varname>AUSTRALIAN_TIMEZONES</varname> (<type>boolean</type>)</term>
<indexterm><primary>Australian time zones</></>
<listitem>
<para>
<term><varname>DB_USER_NAMESPACE</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- This allows per-database user names. You can create users as <literal>
- username@dbname</>. When <literal>username</> is passed by the client,
- <literal>@</> and the database name is appended to the user name and
- that database-specific user name is looked up by the server.
- When creating user names containing <literal>@</>, you will need
- to quote the user name.
+ This allows per-database user names. It is off by default.
+ </para>
+
+ <para>
+ If this is on, create users as <literal> username@dbname</>.
+ When <literal>username</> is passed by a connecting client,
+ <literal>@</> and the database name is appended to the user
+ name and that database-specific user name is looked up by the
+ server. Note that when you create users with names containing
+ <literal>@</> within the SQL environment, you will need to
+ quote the user name.
</para>
+
<para>
- With this option enabled, you can still create ordinary global
- users. Simply append <literal>@</> when specifying the user name
- in the client. The <literal>@</> will be stripped off and looked up
- by the server.
+ With this option enabled, you can still create ordinary global
+ users. Simply append <literal>@</> when specifying the user
+ name in the client. The <literal>@</> will be stripped off
+ before the user name is looked up by the server.
</para>
+
+ <note>
+ <para>
+ This feature is intended as a temporary measure until a
+ complete solution is found. At that time, this option will
+ be removed.
+ </para>
+ </note>
</listitem>
</varlistentry>
</para>
<para>
- Consult the <citetitle>PostgreSQL User's Guide</citetitle> and
+ Consult the &cite-user; and
the command <command>SET TRANSACTION</command> for more
information.
</para>
distribution are installed. (Use <literal>pg_config
--pkglibdir</literal> to print the name of this directory.) For
example:
- <informalexample>
<programlisting>
dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</programlisting>
- </informalexample>
</para>
<para>
<listitem>
<para>
When a password is specified in <command>CREATE USER</> or
- <command>ALTER USER</> without writing either ENCRYPTED or
- UNENCRYPTED, this flag determines whether the password is to be
+ <command>ALTER USER</> without writing either <literal>ENCRYPTED</> or
+ <literal>UNENCRYPTED</>, this flag determines whether the password is to be
encrypted. The default is on (encrypt the password).
</para>
</listitem>
<indexterm><primary>namespaces</></>
<listitem>
<para>
- This variable specifies the order in which namespaces are searched
- when an object (table, data type, function, etc) is referenced by a
+ This variable specifies the order in which schemas are searched
+ when an object (table, data type, function, etc.) is referenced by a
simple name with no schema component. When there are objects of
- identical names in different namespaces, the one found first
+ identical names in different schemas, the one found first
in the search path is used. An object that is not in any of the
- namespaces in the search path can only be referenced by specifying
- its containing namespace with a qualified (dotted) name.
+ schemas in the search path can only be referenced by specifying
+ its containing schema with a qualified (dotted) name.
</para>
<para>
- The value for search_path has to be a comma-separated
- list of namespace (schema) names. If one of the list items is
- the special value <literal>$user</literal>, then the namespace
- having the same name as the SESSION_USER is substituted, if there
- is such a namespace. (If not, <literal>$user</literal> is ignored.)
+ The value for <varname>search_path</varname> has to be a comma-separated
+ list of schema names. If one of the list items is
+ the special value <literal>$user</literal>, then the schema
+ having the same name as the <function>SESSION_USER</> is substituted, if there
+ is such a schema. (If not, <literal>$user</literal> is ignored.)
</para>
<para>
- The system catalog namespace, <literal>pg_catalog</>, is always
+ The system catalog schema, <literal>pg_catalog</>, is always
searched, whether it is mentioned in the path or not. If it is
mentioned in the path then it will be searched in the specified
order. If <literal>pg_catalog</> is not in the path then it will
be searched <emphasis>before</> searching any of the path items.
- It should also be noted that the temporary-table namespace,
- <literal>pg_temp_nnn</>, is implicitly searched before any of
+ It should also be noted that the temporary-table schema,
+ <literal>pg_temp_<replaceable>nnn</></>, is implicitly searched before any of
these.
</para>
<para>
When objects are created without specifying a particular target
- namespace, they will be placed in the first namespace listed
+ schema, they will be placed in the first schema listed
in the search path. An error is reported if the search path is
empty.
</para>
<para>
The default value for this parameter is
<literal>'$user, public'</literal> (where the second part will be
- ignored if there is no namespace named <literal>public</>).
+ ignored if there is no schema named <literal>public</>).
This supports shared use of a database (where no users
- have private namespaces, and all share use of <literal>public</>),
- private per-user namespaces, and combinations of these. Other
+ have private schemas, and all share use of <literal>public</>),
+ private per-user schemas, and combinations of these. Other
effects can be obtained by altering the default search path
setting, either globally or per-user.
</para>
- <para>
- By default, a newly created database will contain a world-writable
- namespace named <literal>public</>, but no private namespaces.
- The administrator may choose to restrict permissions on
- <literal>public</> or even remove it, if that suits his purposes.
- </para>
-
<para>
<indexterm>
<primary>schemas</primary>
shows how the requests appearing in <varname>search_path</varname>
were resolved.
</para>
+
+ <para>
+ For more information on schema handling, see the &cite-user;.
+ </para>
</listitem>
</varlistentry>
<term><varname>SILENT_MODE</varname> (<type>bool</type>)</term>
<listitem>
<para>
- Runs postmaster silently. If this option is set, the postmaster
+ Runs the server silently. If this option is set, the server
will automatically run in background and any controlling ttys
are disassociated, thus no messages are written to standard
- output or standard error (same effect as postmaster's -S
+ output or standard error (same effect as <command>postmaster</>'s <option>-S</option>
option). Unless some logging system such as
<application>syslog</> is enabled, using this option is
discouraged since it makes it impossible to see error messages.
<para>
Specifies the amount of memory to be used by internal sorts and
hashes before switching to temporary disk files. The value is
- specified in kilobytes, and defaults to 1024 kilobytes (1MB).
+ specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
Note that for a complex query, several sorts might be running in
parallel, and each one will be allowed to use as much memory as
this value specifies before it starts to put data into temporary
files. Also, each running backend could be doing one or more
sorts simultaneously, so the total memory used could be many
times the value of <varname>SORT_MEM</varname>. Sorts are used
- by ORDER BY, merge joins, and CREATE INDEX.
+ by <literal>ORDER BY</>, merge joins, and <command>CREATE INDEX</>.
</para>
</listitem>
</varlistentry>
behavior you can set this variable to off, but in the long run
you are encouraged to change your applications to use the
<literal>ONLY</literal> keyword to exclude subtables. See the
- SQL language reference and the <citetitle>User's
- Guide</citetitle> for more information about inheritance.
+ SQL language reference and the &cite-user; for more information about inheritance.
</para>
</listitem>
</varlistentry>
<para>
Sets the time zone for displaying and interpreting timestamps.
The default is to use whatever the system environment
- specifies as the timezone.
+ specifies as the time zone.
</para>
</listitem>
</varlistentry>
<literal><replaceable>expr</> = NULL</literal> (or <literal>NULL
= <replaceable>expr</></literal>) are treated as
<literal><replaceable>expr</> IS NULL</literal>, that is, they
- return true if <replaceable>expr</> evaluates to the NULL value,
+ return true if <replaceable>expr</> evaluates to the null value,
and false otherwise. The correct behavior of
<literal><replaceable>expr</> = NULL</literal> is to always
- return NULL (unknown). Therefore this option defaults to off.
+ return null (unknown). Therefore this option defaults to off.
</para>
<para>
null values, so if you use that interface to access the database you
might want to turn this option on. Since expressions of the
form <literal><replaceable>expr</> = NULL</literal> always
- return NULL (using the correct interpretation) they are not
+ return the null value (using the correct interpretation) they are not
very useful and do not appear often in normal applications, so
this option does little harm in practice. But new users are
frequently confused about the semantics of expressions
- involving NULL, so this option is not on by default.
+ involving null values, so this option is not on by default.
</para>
<para>
</para>
<para>
- Refer to the <citetitle>User's Guide</citetitle> for related
- information.
+ Refer to the &cite-user; for related information.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the directory of the Unix-domain socket on which the
- <application>postmaster</application> is to listen for
+ server is to listen for
connections from client applications. The default is normally
<filename>/tmp</filename>, but can be changed at build time.
</para>
<para>
Sets the group owner of the Unix domain socket. (The owning
user of the socket is always the user that starts the
- postmaster.) In combination with the option
+ server.) In combination with the option
<option>UNIX_SOCKET_PERMISSIONS</option> this can be used as
an additional access control mechanism for this socket type.
By default this is the empty string, which uses the default
anyone can connect. Reasonable alternatives are
<literal>0770</literal> (only user and group, see also under
<option>UNIX_SOCKET_GROUP</option>) and <literal>0700</literal>
- (only user). (Note that actually for a Unix socket, only write
+ (only user). (Note that actually for a Unix domain socket, only write
permission matters and there is no point in setting or revoking
read or execute permissions.)
</para>
enough additional transactions may become ready to commit within
the given interval. But the delay is just wasted if no other
transactions become ready to commit. Therefore, the delay is
- only performed if at least COMMIT_SIBLINGS other transactions
- are active at the instant that a backend has written its commit
+ only performed if at least <varname>COMMIT_SIBLINGS</varname> other transactions
+ are active at the instant that a backend process has written its commit
record.
</para>
</listitem>
<term><varname>WAL_DEBUG</varname> (<type>integer</type>)</term>
<listitem>
<para>
- If non-zero, turn on WAL-related debugging output on standard
+ If nonzero, turn on WAL-related debugging output on standard
error.
</para>
</listitem>
</sect2>
- <sect2 id="runtime-config-short">
- <title>Short options</title>
+ <sect2 id="runtime-config-short">
+ <title>Short Options</title>
+
<para>
For convenience there are also single letter option switches
- available for many parameters. They are described in the following
- table.
+ available for many parameters. They are described in <xref
+ linkend="runtime-config-short-table">.
+ </para>
- <table>
+ <table id="runtime-config-short-table">
<title>Short option key</title>
- <tgroup cols="3">
- <colspec colnum="3" align="center">
+ <tgroup cols="2">
<thead>
<row>
<entry>Short option</entry>
<entry>Equivalent</entry>
- <entry>Remark</entry>
</row>
</thead>
+
<tbody>
<row>
<entry><option>-B <replaceable>x</replaceable></option></entry>
<entry><literal>shared_buffers = <replaceable>x</replaceable></></entry>
- <entry></entry>
</row>
<row>
<entry><option>-d <replaceable>x</replaceable></option></entry>
- <entry><literal>server_min_messages = <replaceable>DEBUGx</replaceable></></entry>
- <entry></entry>
+ <entry><literal>server_min_messages = DEBUG<replaceable>x</replaceable></></entry>
</row>
<row>
<entry><option>-F</option></entry>
<entry><literal>fsync = off</></entry>
- <entry></entry>
</row>
<row>
<entry><option>-h <replaceable>x</replaceable></option></entry>
<entry><literal>virtual_host = <replaceable>x</replaceable></></entry>
- <entry></entry>
</row>
<row>
<entry><option>-i</option></entry>
<entry><literal>tcpip_socket = on</></entry>
- <entry></entry>
</row>
<row>
<entry><option>-k <replaceable>x</replaceable></option></entry>
<entry><literal>unix_socket_directory = <replaceable>x</replaceable></></entry>
- <entry></entry>
</row>
<row>
<entry><option>-l</option></entry>
<entry><literal>ssl = on</></entry>
- <entry></entry>
</row>
<row>
<entry><option>-N <replaceable>x</replaceable></option></entry>
<entry><literal>max_connections = <replaceable>x</replaceable></></entry>
- <entry></entry>
</row>
<row>
<entry><option>-p <replaceable>x</replaceable></option></entry>
<entry><literal>port = <replaceable>x</replaceable></></entry>
- <entry></entry>
</row>
<row>
- <entry><option>-fi</option>, <option>-fh</option>, <option>-fm</option>, <option>-fn</option>, <option>-fs</option>, <option>-ft</option></entry>
- <entry><literal>enable_indexscan=off</>, <literal>enable_hashjoin=off</>,
- <literal>enable_mergejoin=off</>, <literal>enable_nestloop=off</>, <literal>enable_seqscan=off</>,
- <literal>enable_tidscan=off</></entry>
- <entry>*</entry>
+ <entry>
+ <option>-fi</option>, <option>-fh</option>,
+ <option>-fm</option>, <option>-fn</option>,
+ <option>-fs</option>, <option>-ft</option><footnote
+ id="fn.runtime-config-short">
+ <para>
+ For historical reasons, these options must be passed to
+ the individual backend process via the <option>-o</option>
+ postmaster option, for example,
+<screen>
+$ <userinput>postmaster -o '-S 1024 -s'</userinput>
+</screen>
+ or via <envar>PGOPTIONS</envar> from the client side, as
+ explained above.
+ </para>
+ </footnote>
+ </entry>
+ <entry>
+ <literal>enable_indexscan=off</>,
+ <literal>enable_hashjoin=off</>,
+ <literal>enable_mergejoin=off</>,
+ <literal>enable_nestloop=off</>,
+ <literal>enable_seqscan=off</>,
+ <literal>enable_tidscan=off</>
+ </entry>
</row>
+
<row>
- <entry><option>-S <replaceable>x</replaceable></option></entry>
- <entry><literal>sort_mem = <replaceable>x</replaceable></></entry>
- <entry>*</entry>
+ <entry><option>-s</option><footnoteref linkend="fn.runtime-config-short"></entry>
+ <entry><literal>show_statement_stats = on</></entry>
</row>
+
<row>
- <entry><option>-s</option></entry>
- <entry><literal>show_statement_stats = on</></entry>
- <entry>*</entry>
+ <entry><option>-S <replaceable>x</replaceable></option><footnoteref linkend="fn.runtime-config-short">
+ </entry>
+ <entry><literal>sort_mem = <replaceable>x</replaceable></></entry>
</row>
+
<row>
- <entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option></entry>
+ <entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option><footnoteref linkend="fn.runtime-config-short"></entry>
<entry><literal>show_parser_stats=on</>, <literal>show_planner_stats=on</>, <literal>show_executor_stats=on</></entry>
- <entry>*</entry>
</row>
</tbody>
</tgroup>
</table>
- For historical reasons, options marked <quote>*</quote> must be
- passed to the individual backend process via the
- <option>-o</option> postmaster option, for example,
-<screen>
-$ <userinput>postmaster -o '-S 1024 -s'</userinput>
-</screen>
- or via <envar>PGOPTIONS</envar> from the client side, as explained
- above.
- </para>
- </sect2>
+ </sect2>
</sect1>
<row>
<entry><varname>SHMMAX</></>
<entry>Maximum size of shared memory segment (bytes)</>
- <entry>250kB + 8.2kB * <varname>shared_buffers</> + 14.2kB * <varname>max_connections</> or infinity</entry>
+ <entry>250kB + 8.2 kB * <varname>shared_buffers</> + 14.2 kB * <varname>max_connections</> or infinity</entry>
</row>
<row>
mind that shared memory is not pageable; it is locked in RAM.
To increase the number of shared buffers supported by the
postmaster, add the following to your kernel configuration
- file. A <varname>SHMALL</> value of 1024 represents 4MB of
+ file. A <varname>SHMALL</> value of 1024 represents 4 MB of
shared memory. The following increases the maximum shared
memory area to 32 MB:
<programlisting>
<para>
For those running 4.1 or later, just make the above changes,
recompile the kernel, and reboot. For those running earlier
- releases, use <application>bpatch</> to find the
+ releases, use <command>bpatch</> to find the
<varname>sysptsize</> value in the current kernel. This is
computed dynamically at boot time.
<screen>
<sect1 id="postmaster-shutdown">
- <title>Shutting down the server</title>
+ <title>Shutting Down the Server</title>
<para>
There are several ways to shut down the database server. You control
<para>
With SSL support compiled in, the <productname>PostgreSQL</> server
- can be started with the argument <option>-l</> (ell) to enable
- SSL connections. When starting in SSL mode, the server will look
- for the files <filename>server.key</> and <filename>server.crt</> in
- the data directory. These files should contain the server private key
- and certificate respectively. These files must be set up correctly
- before an SSL-enabled server can start. If the private key is protected
- with a passphrase, the server will prompt for the passphrase and will
- not start until it has been entered.
+ can be started with SSL support by setting the parameter
+ <varname>ssl</varname> to on in
+ <filename>postgresql.conf</filename>. When starting in SSL mode,
+ the server will look for the files <filename>server.key</> and
+ <filename>server.crt</> in the data directory. These files should
+ contain the server private key and certificate respectively. These
+ files must be set up correctly before an SSL-enabled server can
+ start. If the private key is protected with a passphrase, the
+ server will prompt for the passphrase and will not start until it
+ has been entered.
</para>
<para>
For details on how to create your server private key and certificate,
refer to the <productname>OpenSSL</> documentation. A simple
self-signed certificate can be used to get started for testing, but a
- certificate signed by a <acronym>CA</> (either one of the global
+ certificate signed by a certificate authority (<acronym>CA</>) (either one of the global
<acronym>CAs</> or a local one) should be used in production so the
client can verify the server's identity. To create a quick
self-signed certificate, use the following
<productname>OpenSSL</productname> command:
<programlisting>
-cd <replaceable>$PGDATA</replaceable>
openssl req -new -text -out server.req
</programlisting>
Fill out the information that <command>openssl</> asks for. Make sure
that you enter the local host name as Common Name; the challenge
password can be left blank. The script will generate a key that is
- passphrase protected; it will not accept a pass phrase that is less
+ passphrase protected; it will not accept a passphrase that is less
than four characters long. To remove the passphrase (as you must if
you want automatic start-up of the server), run the commands
<programlisting>
</sect1>
<sect1 id="ssh-tunnels">
- <title>Secure TCP/IP Connections with <application>SSH</application> tunnels</title>
+ <title>Secure TCP/IP Connections with <application>SSH</application> Tunnels</title>
<indexterm zone="ssh-tunnels">
<primary>ssh</primary>
</note>
<para>
- One can use <productname>ssh</productname> to encrypt the network
+ One can use <application>SSH</application> to encrypt the network
connection between clients and a
<productname>PostgreSQL</productname> server. Done properly, this
- should lead to an adequately secure network connection.
+ provides an adequately secure network connection.
</para>
<para>
- First make sure that an <application>ssh</application> server is
+ First make sure that an <application>SSH</application> server is
running properly on the same machine as
<productname>PostgreSQL</productname> and that you can log in using
<command>ssh</command> as some user. Then you can establish a secure
tunnel with a command like this from the client machine:
<programlisting>
-$ <userinput>ssh -L 3333:foo.com:5432 joe@foo.com</userinput>
+ssh -L 3333:foo.com:5432 joe@foo.com
</programlisting>
The first number in the <option>-L</option> argument, 3333, is the
port number of your end of the tunnel; it can be chosen freely. The
<tip>
<para>
- Several other products exist that can provide secure tunnels using
+ Several other applications exist that can provide secure tunnels using
a procedure similar in concept to the one just described.
</para>
</tip>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.26 2002/10/24 17:48:54 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.26.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="tutorial-start">
<listitem>
<para>
Using an existing graphical frontend tool like
- <application>PgAccess</application> or
- <application>ApplixWare</application> (via
- <acronym>ODBC</acronym>) to create and manipulate a database.
- These possibilities are not covered in this tutorial.
+ <application>PgAccess</application> or an office suite with
+ <acronym>ODBC</acronym> support to create and manipulate a
+ database. These possibilities are not covered in this
+ tutorial.
</para>
</listitem>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.17 2002/10/24 17:48:54 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.17.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="user-manag">
<para>
A password is only significant if the client authentication
method requires the user to supply a password when connecting
- to the database. At present, the <option>password</>,
+ to the database. The <option>password</>,
<option>md5</>, and <option>crypt</> authentication methods
make use of passwords. Database passwords are separate from
operating system passwords. Specify a password upon user
ALTER USER myname SET enable_indexscan TO off;
</programlisting>
This will save the setting (but not set it immediately) and in
- subsequent connections it will appear as though <literal>SET geqo
+ subsequent connections it will appear as though <literal>SET enable_indexscan
TO off;</literal> had been called right before the session started.
You can still alter this setting during the session; it will only
be the default. To undo any such setting, use <literal>ALTER USER
<literal>USAGE</>, and <literal>ALL PRIVILEGES</>. For more
information on the different types of privileges support by
<productname>PostgreSQL</productname>, refer to the
- <command>GRANT</command> reference manual. The right to modify or
+ <command>GRANT</command> page in the &cite-reference;. The right to modify or
destroy an object is always the privilege of the owner only. To
assign privileges, the <command>GRANT</command> command is
used. So, if <literal>joe</literal> is an existing user, and
projects / postgresql / commitdiff