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 @@ ...@@ -4,7 +4,7 @@
<title>Additional Supplied Modules</title> <title>Additional Supplied Modules</title>
<para> <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 can be found in the <literal>contrib</literal> directory of the
<productname>PostgreSQL</> distribution. <productname>PostgreSQL</> distribution.
These include porting tools, analysis utilities, These include porting tools, analysis utilities,
...@@ -15,7 +15,13 @@ ...@@ -15,7 +15,13 @@
</para> </para>
<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 automatically, unless you build the "world" target
(see <xref linkend="build">). (see <xref linkend="build">).
You can build and install all of them by running: You can build and install all of them by running:
...@@ -88,6 +94,14 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged; ...@@ -88,6 +94,14 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
<xref linkend="extend-extensions">. <xref linkend="extend-extensions">.
</para> </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; &adminpack;
&auth-delay; &auth-delay;
&auto-explain; &auto-explain;
...@@ -109,22 +123,15 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged; ...@@ -109,22 +123,15 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
&isn; &isn;
&lo; &lo;
&ltree; &ltree;
&oid2name;
&pageinspect; &pageinspect;
&passwordcheck; &passwordcheck;
&pgarchivecleanup;
&pgbench;
&pgbuffercache; &pgbuffercache;
&pgcrypto; &pgcrypto;
&pgfreespacemap; &pgfreespacemap;
&pgrowlocks; &pgrowlocks;
&pgstandby;
&pgstatstatements; &pgstatstatements;
&pgstattuple; &pgstattuple;
&pgtestfsync;
&pgtesttiming;
&pgtrgm; &pgtrgm;
&pgupgrade;
&seg; &seg;
&sepgsql; &sepgsql;
&contrib-spi; &contrib-spi;
...@@ -135,7 +142,69 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged; ...@@ -135,7 +142,69 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
&tsearch2; &tsearch2;
&unaccent; &unaccent;
&uuid-ossp; &uuid-ossp;
&vacuumlo;
&xml2; &xml2;
</appendix> </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 ...@@ -1240,6 +1240,15 @@ save_size.pdfjadetex = 15000
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>Author</term>
<listitem>
<para>
Author (only used in the contrib section)
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term>See Also</term> <term>See Also</term>
<listitem> <listitem>
......
doc/src/sgml/oid2name.sgml
View file @ 1c882e07
<!-- doc/src/sgml/oid2name.sgml --> <!-- doc/src/sgml/oid2name.sgml -->
<sect1 id="oid2name" xreflabel="oid2name"> <refentry id="oid2name">
<title>oid2name</title> <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"> <indexterm zone="oid2name">
<primary>oid2name</primary> <primary>oid2name</primary>
</indexterm> </indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>oid2name</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para> <para>
<application>oid2name</> is a utility program that helps administrators to <application>oid2name</> is a utility program that helps administrators to
examine the file structure used by PostgreSQL. To make use of it, you need examine the file structure used by PostgreSQL. To make use of it, you need
...@@ -24,19 +43,16 @@ ...@@ -24,19 +43,16 @@
</para> </para>
</note> </note>
<sect2>
<title>Overview</title>
<para> <para>
<application>oid2name</application> connects to a target database and <application>oid2name</application> connects to a target database and
extracts OID, filenode, and/or table name information. You can also have extracts OID, filenode, and/or table name information. You can also have
it show database OIDs or tablespace OIDs. it show database OIDs or tablespace OIDs.
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title><application>oid2name</> Options</title> <title>Options</title>
<para> <para>
<application>oid2name</application> accepts the following command-line arguments: <application>oid2name</application> accepts the following command-line arguments:
...@@ -142,9 +158,19 @@ ...@@ -142,9 +158,19 @@
OIDs. Alternatively you can give <option>-s</> to get a tablespace OIDs. Alternatively you can give <option>-s</> to get a tablespace
listing. listing.
</para> </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> <title>Examples</title>
<screen> <screen>
...@@ -265,24 +291,14 @@ From database "alvherre": ...@@ -265,24 +291,14 @@ From database "alvherre":
---------------------- ----------------------
155156 foo 155156 foo
</screen> </screen>
</sect2> </refsect1>
<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>
<sect2> <refsect1>
<title>Author</title> <title>Author</title>
<para> <para>
B. Palmer <email>bpalmer@crimelabs.net</email> B. Palmer <email>bpalmer@crimelabs.net</email>
</para> </para>
</sect2> </refsect1>
</sect1> </refentry>
doc/src/sgml/pgarchivecleanup.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgarchivecleanup.sgml --> <!-- doc/src/sgml/pgarchivecleanup.sgml -->
<sect1 id="pgarchivecleanup" xreflabel="pg_archivecleanup"> <refentry id="pgarchivecleanup">
<title>pg_archivecleanup</title> <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"> <indexterm zone="pgarchivecleanup">
<primary>pg_archivecleanup</primary> <primary>pg_archivecleanup</primary>
</indexterm> </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> <para>
<application>pg_archivecleanup</> is designed to be used as an <application>pg_archivecleanup</> is designed to be used as an
<literal>archive_cleanup_command</literal> to clean up WAL file archives when <literal>archive_cleanup_command</literal> to clean up WAL file archives when
...@@ -15,26 +36,6 @@ ...@@ -15,26 +36,6 @@
clean WAL file archives. clean WAL file archives.
</para> </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> <para>
To configure a standby To configure a standby
server to use <application>pg_archivecleanup</>, put this into its server to use <application>pg_archivecleanup</>, put this into its
...@@ -57,14 +58,10 @@ archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r' ...@@ -57,14 +58,10 @@ archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r'
from the same archive location. from the same archive location.
</para> </para>
<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 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 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. all WAL files archived prior to a specific base backup without error.
For example, the following example will remove all files older than For example, the following example will remove all files older than
WAL file name <filename>000000010000003700000010</>: WAL file name <filename>000000010000003700000010</>:
...@@ -79,10 +76,10 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" ...@@ -79,10 +76,10 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E"
<replaceable>archivelocation</> is a directory readable and writable by the <replaceable>archivelocation</> is a directory readable and writable by the
server-owning user. server-owning user.
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title><application>pg_archivecleanup</> Options</title> <title>Options</title>
<para> <para>
<application>pg_archivecleanup</application> accepts the following command-line arguments: <application>pg_archivecleanup</application> accepts the following command-line arguments:
...@@ -124,10 +121,26 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" ...@@ -124,10 +121,26 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E"
</variablelist> </variablelist>
</para> </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> <title>Examples</title>
<para>On Linux or Unix systems, you might use: <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 ...@@ -151,26 +164,21 @@ archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>clean
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</refsect1>
</sect2> <refsect1>
<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>
<title>Author</title> <title>Author</title>
<para> <para>
Simon Riggs <email>simon@2ndquadrant.com</email> Simon Riggs <email>simon@2ndquadrant.com</email>
</para> </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 --> <!-- doc/src/sgml/pgbench.sgml -->
<sect1 id="pgbench" xreflabel="pgbench"> <refentry id="pgbench">
<title>pgbench</title> <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"> <indexterm zone="pgbench">
<primary>pgbench</primary> <primary>pgbench</primary>
</indexterm> </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> <para>
<application>pgbench</application> is a simple program for running benchmark <application>pgbench</application> is a simple program for running benchmark
tests on <productname>PostgreSQL</>. It runs the same sequence of SQL tests on <productname>PostgreSQL</>. It runs the same sequence of SQL
...@@ -38,19 +63,16 @@ tps = 85.296346 (excluding connections establishing) ...@@ -38,19 +63,16 @@ tps = 85.296346 (excluding connections establishing)
settings. The next line reports the number of transactions completed settings. The next line reports the number of transactions completed
and intended (the latter being just the product of number of clients 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 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.) number of transactions is printed.)
The last two lines report the number of transactions per second, The last two lines report the number of transactions per second,
figured with and without counting the time to start database sessions. figured with and without counting the time to start database sessions.
</para> </para>
<sect2>
<title>Overview</title>
<para> <para>
The default TPC-B-like transaction test requires specific tables to be The default TPC-B-like transaction test requires specific tables to be
set up beforehand. <application>pgbench</> should be invoked with 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 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.) step, but will instead need to do whatever setup your test needs.)
Initialization looks like: Initialization looks like:
...@@ -60,8 +82,8 @@ pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbn ...@@ -60,8 +82,8 @@ pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbn
</programlisting> </programlisting>
where <replaceable>dbname</> is the name of the already-created where <replaceable>dbname</> is the name of the already-created
database to test in. (You may also need <literal>-h</>, database to test in. (You may also need <option>-h</>,
<literal>-p</>, and/or <literal>-U</> options to specify how to <option>-p</>, and/or <option>-U</> options to specify how to
connect to the database server.) connect to the database server.)
</para> </para>
...@@ -88,38 +110,37 @@ pgbench_accounts 100000 ...@@ -88,38 +110,37 @@ pgbench_accounts 100000
pgbench_history 0 pgbench_history 0
</screen> </screen>
You can (and, for most purposes, probably should) increase the number You can (and, for most purposes, probably should) increase the number
of rows by using the <literal>-s</> (scale factor) option. The of rows by using the <option>-s</> (scale factor) option. The
<literal>-F</> (fillfactor) option might also be used at this point. <option>-F</> (fillfactor) option might also be used at this point.
</para> </para>
<para> <para>
Once you have done the necessary setup, you can run your benchmark 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> <programlisting>
pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</programlisting> </programlisting>
In nearly all cases, you'll need some options to make a useful test. In nearly all cases, you'll need some options to make a useful test.
The most important options are <literal>-c</> (number of clients), The most important options are <option>-c</> (number of clients),
<literal>-t</> (number of transactions), <literal>-T</> (time limit), <option>-t</> (number of transactions), <option>-T</> (time limit),
and <literal>-f</> (specify a custom script file). and <option>-f</> (specify a custom script file).
See below for a full list. See below for a full list.
</para> </para>
</refsect1>
<refsect1>
<title>Options</title>
<para> <para>
<xref linkend="pgbench-init-options"> shows options that are used The following is divided into three subsections: Different options are used
during database initialization, while during database initialization and while running benchmarks, some options
<xref linkend="pgbench-run-options"> shows options that are used are useful in both cases.
while running benchmarks, and
<xref linkend="pgbench-common-options"> shows options that are useful
in both cases.
</para> </para>
</sect2> <refsect2 id="pgbench-init-options">
<title>Initialization Options</title>
<sect2 id="pgbench-init-options">
<title><application>pgbench</> Initialization Options</title>
<para> <para>
<application>pgbench</application> accepts the following command-line <application>pgbench</application> accepts the following command-line
...@@ -191,10 +212,10 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -191,10 +212,10 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect2>
<sect2 id="pgbench-run-options"> <refsect2 id="pgbench-run-options">
<title><application>pgbench</> Benchmarking Options</title> <title>Benchmarking Options</title>
<para> <para>
<application>pgbench</application> accepts the following command-line <application>pgbench</application> accepts the following command-line
...@@ -237,7 +258,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -237,7 +258,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<listitem> <listitem>
<para> <para>
Define a variable for use by a custom script (see below). Define a variable for use by a custom script (see below).
Multiple <literal>-D</> options are allowed. Multiple <option>-D</> options are allowed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -248,7 +269,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -248,7 +269,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<para> <para>
Read transaction script from <replaceable>filename</>. Read transaction script from <replaceable>filename</>.
See below for details. 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. are mutually exclusive.
</para> </para>
</listitem> </listitem>
...@@ -344,7 +365,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -344,7 +365,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
output. With the built-in tests, this is not necessary; the output. With the built-in tests, this is not necessary; the
correct scale factor will be detected by counting the number of correct scale factor will be detected by counting the number of
rows in the <structname>pgbench_branches</> table. However, when testing 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. will be reported as 1 unless this option is used.
</para> </para>
</listitem> </listitem>
...@@ -373,8 +394,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -373,8 +394,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<listitem> <listitem>
<para> <para>
Run the test for this many seconds, rather than a fixed number of Run the test for this many seconds, rather than a fixed number of
transactions per client. <literal>-t</literal> and transactions per client. <option>-t</option> and
<literal>-T</literal> are mutually exclusive. <option>-T</option> are mutually exclusive.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -384,7 +405,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -384,7 +405,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<listitem> <listitem>
<para> <para>
Vacuum all four standard tables before running the test. 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</> <structname>pgbench_tellers</> and <structname>pgbench_branches</>
tables, and will truncate <structname>pgbench_history</>. tables, and will truncate <structname>pgbench_history</>.
</para> </para>
...@@ -394,10 +415,10 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -394,10 +415,10 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect2>
<sect2 id="pgbench-common-options"> <refsect2 id="pgbench-common-options">
<title><application>pgbench</> Common Options</title> <title>Common Options</title>
<para> <para>
<application>pgbench</application> accepts the following command-line <application>pgbench</application> accepts the following command-line
...@@ -435,9 +456,13 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -435,9 +456,13 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect2>
</refsect1>
<sect2> <refsect1>
<title>Notes</title>
<refsect2>
<title>What is the <quote>Transaction</> Actually Performed in pgbench?</title> <title>What is the <quote>Transaction</> Actually Performed in pgbench?</title>
<para> <para>
...@@ -455,22 +480,22 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -455,22 +480,22 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
</orderedlist> </orderedlist>
<para> <para>
If you specify <literal>-N</>, steps 4 and 5 aren't included in the If you specify <option>-N</>, steps 4 and 5 aren't included in the
transaction. If you specify <literal>-S</>, only the <command>SELECT</> is transaction. If you specify <option>-S</>, only the <command>SELECT</> is
issued. issued.
</para> </para>
</sect2> </refsect2>
<sect2> <refsect2>
<title>Custom Scripts</title> <title>Custom Scripts</title>
<para> <para>
<application>pgbench</application> has support for running custom <application>pgbench</application> has support for running custom
benchmark scenarios by replacing the default transaction script benchmark scenarios by replacing the default transaction script
(described above) with a transaction script read from a file (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 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 case a random one of the scripts is chosen each time a client session
starts a new transaction. starts a new transaction.
</para> </para>
...@@ -485,9 +510,9 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> ...@@ -485,9 +510,9 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
<para> <para>
There is a simple variable-substitution facility for script files. 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. 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. the variable <literal>scale</> is preset to the current scale factor.
Once set, a variable's Once set, a variable's
value can be inserted into a SQL command by writing value can be inserted into a SQL command by writing
...@@ -648,17 +673,17 @@ END; ...@@ -648,17 +673,17 @@ END;
otherwise they'd not be independently touching different rows.) otherwise they'd not be independently touching different rows.)
</para> </para>
</sect2> </refsect2>
<sect2> <refsect2>
<title>Per-Transaction Logging</title> <title>Per-Transaction Logging</title>
<para> <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 taken by each transaction to a log file. The log file will be named
<filename>pgbench_log.<replaceable>nnn</></filename>, where <filename>pgbench_log.<replaceable>nnn</></filename>, where
<replaceable>nnn</> is the PID of the pgbench process. <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 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. same name for its log file as in the standard single worker case.
The additional log files for the other workers will be named The additional log files for the other workers will be named
...@@ -676,7 +701,7 @@ END; ...@@ -676,7 +701,7 @@ END;
where <replaceable>time</> is the total elapsed transaction time in microseconds, where <replaceable>time</> is the total elapsed transaction time in microseconds,
<replaceable>file_no</> identifies which script file was used <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 and <replaceable>time_epoch</>/<replaceable>time_us</> are a
UNIX epoch format timestamp and an offset UNIX epoch format timestamp and an offset
in microseconds (suitable for creating a ISO 8601 in microseconds (suitable for creating a ISO 8601
...@@ -693,13 +718,13 @@ END; ...@@ -693,13 +718,13 @@ END;
0 202 2038 0 1175850569 2663 0 202 2038 0 1175850569 2663
</screen> </screen>
</para> </para>
</sect2> </refsect2>
<sect2> <refsect2>
<title>Per-Statement Latencies</title> <title>Per-Statement Latencies</title>
<para> <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 the elapsed transaction time of each statement executed by every
client. It then reports an average of those values, referred to client. It then reports an average of those values, referred to
as the latency for each statement, after the benchmark has finished. as the latency for each statement, after the benchmark has finished.
...@@ -749,9 +774,9 @@ statement latencies in milliseconds: ...@@ -749,9 +774,9 @@ statement latencies in milliseconds:
Comparing average TPS values with and without latency reporting enabled Comparing average TPS values with and without latency reporting enabled
is a good way to measure if the timing overhead is significant. is a good way to measure if the timing overhead is significant.
</para> </para>
</sect2> </refsect2>
<sect2> <refsect2>
<title>Good Practices</title> <title>Good Practices</title>
<para> <para>
...@@ -762,7 +787,7 @@ statement latencies in milliseconds: ...@@ -762,7 +787,7 @@ statement latencies in milliseconds:
<para> <para>
In the first place, <emphasis>never</> believe any test that runs 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. 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. 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 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: ...@@ -771,11 +796,11 @@ statement latencies in milliseconds:
<para> <para>
For the default TPC-B-like test scenario, the initialization scale factor 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 (<option>-s</>) should be at least as large as the largest number of
clients you intend to test (<literal>-c</>); else you'll mostly be clients you intend to test (<option>-c</>); else you'll mostly be
measuring update contention. There are only <literal>-s</> rows in measuring update contention. There are only <option>-s</> rows in
the <structname>pgbench_branches</> table, and every transaction wants to 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 will undoubtedly result in lots of transactions blocked waiting for
other transactions. other transactions.
</para> </para>
...@@ -798,6 +823,6 @@ statement latencies in milliseconds: ...@@ -798,6 +823,6 @@ statement latencies in milliseconds:
instances concurrently, on several client machines, against the same instances concurrently, on several client machines, against the same
database server. database server.
</para> </para>
</sect2> </refsect2>
</refsect1>
</sect1> </refentry>
doc/src/sgml/pgstandby.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgstandby.sgml --> <!-- doc/src/sgml/pgstandby.sgml -->
<sect1 id="pgstandby" xreflabel="pg_standby"> <refentry id="pgstandby">
<title>pg_standby</title> <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"> <indexterm zone="pgstandby">
<primary>pg_standby</primary> <primary>pg_standby</primary>
</indexterm> </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> <para>
<application>pg_standby</> supports creation of a <quote>warm standby</> <application>pg_standby</> supports creation of a <quote>warm standby</>
database server. It is designed to be a production-ready program, as well database server. It is designed to be a production-ready program, as well
...@@ -21,31 +44,6 @@ ...@@ -21,31 +44,6 @@
server manual (see <xref linkend="warm-standby">). server manual (see <xref linkend="warm-standby">).
</para> </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> <para>
To configure a standby To configure a standby
server to use <application>pg_standby</>, put this into its server to use <application>pg_standby</>, put this into its
...@@ -56,16 +54,6 @@ restore_command = 'pg_standby <replaceable>archiveDir</> %f %p %r' ...@@ -56,16 +54,6 @@ restore_command = 'pg_standby <replaceable>archiveDir</> %f %p %r'
where <replaceable>archiveDir</> is the directory from which WAL segment where <replaceable>archiveDir</> is the directory from which WAL segment
files should be restored. files should be restored.
</para> </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> <para>
If <replaceable>restartwalfile</> is specified, normally by using the If <replaceable>restartwalfile</> is specified, normally by using the
<literal>%r</literal> macro, then all WAL files logically preceding this <literal>%r</literal> macro, then all WAL files logically preceding this
...@@ -118,10 +106,10 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv ...@@ -118,10 +106,10 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title><application>pg_standby</> Options</title> <title>Options</title>
<para> <para>
<application>pg_standby</application> accepts the following command-line arguments: <application>pg_standby</application> accepts the following command-line arguments:
...@@ -226,9 +214,36 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv ...@@ -226,9 +214,36 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
</variablelist> </variablelist>
</para> </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> <title>Examples</title>
<para>On Linux or Unix systems, you might use: <para>On Linux or Unix systems, you might use:
...@@ -339,35 +354,21 @@ recovery_end_command = 'del C:\pgsql.trigger.5442' ...@@ -339,35 +354,21 @@ recovery_end_command = 'del C:\pgsql.trigger.5442'
network. network.
</para> </para>
</sect2> </refsect1>
<sect2>
<title>Supported Server Versions</title>
<para> <refsect1>
<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>
<title>Author</title> <title>Author</title>
<para> <para>
Simon Riggs <email>simon@2ndquadrant.com</email> Simon Riggs <email>simon@2ndquadrant.com</email>
</para> </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 --> <!-- doc/src/sgml/pgtestfsync.sgml -->
<sect1 id="pgtestfsync" xreflabel="pg_test_fsync"> <refentry id="pgtestfsync">
<title>pg_test_fsync</title> <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"> <indexterm zone="pgtestfsync">
<primary>pg_test_fsync</primary> <primary>pg_test_fsync</primary>
</indexterm> </indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_fsync</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para> <para>
<application>pg_test_fsync</> is intended to give you a reasonable <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 idea of what the fastest <xref linkend="guc-wal-sync-method"> is on your
...@@ -17,13 +36,10 @@ ...@@ -17,13 +36,10 @@
since many database servers are not speed-limited by their transaction since many database servers are not speed-limited by their transaction
logs. logs.
</para> </para>
</refsect1>
<sect2> <refsect1>
<title>Usage</title> <title>Options</title>
<synopsis>
pg_test_fsync [options]
</synopsis>
<para> <para>
<application>pg_test_fsync</application> accepts the following <application>pg_test_fsync</application> accepts the following
...@@ -62,14 +78,21 @@ pg_test_fsync [options] ...@@ -62,14 +78,21 @@ pg_test_fsync [options]
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title>Author</title> <title>Author</title>
<para> <para>
Bruce Momjian <email>bruce@momjian.us</email> Bruce Momjian <email>bruce@momjian.us</email>
</para> </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 --> <!-- doc/src/sgml/pgtesttiming.sgml -->
<sect1 id="pgtesttiming" xreflabel="pg_test_timing"> <refentry id="pgtesttiming">
<title>pg_test_timing</title> <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"> <indexterm zone="pgtesttiming">
<primary>pg_test_timing</primary> <primary>pg_test_timing</primary>
</indexterm> </indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_timing</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para> <para>
<application>pg_test_timing</> is a tool to measure the timing overhead <application>pg_test_timing</> is a tool to measure the timing overhead
on your system and confirm that the system time never moves backwards. on your system and confirm that the system time never moves backwards.
Systems that are slow to collect timing data can give less accurate Systems that are slow to collect timing data can give less accurate
<command>EXPLAIN ANALYZE</command> results. <command>EXPLAIN ANALYZE</command> results.
</para> </para>
</refsect1>
<sect2> <refsect1>
<title>Usage</title> <title>Options</title>
<synopsis>
pg_test_timing [options]
</synopsis>
<para> <para>
<application>pg_test_timing</application> accepts the following <application>pg_test_timing</application> accepts the following
...@@ -43,9 +59,12 @@ pg_test_timing [options] ...@@ -43,9 +59,12 @@ pg_test_timing [options]
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title>Usage</title>
<refsect2>
<title>Interpreting results</title> <title>Interpreting results</title>
<para> <para>
...@@ -74,8 +93,8 @@ Histogram of timing durations: ...@@ -74,8 +93,8 @@ Histogram of timing durations:
one microsecond (usec). one microsecond (usec).
</para> </para>
</sect2> </refsect2>
<sect2> <refsect2>
<title>Measuring executor timing overhead</title> <title>Measuring executor timing overhead</title>
<para> <para>
...@@ -103,8 +122,9 @@ EXPLAIN ANALYZE SELECT COUNT(*) FROM t; ...@@ -103,8 +122,9 @@ EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
timing overhead would be less problematic. timing overhead would be less problematic.
</para> </para>
</sect2> </refsect2>
<sect2>
<refsect2>
<title>Changing time sources</title> <title>Changing time sources</title>
<para> <para>
On some newer Linux systems, it's possible to change the clock On some newer Linux systems, it's possible to change the clock
...@@ -178,8 +198,8 @@ Histogram of timing durations: ...@@ -178,8 +198,8 @@ Histogram of timing durations:
1: 27694571 90.23734% 1: 27694571 90.23734%
</screen> </screen>
</sect2> </refsect2>
<sect2> <refsect2>
<title>Clock hardware and timing accuracy</title> <title>Clock hardware and timing accuracy</title>
<para> <para>
...@@ -248,14 +268,22 @@ Histogram of timing durations: ...@@ -248,14 +268,22 @@ Histogram of timing durations:
Programmable Interrupt Controller (APIC) timer, and the Cyclone Programmable Interrupt Controller (APIC) timer, and the Cyclone
timer. These timers aim for millisecond resolution. timer. These timers aim for millisecond resolution.
</para> </para>
</sect2> </refsect2>
</refsect1>
<sect2> <refsect1>
<title>Author</title> <title>Author</title>
<para> <para>
Ants Aasma <email>ants.aasma@eesti.ee</email> Ants Aasma <email>ants.aasma@eesti.ee</email>
</para> </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 --> <!-- doc/src/sgml/pgupgrade.sgml -->
<sect1 id="pgupgrade" xreflabel="pg_upgrade"> <refentry id="pgupgrade">
<title>pg_upgrade</title> <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"> <indexterm zone="pgupgrade">
<primary>pg_upgrade</primary> <primary>pg_upgrade</primary>
</indexterm> </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> <para>
<application>pg_upgrade</> (formerly called <application>pg_migrator</>) allows data <application>pg_upgrade</> (formerly called <application>pg_migrator</>) allows data
stored in <productname>PostgreSQL</> data files to be upgraded to a later <productname>PostgreSQL</> stored in <productname>PostgreSQL</> data files to be upgraded to a later <productname>PostgreSQL</>
...@@ -37,19 +64,14 @@ ...@@ -37,19 +64,14 @@
be checked by <application>pg_upgrade</>. be checked by <application>pg_upgrade</>.
</para> </para>
<sect2>
<title>Supported Versions</title>
<para> <para>
pg_upgrade supports upgrades from 8.3.X and later to the current pg_upgrade supports upgrades from 8.3.X and later to the current
major release of <productname>PostgreSQL</>, including snapshot and alpha releases. major release of <productname>PostgreSQL</>, including snapshot and alpha releases.
</para> </para>
</refsect1>
</sect2> <refsect1>
<title>Options</title>
<sect2>
<title><application>pg_upgrade</> Options</title>
<para> <para>
<application>pg_upgrade</application> accepts the following command-line arguments: <application>pg_upgrade</application> accepts the following command-line arguments:
...@@ -160,10 +182,15 @@ ...@@ -160,10 +182,15 @@
</variablelist> </variablelist>
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title>Upgrade Steps</title> <title>Usage</title>
<para>
These are the steps to perform an upgrade
with <application>pg_upgrade</application>:
</para>
<procedure> <procedure>
<step performance="optional"> <step performance="optional">
...@@ -459,13 +486,54 @@ psql --username postgres --file script.sql postgres ...@@ -459,13 +486,54 @@ psql --username postgres --file script.sql postgres
</step> </step>
</procedure> </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> <refsect2>
<title>Limitations in Upgrading <emphasis>from</> PostgreSQL 8.3</title> <title>Limitations in Upgrading PostgreSQL 8.3</title>
<para> <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, when upgrading from later PostgreSQL releases. For example,
pg_upgrade will not work for upgrading from 8.3 if a user column pg_upgrade will not work for upgrading from 8.3 if a user column
is defined as: is defined as:
...@@ -534,49 +602,18 @@ psql --username postgres --file script.sql postgres ...@@ -534,49 +602,18 @@ psql --username postgres --file script.sql postgres
possible to upgrade from the MSI installer to the one-click installer. possible to upgrade from the MSI installer to the one-click installer.
</para> </para>
</sect2> </refsect2>
<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>
<para> </refsect1>
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> <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 @@ ...@@ -30,6 +30,16 @@
<!-- Custom templates --> <!-- 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:template match="refentry" mode="xref-to">
<xsl:param name="referrer"/> <xsl:param name="referrer"/>
<xsl:param name="xrefstyle"/> <xsl:param name="xrefstyle"/>
......
doc/src/sgml/vacuumlo.sgml
View file @ 1c882e07
<!-- doc/src/sgml/vacuumlo.sgml --> <!-- doc/src/sgml/vacuumlo.sgml -->
<sect1 id="vacuumlo" xreflabel="vacuumlo"> <refentry id="vacuumlo">
<title>vacuumlo</title> <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"> <indexterm zone="vacuumlo">
<primary>vacuumlo</primary> <primary>vacuumlo</primary>
</indexterm> </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> <para>
<application>vacuumlo</> is a simple utility program that will remove any <application>vacuumlo</> is a simple utility program that will remove any
<quote>orphaned</> large objects from a <quote>orphaned</> large objects from a
...@@ -22,30 +42,19 @@ ...@@ -22,30 +42,19 @@
to avoid creating orphaned LOs in the first place. to avoid creating orphaned LOs in the first place.
</para> </para>
<sect2>
<title>Usage</title>
<synopsis>
vacuumlo [options] database [database2 ... databaseN]
</synopsis>
<para> <para>
All databases named on the command line are processed. Available options All databases named on the command line are processed.
include:
</para> </para>
</refsect1>
<variablelist> <refsect1>
<varlistentry> <title>Options</title>
<term><option>-v</option></term>
<listitem>
<para>Write a lot of progress messages.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry> <varlistentry>
<term><option>-n</option></term> <term><option>-h</option> <replaceable>hostname</></term>
<listitem> <listitem>
<para>Don't remove anything, just show what would be done.</para> <para>Database server's host.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -62,6 +71,20 @@ vacuumlo [options] database [database2 ... databaseN] ...@@ -62,6 +71,20 @@ vacuumlo [options] database [database2 ... databaseN]
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><option>-U</option> <replaceable>username</></term> <term><option>-U</option> <replaceable>username</></term>
<listitem> <listitem>
...@@ -69,6 +92,13 @@ vacuumlo [options] database [database2 ... databaseN] ...@@ -69,6 +92,13 @@ vacuumlo [options] database [database2 ... databaseN]
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Write a lot of progress messages.</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term><option>-w</></term> <term><option>-w</></term>
<term><option>--no-password</></term> <term><option>--no-password</></term>
...@@ -102,50 +132,30 @@ vacuumlo [options] database [database2 ... databaseN] ...@@ -102,50 +132,30 @@ vacuumlo [options] database [database2 ... databaseN]
</para> </para>
</listitem> </listitem>
</varlistentry> </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> </variablelist>
</sect2> </refsect1>
<sect2> <refsect1>
<title>Method</title> <title>Notes</title>
<para> <para>
<application>vacuumlo</application> works by the following method:
First, <application>vacuumlo</> builds a temporary table which contains all First, <application>vacuumlo</> builds a temporary table which contains all
of the OIDs of the large objects in the selected database. of the OIDs of the large objects in the selected database. It then scans
</para> through all columns in the database that are of type
<type>oid</> or <type>lo</>, and removes matching entries from the temporary
<para> table. (Note: Only types with these names are considered; in particular,
It then scans through all columns in the database that are of type domains over them are not considered.) The remaining entries in the
<type>oid</> or <type>lo</>, and removes matching entries from the temporary table identify orphaned LOs. These are removed.
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.
</para> </para>
</sect2> </refsect1>
<sect2> <refsect1>
<title>Author</title> <title>Author</title>
<para> <para>
Peter Mount <email>peter@retep.org.uk</email> Peter Mount <email>peter@retep.org.uk</email>
</para> </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