pg_restore - added documentation
I suggest to alter the
pg_restore --help output from
-----------------------------------------
Usage:
pg_restore [OPTION]... [FILE]
General options:
-d, --dbname=NAME output database name
-f, --file=FILENAME output file name
-----------------------------------------------
to:
----------------------------------------------
Usage:
pg_restore [OPTION]... [FILE]
General options:
-d, --dbname=NAME output database name (to restore into a psql
database)
-f, --file=FILENAME output file name (to convert custom/tar to
plain SQL)
-F, --format=c|t specify backup file format (custom or tar,
plain text is not possible) ----------------------------------------------
Reasons:
a) pg_restore may sometimes be used in a "stressed state of mind" where
additional information is essential
b) within win32 there is no man pg_restore possible
c) Not me allown did need some time to understand WHY an "output file
name" makes sense for a resore-utility.
Please find the patch in the upcomming.
Harald
----------------------------------------------
363,365c363,365
< printf(_(" -d, --dbname=NAME output database name\n"));
< printf(_(" -f, --file=FILENAME output file name\n"));
< printf(_(" -F, --format=c|t specify backup file format\n"));
---
printf(_(" -d, --dbname=NAME output database name (to
restore into a psql database) \n"));
printf(_(" -f, --file=FILENAME output file name (to convert
custom/tar to plain SQL)\n"));
printf(_(" -F, --format=c|t specify backup file format
(only custom and tar are allowed, not plain SQL)\n"));
--------------------------------------------------
Harald Armin Massa wrote:
----------------------------------------------
Usage:
pg_restore [OPTION]... [FILE]General options:
-d, --dbname=NAME output database name (to restore into a psql
database)
-f, --file=FILENAME output file name (to convert custom/tar to
plain SQL)
-F, --format=c|t specify backup file format (custom or tar,
plain text is not possible)
----------------------------------------------
These lines are too long for help output. Also, there is no such thing
as a "psql database".
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
Peter Eisentraut wrote:
Harald Armin Massa wrote:
----------------------------------------------
Usage:
pg_restore [OPTION]... [FILE]General options:
-d, --dbname=NAME output database name (to restore into a psql
database)
-f, --file=FILENAME output file name (to convert custom/tar to
plain SQL)
-F, --format=c|t specify backup file format (custom or tar,
plain text is not possible)
----------------------------------------------These lines are too long for help output. Also, there is no such thing
as a "psql database".
Agreed.
However, I wonder if "output database" is the proper name for -d? Isn't
it more "restore database" or "target database"? Output makes me think
of pg_dump.
pg_restore manual page has for -d:
--dbname=dbname
Connect to database dbname and restore directly
into the database.
No mention of "output" there.
I have updated some of the help wording for pg_restore which should clarify
things.
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073Attachments:
/bjm/difftext/plainDownload+6-6
Bruce Momjian wrote:
However, I wonder if "output database" is the proper name for -d?
Isn't it more "restore database" or "target database"?
"restore database name" sounds like, "When this option is specified,
only the database name is restored.". "target database" sounds a lot
better.
Your other change, "issue commands" may be interpreted incorrectly.
When not restoring to a database, the commands are in fact "output",
not "issued". Not sure how to make that clear, though I don't much
like "issue" either way, because it doesn't have a precise meaning.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
OK, wording updated and applied. I used "process" instead of "issue".
---------------------------------------------------------------------------
Peter Eisentraut wrote:
Bruce Momjian wrote:
However, I wonder if "output database" is the proper name for -d?
Isn't it more "restore database" or "target database"?"restore database name" sounds like, "When this option is specified,
only the database name is restored.". "target database" sounds a lot
better.Your other change, "issue commands" may be interpreted incorrectly.
When not restoring to a database, the commands are in fact "output",
not "issued". Not sure how to make that clear, though I don't much
like "issue" either way, because it doesn't have a precise meaning.--
Peter Eisentraut
http://developer.postgresql.org/~petere/
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073Attachments:
/bjm/difftext/plainDownload+4-4
Bruce Momjian wrote:
OK, wording updated and applied. I used "process" instead of
"issue".
I think this is drifting farther and farther from the target... Does
anyone else have a wording suggestion?
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
Peter Eisentraut <peter_e@gmx.net> writes:
Bruce Momjian wrote:
However, I wonder if "output database" is the proper name for -d?
Isn't it more "restore database" or "target database"?
"restore database name" sounds like, "When this option is specified,
only the database name is restored.". "target database" sounds a lot
better.
-d really only specifies the database to which pg_restore initially
connects. If you've requested a CREATE DATABASE command be issued (-C
I think) then the actual restore will happen into that database.
regards, tom lane
Bruce Momjian <pgman@candle.pha.pa.us> writes:
! printf(_(" -C, --create process commands to create the database\n"));
Wow, that's just about *completely* content-free. Obviously
documentation written by a committee :-(
How about
! printf(_(" -d, --dbname=NAME connect to database NAME\n"));
! printf(_(" -C, --create create the target database\n"));
regards, tom lane
Changes made.
---------------------------------------------------------------------------
Tom Lane wrote:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
! printf(_(" -C, --create process commands to create the database\n"));
Wow, that's just about *completely* content-free. Obviously
documentation written by a committee :-(How about
! printf(_(" -d, --dbname=NAME connect to database NAME\n"));
! printf(_(" -C, --create create the target database\n"));
regards, tom lane
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073