From aec962d864273897c0a4633e9ef00f123d1edba1 Mon Sep 17 00:00:00 2001 From: Philip Warner 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 1e5c70006d..452cdbf253 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,5 +1,5 @@ @@ -15,26 +15,29 @@ Postgres documentation pg_dump - Extract a Postgres database into a script file + Extract a Postgres database into a script file or other archive file - 1999-07-20 + 2000-11-22 pg_dump [ dbname ] pg_dump [ -h host ] [ -p port ] - [ -t table ] - [ -a ] [ -c ] [ -d ] [ -D ] [ -i ] [ -n ] [ -N ] - [ -o ] [ -s ] [ -u ] [ -v ] [ -x ] + [ -t table ] + [ -a ] [ -b ] [ -c ] [-C] [ -d ] [ -D ] + [-f file] + [-F format] + [ -i ] [ -n ] [ -N ] [ -o ] [ -O ] [-R] + [ -s ] [ -S ] [ -u ] [ -v ] [ -x ] [ -Z 0..9 ] [ dbname ] - 1998-11-05 + 2000-11-22 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 pg_dump is a utility for dumping out a - Postgres 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. + Postgres 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. + + + The archive files, new with this v7.1, contain enough information for + pg_restore 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. + + pg_dump will produce the queries necessary to re-generate all user-defined types, functions, tables, indices, aggregates, and @@ -330,14 +462,28 @@ dumpSequence(table): SELECT failed is useful for dumping out the contents of a database to move from one Postgres installation to another. After running pg_dump, - 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. + + + When used with one of the alternate file formats and combined with + pg_restore, it provides a flexible archival + and trasfer mechanism. pg_dump can be used + to backup an entire database, then pg_restore + can be used to examine the archive and/or select which parts of the + database are to be restored. + + + + See the pg_restore documentation for details. + + - 1998-11-05 + 2000-11-21 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> -- 2.40.0