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 @@
<title>Additional Supplied Modules</title>
<para>
This appendix contains information regarding the modules that
This appendix and the next one contain information regarding the modules that
can be found in the <literal>contrib</literal> directory of the
<productname>PostgreSQL</> distribution.
These include porting tools, analysis utilities,
......@@ -15,7 +15,13 @@
</para>
<para>
When building from the source distribution, these modules are not built
This appendix covers extensions and other server plug-in modules found in
<literal>contrib</literal>. <xref linkend="contrib-prog"> covers utility
programs.
</para>
<para>
When building from the source distribution, these components are not built
automatically, unless you build the "world" target
(see <xref linkend="build">).
You can build and install all of them by running:
......@@ -88,6 +94,14 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
<xref linkend="extend-extensions">.
</para>
<para>
Note, however, that some of these modules are not <quote>extensions</quote>
in this sense, but are loaded into the server in some other way, for instance
by way of
<xref linkend="guc-shared-preload-libraries">. See the documentation of each
module for details.
</para>
&adminpack;
&auth-delay;
&auto-explain;
......@@ -109,22 +123,15 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
&isn;
&lo;
&ltree;
&oid2name;
&pageinspect;
&passwordcheck;
&pgarchivecleanup;
&pgbench;
&pgbuffercache;
&pgcrypto;
&pgfreespacemap;
&pgrowlocks;
&pgstandby;
&pgstatstatements;
&pgstattuple;
&pgtestfsync;
&pgtesttiming;
&pgtrgm;
&pgupgrade;
&seg;
&sepgsql;
&contrib-spi;
......@@ -135,7 +142,69 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
&tsearch2;
&unaccent;
&uuid-ossp;
&vacuumlo;
&xml2;
</appendix>
<!--
These are two separate appendixes because it is difficult to mix regular
sections (for extensions) and refentries (for programs) in one chapter or
appendix. And we do want the programs as refentries so that we can produce man
pages.
-->
<appendix id="contrib-prog">
<title>Additional Supplied Programs</title>
<para>
This appendix and the previous one contain information regarding the modules that
can be found in the <literal>contrib</literal> directory of the
<productname>PostgreSQL</> distribution. See <xref linkend="contrib"> for
more information about the <literal>contrib</literal> section in general and
server extensions and plug-ins found in <literal>contrib</literal>
specifically.
</para>
<para>
This appendix covers utility programs found in <literal>contrib</literal>.
Once installed, either from source or a packaging system, they are found in
the <filename>bin</filename> directory of the
<productname>PostgreSQL</productname> installation and can be used like any
other program.
</para>
<sect1 id="contrib-prog-client">
<title>Client Applications</title>
<para>
This section covers <productname>PostgreSQL</productname> client
applications in <literal>contrib</literal>. They can be run from anywhere,
independent of where the database server resides. See
also <xref linkend="reference-client"> for information about client
applications that part of the core <productname>PostgreSQL</productname>
distribution.
</para>
&oid2name;
&pgbench;
&vacuumlo;
</sect1>
<sect1 id="contrib-prog-server">
<title>Server Applications</title>
<para>
This section covers <productname>PostgreSQL</productname> server-related
applications in <literal>contrib</literal>. They are typically run on the
host where the database server resides. See also <xref
linkend="reference-server"> for information about server applications that
part of the core <productname>PostgreSQL</productname> distribution.
</para>
&pgarchivecleanup;
&pgstandby;
&pgtestfsync;
&pgtesttiming;
&pgupgrade;
</sect1>
</appendix>
doc/src/sgml/docguide.sgml
View file @ 1c882e07
......@@ -1240,6 +1240,15 @@ save_size.pdfjadetex = 15000
</listitem>
</varlistentry>
<varlistentry>
<term>Author</term>
<listitem>
<para>
Author (only used in the contrib section)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>See Also</term>
<listitem>
......
doc/src/sgml/oid2name.sgml
View file @ 1c882e07
<!-- doc/src/sgml/oid2name.sgml -->
<sect1 id="oid2name" xreflabel="oid2name">
<title>oid2name</title>
<refentry id="oid2name">
<refmeta>
<refentrytitle>oid2name</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>oid2name</refname>
<refpurpose>resolve OIDs and file nodes in a <productname>PostgreSQL</productname> data directory</refpurpose>
</refnamediv>
<indexterm zone="oid2name">
<primary>oid2name</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>oid2name</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>oid2name</> is a utility program that helps administrators to
examine the file structure used by PostgreSQL. To make use of it, you need
......@@ -24,19 +43,16 @@
</para>
</note>
<sect2>
<title>Overview</title>
<para>
<application>oid2name</application> connects to a target database and
extracts OID, filenode, and/or table name information. You can also have
it show database OIDs or tablespace OIDs.
</para>
</sect2>
</refsect1>
<sect2>
<title><application>oid2name</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>oid2name</application> accepts the following command-line arguments:
......@@ -142,9 +158,19 @@
OIDs. Alternatively you can give <option>-s</> to get a tablespace
listing.
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Notes</title>
<para>
<application>oid2name</> requires a running database server with
non-corrupt system catalogs. It is therefore of only limited use
for recovering from catastrophic database corruption situations.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
......@@ -265,24 +291,14 @@ From database "alvherre":
----------------------
155156 foo
</screen>
</sect2>
<sect2>
<title>Limitations</title>
<para>
<application>oid2name</> requires a running database server with
non-corrupt system catalogs. It is therefore of only limited use
for recovering from catastrophic database corruption situations.
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
B. Palmer <email>bpalmer@crimelabs.net</email>
</para>
</sect2>
</refsect1>
</sect1>
</refentry>
doc/src/sgml/pgarchivecleanup.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgarchivecleanup.sgml -->
<sect1 id="pgarchivecleanup" xreflabel="pg_archivecleanup">
<title>pg_archivecleanup</title>
<refentry id="pgarchivecleanup">
<refmeta>
<refentrytitle><application>pg_archivecleanup</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_archivecleanup</refname>
<refpurpose>clean up <productname>PostgreSQL</productname> WAL archive files</refpurpose>
</refnamediv>
<indexterm zone="pgarchivecleanup">
<primary>pg_archivecleanup</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_archivecleanup</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>archivelocation</replaceable></arg>
<arg choice="plain"><replaceable>oldestkeptwalfile</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_archivecleanup</> is designed to be used as an
<literal>archive_cleanup_command</literal> to clean up WAL file archives when
......@@ -15,26 +36,6 @@
clean WAL file archives.
</para>
<para>
<application>pg_archivecleanup</application> features include:
</para>
<itemizedlist>
<listitem>
<para>
Written in C, so very portable and easy to install
</para>
</listitem>
<listitem>
<para>
Easy-to-modify source code, with specifically designated
sections to modify for your own needs
</para>
</listitem>
</itemizedlist>
<sect2>
<title>Usage</title>
<para>
To configure a standby
server to use <application>pg_archivecleanup</>, put this into its
......@@ -57,14 +58,10 @@ archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r'
from the same archive location.
</para>
<para>
The full syntax of <application>pg_archivecleanup</>'s command line is
<synopsis>
pg_archivecleanup <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>restartwalfile</>
</synopsis>
When used as a standalone program all WAL files logically preceding the
<literal>restartwalfile</> will be removed <replaceable>archivelocation</>.
<replaceable>oldestkeptwalfile</> will be removed from <replaceable>archivelocation</>.
In this mode, if you specify a <filename>.backup</> file name, then only the file prefix
will be used as the <literal>restartwalfile</>. This allows you to remove
will be used as the <replaceable>oldestkeptwalfile</>. This allows you to remove
all WAL files archived prior to a specific base backup without error.
For example, the following example will remove all files older than
WAL file name <filename>000000010000003700000010</>:
......@@ -79,10 +76,10 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E"
<replaceable>archivelocation</> is a directory readable and writable by the
server-owning user.
</para>
</sect2>
</refsect1>
<sect2>
<title><application>pg_archivecleanup</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>pg_archivecleanup</application> accepts the following command-line arguments:
......@@ -124,10 +121,26 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E"
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<application>pg_archivecleanup</application> is designed to work with
<productname>PostgreSQL</> 8.0 and later when used as a standalone utility,
or with <productname>PostgreSQL</> 9.0 and later when used as an
archive cleanup command.
</para>
</sect2>
<para>
<application>pg_archivecleanup</application> is written in C and has an
easy-to-modify source code, with specifically designated sections to modify
for your own needs
</para>
</refsect1>
<sect2>
<refsect1>
<title>Examples</title>
<para>On Linux or Unix systems, you might use:
......@@ -151,26 +164,21 @@ archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>clean
</para>
</listitem>
</itemizedlist>
</refsect1>
</sect2>
<sect2>
<title>Supported Server Versions</title>
<para>
<application>pg_archivecleanup</application> is designed to work with
<productname>PostgreSQL</> 8.0 and later when used as a standalone utility,
or with <productname>PostgreSQL</> 9.0 and later when used as an
archive cleanup command.
</para>
</sect2>
<sect2>
<refsect1>
<title>Author</title>
<para>
Simon Riggs <email>simon@2ndquadrant.com</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="pgstandby"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgbench.sgml
View file @ 1c882e07
This diff is collapsed.
doc/src/sgml/pgstandby.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgstandby.sgml -->
<sect1 id="pgstandby" xreflabel="pg_standby">
<title>pg_standby</title>
<refentry id="pgstandby">
<refmeta>
<refentrytitle><application>pg_standby</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_standby</refname>
<refpurpose>supports the creation of a <productname>PostgreSQL</productname> warm standby server</refpurpose>
</refnamediv>
<indexterm zone="pgstandby">
<primary>pg_standby</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_standby</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>archivelocation</replaceable></arg>
<arg choice="plain"><replaceable>nextwalfile</replaceable></arg>
<arg choice="plain"><replaceable>xlogfilepath</replaceable></arg>
<arg choice="opt"><replaceable>restartwalfile</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_standby</> supports creation of a <quote>warm standby</>
database server. It is designed to be a production-ready program, as well
......@@ -21,31 +44,6 @@
server manual (see <xref linkend="warm-standby">).
</para>
<para>
<application>pg_standby</application> features include:
</para>
<itemizedlist>
<listitem>
<para>
Written in C, so very portable and easy to install
</para>
</listitem>
<listitem>
<para>
Easy-to-modify source code, with specifically designated
sections to modify for your own needs
</para>
</listitem>
<listitem>
<para>
Already tested on Linux and Windows
</para>
</listitem>
</itemizedlist>
<sect2>
<title>Usage</title>
<para>
To configure a standby
server to use <application>pg_standby</>, put this into its
......@@ -56,16 +54,6 @@ restore_command = 'pg_standby <replaceable>archiveDir</> %f %p %r'
where <replaceable>archiveDir</> is the directory from which WAL segment
files should be restored.
</para>
<para>
The full syntax of <application>pg_standby</>'s command line is
<synopsis>
pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>nextwalfile</> <replaceable>xlogfilepath</> <optional> <replaceable>restartwalfile</> </optional>
</synopsis>
When used within <varname>restore_command</>, the <literal>%f</> and
<literal>%p</> macros should be specified for <replaceable>nextwalfile</>
and <replaceable>xlogfilepath</> respectively, to provide the actual file
and path required for the restore.
</para>
<para>
If <replaceable>restartwalfile</> is specified, normally by using the
<literal>%r</literal> macro, then all WAL files logically preceding this
......@@ -118,10 +106,10 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<title><application>pg_standby</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>pg_standby</application> accepts the following command-line arguments:
......@@ -226,9 +214,36 @@ pg_standby <optional> <replaceable>option</> ... </optional> <replaceable>archiv
</variablelist>
</para>
</sect2>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<application>pg_standby</application> is designed to work with
<productname>PostgreSQL</> 8.2 and later.
</para>
<para>
<productname>PostgreSQL</> 8.3 provides the <literal>%r</literal> macro,
which is designed to let <application>pg_standby</application> know the
last file it needs to keep. With <productname>PostgreSQL</> 8.2, the
<literal>-k</literal> option must be used if archive cleanup is
required. This option remains available in 8.3, but its use is deprecated.
</para>
<para>
<productname>PostgreSQL</> 8.4 provides the
<varname>recovery_end_command</> option. Without this option
a leftover trigger file can be hazardous.
</para>
<para>
<application>pg_standby</application> is written in C and has an
easy-to-modify source code, with specifically designated sections to modify
for your own needs
</para>
</refsect1>
<sect2>
<refsect1>
<title>Examples</title>
<para>On Linux or Unix systems, you might use:
......@@ -339,35 +354,21 @@ recovery_end_command = 'del C:\pgsql.trigger.5442'
network.
</para>
</sect2>
<sect2>
<title>Supported Server Versions</title>
</refsect1>
<para>
<application>pg_standby</application> is designed to work with
<productname>PostgreSQL</> 8.2 and later.
</para>
<para>
<productname>PostgreSQL</> 8.3 provides the <literal>%r</literal> macro,
which is designed to let <application>pg_standby</application> know the
last file it needs to keep. With <productname>PostgreSQL</> 8.2, the
<literal>-k</literal> option must be used if archive cleanup is
required. This option remains available in 8.3, but its use is deprecated.
</para>
<para>
<productname>PostgreSQL</> 8.4 provides the
<varname>recovery_end_command</> option. Without this option
a leftover trigger file can be hazardous.
</para>
</sect2>
<sect2>
<refsect1>
<title>Author</title>
<para>
Simon Riggs <email>simon@2ndquadrant.com</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="pgarchivecleanup"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgtestfsync.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgtestfsync.sgml -->
<sect1 id="pgtestfsync" xreflabel="pg_test_fsync">
<title>pg_test_fsync</title>
<refentry id="pgtestfsync">
<refmeta>
<refentrytitle><application>pg_test_fsync</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_test_fsync</refname>
<refpurpose>determine fastest wal_sync_method for <productname>PostgreSQL</productname></refpurpose>
</refnamediv>
<indexterm zone="pgtestfsync">
<primary>pg_test_fsync</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_fsync</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_test_fsync</> is intended to give you a reasonable
idea of what the fastest <xref linkend="guc-wal-sync-method"> is on your
......@@ -17,13 +36,10 @@
since many database servers are not speed-limited by their transaction
logs.
</para>
</refsect1>
<sect2>
<title>Usage</title>
<synopsis>
pg_test_fsync [options]
</synopsis>
<refsect1>
<title>Options</title>
<para>
<application>pg_test_fsync</application> accepts the following
......@@ -62,14 +78,21 @@ pg_test_fsync [options]
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
Bruce Momjian <email>bruce@momjian.us</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="app-postgres"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgtesttiming.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgtesttiming.sgml -->
<sect1 id="pgtesttiming" xreflabel="pg_test_timing">
<title>pg_test_timing</title>
<refentry id="pgtesttiming">
<refmeta>
<refentrytitle><application>pg_test_timing</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_test_timing</refname>
<refpurpose>measure timing overhead</refpurpose>
</refnamediv>
<indexterm zone="pgtesttiming">
<primary>pg_test_timing</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_timing</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_test_timing</> is a tool to measure the timing overhead
on your system and confirm that the system time never moves backwards.
Systems that are slow to collect timing data can give less accurate
<command>EXPLAIN ANALYZE</command> results.
</para>
</refsect1>
<sect2>
<title>Usage</title>
<synopsis>
pg_test_timing [options]
</synopsis>
<refsect1>
<title>Options</title>
<para>
<application>pg_test_timing</application> accepts the following
......@@ -43,9 +59,12 @@ pg_test_timing [options]
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Usage</title>
<refsect2>
<title>Interpreting results</title>
<para>
......@@ -74,8 +93,8 @@ Histogram of timing durations:
one microsecond (usec).
</para>
</sect2>
<sect2>
</refsect2>
<refsect2>
<title>Measuring executor timing overhead</title>
<para>
......@@ -103,8 +122,9 @@ EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
timing overhead would be less problematic.
</para>
</sect2>
<sect2>
</refsect2>
<refsect2>
<title>Changing time sources</title>
<para>
On some newer Linux systems, it's possible to change the clock
......@@ -178,8 +198,8 @@ Histogram of timing durations:
1: 27694571 90.23734%
</screen>
</sect2>
<sect2>
</refsect2>
<refsect2>
<title>Clock hardware and timing accuracy</title>
<para>
......@@ -248,14 +268,22 @@ Histogram of timing durations:
Programmable Interrupt Controller (APIC) timer, and the Cyclone
timer. These timers aim for millisecond resolution.
</para>
</sect2>
</refsect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
Ants Aasma <email>ants.aasma@eesti.ee</email>
</para>
</sect2>
</refsect1>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="sql-explain"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/pgupgrade.sgml
View file @ 1c882e07
<!-- doc/src/sgml/pgupgrade.sgml -->
<sect1 id="pgupgrade" xreflabel="pg_upgrade">
<title>pg_upgrade</title>
<refentry id="pgupgrade">
<refmeta>
<refentrytitle><application>pg_upgrade</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_upgrade</refname>
<refpurpose>upgrade a <productname>PostgreSQL</productname> server instance</refpurpose>
</refnamediv>
<indexterm zone="pgupgrade">
<primary>pg_upgrade</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_upgrade</command>
<arg choice="plain"><option>-b</option></arg>
<arg choice="plain"><replaceable>oldbindir</replaceable></arg>
<arg choice="plain"><option>-B</option></arg>
<arg choice="plain"><replaceable>newbindir</replaceable></arg>
<arg choice="plain"><option>-d</option></arg>
<arg choice="plain"><replaceable>olddatadir</replaceable></arg>
<arg choice="plain"><option>-D</option></arg>
<arg choice="plain"><replaceable>newdatadir</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_upgrade</> (formerly called <application>pg_migrator</>) allows data
stored in <productname>PostgreSQL</> data files to be upgraded to a later <productname>PostgreSQL</>
......@@ -37,19 +64,14 @@
be checked by <application>pg_upgrade</>.
</para>
<sect2>
<title>Supported Versions</title>
<para>
pg_upgrade supports upgrades from 8.3.X and later to the current
major release of <productname>PostgreSQL</>, including snapshot and alpha releases.
</para>
</refsect1>
</sect2>
<sect2>
<title><application>pg_upgrade</> Options</title>
<refsect1>
<title>Options</title>
<para>
<application>pg_upgrade</application> accepts the following command-line arguments:
......@@ -160,10 +182,15 @@
</variablelist>
</para>
</sect2>
</refsect1>
<sect2>
<title>Upgrade Steps</title>
<refsect1>
<title>Usage</title>
<para>
These are the steps to perform an upgrade
with <application>pg_upgrade</application>:
</para>
<procedure>
<step performance="optional">
......@@ -459,13 +486,54 @@ psql --username postgres --file script.sql postgres
</step>
</procedure>
</sect2>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<application>pg_upgrade</> does not support upgrading of databases
containing these <type>reg*</> OID-referencing system data types:
<type>regproc</>, <type>regprocedure</>, <type>regoper</>,
<type>regoperator</>, <type>regconfig</>, and
<type>regdictionary</>. (<type>regtype</> can be upgraded.)
</para>
<para>
All failure, rebuild, and reindex cases will be reported by
<application>pg_upgrade</> if they affect your installation;
post-upgrade scripts to rebuild tables and indexes will be
generated automatically.
</para>
<para>
For deployment testing, create a schema-only copy of the old cluster,
insert dummy data, and upgrade that.
</para>
<para>
If you are upgrading a pre-<productname>PostgreSQL</> 9.2 cluster
that uses a configuration-file-only directory, you must pass the
real data directory location to <application>pg_upgrade</>, and
pass the configuration directory location to the server, e.g.
<literal>-d /real-data-directory -o '-D /configuration-directory'</>.
</para>
<para>
If you want to use link mode and you do not want your old cluster
to be modified when the new cluster is started, make a copy of the
old cluster and upgrade that in link mode. To make a valid copy
of the old cluster, use <command>rsync</> to create a dirty
copy of the old cluster while the server is running, then shut down
the old server and run <command>rsync</> again to update the copy with any
changes to make it consistent.
</para>
<sect2>
<title>Limitations in Upgrading <emphasis>from</> PostgreSQL 8.3</title>
<refsect2>
<title>Limitations in Upgrading PostgreSQL 8.3</title>
<para>
Upgrading from PostgreSQL 8.3 has additional restrictions not present
Upgrading <emphasis>from</emphasis> PostgreSQL 8.3 has additional restrictions not present
when upgrading from later PostgreSQL releases. For example,
pg_upgrade will not work for upgrading from 8.3 if a user column
is defined as:
......@@ -534,49 +602,18 @@ psql --username postgres --file script.sql postgres
possible to upgrade from the MSI installer to the one-click installer.
</para>
</sect2>
<sect2>
<title>Notes</title>
<para>
<application>pg_upgrade</> does not support upgrading of databases
containing these <type>reg*</> OID-referencing system data types:
<type>regproc</>, <type>regprocedure</>, <type>regoper</>,
<type>regoperator</>, <type>regconfig</>, and
<type>regdictionary</>. (<type>regtype</> can be upgraded.)
</para>
<para>
All failure, rebuild, and reindex cases will be reported by
<application>pg_upgrade</> if they affect your installation;
post-upgrade scripts to rebuild tables and indexes will be
generated automatically.
</para>
</refsect2>
<para>
For deployment testing, create a schema-only copy of the old cluster,
insert dummy data, and upgrade that.
</para>
<para>
If you are upgrading a pre-<productname>PostgreSQL</> 9.2 cluster
that uses a configuration-file-only directory, you must pass the
real data directory location to <application>pg_upgrade</>, and
pass the configuration directory location to the server, e.g.
<literal>-d /real-data-directory -o '-D /configuration-directory'</>.
</para>
<para>
If you want to use link mode and you do not want your old cluster
to be modified when the new cluster is started, make a copy of the
old cluster and upgrade that in link mode. To make a valid copy
of the old cluster, use <command>rsync</> to create a dirty
copy of the old cluster while the server is running, then shut down
the old server and run <command>rsync</> again to update the copy with any
changes to make it consistent.
</para>
</refsect1>
</sect2>
<refsect1>
<title>See Also</title>
</sect1>
<simplelist type="inline">
<member><xref linkend="app-initdb"></member>
<member><xref linkend="app-pg-ctl"></member>
<member><xref linkend="app-pgdump"></member>
<member><xref linkend="app-postgres"></member>
</simplelist>
</refsect1>
</refentry>
doc/src/sgml/stylesheet-man.xsl
View file @ 1c882e07
......@@ -30,6 +30,16 @@
<!-- Custom templates -->
<!-- Improve output of email element. See also
<https://sourceforge.net/tracker/?func=detail&aid=3524417&group_id=21935&atid=373747>
-->
<xsl:template match="email">
<xsl:text>&lt;</xsl:text>
<xsl:apply-templates/>
<xsl:text>&gt;</xsl:text>
</xsl:template>
<xsl:template match="refentry" mode="xref-to">
<xsl:param name="referrer"/>
<xsl:param name="xrefstyle"/>
......
doc/src/sgml/vacuumlo.sgml
View file @ 1c882e07
<!-- doc/src/sgml/vacuumlo.sgml -->
<sect1 id="vacuumlo" xreflabel="vacuumlo">
<title>vacuumlo</title>
<refentry id="vacuumlo">
<refmeta>
<refentrytitle><application>vacuumlo</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>vacuumlo</refname>
<refpurpose>remove orphaned large objects from a <productname>PostgreSQL</productname> database</refpurpose>
</refnamediv>
<indexterm zone="vacuumlo">
<primary>vacuumlo</primary>
</indexterm>
<refsynopsisdiv>
<cmdsynopsis>
<command>vacuumlo</command>
<arg choice="opt" rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>vacuumlo</> is a simple utility program that will remove any
<quote>orphaned</> large objects from a
......@@ -22,30 +42,19 @@
to avoid creating orphaned LOs in the first place.
</para>
<sect2>
<title>Usage</title>
<synopsis>
vacuumlo [options] database [database2 ... databaseN]
</synopsis>
<para>
All databases named on the command line are processed. Available options
include:
All databases named on the command line are processed.
</para>
</refsect1>
<variablelist>
<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Write a lot of progress messages.</para>
</listitem>
</varlistentry>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-n</option></term>
<term><option>-h</option> <replaceable>hostname</></term>
<listitem>
<para>Don't remove anything, just show what would be done.</para>
<para>Database server's host.</para>
</listitem>
</varlistentry>
......@@ -62,6 +71,20 @@ vacuumlo [options] database [database2 ... databaseN]
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<listitem>
<para>Don't remove anything, just show what would be done.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>port</></term>
<listitem>
<para>Database server's port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-U</option> <replaceable>username</></term>
<listitem>
......@@ -69,6 +92,13 @@ vacuumlo [options] database [database2 ... databaseN]
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<listitem>
<para>Write a lot of progress messages.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</></term>
<term><option>--no-password</></term>
......@@ -102,50 +132,30 @@ vacuumlo [options] database [database2 ... databaseN]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option> <replaceable>hostname</></term>
<listitem>
<para>Database server's host.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>port</></term>
<listitem>
<para>Database server's port.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</refsect1>
<sect2>
<title>Method</title>
<refsect1>
<title>Notes</title>
<para>
<application>vacuumlo</application> works by the following method:
First, <application>vacuumlo</> builds a temporary table which contains all
of the OIDs of the large objects in the selected database.
</para>
<para>
It then scans through all columns in the database that are of type
<type>oid</> or <type>lo</>, and removes matching entries from the
temporary table. (Note: only types with these names are considered;
in particular, domains over them are not considered.)
</para>
<para>
The remaining entries in the temporary table identify orphaned LOs.
These are removed.
of the OIDs of the large objects in the selected database. It then scans
through all columns in the database that are of type
<type>oid</> or <type>lo</>, and removes matching entries from the temporary
table. (Note: Only types with these names are considered; in particular,
domains over them are not considered.) The remaining entries in the
temporary table identify orphaned LOs. These are removed.
</para>
</sect2>
</refsect1>
<sect2>
<refsect1>
<title>Author</title>
<para>
Peter Mount <email>peter@retep.org.uk</email>
</para>
</sect2>
</refsect1>
</sect1>
</refentry>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment