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
Expand all 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
This diff is collapsed.
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