mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2025-01-18 18:44:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

Editorial work on descriptions of options.

Browse Source
This commit is contained in:
Tom Lane 2001-10-23 22:11:22 +00:00
parent b662e321c5
commit 92e1b7431f
3 changed files with 126 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
doc/src/sgml/ref/pg_dump.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.37 2001/09/21 21:58:29 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.38 2001/10/23 22:11:22 tgl Exp $
Postgres documentation
-->
@ -64,7 +64,7 @@ Postgres documentation
<productname>PostgreSQL</productname> database into a script or an
archive file. The script files are in plain text format and
contain the SQL commands required to reconstruct the database to
the state it was in at the time is was saved. They can be used to
the state it was in at the time it was saved. They can be used to
reconstruct the database even on other machines and other
architectures, with some modifications even on other RDBMS
products. The alternative archive file formats are meant to be
@ -91,12 +91,19 @@ Postgres documentation
<para>
When used with one of the archive file formats and combined with
<command>pg_restore</command>, it provides a flexible archival and
<xref linkend="app-pgrestore">, <command>pg_dump</command> provides a
flexible archival and
transfer mechanism. <command>pg_dump</command> can be used to
backup an entire database, then <command>pg_restore</command> can
be used to examine the archive and/or select which parts of the
database are to be restored. See the <xref
linkend="app-pgrestore"> documentation for details.
database are to be restored.
The most flexible output file format is the <quote>custom</quote>
format (<option>-Fc</option>). It allows for selection and
reordering of all archived items, and is compressed by default. The
<filename>tar</filename> format (<option>-Ft</option>) is not
compressed and it is not possible to reorder data when loading, but
it is otherwise quite flexible; moreover, it can be manipulated with
other tools such as <filename>tar</filename>.
</para>
<para>
@ -124,7 +131,7 @@ Postgres documentation
<term><replaceable class="parameter">dbname</replaceable></term>
<listitem>
<para>
Specifies the name of the database to be extracted.
Specifies the name of the database to be dumped.
</para>
</listitem>
</varlistentry>
@ -136,6 +143,12 @@ Postgres documentation
<para>
Dump only the data, not the schema (data definitions).
</para>
<para>
This option is only meaningful for the plain text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
</varlistentry>
@ -154,8 +167,14 @@ Postgres documentation
<term>--clean</term>
<listitem>
<para>
Output commands to clean (drop) the schema prior to (the
commands for) creating it.
Output commands to clean (drop)
database objects prior to (the commands for) creating them.
</para>
<para>
This option is only meaningful for the plain text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
</varlistentry>
@ -165,7 +184,16 @@ Postgres documentation
<term>--create</term>
<listitem>
<para>
For plain text (script) output, include commands to create the database itself.
Begin the output with a command to create the
database itself and reconnect to the created database. (With a
script of this form, it doesn't matter which database you connect
to before running the script.)
</para>
<para>
This option is only meaningful for the plain text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
</varlistentry>
@ -175,7 +203,7 @@ Postgres documentation
<term>--inserts</term>
<listitem>
<para>
Dump data as proper <command>INSERT</command> commands (rather
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very
slow, but it makes the archives more portable to other RDBMS
packages.
@ -193,7 +221,8 @@ Postgres documentation
column names (<literal>INSERT INTO
<replaceable>table</replaceable>
(<replaceable>column</replaceable>, ...) VALUES
...</literal>). This will make restoration very slow.
...</literal>). This will make restoration very slow,
but it is necessary if you desire to rearrange column ordering.
</para>
</listitem>
</varlistentry>
@ -306,7 +335,7 @@ Postgres documentation
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every
table. Use this option if your application references the oid
table. Use this option if your application references the OID
columns in some way (e.g., in a foreign key constraint).
Otherwise, this option should not be used.
</para>
@ -318,7 +347,7 @@ Postgres documentation
<term>--no-owner</term>
<listitem>
<para>
In plain text output mode, do not output commands to set the
Do not output commands to set the
object ownership to match the original database. Typically,
<command>pg_dump</command> issues
(<command>psql</command>-specific) <command>\connect</command>
@ -332,7 +361,7 @@ Postgres documentation
<para>
This option is only meaningful for the plain text format. For
the other formats, you need to specify the option when you
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
@ -343,7 +372,7 @@ Postgres documentation
<term>--no-reconnect</term>
<listitem>
<para>
In plain text output mode, prohibit <command>pg_dump</command>
Prohibit <command>pg_dump</command>
from outputting a script that would require reconnections to
the database while being restored. An average restoration
script usually has to reconnect several times as different
@ -362,7 +391,7 @@ Postgres documentation
<para>
This option is only meaningful for the plain text format. For
the other formats, you need to specify the option when you
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>
@ -451,7 +480,7 @@ Postgres documentation
<para>
This option is only meaningful for the plain text format. For
the other formats, you need to specify the option when you
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</listitem>

14
doc/src/sgml/ref/pg_dumpall.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.24 2001/10/05 15:50:11 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.25 2001/10/23 22:11:22 tgl Exp $
Postgres documentation
-->
@ -50,7 +50,12 @@ Postgres documentation
<para>
Thus, <application>pg_dumpall</application> is an integrated
solution for backing up your databases.
solution for backing up your databases. But note a limitation:
it cannot dump <quote>large objects</quote>, since
<application>pg_dump</application> cannot dump such objects into
text files. If you have databases containing large objects,
they should be dumped using one of <application>pg_dump</application>'s
non-text output modes.
</para>
<para>
@ -78,7 +83,10 @@ Postgres documentation
<term>-c, --clean</term>
<listitem>
<para>
Clean (drop) database before creating schema.
Include SQL commands to clean (drop) database objects before
recreating them. (This option is fairly useless, since the
output script expects to create the databases themselves;
they would always be empty upon creation.)
</para>
</listitem>
</varlistentry>

143
doc/src/sgml/ref/pg_restore.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.17 2001/09/21 21:58:30 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.18 2001/10/23 22:11:22 tgl Exp $ -->
<refentry id="APP-PGRESTORE">
<docinfo>
@ -62,7 +62,10 @@
<command>pg_restore</command> is a utility for restoring a
<productname>Postgres</productname> database from an archive
created by <xref linkend="app-pgdump"> in one of the non-plain-text
formats.
formats. It
will issue the commands necessary to re-generate all user-defined
types, functions, tables, indexes, aggregates, and operators, as
well as the data in the tables.
</para>
<para>
@ -70,10 +73,7 @@
<command>pg_restore</command> to rebuild the database, but also
allow <command>pg_restore</command> to be selective about what is
restored, or even to reorder the items prior to being restored. The
archive files are designed to be portable across architectures. It
will issue the commands necessary to re-generate all user-defined
types, functions, tables, indexes, aggregates, and operators, as
well as the data in the tables.
archive files are designed to be portable across architectures.
</para>
<para>
@ -84,7 +84,7 @@
or standard output), similar to the ones created by the
<command>pg_dump</command> plain text format. Some of the options
controlling the script output are therefore analogous to
<command>pg_dump</command>.
<command>pg_dump</command> options.
</para>
<para>
@ -96,67 +96,6 @@
using <command>COPY</command> statements.
</para>
<para>
The most flexible output file format is the <quote>custom</quote>
format (<option>-Fc</option>). It allows for selection and
reordering of all archived items, and is compressed by default. The
<filename>tar</filename> format (<option>-Ft</option>) is not
compressed and it is not possible to reorder data when loading, but
it is otherwise quite flexible.
</para>
<para>
To reorder the items, it is first necessary to dump the table of
contents of the archive:
<screen>
<prompt>$</prompt> <userinput>pg_restore archive.file -l &gt; archive.list</userinput>
</screen>
This file consists of a header and one line for each item, e.g.,
<programlisting>
;
; Archive created at Fri Jul 28 22:28:36 2000
; dbname: birds
; TOC Entries: 74
; Compression: 0
; Dump Version: 1.4-0
; Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>
Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
internal archive ID assigned to each item.
</para>
<para>
Lines in the file can be commented out, deleted, and reordered. For example,
<programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
could be used as input to <command>pg_restore</command> and would only restore
items 10 and 6, in that order.
<screen>
<prompt>$</prompt> <userinput>pg_restore archive.file -L archive.list</userinput>
</screen>
</para>
<refsect2 id="app-pgrestore-options">
<title>
Options
@ -192,7 +131,7 @@
<term>--clean</term>
<listitem>
<para>
Clean (drop) schema prior to create.
Clean (drop) database objects before recreating them.
</para>
</listitem>
</varlistentry>
@ -202,7 +141,11 @@
<term>--create</term>
<listitem>
<para>
Include SQL to create the schema.
Create the database before restoring into it.
(When this switch appears, the database named with <option>-d</option>
is used only
to issue the initial CREATE DATABASE command. All data is restored
into the database name that appears in the archive.)
</para>
</listitem>
</varlistentry>
@ -223,8 +166,8 @@
<term>--file=<replaceable>filename</replaceable></term>
<listitem>
<para>
Specify output file for generated script. (Use with the
<option>-l</option> option.) Default is the standard output.
Specify output file for generated script, or for the listing
when used with <option>-l</option>. Default is the standard output.
</para>
</listitem>
</varlistentry>
@ -365,7 +308,7 @@
While restoring an archive, <command>pg_restore</command>
typically has to reconnect to the database several times with
different user names to set the correct ownership of the
created objects. If this is undesriable (e.g., because manual
created objects. If this is undesirable (e.g., because manual
interaction (passwords) would be necessary for each
reconnection), this option prevents
<command>pg_restore</command> from issuing any reconnection
@ -449,7 +392,7 @@
<para>
Normally, if restoring an archive requires altering the
current database user (e.g., to set correct object
ownerships), a new connection to the database must be openend,
ownerships), a new connection to the database must be opened,
which might require manual interaction (e.g., passwords). If
you use the <option>-X use-set-session-authorization</option>,
then <command>pg_restore</command> will instead use the <xref
@ -634,6 +577,58 @@ connectDBStart() -- connect() failed: No such file or directory
<screen>
<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
</screen>
</para>
<para>
To reorder database items, it is first necessary to dump the table of
contents of the archive:
<screen>
<prompt>$</prompt> <userinput>pg_restore archive.file -l &gt; archive.list</userinput>
</screen>
The listing file consists of a header and one line for each item, e.g.,
<programlisting>
;
; Archive created at Fri Jul 28 22:28:36 2000
; dbname: birds
; TOC Entries: 74
; Compression: 0
; Dump Version: 1.4-0
; Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>
Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
internal archive ID assigned to each item.
</para>
<para>
Lines in the file can be commented out, deleted, and reordered. For example,
<programlisting>
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
could be used as input to <command>pg_restore</command> and would only restore
items 10 and 6, in that order.
<screen>
<prompt>$</prompt> <userinput>pg_restore archive.file -L archive.list</userinput>
</screen>
</para>