path: root/doc/src/sgml/ref/pg_dump.sgml

<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> ]
    [ -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>
    <para>
      To reload this database:
      
      <programlisting>
	psql -e database < db.out
      </programlisting>
    </para>
  </refsect1>
</REFENTRY>