Skip to content

P
Postgres FD Implementation
Commit 1c882e07 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Split contrib documentation into extensions and programs 

Create separate appendixes for contrib extensions and other server
plugins on the one hand, and utility programs on the other.  Recast
the documentation of the latter as refentries, so that man pages are
generated.
parent 4f696030
Hide whitespace changes
Inline Side-by-side
Showing with 597 additions and 361 deletions
doc/src/sgml/contrib.sgml
View file @ 1c882e07
......@@ -4,7 +4,7 @@
<title>Additional Supplied Modules</title>
<para>
This appendix contains information regarding the modules that
This appendix and the next one contain information regarding the modules that
can be found in the <literal>contrib</literal> directory of the
<productname>PostgreSQL</> distribution.
These include porting tools, analysis utilities,
......@@ -15,7 +15,13 @@
</para>
<para>
When building from the source distribution, these modules are not built
This appendix covers extensions and other server plug-in modules found in
<literal>contrib</literal>. <xref linkend="contrib-prog"> covers utility
programs.
</para>
<para>
When building from the source distribution, these components are not built
automatically, unless you build the "world" target
(see <xref linkend="build">).
You can build and install all of them by running:
......@@ -88,6 +94,14 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
<xref linkend="extend-extensions">.
</para>
<para>
Note, however, that some of these modules are not <quote>extensions</quote>
in this sense, but are loaded into the server in some other way, for instance
by way of
<xref linkend="guc-shared-preload-libraries">. See the documentation of each
module for details.
</para>
&adminpack;
&auth-delay;
&auto-explain;
......@@ -109,22 +123,15 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
&isn;
&lo;
&ltree;
&oid2name;
&pageinspect;
&passwordcheck;
&pgarchivecleanup;
&pgbench;
&pgbuffercache;
&pgcrypto;
&pgfreespacemap;
&pgrowlocks;
&pgstandby;
&pgstatstatements;
&pgstattuple;
&pgtestfsync;
&pgtesttiming;
&pgtrgm;
&pgupgrade;
&seg;
&sepgsql;
&contrib-spi;
......@@ -135,7 +142,69 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
&tsearch2;
&unaccent;
&uuid-ossp;
&vacuumlo;
&xml2;
</appendix>
<!--
These are two separate appendixes because it is difficult to mix regular
sections (for extensions) and refentries (for programs) in one chapter or
appendix. And we do want the programs as refentries so that we can produce man
pages.
-->
<appendix id="contrib-prog">
<title>Additional Supplied Programs</title>
<para>
This appendix and the previous one contain information regarding the modules that
can be found in the <literal>contrib</literal> directory of the
<productname>PostgreSQL</> distribution. See <xref linkend="contrib"> for
more information about the <literal>contrib</literal> section in general and
server extensions and plug-ins found in <literal>contrib</literal>
specifically.
</para>
<para>
This appendix covers utility programs found in <literal>contrib</literal>.
Once installed, either from source or a packaging system, they are found in
the <filename>bin</filename> directory of the
<productname>PostgreSQL</productname> installation and can be used like any
other program.
</para>
<sect1 id="contrib-prog-client">
<title>Client Applications</title>
<para>
This section covers <productname>PostgreSQL</productname> client
applications in <literal>contrib</literal>. They can be run from anywhere,
independent of where the database server resides. See
also <xref linkend="reference-client"> for information about client
applications that part of the core <productname>PostgreSQL</productname>
distribution.
</para>
&oid2name;
&pgbench;
&vacuumlo;
</sect1>
<sect1 id="contrib-prog-server">
<title>Server Applications</title>
<para>
This section covers <productname>PostgreSQL</productname> server-related
applications in <literal>contrib</literal>. They are typically run on the
host where the database server resides. See also <xref
linkend="reference-server"> for information about server applications that
part of the core <productname>PostgreSQL</productname> distribution.
</para>
&pgarchivecleanup;
&pgstandby;
&pgtestfsync;
&pgtesttiming;
&pgupgrade;
</sect1>
</appendix>
doc/src/sgml/docguide.sgml
View file @ 1c882e07
......@@ -1240,6 +1240,15 @@ save_size.pdfjadetex = 15000
</listitem>
</varlistentry>
<varlistentry>
<term>Author</term>
<listitem>
<para>
Author (only used in the contrib section)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>See Also</term>
<listitem>
......
doc/src/sgml/oid2name.sgml
View file @ 1c882e07
<!-- doc/src/sgml/oid2name.sgml -->
<sect1 id="oid2name" xreflabel="oid2name">
<title>oid2name</title>
<refentry id="oid2name">
<refmeta>
<refentrytitle>oid2name</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>oid2name</refname>
<refpurpose>resolve OIDs and file nodes in a <productname>PostgreSQL</productname> data directory</refpurpose>
</refnamediv>
<indexterm zone="oid2name">
<primary>oid2name</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>oid2name</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>oid2name</> is a utility program that helps administrators to
examine the file structure used by PostgreSQL. To make use of it, you need
......@@ -24,19 +43,16 @@
</para>
</note>
<sect2>
<title>Overview</title>
<para>
<application>oid2name</application> connects to a target database and
extracts OID, filenode, and/or table name information. You can also have
it show database OIDs or tablespace OIDs.
</para>
</sect2>
</refsect1>
<sect2>
<title><application>oid2name</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>oid2name</application> accepts the following command-line arguments:
......@@ -142,9 +158,19 @@
OIDs. Alternatively you can give <option>-s</> to get a tablespace
listing.
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Notes</title>
<para>
<application>oid2name</> requires a running database server with
non-corrupt system catalogs. It is therefore of only limited use
for recovering from catastrophic database corruption situations.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
......@@ -265,24 +291,14 @@ From database "alvherre":
----------------------
155156 foo
</screen>
</sect2>
<sect2>
<title>Limitations</title>
<para>
<application>oid2name</> requires a running database server with
non-corrupt system catalogs. It is therefore of only limited use
for recovering from catastrophic database corruption situations.
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
B. Palmer <email>bpalmer@crimelabs.net</email>
</para>
</sect2>
</refsect1>
</sect1>
</refentry>
doc/src/sgml/pgarchivecleanup.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgarchivecleanup.sgml -->
<sect1 id="pgarchivecleanup" xreflabel="pg_archivecleanup">
<title>pg_archivecleanup</title>
<refentry id="pgarchivecleanup">
<refmeta>
<refentrytitle><application>pg_archivecleanup</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_archivecleanup</refname>
<refpurpose>clean up <productname>PostgreSQL</productname> WAL archive files</refpurpose>
</refnamediv>
<indexterm zone="pgarchivecleanup">
<primary>pg_archivecleanup</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_archivecleanup</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>archivelocation</replaceable></arg>
<arg choice="plain"><replaceable>oldestkeptwalfile</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_archivecleanup</> is designed to be used as an
<literal>archive_cleanup_command</literal> to clean up WAL file archives when
......@@ -15,26 +36,6 @@
clean WAL file archives.
</para>
<para>
<application>pg_archivecleanup</application> features include:
</para>
<itemizedlist>
<listitem>
<para>
Written in C, so very portable and easy to install
</para>
</listitem>
<listitem>
<para>
Easy-to-modify source code, with specifically designated
sections to modify for your own needs
</para>
</listitem>
</itemizedlist>
<sect2>
<title>Usage</title>
<para>
To configure a standby
server to use <application>pg_archivecleanup</>, put this into its
......@@ -57,14 +58,10 @@ archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r'
from the same archive location.
</para>
<para>
The full syntax of <application>pg_archivecleanup</>'s command line is
<synopsis>
pg_archivecleanup <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>restartwalfile</>
</synopsis>
When used as a standalone program all WAL files logically preceding the
<literal>restartwalfile</> will be removed <replaceable>archivelocation</>.
<replaceable>oldestkeptwalfile</> will be removed from <replaceable>archivelocation</>.
In this mode, if you specify a <filename>.backup</> file name, then only the file prefix
will be used as the <literal>restartwalfile</>. This allows you to remove
will be used as the <replaceable>oldestkeptwalfile</>. This allows you to remove
all WAL files archived prior to a specific base backup without error.
For example, the following example will remove all files older than
WAL file name <filename>000000010000003700000010</>:
......@@ -79,10 +76,10 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E"
<replaceable>archivelocation</> is a directory readable and writable by the
server-owning user.
</para>
</sect2>
</refsect1>
<sect2>
<title><application>pg_archivecleanup</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>pg_archivecleanup</application> accepts the following command-line arguments:
......@@ -124,10 +121,26 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E"
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<application>pg_archivecleanup</application> is designed to work with
<productname>PostgreSQL</> 8.0 and later when used as a standalone utility,
or with <productname>PostgreSQL</> 9.0 and later when used as an
archive cleanup command.
</para>
</sect2>
<para>
<application>pg_archivecleanup</application> is written in C and has an
easy-to-modify source code, with specifically designated sections to modify
for your own needs
</para>
</refsect1>
<sect2>
<refsect1>
<title>Examples</title>
<para>On Linux or Unix systems, you might use:
......@@ -151,26 +164,21 @@ archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>clean
</para>
</listitem>
</itemizedlist>
</refsect1>
</sect2>
<sect2>
<title>Supported Server Versions</title>
<para>
<application>pg_archivecleanup</application> is designed to work with
<productname>PostgreSQL</> 8.0 and later when used as a standalone utility,
or with <productname>PostgreSQL</> 9.0 and later when used as an
archive cleanup command.
</para>
</sect2>
<sect2>
<refsect1>
<title>Author</title>
<para>
Simon Riggs <email>simon@2ndquadrant.com</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="pgstandby"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgbench.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgbench.sgml -->
<sect1 id="pgbench" xreflabel="pgbench">
<title>pgbench</title>
<refentry id="pgbench">
<refmeta>
<refentrytitle><application>pgbench</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pgbench</refname>
<refpurpose>run a benchmark test on <productname>PostgreSQL</productname></refpurpose>
</refnamediv>
<indexterm zone="pgbench">
<primary>pgbench</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pgbench</command>
<arg choice="plain"><option>-i</option></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="opt"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pgbench</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="opt"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pgbench</application> is a simple program for running benchmark
tests on <productname>PostgreSQL</>. It runs the same sequence of SQL
......@@ -38,19 +63,16 @@ tps = 85.296346 (excluding connections establishing)
settings. The next line reports the number of transactions completed
and intended (the latter being just the product of number of clients
and number of transactions per client); these will be equal unless the run
failed before completion. (In <literal>-T</> mode, only the actual
failed before completion. (In <option>-T</> mode, only the actual
number of transactions is printed.)
The last two lines report the number of transactions per second,
figured with and without counting the time to start database sessions.
</para>
<sect2>
<title>Overview</title>
<para>
The default TPC-B-like transaction test requires specific tables to be
set up beforehand. <application>pgbench</> should be invoked with
the <literal>-i</> (initialize) option to create and populate these
the <option>-i</> (initialize) option to create and populate these
tables. (When you are testing a custom script, you don't need this
step, but will instead need to do whatever setup your test needs.)
Initialization looks like:
......@@ -60,8 +82,8 @@ pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbn
</programlisting>
where <replaceable>dbname</> is the name of the already-created
database to test in. (You may also need <literal>-h</>,
<literal>-p</>, and/or <literal>-U</> options to specify how to
database to test in. (You may also need <option>-h</>,
<option>-p</>, and/or <option>-U</> options to specify how to
connect to the database server.)
</para>
......@@ -88,38 +110,37 @@ pgbench_accounts 100000
pgbench_history 0
</screen>
You can (and, for most purposes, probably should) increase the number
of rows by using the <literal>-s</> (scale factor) option. The
<literal>-F</> (fillfactor) option might also be used at this point.
of rows by using the <option>-s</> (scale factor) option. The
<option>-F</> (fillfactor) option might also be used at this point.
</para>
<para>
Once you have done the necessary setup, you can run your benchmark
with a command that doesn't include <literal>-i</>, that is
with a command that doesn't include <option>-i</>, that is
<programlisting>
pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</programlisting>
In nearly all cases, you'll need some options to make a useful test.
The most important options are <literal>-c</> (number of clients),
<literal>-t</> (number of transactions), <literal>-T</> (time limit),
and <literal>-f</> (specify a custom script file).
The most important options are <option>-c</> (number of clients),
<option>-t</> (number of transactions), <option>-T</> (time limit),
and <option>-f</> (specify a custom script file).
See below for a full list.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<xref linkend="pgbench-init-options"> shows options that are used
during database initialization, while
<xref linkend="pgbench-run-options"> shows options that are used
while running benchmarks, and
<xref linkend="pgbench-common-options"> shows options that are useful
in both cases.
The following is divided into three subsections: Different options are used
during database initialization and while running benchmarks, some options
are useful in both cases.
</para>
</sect2>
<sect2 id="pgbench-init-options">
<title><application>pgbench</> Initialization Options</title>
<refsect2 id="pgbench-init-options">
<title>Initialization Options</title>
<para>
<application>pgbench</application> accepts the following command-line
......@@ -191,10 +212,10 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</variablelist>
</para>
</sect2>
</refsect2>
<sect2 id="pgbench-run-options">
<title><application>pgbench</> Benchmarking Options</title>
<refsect2 id="pgbench-run-options">
<title>Benchmarking Options</title>
<para>
<application>pgbench</application> accepts the following command-line
......@@ -237,7 +258,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<listitem>
<para>
Define a variable for use by a custom script (see below).
Multiple <literal>-D</> options are allowed.
Multiple <option>-D</> options are allowed.
</para>
</listitem>
</varlistentry>
......@@ -248,7 +269,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<para>
Read transaction script from <replaceable>filename</>.
See below for details.
<literal>-N</literal>, <literal>-S</literal>, and <literal>-f</literal>
<option>-N</option>, <option>-S</option>, and <option>-f</option>
are mutually exclusive.
</para>
</listitem>
......@@ -344,7 +365,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
output. With the built-in tests, this is not necessary; the
correct scale factor will be detected by counting the number of
rows in the <structname>pgbench_branches</> table. However, when testing
custom benchmarks (<literal>-f</> option), the scale factor
custom benchmarks (<option>-f</> option), the scale factor
will be reported as 1 unless this option is used.
</para>
</listitem>
......@@ -373,8 +394,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<listitem>
<para>
Run the test for this many seconds, rather than a fixed number of
transactions per client. <literal>-t</literal> and
<literal>-T</literal> are mutually exclusive.
transactions per client. <option>-t</option> and
<option>-T</option> are mutually exclusive.
</para>
</listitem>
</varlistentry>
......@@ -384,7 +405,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<listitem>
<para>
Vacuum all four standard tables before running the test.
With neither <literal>-n</> nor <literal>-v</>, pgbench will vacuum the
With neither <option>-n</> nor <option>-v</>, pgbench will vacuum the
<structname>pgbench_tellers</> and <structname>pgbench_branches</>
tables, and will truncate <structname>pgbench_history</>.
</para>
......@@ -394,10 +415,10 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</variablelist>
</para>
</sect2>
</refsect2>
<sect2 id="pgbench-common-options">
<title><application>pgbench</> Common Options</title>
<refsect2 id="pgbench-common-options">
<title>Common Options</title>
<para>
<application>pgbench</application> accepts the following command-line
......@@ -435,9 +456,13 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</variablelist>
</para>
</sect2>
</refsect2>
</refsect1>
<sect2>
<refsect1>
<title>Notes</title>
<refsect2>
<title>What is the <quote>Transaction</> Actually Performed in pgbench?</title>
<para>
......@@ -455,22 +480,22 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</orderedlist>
<para>
If you specify <literal>-N</>, steps 4 and 5 aren't included in the
transaction. If you specify <literal>-S</>, only the <command>SELECT</> is
If you specify <option>-N</>, steps 4 and 5 aren't included in the
transaction. If you specify <option>-S</>, only the <command>SELECT</> is
issued.
</para>
</sect2>
</refsect2>
<sect2>
<refsect2>
<title>Custom Scripts</title>
<para>
<application>pgbench</application> has support for running custom
benchmark scenarios by replacing the default transaction script
(described above) with a transaction script read from a file
(<literal>-f</literal> option). In this case a <quote>transaction</>
(<option>-f</option> option). In this case a <quote>transaction</>
counts as one execution of a script file. You can even specify
multiple scripts (multiple <literal>-f</literal> options), in which
multiple scripts (multiple <option>-f</option> options), in which
case a random one of the scripts is chosen each time a client session
starts a new transaction.
</para>
......@@ -485,9 +510,9 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<para>
There is a simple variable-substitution facility for script files.
Variables can be set by the command-line <literal>-D</> option,
Variables can be set by the command-line <option>-D</> option,
explained above, or by the meta commands explained below.
In addition to any variables preset by <literal>-D</> command-line options,
In addition to any variables preset by <option>-D</> command-line options,
the variable <literal>scale</> is preset to the current scale factor.
Once set, a variable's
value can be inserted into a SQL command by writing
......@@ -648,17 +673,17 @@ END;
otherwise they'd not be independently touching different rows.)
</para>
</sect2>
</refsect2>
<sect2>
<refsect2>
<title>Per-Transaction Logging</title>
<para>
With the <literal>-l</> option, <application>pgbench</> writes the time
With the <option>-l</> option, <application>pgbench</> writes the time
taken by each transaction to a log file. The log file will be named
<filename>pgbench_log.<replaceable>nnn</></filename>, where
<replaceable>nnn</> is the PID of the pgbench process.
If the <literal>-j</> option is 2 or higher, creating multiple worker
If the <option>-j</> option is 2 or higher, creating multiple worker
threads, each will have its own log file. The first worker will use the
same name for its log file as in the standard single worker case.
The additional log files for the other workers will be named
......@@ -676,7 +701,7 @@ END;
where <replaceable>time</> is the total elapsed transaction time in microseconds,
<replaceable>file_no</> identifies which script file was used
(useful when multiple scripts were specified with <literal>-f</>),
(useful when multiple scripts were specified with <option>-f</>),
and <replaceable>time_epoch</>/<replaceable>time_us</> are a
UNIX epoch format timestamp and an offset
in microseconds (suitable for creating a ISO 8601
......@@ -693,13 +718,13 @@ END;
0 202 2038 0 1175850569 2663
</screen>
</para>
</sect2>
</refsect2>
<sect2>
<refsect2>
<title>Per-Statement Latencies</title>
<para>
With the <literal>-r</> option, <application>pgbench</> collects
With the <option>-r</> option, <application>pgbench</> collects
the elapsed transaction time of each statement executed by every
client. It then reports an average of those values, referred to
as the latency for each statement, after the benchmark has finished.
......@@ -749,9 +774,9 @@ statement latencies in milliseconds:
Comparing average TPS values with and without latency reporting enabled
is a good way to measure if the timing overhead is significant.
</para>
</sect2>
</refsect2>
<sect2>
<refsect2>
<title>Good Practices</title>
<para>
......@@ -762,7 +787,7 @@ statement latencies in milliseconds:
<para>
In the first place, <emphasis>never</> believe any test that runs
for only a few seconds. Use the <literal>-t</> or <literal>-T</> option
for only a few seconds. Use the <option>-t</> or <option>-T</> option
to make the run last at least a few minutes, so as to average out noise.
In some cases you could need hours to get numbers that are reproducible.
It's a good idea to try the test run a few times, to find out if your
......@@ -771,11 +796,11 @@ statement latencies in milliseconds:
<para>
For the default TPC-B-like test scenario, the initialization scale factor
(<literal>-s</>) should be at least as large as the largest number of
clients you intend to test (<literal>-c</>); else you'll mostly be
measuring update contention. There are only <literal>-s</> rows in
(<option>-s</>) should be at least as large as the largest number of
clients you intend to test (<option>-c</>); else you'll mostly be
measuring update contention. There are only <option>-s</> rows in
the <structname>pgbench_branches</> table, and every transaction wants to
update one of them, so <literal>-c</> values in excess of <literal>-s</>
update one of them, so <option>-c</> values in excess of <option>-s</>
will undoubtedly result in lots of transactions blocked waiting for
other transactions.
</para>
......@@ -798,6 +823,6 @@ statement latencies in milliseconds:
instances concurrently, on several client machines, against the same
database server.
</para>
</sect2>
</sect1>
</refsect2>
</refsect1>
</refentry>
doc/src/sgml/pgstandby.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgstandby.sgml -->
<sect1 id="pgstandby" xreflabel="pg_standby">
<title>pg_standby</title>
<refentry id="pgstandby">
<refmeta>
<refentrytitle><application>pg_standby</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_standby</refname>
<refpurpose>supports the creation of a <productname>PostgreSQL</productname> warm standby server</refpurpose>
</refnamediv>
<indexterm zone="pgstandby">
<primary>pg_standby</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_standby</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>archivelocation</replaceable></arg>
<arg choice="plain"><replaceable>nextwalfile</replaceable></arg>
<arg choice="plain"><replaceable>xlogfilepath</replaceable></arg>
<arg choice="opt"><replaceable>restartwalfile</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_standby</> supports creation of a <quote>warm standby</>
database server. It is designed to be a production-ready program, as well
......@@ -21,31 +44,6 @@
server manual (see <xref linkend="warm-standby">).
</para>
<para>
<application>pg_standby</application> features include:
</para>
<itemizedlist>
<listitem>
<para>
Written in C, so very portable and easy to install
</para>
</listitem>
<listitem>
<para>
Easy-to-modify source code, with specifically designated
sections to modify for your own needs
</para>
</listitem>
<listitem>
<para>
Already tested on Linux and Windows
</para>
</listitem>
</itemizedlist>
<sect2>
<title>Usage</title>
<para>
To configure a standby
server to use <application>pg_standby</>, put this into its
......@@ -56,16 +54,6 @@ restore_command = 'pg_standby <replaceable>archiveDir</> %f %p %r'
where <replaceable>archiveDir</> is the directory from which WAL segment
files should be restored.
</para>
<para>
The full syntax of <application>pg_standby</>'s command line is
<synopsis>
pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>nextwalfile</> <replaceable>xlogfilepath</> <optional> <replaceable>restartwalfile</> </optional>
</synopsis>
When used within <varname>restore_command</>, the <literal>%f</> and
<literal>%p</> macros should be specified for <replaceable>nextwalfile</>
and <replaceable>xlogfilepath</> respectively, to provide the actual file
and path required for the restore.
</para>
<para>
If <replaceable>restartwalfile</> is specified, normally by using the
<literal>%r</literal> macro, then all WAL files logically preceding this
......@@ -118,10 +106,10 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<title><application>pg_standby</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>pg_standby</application> accepts the following command-line arguments:
......@@ -226,9 +214,36 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
</variablelist>
</para>
</sect2>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<application>pg_standby</application> is designed to work with
<productname>PostgreSQL</> 8.2 and later.
</para>
<para>
<productname>PostgreSQL</> 8.3 provides the <literal>%r</literal> macro,
which is designed to let <application>pg_standby</application> know the
last file it needs to keep. With <productname>PostgreSQL</> 8.2, the
<literal>-k</literal> option must be used if archive cleanup is
required. This option remains available in 8.3, but its use is deprecated.
</para>
<para>
<productname>PostgreSQL</> 8.4 provides the
<varname>recovery_end_command</> option. Without this option
a leftover trigger file can be hazardous.
</para>
<para>
<application>pg_standby</application> is written in C and has an
easy-to-modify source code, with specifically designated sections to modify
for your own needs
</para>
</refsect1>
<sect2>
<refsect1>
<title>Examples</title>
<para>On Linux or Unix systems, you might use:
......@@ -339,35 +354,21 @@ recovery_end_command = 'del C:\pgsql.trigger.5442'
network.
</para>
</sect2>
<sect2>
<title>Supported Server Versions</title>
</refsect1>
<para>
<application>pg_standby</application> is designed to work with
<productname>PostgreSQL</> 8.2 and later.
</para>
<para>
<productname>PostgreSQL</> 8.3 provides the <literal>%r</literal> macro,
which is designed to let <application>pg_standby</application> know the
last file it needs to keep. With <productname>PostgreSQL</> 8.2, the
<literal>-k</literal> option must be used if archive cleanup is
required. This option remains available in 8.3, but its use is deprecated.
</para>
<para>
<productname>PostgreSQL</> 8.4 provides the
<varname>recovery_end_command</> option. Without this option
a leftover trigger file can be hazardous.
</para>
</sect2>
<sect2>
<refsect1>
<title>Author</title>
<para>
Simon Riggs <email>simon@2ndquadrant.com</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="pgarchivecleanup"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgtestfsync.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgtestfsync.sgml -->
<sect1 id="pgtestfsync" xreflabel="pg_test_fsync">
<title>pg_test_fsync</title>
<refentry id="pgtestfsync">
<refmeta>
<refentrytitle><application>pg_test_fsync</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_test_fsync</refname>
<refpurpose>determine fastest wal_sync_method for <productname>PostgreSQL</productname></refpurpose>
</refnamediv>
<indexterm zone="pgtestfsync">
<primary>pg_test_fsync</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_fsync</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_test_fsync</> is intended to give you a reasonable
idea of what the fastest <xref linkend="guc-wal-sync-method"> is on your
......@@ -17,13 +36,10 @@
since many database servers are not speed-limited by their transaction
logs.
</para>
</refsect1>
<sect2>
<title>Usage</title>
<synopsis>
pg_test_fsync [options]
</synopsis>
<refsect1>
<title>Options</title>
<para>
<application>pg_test_fsync</application> accepts the following
......@@ -62,14 +78,21 @@ pg_test_fsync [options]
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
Bruce Momjian <email>bruce@momjian.us</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="app-postgres"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgtesttiming.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgtesttiming.sgml -->
<sect1 id="pgtesttiming" xreflabel="pg_test_timing">
<title>pg_test_timing</title>
<refentry id="pgtesttiming">
<refmeta>
<refentrytitle><application>pg_test_timing</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_test_timing</refname>
<refpurpose>measure timing overhead</refpurpose>
</refnamediv>
<indexterm zone="pgtesttiming">
<primary>pg_test_timing</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_timing</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_test_timing</> is a tool to measure the timing overhead
on your system and confirm that the system time never moves backwards.
Systems that are slow to collect timing data can give less accurate
<command>EXPLAIN ANALYZE</command> results.
</para>
</refsect1>
<sect2>
<title>Usage</title>
<synopsis>
pg_test_timing [options]
</synopsis>
<refsect1>
<title>Options</title>
<para>
<application>pg_test_timing</application> accepts the following
......@@ -43,9 +59,12 @@ pg_test_timing [options]
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Usage</title>
<refsect2>
<title>Interpreting results</title>
<para>
......@@ -74,8 +93,8 @@ Histogram of timing durations:
one microsecond (usec).
</para>
</sect2>
<sect2>
</refsect2>
<refsect2>
<title>Measuring executor timing overhead</title>
<para>
......@@ -103,8 +122,9 @@ EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
timing overhead would be less problematic.
</para>
</sect2>
<sect2>
</refsect2>
<refsect2>
<title>Changing time sources</title>
<para>
On some newer Linux systems, it's possible to change the clock
......@@ -178,8 +198,8 @@ Histogram of timing durations:
1: 27694571 90.23734%
</screen>
</sect2>
<sect2>
</refsect2>
<refsect2>
<title>Clock hardware and timing accuracy</title>
<para>
......@@ -248,14 +268,22 @@ Histogram of timing durations:
Programmable Interrupt Controller (APIC) timer, and the Cyclone
timer. These timers aim for millisecond resolution.
</para>
</sect2>
</refsect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
Ants Aasma <email>ants.aasma@eesti.ee</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="sql-explain"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgupgrade.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgupgrade.sgml -->
<sect1 id="pgupgrade" xreflabel="pg_upgrade">
<title>pg_upgrade</title>
<refentry id="pgupgrade">
<refmeta>
<refentrytitle><application>pg_upgrade</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_upgrade</refname>
<refpurpose>upgrade a <productname>PostgreSQL</productname> server instance</refpurpose>
</refnamediv>
<indexterm zone="pgupgrade">
<primary>pg_upgrade</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_upgrade</command>
<arg choice="plain"><option>-b</option></arg>
<arg choice="plain"><replaceable>oldbindir</replaceable></arg>
<arg choice="plain"><option>-B</option></arg>
<arg choice="plain"><replaceable>newbindir</replaceable></arg>
<arg choice="plain"><option>-d</option></arg>
<arg choice="plain"><replaceable>olddatadir</replaceable></arg>
<arg choice="plain"><option>-D</option></arg>
<arg choice="plain"><replaceable>newdatadir</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_upgrade</> (formerly called <application>pg_migrator</>) allows data
stored in <productname>PostgreSQL</> data files to be upgraded to a later <productname>PostgreSQL</>
......@@ -37,19 +64,14 @@
be checked by <application>pg_upgrade</>.
</para>
<sect2>
<title>Supported Versions</title>
<para>
pg_upgrade supports upgrades from 8.3.X and later to the current
major release of <productname>PostgreSQL</>, including snapshot and alpha releases.
</para>
</refsect1>
</sect2>
<sect2>
<title><application>pg_upgrade</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>pg_upgrade</application> accepts the following command-line arguments:
......@@ -160,10 +182,15 @@
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<title>Upgrade Steps</title>
<refsect1>
<title>Usage</title>
<para>
These are the steps to perform an upgrade
with <application>pg_upgrade</application>:
</para>
<procedure>
<step performance="optional">
......@@ -459,13 +486,54 @@ psql --username postgres --file script.sql postgres
</step>
</procedure>
</sect2>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<application>pg_upgrade</> does not support upgrading of databases
containing these <type>reg*</> OID-referencing system data types:
<type>regproc</>, <type>regprocedure</>, <type>regoper</>,
<type>regoperator</>, <type>regconfig</>, and
<type>regdictionary</>. (<type>regtype</> can be upgraded.)
</para>
<para>
All failure, rebuild, and reindex cases will be reported by
<application>pg_upgrade</> if they affect your installation;
post-upgrade scripts to rebuild tables and indexes will be
generated automatically.
</para>
<para>
For deployment testing, create a schema-only copy of the old cluster,
insert dummy data, and upgrade that.
</para>
<para>
If you are upgrading a pre-<productname>PostgreSQL</> 9.2 cluster
that uses a configuration-file-only directory, you must pass the
real data directory location to <application>pg_upgrade</>, and
pass the configuration directory location to the server, e.g.
<literal>-d /real-data-directory -o '-D /configuration-directory'</>.
</para>
<para>
If you want to use link mode and you do not want your old cluster
to be modified when the new cluster is started, make a copy of the
old cluster and upgrade that in link mode. To make a valid copy
of the old cluster, use <command>rsync</> to create a dirty
copy of the old cluster while the server is running, then shut down
the old server and run <command>rsync</> again to update the copy with any
changes to make it consistent.
</para>
<sect2>
<title>Limitations in Upgrading <emphasis>from</> PostgreSQL 8.3</title>
<refsect2>
<title>Limitations in Upgrading PostgreSQL 8.3</title>
<para>
Upgrading from PostgreSQL 8.3 has additional restrictions not present
Upgrading <emphasis>from</emphasis> PostgreSQL 8.3 has additional restrictions not present
when upgrading from later PostgreSQL releases. For example,
pg_upgrade will not work for upgrading from 8.3 if a user column
is defined as:
......@@ -534,49 +602,18 @@ psql --username postgres --file script.sql postgres
possible to upgrade from the MSI installer to the one-click installer.
</para>
</sect2>
<sect2>
<title>Notes</title>
<para>
<application>pg_upgrade</> does not support upgrading of databases
containing these <type>reg*</> OID-referencing system data types:
<type>regproc</>, <type>regprocedure</>, <type>regoper</>,
<type>regoperator</>, <type>regconfig</>, and
<type>regdictionary</>. (<type>regtype</> can be upgraded.)
</para>
<para>
All failure, rebuild, and reindex cases will be reported by
<application>pg_upgrade</> if they affect your installation;
post-upgrade scripts to rebuild tables and indexes will be
generated automatically.
</para>
</refsect2>
<para>
For deployment testing, create a schema-only copy of the old cluster,
insert dummy data, and upgrade that.
</para>
<para>
If you are upgrading a pre-<productname>PostgreSQL</> 9.2 cluster
that uses a configuration-file-only directory, you must pass the
real data directory location to <application>pg_upgrade</>, and
pass the configuration directory location to the server, e.g.
<literal>-d /real-data-directory -o '-D /configuration-directory'</>.
</para>
<para>
If you want to use link mode and you do not want your old cluster
to be modified when the new cluster is started, make a copy of the
old cluster and upgrade that in link mode. To make a valid copy
of the old cluster, use <command>rsync</> to create a dirty
copy of the old cluster while the server is running, then shut down
the old server and run <command>rsync</> again to update the copy with any
changes to make it consistent.
</para>
</refsect1>
</sect2>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="app-initdb"></member>
<member><xref linkend="app-pg-ctl"></member>
<member><xref linkend="app-pgdump"></member>
<member><xref linkend="app-postgres"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/stylesheet-man.xsl
View file @ 1c882e07
......@@ -30,6 +30,16 @@
<!-- Custom templates -->
<!-- Improve output of email element. See also
<https://sourceforge.net/tracker/?func=detail&aid=3524417&group_id=21935&atid=373747>
-->
<xsl:template match="email">
<xsl:text>&lt;</xsl:text>
<xsl:apply-templates/>
<xsl:text>&gt;</xsl:text>
</xsl:template>
<xsl:template match="refentry" mode="xref-to">
<xsl:param name="referrer"/>
<xsl:param name="xrefstyle"/>
......
doc/src/sgml/vacuumlo.sgml
View file @ 1c882e07
<!-- doc/src/sgml/vacuumlo.sgml -->
<sect1 id="vacuumlo" xreflabel="vacuumlo">
<title>vacuumlo</title>
<refentry id="vacuumlo">
<refmeta>
<refentrytitle><application>vacuumlo</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vacuumlo</refname>
<refpurpose>remove orphaned large objects from a <productname>PostgreSQL</productname> database</refpurpose>
</refnamediv>
<indexterm zone="vacuumlo">
<primary>vacuumlo</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>vacuumlo</command>
<arg choice="opt" rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>vacuumlo</> is a simple utility program that will remove any
<quote>orphaned</> large objects from a
......@@ -22,30 +42,19 @@
to avoid creating orphaned LOs in the first place.
</para>
<sect2>
<title>Usage</title>
<synopsis>
vacuumlo [options] database [database2 ... databaseN]
</synopsis>
<para>
All databases named on the command line are processed. Available options
include:
All databases named on the command line are processed.
</para>
</refsect1>
<variablelist>
<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Write a lot of progress messages.</para>
</listitem>
</varlistentry>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-n</option></term>
<term><option>-h</option> <replaceable>hostname</></term>
<listitem>
<para>Don't remove anything, just show what would be done.</para>
<para>Database server's host.</para>
</listitem>
</varlistentry>
......@@ -62,6 +71,20 @@ vacuumlo [options] database [database2 ... databaseN]
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<listitem>
<para>Don't remove anything, just show what would be done.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>port</></term>
<listitem>
<para>Database server's port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-U</option> <replaceable>username</></term>
<listitem>
......@@ -69,6 +92,13 @@ vacuumlo [options] database [database2 ... databaseN]
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Write a lot of progress messages.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</></term>
<term><option>--no-password</></term>
......@@ -102,50 +132,30 @@ vacuumlo [options] database [database2 ... databaseN]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option> <replaceable>hostname</></term>
<listitem>
<para>Database server's host.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>port</></term>
<listitem>
<para>Database server's port.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</refsect1>
<sect2>
<title>Method</title>
<refsect1>
<title>Notes</title>
<para>
<application>vacuumlo</application> works by the following method:
First, <application>vacuumlo</> builds a temporary table which contains all
of the OIDs of the large objects in the selected database.
</para>
<para>
It then scans through all columns in the database that are of type
<type>oid</> or <type>lo</>, and removes matching entries from the
temporary table. (Note: only types with these names are considered;
in particular, domains over them are not considered.)
</para>
<para>
The remaining entries in the temporary table identify orphaned LOs.
These are removed.
of the OIDs of the large objects in the selected database. It then scans
through all columns in the database that are of type
<type>oid</> or <type>lo</>, and removes matching entries from the temporary
table. (Note: Only types with these names are considered; in particular,
domains over them are not considered.) The remaining entries in the
temporary table identify orphaned LOs. These are removed.
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
Peter Mount <email>peter@retep.org.uk</email>
</para>
</sect2>
</refsect1>
</sect1>
</refentry>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment