summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 4f69603)
raw | patch | inline | side by side (parent: 4f69603)
| author | Peter Eisentraut <peter_e@gmx.net> | |
| Wed, 9 May 2012 17:39:53 +0000 (20:39 +0300) | ||
| committer | Peter Eisentraut <peter_e@gmx.net> | |
| Wed, 9 May 2012 17:39:53 +0000 (20:39 +0300) |
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.
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.
index 07190c5eff2523d68c21f19bb4e19074bf4b6dcd..6b13a0abefb9fbebbee2487c6b0bbb96c06e0f24 100644 (file)
<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,
</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:
<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;
&isn;
&lo;
<ree;
- &oid2name;
&pageinspect;
&passwordcheck;
- &pgarchivecleanup;
- &pgbench;
&pgbuffercache;
&pgcrypto;
&pgfreespacemap;
&pgrowlocks;
- &pgstandby;
&pgstatstatements;
&pgstattuple;
- &pgtestfsync;
- &pgtesttiming;
&pgtrgm;
- &pgupgrade;
&seg;
&sepgsql;
&contrib-spi;
&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>
index 0b40a57fd99faae12b7a3d8d00d78ecbfe7e1749..8aaafb0a340f16cab6142b67a756b83cf6efbc78 100644 (file)
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Author</term>
+ <listitem>
+ <para>
+ Author (only used in the contrib section)
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>See Also</term>
<listitem>
index 3e4fe24a49f5ef54b7c734fd9215c414340579b5..a4c83925abac72d533e42d8200edf1c03d658053 100644 (file)
<!-- 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
</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:
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>
----------------------
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>
index 40bac8547003043b7c68f47c4e238487e55f7e42..4ae9c45f87fe2e91f4f4492fb1968b38984721d1 100644 (file)
<!-- 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
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</>:
<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:
</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>
index 2ae3b9e317f3dbbc9d6ae9410e239fad03206a18..16ac69f9ee0eb207679e635d92901c4a72537fed 100644 (file)
<!-- 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
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:
</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>
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
</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
<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>
<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>
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>
<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>
<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>
</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
</variablelist>
</para>
- </sect2>
+ </refsect2>
+ </refsect1>
- <sect2>
+ <refsect1>
+ <title>Notes</title>
+
+ <refsect2>
<title>What is the <quote>Transaction</> Actually Performed in pgbench?</title>
<para>
</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>
<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
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
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
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.
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>
<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
<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>
instances concurrently, on several client machines, against the same
database server.
</para>
- </sect2>
-
-</sect1>
+ </refsect2>
+ </refsect1>
+</refentry>
index e698cb73e6390cf99b7a6e6e458ee954147afd85..0fe3f646bc0cc2e92dff0625b70624c46569fc4d 100644 (file)
<!-- 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
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
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:
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>
index 9e17b0499080dd3f12ca96df3d99d0c06afa1311..ad5ddeb2288f74632c8b24817e5147c357e4e6fe 100644 (file)
<!-- 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
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
</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>
index 86af4e28dc0a7a54a62f2e6a4b080404380ce972..586611f6f41c1ed3fd03cfed3f3be0f1b5a668d9 100644 (file)
<!-- 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
</variablelist>
</para>
- </sect2>
+ </refsect1>
- <sect2>
+ <refsect1>
+ <title>Usage</title>
+
+ <refsect2>
<title>Interpreting results</title>
<para>
one microsecond (usec).
</para>
- </sect2>
- <sect2>
+ </refsect2>
+ <refsect2>
<title>Measuring executor timing overhead</title>
<para>
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
1: 27694571 90.23734%
</screen>
- </sect2>
- <sect2>
+ </refsect2>
+ <refsect2>
<title>Clock hardware and timing accuracy</title>
<para>
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>
index 6ecdfda67198cef705353a8a5de1bc4ec80cb74f..ef99212b0fda417bb2efee896248f11ff7f16409 100644 (file)
<!-- 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</>
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:
</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">
</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:
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>
index 195c892c0b13aa6843361f749355ceab1c179918..f5c890ef609e589f79a850fd8ba02c529d976db5 100644 (file)
<!-- 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><</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>></xsl:text>
+</xsl:template>
+
+
<xsl:template match="refentry" mode="xref-to">
<xsl:param name="referrer"/>
<xsl:param name="xrefstyle"/>
index 97753de6c0c3ab0b9a045cbd36b89df25bc66a77..4640744e8b7080aa9d03cc2f99277e84a2f4f0ab 100644 (file)
<!-- 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
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>
</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>
</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>
</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>