bad examples in pg_dump README
The ./src/bin/pg_dump README contains several inoperable examples.
First, this suggestion:
| or to list tables:
|
| pg_restore <backup-file> --table | less
seems bogus, i.e. the --table option requires an argument specifing
which table to restore, and does not "list tables". Next, this
suggested command:
| pg_restore <backup-file> -l --oid --rearrange | less
hasn't worked since 7.4 or thereabouts, since we don't have
--rearrange or --oid anymore. (I'm not sure we ever had --oid, maybe
it was supposed to be --oid-order?). Then, three examples claim we
support a "--use" flag, e.g.
| pg_restore backup.bck --use=toc.lis > script.sql
where presumably "--use-list" was meant. Further little gripes with
this README include mixed use of tabs and spaces for the examples, and
lines running over the 80-column limit which at least some of our
other READMEs seem to honor.
I started out attempting to fix up the README, keeping the original
example commands intact, but upon further reflection I think the
examples of dumping, restoring, and selective-restoring in that REAMDE
don't belong there anyway. There are already better examples of such
usage in the pg_dump/pg_restore documentation pages, and IMO that's
where such generally-useful usage information belongs.
I propose slimming down the pg_dump README, keeping intact the
introductory notes and details of the tar format.
Josh
Attachments:
pg_dump_README.diffapplication/octet-stream; name=pg_dump_README.diffDownload
diff --git a/src/bin/pg_dump/README b/src/bin/pg_dump/README
new file mode 100644
index 5015b7c..280028a
*** a/src/bin/pg_dump/README
--- b/src/bin/pg_dump/README
*************** Notes on pg_dump
*** 5,77 ****
1. pg_dump, by default, still outputs text files.
! 2. pg_dumpall forces all pg_dump output to be text, since it also outputs text into the same output stream.
3. The plain text output format cannot be used as input into pg_restore.
- To dump a database into the new custom format, type:
-
- pg_dump <db-name> -Fc > <backup-file>
-
- or, to dump in TAR format
-
- pg_dump <db-name> -Ft > <backup-file>
-
- To restore, try
-
- To list contents:
-
- pg_restore -l <backup-file> | less
-
- or to list tables:
-
- pg_restore <backup-file> --table | less
-
- or to list in a different order
-
- pg_restore <backup-file> -l --oid --rearrange | less
-
- Once you are happy with the list, just remove the '-l', and an SQL script will be output.
-
-
- You can also dump a listing:
-
- pg_restore -l <backup-file> > toc.lis
- or
- pg_restore -l <backup-file> -f toc.lis
-
- edit it, and rearrange the lines (or delete some):
-
- vi toc.lis
-
- then use it to restore selected items:
-
- pg_restore <backup-file> --use=toc.lis -l | less
-
- When you like the list, type
-
- pg_restore backup.bck --use=toc.lis > script.sql
-
- or, simply:
-
- createdb newdbname
- pg_restore backup.bck --use=toc.lis | psql newdbname
-
-
TAR
===
! The TAR archive that pg_dump creates currently has a blank username & group for the files,
! but should be otherwise valid. It also includes a 'restore.sql' script which is there for
! the benefit of humans. The script is never used by pg_restore.
! Note: the TAR format archive can only be used as input into pg_restore if it is in TAR form.
! (ie. you should not extract the files then expect pg_restore to work).
! You can extract, edit, and tar the files again, and it should work, but the 'toc'
! file should go at the start, the data files be in the order they are used, and
! the BLOB files at the end.
Philip Warner, 16-Jul-2000
--- 5,31 ----
1. pg_dump, by default, still outputs text files.
! 2. pg_dumpall forces all pg_dump output to be text, since it also outputs
! text into the same output stream.
3. The plain text output format cannot be used as input into pg_restore.
TAR
===
! The TAR archive that pg_dump creates currently has a blank username & group
! for the files, but should be otherwise valid. It also includes a 'restore.sql'
! script which is there for the benefit of humans. The script is never used by
! pg_restore.
! Note: the TAR format archive can only be used as input into pg_restore if it
! is in TAR form (i.e. you should not extract the files then expect pg_restore
! to work).
! You can extract, edit, and tar the files again, and it should work, but the
! 'toc' file should go at the start, the data files be in the order they are
! used, and the BLOB files at the end.
Philip Warner, 16-Jul-2000
On Fri, Jan 4, 2013 at 3:36 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote:
The ./src/bin/pg_dump README contains several inoperable examples.
First, this suggestion:| or to list tables:
|
| pg_restore <backup-file> --table | lessseems bogus, i.e. the --table option requires an argument specifing
which table to restore, and does not "list tables". Next, this
suggested command:| pg_restore <backup-file> -l --oid --rearrange | less
hasn't worked since 7.4 or thereabouts, since we don't have
--rearrange or --oid anymore. (I'm not sure we ever had --oid, maybe
it was supposed to be --oid-order?). Then, three examples claim we
support a "--use" flag, e.g.| pg_restore backup.bck --use=toc.lis > script.sql
where presumably "--use-list" was meant. Further little gripes with
this README include mixed use of tabs and spaces for the examples, and
lines running over the 80-column limit which at least some of our
other READMEs seem to honor.I started out attempting to fix up the README, keeping the original
example commands intact, but upon further reflection I think the
examples of dumping, restoring, and selective-restoring in that REAMDE
don't belong there anyway. There are already better examples of such
usage in the pg_dump/pg_restore documentation pages, and IMO that's
where such generally-useful usage information belongs.I propose slimming down the pg_dump README, keeping intact the
introductory notes and details of the tar format.
Do we need to keep it at all, really? Certainly the introductory part
is covered in the main documentation already...
I believe the tar notes are also out of date. For example, they claim
that you can't expect pg_restore to work with an uncompressed tar
format - yet the header in pg_backup_tar.c says that an uncompressed
tar format is compatible with a directory format dump, and thus you
*can* use pg_restore.
(And fwiw,the note about the user should probably go in src/port/ now
that we moved the tar header creation there a few days ago)
I would suggest we just drop the README file completely. I don't think
it adds any value at all.
Any objections to that path? :)
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On Sat, Jan 5, 2013 at 7:34 AM, Magnus Hagander <magnus@hagander.net> wrote:
On Fri, Jan 4, 2013 at 3:36 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote:
Do we need to keep it at all, really? Certainly the introductory part
is covered in the main documentation already...
Pretty much. (I did find note #2 mildly interesting.)
I believe the tar notes are also out of date. For example, they claim
that you can't expect pg_restore to work with an uncompressed tar
format - yet the header in pg_backup_tar.c says that an uncompressed
tar format is compatible with a directory format dump, and thus you
*can* use pg_restore.(And fwiw,the note about the user should probably go in src/port/ now
that we moved the tar header creation there a few days ago)
Hrm yeah, so the second paragraph under the tar section can certainly be axed.
I would suggest we just drop the README file completely. I don't think
it adds any value at all.Any objections to that path? :)
I think that's OK, since there's not much left in that README after
removing the bogus examples, introductory text that's covered
elsewhere, and obsolete second paragraph about the tar format. Perhaps
we could keep the other paragraphs about the tar format, either in the
header comments for pg_backup_tar.c or in src/port/, though?
Oh, and for this comment in pg_backup_tar.c:
| * See the headers to pg_backup_files & pg_restore for more
details.
there is no longer a pg_backup_files.c.
Josh
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On Sat, 2013-01-05 at 15:34 +0100, Magnus Hagander wrote:
On Fri, Jan 4, 2013 at 3:36 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote:
I propose slimming down the pg_dump README, keeping intact the
introductory notes and details of the tar format.Do we need to keep it at all, really? Certainly the introductory part
is covered in the main documentation already...
I'd remove it and distribute the remaining information, if any, between
the source code and the man page.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
On Mon, Jan 7, 2013 at 8:12 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
On Sat, 2013-01-05 at 15:34 +0100, Magnus Hagander wrote:
On Fri, Jan 4, 2013 at 3:36 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote:
I propose slimming down the pg_dump README, keeping intact the
introductory notes and details of the tar format.Do we need to keep it at all, really? Certainly the introductory part
is covered in the main documentation already...I'd remove it and distribute the remaining information, if any, between
the source code and the man page.
Here's a patch to do so. After removing the discussed bogus
information, there were only two notes which I still found relevant,
so I stuck those in the appropriate header comments.
I didn't preserve the comment about "blank username & group" for
tar'ed files, since there are already some comments along these lines
in tarCreateHeader(), and these are "postgres" not "blank" nowadays.
The pg_dump/pg_restore man pages seemed to already do a good enough
job of showing usage examples that I didn't find anything worth adding
there.
Josh
Attachments:
pg_dump_README.v2.diffapplication/octet-stream; name=pg_dump_README.v2.diffDownload
commit 407f7db92238942377b39744f715de82f489a342
Author: Josh Kupershmidt <schmiddy@gmail.com>
Date: Tue Jan 8 19:37:47 2013 -0700
Get rid of pg_dump's README, since it was largely full of outdated
and incorrect information. Move the few notes which were still relevant
into header comments of pg_backup_tar.c and pg_dumpall.c.
diff --git a/src/bin/pg_dump/README b/src/bin/pg_dump/README
deleted file mode 100644
index 5015b7c..0000000
--- a/src/bin/pg_dump/README
+++ /dev/null
@@ -1,78 +0,0 @@
-src/bin/pg_dump/README
-
-Notes on pg_dump
-================
-
-1. pg_dump, by default, still outputs text files.
-
-2. pg_dumpall forces all pg_dump output to be text, since it also outputs text into the same output stream.
-
-3. The plain text output format cannot be used as input into pg_restore.
-
-
-To dump a database into the new custom format, type:
-
- pg_dump <db-name> -Fc > <backup-file>
-
-or, to dump in TAR format
-
- pg_dump <db-name> -Ft > <backup-file>
-
-To restore, try
-
- To list contents:
-
- pg_restore -l <backup-file> | less
-
- or to list tables:
-
- pg_restore <backup-file> --table | less
-
- or to list in a different order
-
- pg_restore <backup-file> -l --oid --rearrange | less
-
-Once you are happy with the list, just remove the '-l', and an SQL script will be output.
-
-
-You can also dump a listing:
-
- pg_restore -l <backup-file> > toc.lis
- or
- pg_restore -l <backup-file> -f toc.lis
-
-edit it, and rearrange the lines (or delete some):
-
- vi toc.lis
-
-then use it to restore selected items:
-
- pg_restore <backup-file> --use=toc.lis -l | less
-
-When you like the list, type
-
- pg_restore backup.bck --use=toc.lis > script.sql
-
-or, simply:
-
- createdb newdbname
- pg_restore backup.bck --use=toc.lis | psql newdbname
-
-
-TAR
-===
-
-The TAR archive that pg_dump creates currently has a blank username & group for the files,
-but should be otherwise valid. It also includes a 'restore.sql' script which is there for
-the benefit of humans. The script is never used by pg_restore.
-
-Note: the TAR format archive can only be used as input into pg_restore if it is in TAR form.
-(ie. you should not extract the files then expect pg_restore to work).
-
-You can extract, edit, and tar the files again, and it should work, but the 'toc'
-file should go at the start, the data files be in the order they are used, and
-the BLOB files at the end.
-
-
-Philip Warner, 16-Jul-2000
-pjw@rhyme.com.au
diff --git a/src/bin/pg_dump/pg_backup_tar.c b/src/bin/pg_dump/pg_backup_tar.c
index 5e56070..d090612 100644
--- a/src/bin/pg_dump/pg_backup_tar.c
+++ b/src/bin/pg_dump/pg_backup_tar.c
@@ -5,11 +5,14 @@
* This file is copied from the 'files' format file, but dumps data into
* one temp file then sends it to the output TAR archive.
*
+ * The tar format also includes a 'restore.sql' script which is there for
+ * the benefit of humans. This script is never used by pg_restore.
+ *
* NOTE: If you untar the created 'tar' file, the resulting files are
* compatible with the 'directory' format. Please keep the two formats in
* sync.
*
- * See the headers to pg_backup_files & pg_restore for more details.
+ * See the headers to pg_backup_directory & pg_restore for more details.
*
* Copyright (c) 2000, Philip Warner
* Rights are granted to use this software in any way so long
diff --git a/src/bin/pg_dump/pg_dumpall.c b/src/bin/pg_dump/pg_dumpall.c
index 9d3ff55..0662bc2 100644
--- a/src/bin/pg_dump/pg_dumpall.c
+++ b/src/bin/pg_dump/pg_dumpall.c
@@ -5,6 +5,8 @@
* Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
+ * pg_dumpall forces all pg_dump output to be text, since it also outputs
+ * text into the same output stream.
*
* src/bin/pg_dump/pg_dumpall.c
*
On Tue, 2013-01-08 at 19:55 -0700, Josh Kupershmidt wrote:
On Mon, Jan 7, 2013 at 8:12 PM, Peter Eisentraut <peter_e@gmx.net> wrote:
On Sat, 2013-01-05 at 15:34 +0100, Magnus Hagander wrote:
On Fri, Jan 4, 2013 at 3:36 AM, Josh Kupershmidt <schmiddy@gmail.com> wrote:
I propose slimming down the pg_dump README, keeping intact the
introductory notes and details of the tar format.Do we need to keep it at all, really? Certainly the introductory part
is covered in the main documentation already...I'd remove it and distribute the remaining information, if any, between
the source code and the man page.Here's a patch to do so. After removing the discussed bogus
information, there were only two notes which I still found relevant,
so I stuck those in the appropriate header comments.
Committed.
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers