From 238d21d7d28612bfebc2989ba649a1b137c29cbe Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Tue, 25 May 2010 15:55:28 +0000 Subject: [PATCH] Modify pg_standby, pgbench, and pg_upgrade manual pages to be consistent in their display of command-line options with other client applications. --- contrib/pg_upgrade/option.c | 30 +-- doc/src/sgml/oid2name.sgml | 4 +- doc/src/sgml/pgbench.sgml | 483 ++++++++++++++++++++---------------- doc/src/sgml/pgstandby.sgml | 193 +++++++------- doc/src/sgml/pgupgrade.sgml | 20 +- 5 files changed, 406 insertions(+), 324 deletions(-) diff --git a/contrib/pg_upgrade/option.c b/contrib/pg_upgrade/option.c index 3a04b3078c..df737ac228 100644 --- a/contrib/pg_upgrade/option.c +++ b/contrib/pg_upgrade/option.c @@ -226,21 +226,21 @@ usage(migratorContext *ctx) printf(_("\nUsage: pg_upgrade [OPTIONS]...\n\ \n\ Options:\n\ - -b, --old-bindir=OLDBINDIR old cluster executable directory\n\ - -B, --new-bindir=NEWBINDIR new cluster executable directory\n\ - -c, --check check clusters only, don't change any data\n\ - -d, --old-datadir=OLDDATADIR old cluster data directory\n\ - -D, --new-datadir=NEWDATADIR new cluster data directory\n\ - -g, --debug enable debugging\n\ - -G, --debugfile=DEBUGFILENAME output debugging activity to file\n\ - -k, --link link instead of copying files to new cluster\n\ - -l, --logfile=LOGFILENAME log session activity to file\n\ - -p, --old-port=portnum old cluster port number (default %d)\n\ - -P, --new-port=portnum new cluster port number (default %d)\n\ - -u, --user=username clusters superuser (default \"%s\")\n\ - -v, --verbose enable verbose output\n\ - -V, --version display version information, then exit\n\ - -h, --help show this help, then exit\n\ + -b, --old-bindir=old_bindir old cluster executable directory\n\ + -B, --new-bindir=new_bindir new cluster executable directory\n\ + -c, --check check clusters only, don't change any data\n\ + -d, --old-datadir=old_datadir old cluster data directory\n\ + -D, --new-datadir=new_datadir new cluster data directory\n\ + -g, --debug enable debugging\n\ + -G, --debugfile=debug_filename output debugging activity to file\n\ + -k, --link link instead of copying files to new cluster\n\ + -l, --logfile=log_filename log session activity to file\n\ + -p, --old-port=old_portnum old cluster port number (default %d)\n\ + -P, --new-port=new_portnum new cluster port number (default %d)\n\ + -u, --user=username clusters superuser (default \"%s\")\n\ + -v, --verbose enable verbose output\n\ + -V, --version display version information, then exit\n\ + -h, --help show this help, then exit\n\ \n\ Before running pg_upgrade you must:\n\ create a new database cluster (using the new version of initdb)\n\ diff --git a/doc/src/sgml/oid2name.sgml b/doc/src/sgml/oid2name.sgml index 1c12789352..5e793ce199 100644 --- a/doc/src/sgml/oid2name.sgml +++ b/doc/src/sgml/oid2name.sgml @@ -1,4 +1,4 @@ - + oid2name @@ -36,7 +36,7 @@ - <application>oid2name</> options + <application>oid2name</> Options oid2name accepts the following command-line arguments: diff --git a/doc/src/sgml/pgbench.sgml b/doc/src/sgml/pgbench.sgml index 98e3b12438..bc0cd9c0c2 100644 --- a/doc/src/sgml/pgbench.sgml +++ b/doc/src/sgml/pgbench.sgml @@ -1,4 +1,4 @@ - + pgbench @@ -116,218 +116,285 @@ pgbench options dbname in both cases. - - <application>pgbench</application> initialization options - - - - Option - Description - - + - - - -i - - Required to invoke initialization mode. - - - - -s scale_factor - - Multiply the number of rows generated by the scale factor. - For example, -s 100 will create 10,000,000 rows - in the pgbench_accounts table. Default is 1. - - - - -F fillfactor - - Create the pgbench_accounts, - pgbench_tellers and - pgbench_branches tables with the given fillfactor. - Default is 100. - - - - -
+ + <application>pgbench</> Initialization Options - - <application>pgbench</application> benchmarking options - - - - Option - Description - - + + pgbench accepts the following command-line + initialization arguments: - - - -c clients - - Number of clients simulated, that is, number of concurrent database - sessions. Default is 1. - - - - -j threads - - Number of worker threads within pgbench. - Using more than one thread can be helpful on multi-CPU machines. - The number of clients must be a multiple of the number of threads, - since each thread is given the same number of client sessions to manage. - Default is 1. - - - - -t transactions - - Number of transactions each client runs. Default is 10. - - - - -T seconds - - Run the test for this many seconds, rather than a fixed number of - transactions per client. -t and - -T are mutually exclusive. - - - - -M querymode - - Protocol to use for submitting queries to the server: - - - simple: use simple query protocol. - - - extended: use extended query protocol. - - - prepared: use extended query protocol with prepared statements. - - - The default is simple query protocol. (See - for more information.) - - - - -N - - Do not update pgbench_tellers and - pgbench_branches. - This will avoid update contention on these tables, but - it makes the test case even less like TPC-B. - - - - -S - - Perform select-only transactions instead of TPC-B-like test. - - - - -f filename - - Read transaction script from filename. - See below for details. - -N, -S, and -f - are mutually exclusive. - - - - -n - - Perform no vacuuming before running the test. - This option is necessary - if you are running a custom test scenario that does not include - the standard tables pgbench_accounts, - pgbench_branches, pgbench_history, and - pgbench_tellers. - - - - -v - - Vacuum all four standard tables before running the test. - With neither -n nor -v, pgbench will vacuum the - pgbench_tellers and pgbench_branches - tables, and will truncate pgbench_history. - - - - -D varname=value - - Define a variable for use by a custom script (see below). - Multiple -D options are allowed. - - - - -C - - Establish a new connection for each transaction, rather than - doing it just once per client session. - This is useful to measure the connection overhead. - - - - -l - - Write the time taken by each transaction to a logfile. - See below for details. - - - - -s scale_factor - - Report the specified scale factor in pgbench's - output. With the built-in tests, this is not necessary; the - correct scale factor will be detected by counting the number of - rows in the pgbench_branches table. However, when testing - custom benchmarks (-f option), the scale factor - will be reported as 1 unless this option is used. - - - - -d - - Print debugging output. - - - - -
+ - - <application>pgbench</application> common options - - - - Option - Description - - + + fillfactor + + + Create the pgbench_accounts, + pgbench_tellers and + pgbench_branches tables with the given fillfactor. + Default is 100. + + + + + + + + + Required to invoke initialization mode. + + + + + + scale_factor + + + Multiply the number of rows generated by the scale factor. + For example, -s 100 will create 10,000,000 rows + in the pgbench_accounts table. Default is 1. + + + + + + + + + + + <application>pgbench</> Benchmarking Options + + + pgbench accepts the following command-line + benchmarking arguments: + + + + + clients + + + Number of clients simulated, that is, number of concurrent database + sessions. Default is 1. + + + + + + + + + Establish a new connection for each transaction, rather than + doing it just once per client session. + This is useful to measure the connection overhead. + + + + + + + + + Print debugging output. + + + + + + varname=value + + + Define a variable for use by a custom script (see below). + Multiple -D options are allowed. + + + + + + filename + + + Read transaction script from filename. + See below for details. + -N, -S, and -f + are mutually exclusive. + + + + + + threads + + + Number of worker threads within pgbench. + Using more than one thread can be helpful on multi-CPU machines. + The number of clients must be a multiple of the number of threads, + since each thread is given the same number of client sessions to manage. + Default is 1. + + + + + + + + + Write the time taken by each transaction to a logfile. + See below for details. + + + + + + querymode + + + Protocol to use for submitting queries to the server: + + + simple: use simple query protocol. + + + extended: use extended query protocol. + + + prepared: use extended query protocol with prepared statements. + + + The default is simple query protocol. (See + for more information.) + + + + + + + + + Perform no vacuuming before running the test. + This option is necessary + if you are running a custom test scenario that does not include + the standard tables pgbench_accounts, + pgbench_branches, pgbench_history, and + pgbench_tellers. + + + + + + + + + Do not update pgbench_tellers and + pgbench_branches. + This will avoid update contention on these tables, but + it makes the test case even less like TPC-B. + + + + + + scale_factor + + + Report the specified scale factor in pgbench's + output. With the built-in tests, this is not necessary; the + correct scale factor will be detected by counting the number of + rows in the pgbench_branches table. However, when testing + custom benchmarks (-f option), the scale factor + will be reported as 1 unless this option is used. + + + + + + + + + Perform select-only transactions instead of TPC-B-like test. + + + + + + transactions + + + Number of transactions each client runs. Default is 10. + + + + + + seconds + + + Run the test for this many seconds, rather than a fixed number of + transactions per client. -t and + -T are mutually exclusive. + + + + + + + + + Vacuum all four standard tables before running the test. + With neither -n nor -v, pgbench will vacuum the + pgbench_tellers and pgbench_branches + tables, and will truncate pgbench_history. + + + + + + + + + + + <application>pgbench</> Common Options + + + pgbench accepts the following command-line + common arguments: + + + + + hostname + + + The database server's hostname + + + + + + port + + + The database server's port number + + + + + + login + + + The username to connect as + + + + + + - - - -h hostname - database server's host - - - -p port - database server's port - - - -U login - username to connect as - - - -
diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml index ce81de3a18..2a4e03185f 100644 --- a/doc/src/sgml/pgstandby.sgml +++ b/doc/src/sgml/pgstandby.sgml @@ -1,4 +1,4 @@ - + pg_standby @@ -122,99 +122,114 @@ pg_standby option ... archiv - - <application>pg_standby</> options - - - - Option - Default - Description - - - - - -c - yes - - Use cp or copy command to restore WAL files - from archive. - - - - -d - no - Print lots of debug logging output on stderr. - - - -k numfiles - 0 - - Remove files from archivelocation so that - no more than this many WAL files before the current one are kept in the - archive. Zero (the default) means not to remove any files from - archivelocation. - This parameter will be silently ignored if - restartwalfile is specified, since that - specification method is more accurate in determining the correct - archive cut-off point. - Use of this parameter is deprecated as of - PostgreSQL 8.3; it is safer and more efficient to - specify a restartwalfile parameter. A too - small setting could result in removal of files that are still needed - for a restart of the standby server, while a too large setting wastes - archive space. - - - - -r maxretries - 3 - - Set the maximum number of times to retry the copy command if it - fails. After each failure, we wait for sleeptime * - num_retries + + + + <application>pg_standby</> Options + + + pg_standby accepts the following command-line arguments: + + + + + + + + Use cp or copy command to restore WAL files + from archive. This is the only supported behavior so this option is useless. + + + + + + + + + Print lots of debug logging output on stderr. + + + + + + + + + Remove files from archivelocation so that + no more than this many WAL files before the current one are kept in the + archive. Zero (the default) means not to remove any files from + archivelocation. + This parameter will be silently ignored if + restartwalfile is specified, since that + specification method is more accurate in determining the correct + archive cut-off point. + Use of this parameter is deprecated as of + PostgreSQL 8.3; it is safer and more efficient to + specify a restartwalfile parameter. A too + small setting could result in removal of files that are still needed + for a restart of the standby server, while a too large setting wastes + archive space. + + + + + + maxretries + + + Set the maximum number of times to retry the copy command if + it fails (default 3). After each failure, we wait for + sleeptime * num_retries so that the wait time increases progressively. So by default, we will wait 5 secs, 10 secs, then 15 secs before reporting the failure back to the standby server. This will be interpreted as end of recovery and the standby will come up fully as a result. - - - - -s sleeptime - 5 - - Set the number of seconds (up to 60) to sleep between tests to see - if the WAL file to be restored is available in the archive yet. - The default setting is not necessarily recommended; - consult for discussion. - - - - -t triggerfile - none - - Specify a trigger file whose presence should cause failover. - It is recommended that you use a structured filename to - avoid confusion as to which server is being triggered - when multiple servers exist on the same system; for example - /tmp/pgsql.trigger.5432. - - - - -w maxwaittime - 0 - - Set the maximum number of seconds to wait for the next WAL file, - after which a fast failover will be performed. - A setting of zero (the default) means wait forever. - The default setting is not necessarily recommended; - consult for discussion. - - - - -
+ + + + + + sleeptime + + + Set the number of seconds (up to 60, default 5) to sleep between + tests to see if the WAL file to be restored is available in + the archive yet. The default setting is not necessarily + recommended; consult for discussion. + + + + + + triggerfile + + + Specify a trigger file whose presence should cause failover. + It is recommended that you use a structured filename to + avoid confusion as to which server is being triggered + when multiple servers exist on the same system; for example + /tmp/pgsql.trigger.5432. + + + + + + maxwaittime + + + Set the maximum number of seconds to wait for the next WAL file, + after which a fast failover will be performed. + A setting of zero (the default) means wait forever. + The default setting is not necessarily recommended; + consult for discussion. + + + + + + + diff --git a/doc/src/sgml/pgupgrade.sgml b/doc/src/sgml/pgupgrade.sgml index e5c054c137..69ff9dba1b 100644 --- a/doc/src/sgml/pgupgrade.sgml +++ b/doc/src/sgml/pgupgrade.sgml @@ -1,4 +1,4 @@ - + pg_upgrade @@ -38,7 +38,7 @@ - <application>pg_upgrade</> options + <application>pg_upgrade</> Options pg_upgrade accepts the following command-line arguments: @@ -46,13 +46,13 @@ - OLDBINDIR + old_bindir OLDBINDIR specify the old cluster executable directory - NEWBINDIR + new_bindir NEWBINDIR specify the new cluster executable directory @@ -64,13 +64,13 @@ - OLDDATADIR + old_datadir OLDDATADIR specify the old cluster data directory - NEWDATADIR + new_datadir NEWDATADIR specify the new cluster data directory @@ -82,7 +82,7 @@ - DEBUGFILENAME + debug_filename DEBUGFILENAME output debugging activity to file @@ -94,19 +94,19 @@ - LOGFILENAME + log_filename LOGFILENAME log session activity to file - portnum + old_portnum portnum specify the old cluster port number - portnum + new_portnum portnum specify the new cluster port number