diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_dump.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_dump.sgml | 805 |
1 files changed, 389 insertions, 416 deletions
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index e56b573cca..f96d278b4b 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1,423 +1,396 @@ -<REFENTRY ID="APP-PG-DUMP"> -<REFMETA> -<REFENTRYTITLE id="pg-dump"> -<application>pg_dump</application> -</REFENTRYTITLE> -<REFMISCINFO>Application</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME> -<application>pg_dump</application> -</REFNAME> -<REFPURPOSE> -Extract a <productname>Postgres</productname> database into a script file -</REFPURPOSE> - </refnamediv> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-11-05</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> +<refentry id="APP-PG-DUMP"> + <refmeta> + <refentrytitle id="pg-dump"> + <application>pg_dump</application> + </refentrytitle> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + <application>pg_dump</application> + </refname> + <refpurpose> + Extract a <productname>Postgres</productname> database into a script file + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1998-11-05</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> ] - [ -f <replaceable class="parameter">outputfile</replaceable> ] + [ -t <replaceable class="parameter">table</replaceable> ] [ -f <replaceable class="parameter">outputfile</replaceable> ] [ -a ] [ -c ] [ -d ] [ -D ] [ -n ] [ -N ] [ -o ] [ -s ] [ -u ] [ -v ] [ -x ] [ <replaceable class="parameter">dbname</replaceable> ] -</SYNOPSIS> - - <REFSECT2 ID="R2-APP-PG-DUMP-1"> - <REFSECT2INFO> - <DATE>1998-11-05</DATE> - </REFSECT2INFO> - <TITLE> - Inputs - </TITLE> - <PARA> - <application>pg_dump</application> accepts the following command line arguments: - - <variablelist> - <varlistentry> - <term> - <replaceable class="parameter">dbname</replaceable> - </term> - <listitem> - <para> - Specifies the name of the database to be extracted. - <replaceable class="parameter">dbname</replaceable> - defaults to the value of the - <envar>USER</envar> - environment variable. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -a - </term> - <listitem> - <para> - Dump out only the data, no schema (definitions). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -c - </term> - <listitem> - <para> - Clean(drop) schema prior to create. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -d - </term> - <listitem> - <para> - Dump data as proper insert strings. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -D - </term> - <listitem> - <para> - Dump data as inserts with attribute names - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -f <replaceable class="parameter">filename</replaceable> - </term> - <listitem> - <para> - Specifies the output file. Defaults to <filename>stdout</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -n - </term> - <listitem> - <para> - Suppress double quotes around identifiers unless absolutely necessary. - This may cause trouble loading this dumped data if there are reserved words - used for identifiers. - This was the default behavior in pre-v6.4 <application>pg_dump</application>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -N - </term> - <listitem> - <para> - Include double quotes around identifiers. - This is the default. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -o - </term> - <listitem> - <para> - Dump object identifiers (<acronym>OID</acronym>s) for every table. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -s - </term> - <listitem> - <para> - Dump out only the schema (definitions), no data. - </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> - <para> - Use password authentication. Prompts for username and password. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -v - </term> - <listitem> - <para> - Specifies verbose mode - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -x - </term> - <listitem> - <para> - Prevent dumping of ACLs (grant/revoke commands) and table ownership information. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - <para> - <application>pg_dump</application> also accepts - the following command line arguments for connection parameters: - - <variablelist> - <varlistentry> - <term> - -h <replaceable class="parameter">host</replaceable> - </term> - <listitem> - <para> - Specifies the hostname of the machine on which the - <application>postmaster</application> - is running. Defaults to using a local Unix domain socket - rather than an IP connection.. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -p <replaceable class="parameter">port</replaceable> - </term> - <listitem> - <para> - Specifies the Internet TCP/IP port or local Unix domain socket file - extension on which the <application>postmaster</application> - is listening for connections. The port number defaults to 5432, - or the value of the <envar>PGPORT</envar> - environment variable (if set). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - -u - </term> - <listitem> - <para> - Use password authentication. - Prompts for - <replaceable class="parameter">username</replaceable> - and <replaceable class="parameter">password</replaceable>. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect2> - - <REFSECT2 ID="R2-APP-PG-DUMP-2"> - <REFSECT2INFO> - <DATE>1998-11-05</DATE> - </REFSECT2INFO> - <TITLE> - Outputs - </TITLE> - <PARA> - <application>pg_dump</application> will create a file or - write to <filename>stdout</filename>. - - <variablelist> - <varlistentry> - <term> - Connection to database 'template1' failed. - connectDB() failed: Is the postmaster running and accepting connections - at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? - </term> - <listitem> - <para> - <application>pg_dump</application> could not attach to the - <application>postmaster</application> - process on the specified host and port. If you see this message, - ensure that the <application>postmaster</application> - is running on the proper host and that you have specified the proper - port. If your site uses an authentication system, ensure that you - have obtained the required authentication credentials. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - Connection to database '<replaceable class="parameter">dbname</replaceable>' failed. - FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' - </term> - <listitem> - <para> - You do not have a valid entry in the relation <literal>pg_shadow</literal> - and and will not be allowed to access <productname>Postgres</productname>. - Contact your <productname>Postgres</productname> administrator. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed - </term> - <listitem> - <para> - You do not have permission to read the database. - Contact your <productname>Postgres</productname> site administrator. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - <note> - <para> - <application>pg_dump</application> internally executes - <command>SELECT</command> statements. If you have problems running - <application>pg_dump</application>, - make sure you are able to select information from the database using, for - example, <application>psql</application>. - </para> - </note> - </refsect2> - </refsynopsisdiv> - - <REFSECT1 ID="R1-APP-PG-DUMP-1"> - <REFSECT1INFO> - <DATE>1998-11-05</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. - <application>pg_dump</application> - will produce the queries necessary to re-generate all - user-defined types, functions, tables, indices, aggregates, and - operators. In addition, all the data is copied out in text format so - that it can be readily copied in again, as well as imported into tools - for editing. - </para> - <para> - <application>pg_dump</application> - 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 - in light of the limitations listed below. - </para> - </refsect1> - - <REFSECT1 ID="R1-APP-PG-DUMP-2"> - <REFSECT1INFO> - <DATE>1998-11-05</DATE> - </REFSECT1INFO> - <TITLE> - Notes - </TITLE> - <PARA> - <application>pg_dump</application> has a few limitations. - The limitations mostly stem from - difficulty in extracting certain meta-information from the system - catalogs. - - <variablelist> - <varlistentry> - <term> - partial indices - </term> - <listitem> - <para> - <application>pg_dump</application> - does not understand partial indices. The reason is - the same as above; partial index predicates are stored as plans. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - large objects - </term> - <listitem> - <para> - <application>pg_dump</application> does not handle large objects. - Large objects are ignored and must be dealt with manually. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect1> - - <REFSECT1 ID="R1-APP-PG-DUMP-3"> - <REFSECT1INFO> - <DATE>1998-11-05</DATE> - </REFSECT1INFO> - <TITLE> - Usage - </TITLE> - <PARA> - To dump a database of the same name as the user: - - <programlisting> - % pg_dump > db.out - </programlisting> - </para> + </synopsis> + + <refsect2 id="R2-APP-PG-DUMP-1"> + <refsect2info> + <date>1998-11-05</date> + </refsect2info> + <title> + Inputs + </title> + <para> + <application>pg_dump</application> accepts the following command + line arguments: + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">dbname</replaceable></term> + <listitem> + <para> + Specifies the name of the database to be extracted. + <replaceable class="parameter">dbname</replaceable> + defaults to the value of the + <envar>USER</envar> + environment variable. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-a</term> + <listitem> + <para> + Dump out only the data, no schema (definitions). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-c</term> + <listitem> + <para> + Clean(drop) schema prior to create. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-d</term> + <listitem> + <para> + Dump data as proper insert strings. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-D</term> + <listitem> + <para> + Dump data as inserts with attribute names + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-f <replaceable class="parameter">filename</replaceable></term> + <listitem> + <para> + Specifies the output file. Defaults to <filename>stdout</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-n</term> + <listitem> + <para> + Suppress double quotes around identifiers unless absolutely necessary. + This may cause trouble loading this dumped data if there are reserved words + used for identifiers. + This was the default behavior in pre-v6.4 <application>pg_dump</application>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-N</term> + <listitem> + <para> + Include double quotes around identifiers. + This is the default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-o</term> + <listitem> + <para> + Dump object identifiers (<acronym>OID</acronym>s) for every table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-s</term> + <listitem> + <para> + Dump out only the schema (definitions), no data. + </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> + <para> + Use password authentication. Prompts for username and password. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-v</term> + <listitem> + <para> + Specifies verbose mode + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-x</term> + <listitem> + <para> + Prevent dumping of ACLs (grant/revoke commands) and table ownership information. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + <para> + <application>pg_dump</application> also accepts + the following command line arguments for connection parameters: + + <variablelist> + <varlistentry> + <term>-h <replaceable class="parameter">host</replaceable></term> + <listitem> + <para> + Specifies the hostname of the machine on which the + <application>postmaster</application> + is running. Defaults to using a local Unix domain socket + rather than an IP connection.. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-p <replaceable class="parameter">port</replaceable></term> + <listitem> + <para> + Specifies the Internet TCP/IP port or local Unix domain socket file + extension on which the <application>postmaster</application> + is listening for connections. The port number defaults to 5432, + or the value of the <envar>PGPORT</envar> + environment variable (if set). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-u</term> + <listitem> + <para> + Use password authentication. + Prompts for + <replaceable class="parameter">username</replaceable> + and <replaceable class="parameter">password</replaceable>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <refsect2 id="R2-APP-PG-DUMP-2"> + <refsect2info> + <date>1998-11-05</date> + </refsect2info> + <title> + Outputs + </title> + <para> + <application>pg_dump</application> will create a file or + write to <filename>stdout</filename>. + + <variablelist> + <varlistentry> + <term><computeroutput> +Connection to database 'template1' failed. +connectDB() failed: Is the postmaster running and accepting connections + at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'? + </computeroutput></term> + <listitem> + <para> + <application>pg_dump</application> could not attach to the + <application>postmaster</application> + process on the specified host and port. If you see this message, + ensure that the <application>postmaster</application> + is running on the proper host and that you have specified the proper + port. If your site uses an authentication system, ensure that you + have obtained the required authentication credentials. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><computeroutput> +Connection to database '<replaceable class="parameter">dbname</replaceable>' failed. +FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow' + </computeroutput></term> + <listitem> + <para> + You do not have a valid entry in the relation <literal>pg_shadow</literal> + and and will not be allowed to access <productname>Postgres</productname>. + Contact your <productname>Postgres</productname> administrator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><computeroutput> +dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed + </computeroutput></term> + <listitem> + <para> + You do not have permission to read the database. + Contact your <productname>Postgres</productname> site administrator. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <note> <para> - To reload this database: - - <programlisting> - psql -e database < db.out - </programlisting> + <application>pg_dump</application> internally executes + <command>SELECT</command> statements. If you have problems running + <application>pg_dump</application>, + make sure you are able to select information from the database using, for + example, <application>psql</application>. </para> - </refsect1> -</REFENTRY> + </note> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-APP-PG-DUMP-1"> + <refsect1info> + <date>1998-11-05</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. + <application>pg_dump</application> + will produce the queries necessary to re-generate all + user-defined types, functions, tables, indices, aggregates, and + operators. In addition, all the data is copied out in text format so + that it can be readily copied in again, as well as imported into tools + for editing. + </para> + + <para> + <application>pg_dump</application> + 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 + in light of the limitations listed below. + </para> + </refsect1> + + <refsect1 id="R1-APP-PG-DUMP-2"> + <refsect1info> + <date>1998-11-05</date> + </refsect1info> + <title> + Notes + </title> + <para> + <application>pg_dump</application> has a few limitations. + The limitations mostly stem from + difficulty in extracting certain meta-information from the system + catalogs. + + <itemizedlist> + <listitem> + <para> + <application>pg_dump</application> + does not understand partial indices. The reason is + the same as above; partial index predicates are stored as plans. + </para> + </listitem> + + <listitem> + <para> + <application>pg_dump</application> does not handle large objects. + Large objects are ignored and must be dealt with manually. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + + <refsect1 id="R1-APP-PG-DUMP-3"> + <refsect1info> + <date>1998-11-05</date> + </refsect1info> + <title> + Usage + </title> + <para> + To dump a database of the same name as the user: + + <programlisting> +% pg_dump > db.out + </programlisting> + </para> + + <para> + To reload this database: + + <programlisting> +% psql -e database < db.out + </programlisting> + </para> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> |