From aec962d864273897c0a4633e9ef00f123d1edba1 Mon Sep 17 00:00:00 2001
From: Philip Warner <pjw@rhyme.com.au>
Date: Tue, 21 Nov 2000 15:39:09 +0000
Subject: [PATCH] Update for new pg_dump with blobs etc
---
doc/src/sgml/ref/pg_dump.sgml | 256 ++++++++++++++++++++++++++++------
1 file changed, 210 insertions(+), 46 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 1e5c70006da..452cdbf253d 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.23 2000/11/13 23:57:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.24 2000/11/21 15:39:09 pjw Exp $
Postgres documentation
-->
@@ -15,26 +15,29 @@ Postgres documentation
<application>pg_dump</application>
</refname>
<refpurpose>
- Extract a <productname>Postgres</productname> database into a script file
+ Extract a <productname>Postgres</productname> database into a script file or other archive file
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
- <date>1999-07-20</date>
+ <date>2000-11-22</date>
</refsynopsisdivinfo>
<synopsis>
pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
[ -p <replaceable class="parameter">port</replaceable> ]
- [ -t <replaceable class="parameter">table</replaceable> ]
- [ -a ] [ -c ] [ -d ] [ -D ] [ -i ] [ -n ] [ -N ]
- [ -o ] [ -s ] [ -u ] [ -v ] [ -x ]
+ [ -t <replaceable class="parameter">table</replaceable> ]
+ [ -a ] [ -b ] [ -c ] [-C] [ -d ] [ -D ]
+ [-f <REPLACEABLE CLASS="PARAMETER">file</REPLACEABLE>]
+ [-F <REPLACEABLE CLASS="PARAMETER">format</REPLACEABLE>]
+ [ -i ] [ -n ] [ -N ] [ -o ] [ -O ] [-R]
+ [ -s ] [ -S ] [ -u ] [ -v ] [ -x ] [ -Z 0..9 ]
[ <replaceable class="parameter">dbname</replaceable> ]
</synopsis>
<refsect2 id="R2-APP-PG-DUMP-1">
<refsect2info>
- <date>1998-11-05</date>
+ <date>2000-11-22</date>
</refsect2info>
<title>
Inputs
@@ -66,20 +69,39 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
</listitem>
</varlistentry>
- <varlistentry>
- <term>-c</term>
- <listitem>
- <para>
- Clean (drop) schema prior to create.
- </para>
- </listitem>
- </varlistentry>
-
+ <varlistentry>
+ <term>-b</term>
+ <listitem>
+ <para>
+ Dump BLOB data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-c</term>
+ <listitem>
+ <para>
+ Clean (drop) schema prior to create.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-C</term>
+ <listitem>
+ <para>
+ For plain text (script) output, include SQL to create the database itself.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-d</term>
<listitem>
<para>
- Dump data as proper insert strings.
+ Dump data as proper insert strings. This is not recommended for large databases
+ for performance reasons.
</para>
</listitem>
</varlistentry>
@@ -88,10 +110,68 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
<term>-D</term>
<listitem>
<para>
- Dump data as inserts with attribute names
+ Dump data as inserts with attribute names. This is not recommended for large databases
+ for performance reasons.
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>-f <replaceable class="parameter">file</replaceable></term>
+ <listitem>
+ <para>
+ Send output to the specified file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-F <replaceable class="parameter">format</replaceable></term>
+ <listitem>
+ <para>
+ Format can be one of the following:
+ </para>
+
+
+ <variablelist>
+ <varlistentry>
+ <term>p</term>
+ <listitem>
+ <para>
+ output a plain text SQL script file (default)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>t</term>
+ <listitem>
+ <para>
+ output a TAR archive suitable for input into
+ <APPLICATION>pg_restore</APPLICATION>. Using this archive format
+ allows reordering and/or exclusion of schema elements
+ at the time the database is restored. It is also possible to limit
+ which data is reloaded at restore time.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>c</term>
+ <listitem>
+ <para>
+ output a custom archive suitable for input into
+ <APPLICATION>pg_restore</APPLICATION>. This is the most flexible
+ format in that it allows reordering of data load as well
+ as schema elements. This format is also compressed by default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+ </varlistentry>
<varlistentry>
<term>-i</term>
@@ -132,15 +212,37 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
</listitem>
</varlistentry>
- <varlistentry>
- <term>-o</term>
- <listitem>
- <para>
- Dump object identifiers (<acronym>OID</acronym>s) for every table.
- </para>
- </listitem>
- </varlistentry>
-
+ <varlistentry>
+ <term>-o</term>
+ <listitem>
+ <para>
+ Dump object identifiers (<acronym>OID</acronym>s) for every table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-O</term>
+ <listitem>
+ <para>
+ In plain text output mode, don't set object ownership to match the
+ original database. Typically, <APPLICATION>pg_dump</APPLICATION>
+ issues <PROGRAMLISTING>\connect</PROGRAMLISTING> statments to set
+ ownership of schema elements.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-R</term>
+ <listitem>
+ <para>
+ In plain text output mode, prohibit <APPLICATION>pg_dump</APPLICATION>
+ from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> statements.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-s</term>
<listitem>
@@ -150,15 +252,25 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
</listitem>
</varlistentry>
- <varlistentry>
- <term>-t <replaceable class="parameter">table</replaceable></term>
- <listitem>
- <para>
- Dump data for <replaceable class="parameter">table</replaceable> only.
- </para>
- </listitem>
- </varlistentry>
-
+ <varlistentry>
+ <term>-S <replaceable class="parameter">username</replaceable></term>
+ <listitem>
+ <para>
+ Specify the superuser username to use when disabling triggers and/or
+ setting ownership of schema elements.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-t <replaceable class="parameter">table</replaceable></term>
+ <listitem>
+ <para>
+ Dump data for <replaceable class="parameter">table</replaceable> only.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-u</term>
<listitem>
@@ -185,6 +297,17 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>-Z <replaceable class="parameter">0..9</replaceable></term>
+ <listitem>
+ <para>
+ Specify the compression level to use in archive formats that support
+ compression (currently only the custom archive format supports compression).
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
@@ -306,17 +429,26 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<refsect1 id="R1-APP-PG-DUMP-1">
<refsect1info>
- <date>1998-11-05</date>
+ <date>2000-</date>
</refsect1info>
<title>
Description
</title>
<para>
<application>pg_dump</application> is a utility for dumping out a
- <productname>Postgres</productname> database into a script file
- containing query commands. The script
- files are in text format and can be used to reconstruct the database,
- even on other machines and other architectures.
+ <productname>Postgres</productname> database into a script or archive
+ file containing query commands. The script files are in text format
+ and can be used to reconstruct the database, even on other machines
+ and other architectures.
+ </para>
+ <para>
+ The archive files, new with this v7.1, contain enough information for
+ <APPLICATION>pg_restore</APPLICATION> to rebuild the database, but also
+ allow pg_restore to be selective about what is restored, or even to
+ reorder the items prior to being restored. The archive files should
+ also be portable across architectures.
+ </para>
+ <para>
<application>pg_dump</application>
will produce the queries necessary to re-generate all
user-defined types, functions, tables, indices, aggregates, and
@@ -330,14 +462,28 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
is useful for dumping out the contents of a database to move from one
<productname>Postgres</productname> installation to another. After running
<application>pg_dump</application>,
- one should examine the output script file for any warnings, especially
+ one should examine the output for any warnings, especially
in light of the limitations listed below.
</para>
+
+ <para>
+ When used with one of the alternate file formats and combined with
+ <APPLICATION>pg_restore</APPLICATION>, it provides a flexible archival
+ and trasfer mechanism. <APPLICATION>pg_dump</APPLICATION> can be used
+ to backup an entire database, then <APPLICATION>pg_restore</APPLICATION>
+ can be used to examine the archive and/or select which parts of the
+ database are to be restored.
+ </para>
+
+ <para>
+ See the <APPLICATION>pg_restore</APPLICATION> documentation for details.
+ </para>
+
</refsect1>
<refsect1 id="R1-APP-PG-DUMP-2">
<refsect1info>
- <date>1998-11-05</date>
+ <date>2000-11-21</date>
</refsect1info>
<title>
Notes
@@ -359,8 +505,9 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem>
<para>
- <application>pg_dump</application> does not handle large objects.
- Large objects are ignored and must be dealt with manually.
+ When dumping a single table or as plain text, <application>pg_dump</application>
+ does not handle large objects. Large objects must be dumped in their
+ entirity using one of the binary archive formats.
</para>
</listitem>
@@ -379,7 +526,7 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<refsect1 id="R1-APP-PG-DUMP-3">
<refsect1info>
- <date>1998-11-05</date>
+ <date>2000-11-21</date>
</refsect1info>
<title>
Usage
@@ -399,6 +546,23 @@ $ pg_dump > db.out
$ psql -e database < db.out
</programlisting>
</para>
+
+ <para>
+ To dump a database called mydb that contains BLOBs to a TAR file:
+
+ <programlisting>
+$ pg_dump -Ft --blobs mydb > db.tar
+ </programlisting>
+ </para>
+
+ <para>
+ To reload this database (with BLOBs) to an existing db called newdb:
+
+ <programlisting>
+$ pg_restore db.tar --db=newdb
+ </programlisting>
+ </para>
+
</refsect1>
</refentry>
--
GitLab