Hi, In another thread I had previously suggested adding a 2nd synopsis to the pg_createsubscriber docs. See [1, comment #5].
------
CURRENT
pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
SUGGESTION
pg_createsubscriber [option...] {-a | --all} { -D | --pgdata }datadir
{ -P | --publisher-server }connstr
pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
------
A patch was made for doing this [2, v23-0002] but after some debate it
was omitted from the push for the --all option [3]. I was away at the
time so I missed a chance to defend why I felt adding the extra
synopsis may be a good idea. I'll try to do that now:
Nominating which databas(es) the pg_createsubscriber should process is
maybe the most fundamental option of this tool. My reason for the 2nd
synopsis boils down to the fact that "--all" option and "--database"
options are incompatible. E.g there are 2 ways to nominate the
databases: 1) specify them individually or 2) use all of them. It
already describes this in all the option descriptions, but I felt
adding the --all synopsis just makes that point more clear.
Now, vacuumdb was previously cited as a precedent to leave this
unchanged. E.g. vacuumdb doesn't have a separate synopsis for just for
"--all", so pg_createsubscriber doesn't need to either. I think that's
an invalid comparison. The vacuumdb actually does make the distinction
between specifically naming a database and saying --all: e.g. "[
dbname | -a | --all ]". But, it can do that because as far as I know
vacuumdb only accepts a single "--dbname", whereas pg_createsubscriber
allows multiple "--database" options.
This means it would too become complex trying to include --all along
with --database in just one single pg_createsubscriber synopsis. Which
is why, I think 2 separate synopses are warranted.
Thoughts?
(I've reattached the same v23-0002 patch here because it still works)
======
[1]
https://www.postgresql.org/message-id/CAHut%2BPuyBsOJTSygus2-yp60sw_phwYQ-JyC%2BU6fCBMos9x2LA%40mail.gmail.com
[2]
https://www.postgresql.org/message-id/CAHv8RjKU24jCHR2fOHocmdSTqhu7ige5UQsUQMkaTZniLc9DbA%40mail.gmail.com
[3]
https://github.com/postgres/postgres/commit/fb2ea12f42b9453853be043b8ed107e136e1ccb7
Kind Regards,
Peter Smith.
Fujitsu Australia
v23-0002-Synopsis-for-all-option.patch
Description: Binary data
