Thread: 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"));
--------------------------------------------------
Attachment
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 19073
Index: src/bin/pg_dump/pg_restore.c
===================================================================
RCS file: /cvsroot/pgsql/src/bin/pg_dump/pg_restore.c,v
retrieving revision 1.62
diff -c -c -r1.62 pg_restore.c
*** src/bin/pg_dump/pg_restore.c 12 Oct 2004 21:54:44 -0000 1.62
--- src/bin/pg_dump/pg_restore.c 13 Oct 2004 00:40:10 -0000
***************
*** 360,366 ****
printf(_(" %s [OPTION]... [FILE]\n"), progname);
printf(_("\nGeneral options:\n"));
! 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(_(" -i, --ignore-version proceed even when server version mismatches\n"));
--- 360,366 ----
printf(_(" %s [OPTION]... [FILE]\n"), progname);
printf(_("\nGeneral options:\n"));
! printf(_(" -d, --dbname=NAME restore database name\n"));
printf(_(" -f, --file=FILENAME output file name\n"));
printf(_(" -F, --format=c|t specify backup file format\n"));
printf(_(" -i, --ignore-version proceed even when server version mismatches\n"));
***************
*** 369,382 ****
printf(_(" --help show this help, then exit\n"));
printf(_(" --version output version information, then exit\n"));
! printf(_("\nOptions controlling the output content:\n"));
printf(_(" -a, --data-only restore only the data, no schema\n"));
printf(_(" -c, --clean clean (drop) schema prior to create\n"));
printf(_(" -C, --create issue commands to create the database\n"));
printf(_(" -I, --index=NAME restore named index\n"));
printf(_(" -L, --use-list=FILENAME use specified table of contents for ordering\n"
" output from this file\n"));
! printf(_(" -O, --no-owner do not output commands to set object ownership\n"));
printf(_(" -P, --function=NAME(args)\n"
" restore named function\n"));
printf(_(" -s, --schema-only restore only the schema, no data\n"));
--- 369,382 ----
printf(_(" --help show this help, then exit\n"));
printf(_(" --version output version information, then exit\n"));
! printf(_("\nOptions controlling the restore:\n"));
printf(_(" -a, --data-only restore only the data, no schema\n"));
printf(_(" -c, --clean clean (drop) schema prior to create\n"));
printf(_(" -C, --create issue commands to create the database\n"));
printf(_(" -I, --index=NAME restore named index\n"));
printf(_(" -L, --use-list=FILENAME use specified table of contents for ordering\n"
" output from this file\n"));
! printf(_(" -O, --no-owner do not issue commands to set object ownership\n"));
printf(_(" -P, --function=NAME(args)\n"
" restore named function\n"));
printf(_(" -s, --schema-only restore only the schema, no data\n"));
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 19073 Index: src/bin/pg_dump/pg_restore.c =================================================================== RCS file: /cvsroot/pgsql/src/bin/pg_dump/pg_restore.c,v retrieving revision 1.63 diff -c -c -r1.63 pg_restore.c *** src/bin/pg_dump/pg_restore.c 13 Oct 2004 00:42:53 -0000 1.63 --- src/bin/pg_dump/pg_restore.c 13 Oct 2004 14:23:37 -0000 *************** *** 360,366 **** printf(_(" %s [OPTION]... [FILE]\n"), progname); printf(_("\nGeneral options:\n")); ! printf(_(" -d, --dbname=NAME restore database name\n")); printf(_(" -f, --file=FILENAME output file name\n")); printf(_(" -F, --format=c|t specify backup file format\n")); printf(_(" -i, --ignore-version proceed even when server version mismatches\n")); --- 360,366 ---- printf(_(" %s [OPTION]... [FILE]\n"), progname); printf(_("\nGeneral options:\n")); ! printf(_(" -d, --dbname=NAME target database name\n")); printf(_(" -f, --file=FILENAME output file name\n")); printf(_(" -F, --format=c|t specify backup file format\n")); printf(_(" -i, --ignore-version proceed even when server version mismatches\n")); *************** *** 372,378 **** printf(_("\nOptions controlling the restore:\n")); printf(_(" -a, --data-only restore only the data, no schema\n")); printf(_(" -c, --clean clean (drop) schema prior to create\n")); ! printf(_(" -C, --create issue commands to create the database\n")); printf(_(" -I, --index=NAME restore named index\n")); printf(_(" -L, --use-list=FILENAME use specified table of contents for ordering\n" " output from this file\n")); --- 372,378 ---- printf(_("\nOptions controlling the restore:\n")); printf(_(" -a, --data-only restore only the data, no schema\n")); printf(_(" -c, --clean clean (drop) schema prior to create\n")); ! printf(_(" -C, --create process commands to create the database\n")); printf(_(" -I, --index=NAME restore named index\n")); printf(_(" -L, --use-list=FILENAME use specified table of contents for ordering\n" " output from this file\n"));
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