1
1
<!--
2
- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.23 2000/11/13 23:57:20 momjian Exp $
2
+ $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.24 2000/11/21 15:39:09 pjw Exp $
3
3
Postgres documentation
4
4
-->
5
5
@@ -15,26 +15,29 @@ Postgres documentation
15
15
<application>pg_dump</application>
16
16
</refname>
17
17
<refpurpose>
18
- Extract a <productname>Postgres</productname> database into a script file
18
+ Extract a <productname>Postgres</productname> database into a script file or other archive file
19
19
</refpurpose>
20
20
</refnamediv>
21
21
<refsynopsisdiv>
22
22
<refsynopsisdivinfo>
23
- <date>1999-07-20 </date>
23
+ <date>2000-11-22 </date>
24
24
</refsynopsisdivinfo>
25
25
<synopsis>
26
26
pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
27
27
pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
28
28
[ -p <replaceable class="parameter">port</replaceable> ]
29
- [ -t <replaceable class="parameter">table</replaceable> ]
30
- [ -a ] [ -c ] [ -d ] [ -D ] [ -i ] [ -n ] [ -N ]
31
- [ -o ] [ -s ] [ -u ] [ -v ] [ -x ]
29
+ [ -t <replaceable class="parameter">table</replaceable> ]
30
+ [ -a ] [ -b ] [ -c ] [-C] [ -d ] [ -D ]
31
+ [-f <REPLACEABLE CLASS="PARAMETER">file</REPLACEABLE>]
32
+ [-F <REPLACEABLE CLASS="PARAMETER">format</REPLACEABLE>]
33
+ [ -i ] [ -n ] [ -N ] [ -o ] [ -O ] [-R]
34
+ [ -s ] [ -S ] [ -u ] [ -v ] [ -x ] [ -Z 0..9 ]
32
35
[ <replaceable class="parameter">dbname</replaceable> ]
33
36
</synopsis>
34
37
35
38
<refsect2 id="R2-APP-PG-DUMP-1">
36
39
<refsect2info>
37
- <date>1998 -11-05 </date>
40
+ <date>2000 -11-22 </date>
38
41
</refsect2info>
39
42
<title>
40
43
Inputs
@@ -66,20 +69,39 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
66
69
</listitem>
67
70
</varlistentry>
68
71
69
- <varlistentry>
70
- <term>-c</term>
71
- <listitem>
72
- <para>
73
- Clean (drop) schema prior to create.
74
- </para>
75
- </listitem>
76
- </varlistentry>
77
-
72
+ <varlistentry>
73
+ <term>-b</term>
74
+ <listitem>
75
+ <para>
76
+ Dump BLOB data.
77
+ </para>
78
+ </listitem>
79
+ </varlistentry>
80
+
81
+ <varlistentry>
82
+ <term>-c</term>
83
+ <listitem>
84
+ <para>
85
+ Clean (drop) schema prior to create.
86
+ </para>
87
+ </listitem>
88
+ </varlistentry>
89
+
90
+ <varlistentry>
91
+ <term>-C</term>
92
+ <listitem>
93
+ <para>
94
+ For plain text (script) output, include SQL to create the database itself.
95
+ </para>
96
+ </listitem>
97
+ </varlistentry>
98
+
78
99
<varlistentry>
79
100
<term>-d</term>
80
101
<listitem>
81
102
<para>
82
- Dump data as proper insert strings.
103
+ Dump data as proper insert strings. This is not recommended for large databases
104
+ for performance reasons.
83
105
</para>
84
106
</listitem>
85
107
</varlistentry>
@@ -88,10 +110,68 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
88
110
<term>-D</term>
89
111
<listitem>
90
112
<para>
91
- Dump data as inserts with attribute names
113
+ Dump data as inserts with attribute names. This is not recommended for large databases
114
+ for performance reasons.
92
115
</para>
93
116
</listitem>
94
117
</varlistentry>
118
+
119
+ <varlistentry>
120
+ <term>-f <replaceable class="parameter">file</replaceable></term>
121
+ <listitem>
122
+ <para>
123
+ Send output to the specified file.
124
+ </para>
125
+ </listitem>
126
+ </varlistentry>
127
+
128
+ <varlistentry>
129
+ <term>-F <replaceable class="parameter">format</replaceable></term>
130
+ <listitem>
131
+ <para>
132
+ Format can be one of the following:
133
+ </para>
134
+
135
+
136
+ <variablelist>
137
+ <varlistentry>
138
+ <term>p</term>
139
+ <listitem>
140
+ <para>
141
+ output a plain text SQL script file (default)
142
+ </para>
143
+ </listitem>
144
+ </varlistentry>
145
+
146
+ <varlistentry>
147
+ <term>t</term>
148
+ <listitem>
149
+ <para>
150
+ output a TAR archive suitable for input into
151
+ <APPLICATION>pg_restore</APPLICATION>. Using this archive format
152
+ allows reordering and/or exclusion of schema elements
153
+ at the time the database is restored. It is also possible to limit
154
+ which data is reloaded at restore time.
155
+ </para>
156
+ </listitem>
157
+ </varlistentry>
158
+
159
+ <varlistentry>
160
+ <term>c</term>
161
+ <listitem>
162
+ <para>
163
+ output a custom archive suitable for input into
164
+ <APPLICATION>pg_restore</APPLICATION>. This is the most flexible
165
+ format in that it allows reordering of data load as well
166
+ as schema elements. This format is also compressed by default.
167
+ </para>
168
+ </listitem>
169
+ </varlistentry>
170
+
171
+ </variablelist>
172
+
173
+ </listitem>
174
+ </varlistentry>
95
175
96
176
<varlistentry>
97
177
<term>-i</term>
@@ -132,15 +212,37 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
132
212
</listitem>
133
213
</varlistentry>
134
214
135
- <varlistentry>
136
- <term>-o</term>
137
- <listitem>
138
- <para>
139
- Dump object identifiers (<acronym>OID</acronym>s) for every table.
140
- </para>
141
- </listitem>
142
- </varlistentry>
143
-
215
+ <varlistentry>
216
+ <term>-o</term>
217
+ <listitem>
218
+ <para>
219
+ Dump object identifiers (<acronym>OID</acronym>s) for every table.
220
+ </para>
221
+ </listitem>
222
+ </varlistentry>
223
+
224
+ <varlistentry>
225
+ <term>-O</term>
226
+ <listitem>
227
+ <para>
228
+ In plain text output mode, don't set object ownership to match the
229
+ original database. Typically, <APPLICATION>pg_dump</APPLICATION>
230
+ issues <PROGRAMLISTING>\connect</PROGRAMLISTING> statments to set
231
+ ownership of schema elements.
232
+ </para>
233
+ </listitem>
234
+ </varlistentry>
235
+
236
+ <varlistentry>
237
+ <term>-R</term>
238
+ <listitem>
239
+ <para>
240
+ In plain text output mode, prohibit <APPLICATION>pg_dump</APPLICATION>
241
+ from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> statements.
242
+ </para>
243
+ </listitem>
244
+ </varlistentry>
245
+
144
246
<varlistentry>
145
247
<term>-s</term>
146
248
<listitem>
@@ -150,15 +252,25 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
150
252
</listitem>
151
253
</varlistentry>
152
254
153
- <varlistentry>
154
- <term>-t <replaceable class="parameter">table</replaceable></term>
155
- <listitem>
156
- <para>
157
- Dump data for <replaceable class="parameter">table</replaceable> only.
158
- </para>
159
- </listitem>
160
- </varlistentry>
161
-
255
+ <varlistentry>
256
+ <term>-S <replaceable class="parameter">username</replaceable></term>
257
+ <listitem>
258
+ <para>
259
+ Specify the superuser username to use when disabling triggers and/or
260
+ setting ownership of schema elements.
261
+ </para>
262
+ </listitem>
263
+ </varlistentry>
264
+
265
+ <varlistentry>
266
+ <term>-t <replaceable class="parameter">table</replaceable></term>
267
+ <listitem>
268
+ <para>
269
+ Dump data for <replaceable class="parameter">table</replaceable> only.
270
+ </para>
271
+ </listitem>
272
+ </varlistentry>
273
+
162
274
<varlistentry>
163
275
<term>-u</term>
164
276
<listitem>
@@ -185,6 +297,17 @@ pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
185
297
</para>
186
298
</listitem>
187
299
</varlistentry>
300
+
301
+ <varlistentry>
302
+ <term>-Z <replaceable class="parameter">0..9</replaceable></term>
303
+ <listitem>
304
+ <para>
305
+ Specify the compression level to use in archive formats that support
306
+ compression (currently only the custom archive format supports compression).
307
+ </para>
308
+ </listitem>
309
+ </varlistentry>
310
+
188
311
189
312
</variablelist>
190
313
</para>
@@ -306,17 +429,26 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
306
429
307
430
<refsect1 id="R1-APP-PG-DUMP-1">
308
431
<refsect1info>
309
- <date>1998-11-05 </date>
432
+ <date>2000- </date>
310
433
</refsect1info>
311
434
<title>
312
435
Description
313
436
</title>
314
437
<para>
315
438
<application>pg_dump</application> is a utility for dumping out a
316
- <productname>Postgres</productname> database into a script file
317
- containing query commands. The script
318
- files are in text format and can be used to reconstruct the database,
319
- even on other machines and other architectures.
439
+ <productname>Postgres</productname> database into a script or archive
440
+ file containing query commands. The script files are in text format
441
+ and can be used to reconstruct the database, even on other machines
442
+ and other architectures.
443
+ </para>
444
+ <para>
445
+ The archive files, new with this v7.1, contain enough information for
446
+ <APPLICATION>pg_restore</APPLICATION> to rebuild the database, but also
447
+ allow pg_restore to be selective about what is restored, or even to
448
+ reorder the items prior to being restored. The archive files should
449
+ also be portable across architectures.
450
+ </para>
451
+ <para>
320
452
<application>pg_dump</application>
321
453
will produce the queries necessary to re-generate all
322
454
user-defined types, functions, tables, indices, aggregates, and
@@ -330,14 +462,28 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
330
462
is useful for dumping out the contents of a database to move from one
331
463
<productname>Postgres</productname> installation to another. After running
332
464
<application>pg_dump</application>,
333
- one should examine the output script file for any warnings, especially
465
+ one should examine the output for any warnings, especially
334
466
in light of the limitations listed below.
335
467
</para>
468
+
469
+ <para>
470
+ When used with one of the alternate file formats and combined with
471
+ <APPLICATION>pg_restore</APPLICATION>, it provides a flexible archival
472
+ and trasfer mechanism. <APPLICATION>pg_dump</APPLICATION> can be used
473
+ to backup an entire database, then <APPLICATION>pg_restore</APPLICATION>
474
+ can be used to examine the archive and/or select which parts of the
475
+ database are to be restored.
476
+ </para>
477
+
478
+ <para>
479
+ See the <APPLICATION>pg_restore</APPLICATION> documentation for details.
480
+ </para>
481
+
336
482
</refsect1>
337
483
338
484
<refsect1 id="R1-APP-PG-DUMP-2">
339
485
<refsect1info>
340
- <date>1998 -11-05 </date>
486
+ <date>2000 -11-21 </date>
341
487
</refsect1info>
342
488
<title>
343
489
Notes
@@ -359,8 +505,9 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
359
505
360
506
<listitem>
361
507
<para>
362
- <application>pg_dump</application> does not handle large objects.
363
- Large objects are ignored and must be dealt with manually.
508
+ When dumping a single table or as plain text, <application>pg_dump</application>
509
+ does not handle large objects. Large objects must be dumped in their
510
+ entirity using one of the binary archive formats.
364
511
</para>
365
512
</listitem>
366
513
@@ -379,7 +526,7 @@ dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
379
526
380
527
<refsect1 id="R1-APP-PG-DUMP-3">
381
528
<refsect1info>
382
- <date>1998 -11-05 </date>
529
+ <date>2000 -11-21 </date>
383
530
</refsect1info>
384
531
<title>
385
532
Usage
@@ -399,6 +546,23 @@ $ pg_dump > db.out
399
546
$ psql -e database < db.out
400
547
</programlisting>
401
548
</para>
549
+
550
+ <para>
551
+ To dump a database called mydb that contains BLOBs to a TAR file:
552
+
553
+ <programlisting>
554
+ $ pg_dump -Ft --blobs mydb > db.tar
555
+ </programlisting>
556
+ </para>
557
+
558
+ <para>
559
+ To reload this database (with BLOBs) to an existing db called newdb:
560
+
561
+ <programlisting>
562
+ $ pg_restore db.tar --db=newdb
563
+ </programlisting>
564
+ </para>
565
+
402
566
</refsect1>
403
567
</refentry>
404
568
0 commit comments