Message-ID: <2ebde3606beab536a8693e8f54c33dc0981b8478.camel@cybertec.at>
Subject: Re: pg_restore documentation and --create/--single-transaction
 limitation
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>, pgsql-hackers
	 <pgsql-hackers@postgresql.org>
Date: Tue, 30 Sep 2025 11:30:50 +0200
In-Reply-To: 
 <CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr=FuGTYVDSjQ@mail.gmail.com>
References: 
	<CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr=FuGTYVDSjQ@mail.gmail.com>
Content-Type: multipart/mixed; boundary="=-+S+GNK3UvxTYR1ZLGg3G"
User-Agent: Evolution 3.56.2 (3.56.2-2.fc42) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/2ebde3606beab536a8693e8f54c33dc0981b8478.camel%40cybertec.at>
Precedence: bulk

--=-+S+GNK3UvxTYR1ZLGg3G
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Mon, 2025-03-24 at 17:11 +0530, Ashutosh Bapat wrote:
> The pg_restore documentation usually mentions the pair of switches
> which can not be used together. However, it does not mention that
> --create and --single-transaction can not be used together. Here's a
> patch fixing the same.
>=20
> Looking for a precedence, I found that we have mentioned a similar
> limitation concerning --data-only and --schema-only only under
> --schema and not at both the sections. Maybe it's missing or we chose
> to mention it only at one place. But then I am not sure which one
> place I should use to mention the new limitation. So, I have added the
> note in the sections corresponding to both the switches so that a user
> reading either of them knows about the limitation.

I grepped the source for all incompatible options:

  pg_log_error("options -d/--dbname and -f/--file cannot be used together")=
;
  pg_fatal("options -d/--dbname and --restrict-key cannot be used together"=
);
  pg_fatal("options -s/--schema-only and -a/--data-only cannot be used toge=
ther");
  pg_fatal("options -s/--schema-only and --statistics-only cannot be used t=
ogether");
  pg_fatal("options -a/--data-only and --statistics-only cannot be used tog=
ether");
  pg_fatal("options -a/--data-only and --no-data cannot be used together");
  pg_fatal("options -s/--schema-only and --no-schema cannot be used togethe=
r");
  pg_fatal("options --statistics-only and --no-statistics cannot be used to=
gether");
  pg_fatal("options --statistics and --no-statistics cannot be used togethe=
r");
  pg_fatal("options %s and %s cannot be used together",
           "-a/--data-only", "--statistics");
  pg_fatal("options %s and %s cannot be used together",
           "-s/--schema-only", "--statistics");
  pg_fatal("options -c/--clean and -a/--data-only cannot be used together")=
;
  pg_fatal("options -1/--single-transaction and --transaction-size cannot b=
e used together");
  pg_fatal("options -C/--create and -1/--single-transaction cannot be used =
together");
  pg_fatal("cannot specify both --single-transaction and multiple jobs");

Most of them are pretty obvious and need no documentation.  The ones
that are not obvious unless you know the inner workings are that last
two, and the last one is already documented under --jobs.

So I think that your suggestion makes sense.

I tried to improve the English, and I have added the incompatibility
with multiple --jobs to the --single-transaction documentation.

Does that look alright to you?

Yours,
Laurenz Albe

--=-+S+GNK3UvxTYR1ZLGg3G
Content-Disposition: attachment;
	filename="v2-0001-Document-incompatible-pg_restore-options.patch"
Content-Transfer-Encoding: base64
Content-Type: text/x-patch;
	name="v2-0001-Document-incompatible-pg_restore-options.patch";
	charset="UTF-8"

RnJvbSAyZTRhODRmNmY1NDYzMDhkZDgyYmY2NmZmZDY3NjIxNjA4Y2MwNWJlIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBMYXVyZW56IEFsYmUgPGxhdXJlbnouYWxiZUBjeWJlcnRlYy5h
dD4KRGF0ZTogVHVlLCAzMCBTZXAgMjAyNSAxMToyMjo0MiArMDIwMApTdWJqZWN0OiBbUEFUQ0gg
djJdIERvY3VtZW50IGluY29tcGF0aWJsZSBwZ19yZXN0b3JlIG9wdGlvbnMKCk1vc3Qgb2YgdGhl
IGluY3VtcGF0aWJpbGl0aWVzIChzdWNoIGFzIC0tZmlsZSBhbmQgLS1kYm5hbWUpIGFyZSBwcmV0
dHkKb2J2aW91cyBhbmQgbmVlZCBubyBleHBsYW5hdGlvbi4gIEJ1dCBpdCBtYXkgbm90IGJlIG9i
dmlvdXMgdGhhdAotLXNpbmdsZS10cmFuc2FjdGlvbiBjYW5ub3QgYmUgdXNlZCB0b2dldGhlciB3
aXRoIC0tY3JlYXRlIG9yIG11bHRpcGxlCi0tam9icywgc28gbGV0J3MgbWVudGlvbiB0aGF0IGlu
IHRoZSBkb2N1bWVudGF0aW9uLgoKQXV0aG9yOiBBc2h1dG9zaCBCYXBhdCA8YXNodXRvc2guYmFw
YXQub3NzQGdtYWlsLmNvbT4KUmV2aWV3ZWQtQnk6IExhdXJlbnogQWxiZSA8bGF1cmVuei5hbGJl
QGN5YmVydGVjLmF0PgpEaXNjdXNzaW9uOiBodHRwczovL3Bvc3Rnci5lcy9tL0NBRXhIVzV0aTVp
Z0R3T09kZTZzaGdmUzdKUHRDWTlnTnJrQjN4TnIlM0RGdUdUWVZEU2pRJTQwbWFpbC5nbWFpbC5j
b20KLS0tCiBkb2Mvc3JjL3NnbWwvcmVmL3BnX3Jlc3RvcmUuc2dtbCB8IDggKysrKysrKy0KIDEg
ZmlsZSBjaGFuZ2VkLCA3IGluc2VydGlvbnMoKyksIDEgZGVsZXRpb24oLSkKCmRpZmYgLS1naXQg
YS9kb2Mvc3JjL3NnbWwvcmVmL3BnX3Jlc3RvcmUuc2dtbCBiL2RvYy9zcmMvc2dtbC9yZWYvcGdf
cmVzdG9yZS5zZ21sCmluZGV4IGE0NjhhMzgzNjFhLi45M2IyZjE2NTliMyAxMDA2NDQKLS0tIGEv
ZG9jL3NyYy9zZ21sL3JlZi9wZ19yZXN0b3JlLnNnbWwKKysrIGIvZG9jL3NyYy9zZ21sL3JlZi9w
Z19yZXN0b3JlLnNnbWwKQEAgLTE2MCw2ICsxNjAsMTAgQEAgUG9zdGdyZVNRTCBkb2N1bWVudGF0
aW9uCiAgICAgICAgIDxjb21tYW5kPkNSRUFURSBEQVRBQkFTRTwvY29tbWFuZD4gY29tbWFuZHMu
ICBBbGwgZGF0YSBpcyByZXN0b3JlZCBpbnRvIHRoZQogICAgICAgICBkYXRhYmFzZSBuYW1lIHRo
YXQgYXBwZWFycyBpbiB0aGUgYXJjaGl2ZS4KICAgICAgICA8L3BhcmE+CisKKyAgICAgICA8cGFy
YT4KKyAgICAgICAgVGhpcyBvcHRpb24gY2Fubm90IGJlIHVzZWQgdG9nZXRoZXIgd2l0aCA8b3B0
aW9uPi0tc2luZ2xlLXRyYW5zYWN0aW9uPC9vcHRpb24+LgorICAgICAgIDwvcGFyYT4KICAgICAg
IDwvbGlzdGl0ZW0+CiAgICAgIDwvdmFybGlzdGVudHJ5PgogCkBAIC01NDEsNyArNTQ1LDkgQEAg
UG9zdGdyZVNRTCBkb2N1bWVudGF0aW9uCiAgICAgICAgIGVtaXR0ZWQgY29tbWFuZHMgaW4gPGNv
bW1hbmQ+QkVHSU48L2NvbW1hbmQ+Lzxjb21tYW5kPkNPTU1JVDwvY29tbWFuZD4pLiAgVGhpcwog
ICAgICAgICBlbnN1cmVzIHRoYXQgZWl0aGVyIGFsbCB0aGUgY29tbWFuZHMgY29tcGxldGUgc3Vj
Y2Vzc2Z1bGx5LCBvciBubwogICAgICAgICBjaGFuZ2VzIGFyZSBhcHBsaWVkLiBUaGlzIG9wdGlv
biBpbXBsaWVzCi0gICAgICAgIDxvcHRpb24+LS1leGl0LW9uLWVycm9yPC9vcHRpb24+LgorICAg
ICAgICA8b3B0aW9uPi0tZXhpdC1vbi1lcnJvcjwvb3B0aW9uPi4gIEl0IGNhbm5vdCBiZSB1c2Vk
IHRvZ2V0aGVyIHdpdGgKKyAgICAgICAgPG9wdGlvbj4tLWNyZWF0ZTwvb3B0aW9uPiwgd2hpY2gg
c3dpdGNoZXMgZGF0YWJhc2UgY29ubmVjdGlvbnMsIG9yIHdpdGgKKyAgICAgICAgbXVsdGlwbGUg
PG9wdGlvbj4tLWpvYnM8L29wdGlvbj4uCiAgICAgICAgPC9wYXJhPgogICAgICAgPC9saXN0aXRl
bT4KICAgICAgPC92YXJsaXN0ZW50cnk+Ci0tIAoyLjUxLjAKCg==


--=-+S+GNK3UvxTYR1ZLGg3G--