On Fri, Jun 9, 2023 at 6:20 PM Gurjeet Singh <gurj...@singh.im> wrote:
> On Fri, Jun 9, 2023 at 5:42 PM Gregory Smith <gregsmithpg...@gmail.com> wrote:
> > On Fri, Jun 9, 2023 at 1:25 PM Gurjeet Singh <gurj...@singh.im> wrote:
> >>
> >> > $ pgbench -i -I dtGvp -s 500
> >>
> >> The steps are severely under-documented in pgbench --help output.
> >
> > I agree it's not easy to find information. I just went through double
> > checking I had the order recently enough to remember what I did. The man
> > pages have this:
> >
> > > Each step is invoked in the specified order. The default is dtgvp.
> >
> > Which was what I wanted to read. Meanwhile the --help output says:
> >
> > > -I, --init-steps=[dtgGvpf]+ (default "dtgvp")
> >
> > %T$%%Which has the information without a lot of context for what it's used
> > for. I'd welcome some text expansion that added a minimal but functional
> > improvement to that the existing help output; I don't have such text.
>
> Please see attached 2 variants of the patch. Variant 1 simply tells
> the reader to consult pgbench documentation. The second variant
> provides a description for each of the letters, as the documentation
> does. The committer can pick the one they find suitable.
(I was short on time, so had to keep it short in the above email. To
justify this additional email, I have added 2 more options to choose
from. :)
The text ", in the specified order" is an important detail, that
should be included irrespective of the rest of the patch.
My preference would be to use the first variant, since the second one
feels too wordy for --help output. I believe we'll have to choose
between these two; the alternatives will not make anyone happy.
These two variants show the two extremes; bare minimum vs. everything
but the kitchen sink. So one may feel the need to find a middle ground
and provide a "sufficient, but not too much" variant. I have attempted
that in variants 3 and 4; see attached.
The third variant does away with the list of steps, and uses a
paragraph to describe the letters. And the fourth variant makes that
paragraph terse.
In the order of preference I'd choose variant 1, then 2. Variants 3
and 4 feel like a significant degradation from variant 2.
Attached samples.txt shows the snippets of --help output of each of
the variants/patches, for comparison.
Best regards,
Gurjeet
http://Gurje.et
==== variant-1-brief-pointer-to-docs.patch
-i, --initialize invokes initialization mode
-I, --init-steps=[dtgGvpf]+ (default "dtgvp")
run selected initialization steps, in the specified
order
see pgbench documentation for a description of these
steps
-F, --fillfactor=NUM set fill factor
==== variant-2-detailed-description.patch
-i, --initialize invokes initialization mode
-I, --init-steps=[dtgGvpf]+ (default "dtgvp")
run selected initialization steps, in the specified
order
d: Drop any existing pgbench tables
t: Create the tables used by the standard pgbench
scenario
g: Generate data, client-side
G: Generate data, server-side
v: Invoke VACUUM on the standard tables
p: Create primary key indexes on the standard tables
f: Create foreign key constraints between the
standard tables
-F, --fillfactor=NUM set fill factor
==== variant-3-details-not-list.patch
-i, --initialize invokes initialization mode
-I, --init-steps=[dtgGvpf]+ (default "dtgvp")
run selected initialization steps, in the specified
order.
These steps operate on standard tables used by
pgbench
'd' drops the tables, 't' creates the tables, 'g'
generates
the data on client-side, 'G' generates data on
server-side,
'v' vaccums the tables, 'p' creates primary key
constraints,
and 'f' creates foreign key constraints
-F, --fillfactor=NUM set fill factor
==== variant-4-terse-details-not-list.patch
-i, --initialize invokes initialization mode
-I, --init-steps=[dtgGvpf]+ (default "dtgvp")
run selected initialization steps, in the specified
order.
These steps operate on standard tables used by
pgbench
'd' drop table, 't' create tables, 'g' generate data
client-side, 'G' generate data server-side, 'v'
vaccum
tables, 'p' create primary keys, 'f' create foreign
keys
-F, --fillfactor=NUM set fill factor
diff --git a/src/bin/pgbench/pgbench.c b/src/bin/pgbench/pgbench.c
index 508ed218e8..c74a596b86 100644
--- a/src/bin/pgbench/pgbench.c
+++ b/src/bin/pgbench/pgbench.c
@@ -876,7 +876,8 @@ usage(void)
"\nInitialization options:\n"
" -i, --initialize invokes initialization mode\n"
" -I, --init-steps=[" ALL_INIT_STEPS "]+ (default \"" DEFAULT_INIT_STEPS "\")\n"
- " run selected initialization steps\n"
+ " run selected initialization steps, in the specified order\n"
+ " see pgbench documentation for a description of these steps\n"
" -F, --fillfactor=NUM set fill factor\n"
" -n, --no-vacuum do not run VACUUM during initialization\n"
" -q, --quiet quiet logging (one message each 5 seconds)\n"
diff --git a/src/bin/pgbench/pgbench.c b/src/bin/pgbench/pgbench.c
index 508ed218e8..a39ca7dcb5 100644
--- a/src/bin/pgbench/pgbench.c
+++ b/src/bin/pgbench/pgbench.c
@@ -876,7 +876,14 @@ usage(void)
"\nInitialization options:\n"
" -i, --initialize invokes initialization mode\n"
" -I, --init-steps=[" ALL_INIT_STEPS "]+ (default \"" DEFAULT_INIT_STEPS "\")\n"
- " run selected initialization steps\n"
+ " run selected initialization steps, in the specified order\n"
+ " d: Drop any existing pgbench tables\n"
+ " t: Create the tables used by the standard pgbench scenario\n"
+ " g: Generate data, client-side\n"
+ " G: Generate data, server-side\n"
+ " v: Invoke VACUUM on the standard tables\n"
+ " p: Create primary key indexes on the standard tables\n"
+ " f: Create foreign key constraints between the standard tables\n"
" -F, --fillfactor=NUM set fill factor\n"
" -n, --no-vacuum do not run VACUUM during initialization\n"
" -q, --quiet quiet logging (one message each 5 seconds)\n"
diff --git a/src/bin/pgbench/pgbench.c b/src/bin/pgbench/pgbench.c
index 508ed218e8..09e20f1fef 100644
--- a/src/bin/pgbench/pgbench.c
+++ b/src/bin/pgbench/pgbench.c
@@ -876,7 +876,12 @@ usage(void)
"\nInitialization options:\n"
" -i, --initialize invokes initialization mode\n"
" -I, --init-steps=[" ALL_INIT_STEPS "]+ (default \"" DEFAULT_INIT_STEPS "\")\n"
- " run selected initialization steps\n"
+ " run selected initialization steps, in the specified order.\n"
+ " These steps operate on standard tables used by pgbench\n"
+ " 'd' drops the tables, 't' creates the tables, 'g' generates\n"
+ " the data on client-side, 'G' generates data on server-side,\n"
+ " 'v' vaccums the tables, 'p' creates primary key constraints,\n"
+ " and 'f' creates foreign key constraints\n"
" -F, --fillfactor=NUM set fill factor\n"
" -n, --no-vacuum do not run VACUUM during initialization\n"
" -q, --quiet quiet logging (one message each 5 seconds)\n"
diff --git a/src/bin/pgbench/pgbench.c b/src/bin/pgbench/pgbench.c
index 508ed218e8..8fb63789bb 100644
--- a/src/bin/pgbench/pgbench.c
+++ b/src/bin/pgbench/pgbench.c
@@ -876,7 +876,11 @@ usage(void)
"\nInitialization options:\n"
" -i, --initialize invokes initialization mode\n"
" -I, --init-steps=[" ALL_INIT_STEPS "]+ (default \"" DEFAULT_INIT_STEPS "\")\n"
- " run selected initialization steps\n"
+ " run selected initialization steps, in the specified order.\n"
+ " These steps operate on standard tables used by pgbench\n"
+ " 'd' drop table, 't' create tables, 'g' generate data\n"
+ " client-side, 'G' generate data server-side, 'v' vaccum\n"
+ " tables, 'p' create primary keys, 'f' create foreign keys\n"
" -F, --fillfactor=NUM set fill factor\n"
" -n, --no-vacuum do not run VACUUM during initialization\n"
" -q, --quiet quiet logging (one message each 5 seconds)\n"
