Better help output for pgbench -I init_steps

From: Gurjeet Singh <gurjeet(at)singh(dot)im>
To: Postgres Hackers <pgsql-hackers(at)postgresql(dot)org>
Cc: Tristan Partin <tristan(at)neon(dot)tech>, Gregory Smith <gregsmithpgsql(at)gmail(dot)com>
Subject: Better help output for pgbench -I init_steps
Date: 2023-07-12 07:42:14
Message-ID: CABwTF4Xbc=K4tFj5Znc8jx0GCufQa577GCDsWD7=71qDnUEOyQ@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

These patches were created during an unrelated discussion about pgbench.

Please see emails [1] - [6] linked below, for the past discussion.

In brief:

> $ pgbench -i -I dtGvp -s 500

The init-steps are severely under-documented in pgbench --help output.
I think at least a pointer to the the pgbench docs should be mentioned
in the pgbench --help output; an average user may not rush to read the
code to find the explanation, but a hint to where to find more details
about what the letters in --init-steps mean, would save them a lot of
time.

Please see attached 4 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.

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; also 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.

In [6] below, Tristan showed preference for the second variant.

[1] My complaint about -I initi_steps being severely under-documented
in --help output
https://www.postgresql.org/message-id/CABwTF4XMdHTxemhskad41Vj_hp2nPgifjwegOqR52_8-wEbv2Q%40mail.gmail.com

[2] Tristan Partin agreeing with the complaint, and suggesting a patch
would be welcome
https://www.postgresql.org/message-id/CT8BC7RXT33R.3CHYIXGD5NVHK%40gonk

[3] Greg Smith agreeing and saying he'd welcome a few more words about
the init_steps in --help output
https://www.postgresql.org/message-id/CAHLJuCUp5_VUo%2BRJ%2BpSnxeiiZfcstRtTubRP8%2Bu8NEqmrbp4aw%40mail.gmail.com

[4] First set of patches
https://www.postgresql.org/message-id/CABwTF4UKv43ZftJadsxs8%3Da07BmA1U4RU3W1qbmDAguVKJAmZw%40mail.gmail.com

[5] Second set of patches
https://www.postgresql.org/message-id/CABwTF4Ww42arY1Q88_iaraVLxqSU%2B8Yb4oKiTT5gD1sineog9w%40mail.gmail.com

[6] Tristan showing preference for the second variant
https://www.postgresql.org/message-id/CTBN5E2K2YSJ.3QYXGZ09JZXIW%40gonk

+CC Tristan Partin and Greg Smith, since they were involved in the
initial thread.

Best regards,
Gurjeet
http://Gurje.et

Attachment Content-Type Size
samples.txt text/plain 2.4 KB
variant-2-detailed-description.patch application/octet-stream 1.3 KB
variant-1-brief-pointer-to-docs.patch application/octet-stream 860 bytes
variant-4-terse-details-not-list.patch application/octet-stream 1.1 KB
variant-3-details-not-list.patch application/octet-stream 1.2 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Masahiko Sawada 2023-07-12 07:52:23 Re: Testing autovacuum wraparound (including failsafe)
Previous Message Peter Eisentraut 2023-07-12 07:34:42 Re: Exclusion constraints on partitioned tables