Thread: 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
Attachment
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 | 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. 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 HaganderMe: http://www.hagander.net/Work: http://www.redpill-linpro.com/
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
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.
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
Attachment
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.