Skip site navigation (1) Skip section navigation (2)

Re: bad examples in pg_dump README

From: Magnus Hagander <magnus(at)hagander(dot)net>
To: Josh Kupershmidt <schmiddy(at)gmail(dot)com>
Cc: pgsql-hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: bad examples in pg_dump README
Date: 2013-01-05 14:34:26
Message-ID: CABUevEzqGi4b=ZKJE33-+ygYv9wT4v1_4eaC7PYNM+7Rknu_pg@mail.gmail.com (view raw or flat)
Thread:
Lists: pgsql-hackers
On Fri, Jan 4, 2013 at 3:36 AM, Josh Kupershmidt <schmiddy(at)gmail(dot)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 Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/


In response to

Responses

pgsql-hackers by date

Next:From: Magnus HaganderDate: 2013-01-05 14:41:57
Subject: Re: [PATCH] Make pg_basebackup configure and start standby [Review]
Previous:From: Magnus HaganderDate: 2013-01-05 14:11:26
Subject: Re: pg_retainxlog for inclusion in 9.3?

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group