granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/pg_dump.sgml

   1 <REFENTRY ID="APP-PG-DUMP">
   2 <REFMETA>
   3 <REFENTRYTITLE>
   4 <application>pg_dump</application>
   5 </REFENTRYTITLE>
   6 <REFMISCINFO>Application</REFMISCINFO>
   7 </REFMETA>
   8 <REFNAMEDIV>
   9 <REFNAME id="pg-dump">
  10 <application>pg_dump</application>
  11 </REFNAME>
  12 <REFPURPOSE>
  13 Extract a <productname>Postgres</productname> database into a script file
  14 </REFPURPOSE>
  15 <REFSYNOPSISDIV>
  16 <REFSYNOPSISDIVINFO>
  17 <DATE>1998-10-04</DATE>
  18 </REFSYNOPSISDIVINFO>
  19 <SYNOPSIS>
  20 pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
  21 pg_dump [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
  22     [ -t <replaceable class="parameter">table</replaceable> ]
  23     [ -f <replaceable class="parameter">outputfile</replaceable> ]
  24     [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
  25     [ <replaceable class="parameter">dbname</replaceable> ]
  26 </SYNOPSIS>
  27
  28 <REFSECT2 ID="R2-APP-PG-DUMP-1">
  29 <REFSECT2INFO>
  30 <DATE>1998-10-04</DATE>
  31 </REFSECT2INFO>
  32 <TITLE>
  33 Inputs
  34 </TITLE>
  35 <PARA>
  36 <application>pg_dump</application> accepts the following command line arguments:
  37
  38 <variablelist>
  39 <varlistentry>
  40 <term>
  41 <replaceable class="parameter">dbname</replaceable>
  42 </term>
  43 <listitem>
  44 <para>
  45 Specifies the name of the database to be extracted.
  46 <replaceable class="parameter">dbname</replaceable>
  47 defaults to the value of the
  48 <envar>USER</envar>
  49 environment variable.
  50
  51 <varlistentry>
  52 <term>
  53 -a
  54 </term>
  55 <listitem>
  56 <para>
  57 Dump out only the data, no schema (definitions).
  58
  59 <varlistentry>
  60 <term>
  61 -d
  62 </term>
  63 <listitem>
  64 <para>
  65 Dump data as proper insert strings.
  66
  67 <varlistentry>
  68 <term>
  69 -D
  70 </term>
  71 <listitem>
  72 <para>
  73 Dump data as inserts with attribute names
  74
  75 <varlistentry>
  76 <term>
  77 -f <replaceable class="parameter">filename</replaceable>
  78 </term>
  79 <listitem>
  80 <para>
  81 Specifies the output file. Defaults to <filename>stdout</filename>.
  82
  83 <varlistentry>
  84 <term>
  85 -n
  86 </term>
  87 <listitem>
  88 <para>
  89 Suppress double quotes around identifiers unless absolutely necessary.
  90 This may cause trouble loading this dumped data if there are reserved words
  91 used for identifiers.
  92
  93 <varlistentry>
  94 <term>
  95 -o
  96 </term>
  97 <listitem>
  98 <para>
  99 Dump object identifiers (<acronym>OID</acronym>s) for every table.
 100
 101 <varlistentry>
 102 <term>
 103 -s
 104 </term>
 105 <listitem>
 106 <para>
 107 Dump out only the schema (definitions), no data.
 108
 109 <varlistentry>
 110 <term>
 111 -t <replaceable class="parameter">table</replaceable>
 112 </term>
 113 <listitem>
 114 <para>
 115 Dump data for <replaceable class="parameter">table</replaceable> only.
 116
 117 <varlistentry>
 118 <term>
 119 -u
 120 </term>
 121 <listitem>
 122 <para>
 123 Use password authentication. Prompts for username and password.
 124
 125 <varlistentry>
 126 <term>
 127 -v
 128 </term>
 129 <listitem>
 130 <para>
 131 Specifies verbose mode
 132
 133 <varlistentry>
 134 <term>
 135 -z
 136 </term>
 137 <listitem>
 138 <para>
 139 Include ACLs (grant/revoke commands) and table ownership information.
 140
 141 </variablelist>
 142
 143 <para>
 144 <application>pg_dump</application> also accepts
 145 the following command line arguments for connection parameters:
 146
 147 <variablelist>
 148 <varlistentry>
 149 <term>
 150 -h <replaceable class="parameter">host</replaceable>
 151 </term>
 152 <listitem>
 153 <para>
 154 Specifies the hostname of the machine on which the
 155 <application>postmaster</application>
 156 is running.  Defaults to using a local Unix domain socket
 157  rather than an IP connection..
 158
 159 <varlistentry>
 160 <term>
 161 -p <replaceable class="parameter">port</replaceable>
 162 </term>
 163 <listitem>
 164 <para>
 165 Specifies the Internet TCP/IP port or local Unix domain socket file
 166 extension on which the <application>postmaster</application>
 167 is listening for connections.  The port number defaults to 5432,
 168  or the value of the <envar>PGPORT</envar>
 169 environment variable (if set).
 170
 171 <varlistentry>
 172 <term>
 173 -u
 174 </term>
 175 <listitem>
 176 <para>
 177 Use password authentication.
 178 Prompts for
 179 <replaceable class="parameter">username</replaceable>
 180  and <replaceable class="parameter">password</replaceable>.
 181
 182 </variablelist>
 183
 184 <REFSECT2 ID="R2-APP-PG-DUMP-2">
 185 <REFSECT2INFO>
 186 <DATE>1998-10-04</DATE>
 187 </REFSECT2INFO>
 188 <TITLE>
 189 Outputs
 190 </TITLE>
 191 <PARA>
 192 <application>pg_dump</application> will create a file or
 193  write to <filename>stdout</filename>.
 194
 195 <variablelist>
 196 <varlistentry>
 197 <term>
 198 Connection to database 'template1' failed.
 199 connectDB() failed: Is the postmaster running and accepting connections
 200  at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
 201 <listitem>
 202 <para>
 203 <application>pg_dump</application> could not attach to the
 204 <application>postmaster</application>
 205 process on the specified host and port.  If you see this message,
 206 ensure that the <application>postmaster</application>
 207 is running on the proper host and that you have specified the proper
 208 port.  If your site uses an authentication system, ensure that you
 209 have obtained the required authentication credentials.
 210
 211 <varlistentry>
 212 <term>
 213 Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
 214 FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
 215 <listitem>
 216 <para>
 217 You do not have a valid entry in the relation <literal>pg_shadow</literal>
 218 and and will not be allowed to access <productname>Postgres</productname>.
 219 Contact your <productname>Postgres</productname> administrator.
 220
 221 <varlistentry>
 222 <term>
 223 dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
 224 <listitem>
 225 <para>
 226 You do not have permission to read the database.
 227 Contact your <productname>Postgres</productname> site administrator.
 228
 229 </variablelist>
 230
 231 <note>
 232 <para>
 233 <application>pg_dump</application> internally executes
 234 <command>SELECT</command> statements. If you have problems running
 235 <application>pg_dump</application>,
 236 make sure you are able to select information from the database using, for
 237 example, <application>psql</application>.
 238 </note>
 239
 240 <REFSECT1 ID="R1-APP-PG-DUMP-1">
 241 <REFSECT1INFO>
 242 <DATE>1998-10-04</DATE>
 243 </REFSECT1INFO>
 244 <TITLE>
 245 Description
 246 </TITLE>
 247 <PARA>
 248 <application>pg_dump</application> is a utility for dumping out a
 249 <productname>Postgres</productname> database into a script file
 250  containing query commands.  The script
 251 files are in text format and can be used to reconstruct the database,
 252 even on other machines and other architectures.
 253 <application>pg_dump</application>
 254 will produce the queries necessary to re-generate all
 255 user-defined types, functions, tables, indices, aggregates, and
 256 operators.  In addition, all the data is copied out in text format so
 257 that it can be readily copied in again, as well as imported into tools
 258 for editing.
 259
 260 <para>
 261 <application>pg_dump</application>
 262 is useful for dumping out the contents of a database to move from one
 263 <productname>Postgres</productname> installation to another.  After running
 264 <application>pg_dump</application>,
 265  one should examine the output script file for any warnings, especially
 266 in light of the limitations listed below.
 267
 268 <REFSECT1 ID="R1-APP-PG-DUMP-2">
 269 <REFSECT1INFO>
 270 <DATE>1998-10-04</DATE>
 271 </REFSECT1INFO>
 272 <TITLE>
 273 Notes
 274 </TITLE>
 275 <PARA>
 276 <application>pg_dump</application> has a few limitations.
 277 The limitations mostly stem from
 278 difficulty in extracting certain meta-information from the system
 279 catalogs.
 280
 281 <variablelist>
 282 <varlistentry>
 283 <term>
 284 rules and views
 285 <listitem>
 286 <para>
 287 <application>pg_dump</application>
 288 does not understand user-defined rules and views and
 289 will fail to dump them properly.  (This is due to the fact that
 290 rules are stored as plans in the catalogs and not textually).
 291
 292 <varlistentry>
 293 <term>
 294 partial indices
 295 <listitem>
 296 <para>
 297 <application>pg_dump</application>
 298 does not understand partial indices. The reason is
 299 the same as above; partial index predicates are stored as plans.
 300
 301 <varlistentry>
 302 <term>
 303 large objects
 304 <listitem>
 305 <para>
 306 <application>pg_dump</application> does not handle large objects.
 307 Large objects are ignored and must be dealt with manually.
 308
 309 </variablelist>
 310
 311 <REFSECT1 ID="R1-APP-PG-DUMP-3">
 312 <REFSECT1INFO>
 313 <DATE>1998-10-04</DATE>
 314 </REFSECT1INFO>
 315 <TITLE>
 316 Usage
 317 </TITLE>
 318 <PARA>
 319 To dump a database of the same name as the user:
 320
 321 <programlisting>
 322 % pg_dump > db.out
 323 </programlisting>
 324
 325 <para>
 326 To reload this database:
 327
 328 <programlisting>
 329 psql -e database < db.out
 330 </programlisting>
 331
 332 </REFENTRY>