MIME-Version: 1.0
References: 
 <CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr=FuGTYVDSjQ@mail.gmail.com>
 <2ebde3606beab536a8693e8f54c33dc0981b8478.camel@cybertec.at>
In-Reply-To: <2ebde3606beab536a8693e8f54c33dc0981b8478.camel@cybertec.at>
From: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>
Date: Tue, 30 Sep 2025 17:01:28 +0530
Message-ID: 
 <CAExHW5tvMaJupX9c33NqKQ41D-QoDxeYAnnJS580+N690LrA2A@mail.gmail.com>
Subject: Re: pg_restore documentation and --create/--single-transaction
 limitation
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: pgsql-hackers <pgsql-hackers@postgresql.org>
Content-Type: multipart/mixed; boundary="000000000000ab410b0640031861"
Archived-At: 
 <https://www.postgresql.org/message-id/CAExHW5tvMaJupX9c33NqKQ41D-QoDxeYAnnJS580%2BN690LrA2A%40mail.gmail.com>
Precedence: bulk

--000000000000ab410b0640031861
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tue, Sep 30, 2025 at 3:00=E2=80=AFPM Laurenz Albe <laurenz.albe@cybertec=
.at> wrote:
>
> 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.
> >
> > 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 togethe=
r");
>   pg_fatal("options -s/--schema-only and -a/--data-only cannot be used to=
gether");
>   pg_fatal("options -s/--schema-only and --statistics-only cannot be used=
 together");
>   pg_fatal("options -a/--data-only and --statistics-only cannot be used t=
ogether");
>   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 toget=
her");
>   pg_fatal("options --statistics-only and --no-statistics cannot be used =
together");
>   pg_fatal("options --statistics and --no-statistics cannot be used toget=
her");
>   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=
 be used together");
>   pg_fatal("options -C/--create and -1/--single-transaction cannot be use=
d 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.

Thanks a lot for the research and pointing out missing --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?

@@ -541,7 +545,9 @@ PostgreSQL documentation
emitted commands in <command>BEGIN</command>/<command>COMMIT</command>). Th=
is
ensures that either all the commands complete successfully, or no
changes are applied. This option implies
- <option>--exit-on-error</option>.
+ <option>--exit-on-error</option>. It cannot be used together with
+ <option>--create</option>, which switches database connections, or with

I didn't understand ", which switches ..." part. The code comment says
/*
* -C is not compatible with -1, because we can't create a database inside
* a transaction block.
*/
if (opts->createDB && opts->single_txn)
pg_fatal("options -C/--create and -1/--single-transaction cannot be
used together");

It doesn't say anything about switching connections. But it's too low
level of detail, which we may just eliminate.

+ multiple <option>--jobs</option>.

This seems to be confusing. I read it as --single-transaction can not
be used when there are multiple --jobs specifications e.g.
--single-transaction --jobs 1 --jobs 2. Maybe just say " multiple
jobs". Even corresponding --jobs documentation says

pipe or standard input). Also, multiple
jobs cannot be used together with the
option <option>--single-transaction</option>.

Attached patch with those changes.

--=20
Best Wishes,
Ashutosh Bapat

--000000000000ab410b0640031861
Content-Type: text/x-patch; charset="US-ASCII";
	name="0001-Document-more-incompatible-pg_restore-optio-20250930.patch"
Content-Disposition: attachment;
	filename="0001-Document-more-incompatible-pg_restore-optio-20250930.patch"
Content-Transfer-Encoding: base64
Content-ID: <f_mg6h7bm30>
X-Attachment-Id: f_mg6h7bm30

RnJvbSAyYzVlYzAyZDkzZWViODRiNmQ5YTExMGRlYWQ5ODExNmY5OGYxODk2IE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBMYXVyZW56IEFsYmUgPGxhdXJlbnouYWxiZUBjeWJlcnRlYy5h
dD4KRGF0ZTogVHVlLCAzMCBTZXAgMjAyNSAxMToyMjo0MiArMDIwMApTdWJqZWN0OiBbUEFUQ0hd
IERvY3VtZW50IG1vcmUgaW5jb21wYXRpYmxlIHBnX3Jlc3RvcmUgb3B0aW9ucwoKTW9zdCBvZiB0
aGUgcGFpcnMgb2YgaW5jb21wYXRpYmxlIG9wdGlvbnMgKHN1Y2ggYXMgLS1maWxlIGFuZCAtLWRi
bmFtZSkgYXJlCnByZXR0eSBvYnZpb3VzIGFuZCBuZWVkIG5vIGV4cGxhbmF0aW9uLiAgQnV0IGl0
IG1heSBub3QgYmUgb2J2aW91cyB0aGF0Ci0tc2luZ2xlLXRyYW5zYWN0aW9uIGNhbm5vdCBiZSB1
c2VkIHRvZ2V0aGVyIHdpdGggLS1jcmVhdGUgb3IgbXVsdGlwbGUKam9icywgc28gbGV0J3MgbWVu
dGlvbiB0aGF0IGluIHRoZSBkb2N1bWVudGF0aW9uLgoKQXV0aG9yOiBBc2h1dG9zaCBCYXBhdCA8
YXNodXRvc2guYmFwYXQub3NzQGdtYWlsLmNvbT4KUmV2aWV3ZWQtQnk6IExhdXJlbnogQWxiZSA8
bGF1cmVuei5hbGJlQGN5YmVydGVjLmF0PgpEaXNjdXNzaW9uOiBodHRwczovL3Bvc3Rnci5lcy9t
L0NBRXhIVzV0aTVpZ0R3T09kZTZzaGdmUzdKUHRDWTlnTnJrQjN4TnIlM0RGdUdUWVZEU2pRJTQw
bWFpbC5nbWFpbC5jb20KLS0tCiBkb2Mvc3JjL3NnbWwvcmVmL3BnX3Jlc3RvcmUuc2dtbCB8IDcg
KysrKysrLQogMSBmaWxlIGNoYW5nZWQsIDYgaW5zZXJ0aW9ucygrKSwgMSBkZWxldGlvbigtKQoK
ZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yZWYvcGdfcmVzdG9yZS5zZ21sIGIvZG9jL3NyYy9z
Z21sL3JlZi9wZ19yZXN0b3JlLnNnbWwKaW5kZXggYTQ2OGEzODM2MWEuLjBkNjc5NzQ1MGI0IDEw
MDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvcmVmL3BnX3Jlc3RvcmUuc2dtbAorKysgYi9kb2Mvc3Jj
L3NnbWwvcmVmL3BnX3Jlc3RvcmUuc2dtbApAQCAtMTYwLDYgKzE2MCwxMCBAQCBQb3N0Z3JlU1FM
IGRvY3VtZW50YXRpb24KICAgICAgICAgPGNvbW1hbmQ+Q1JFQVRFIERBVEFCQVNFPC9jb21tYW5k
PiBjb21tYW5kcy4gIEFsbCBkYXRhIGlzIHJlc3RvcmVkIGludG8gdGhlCiAgICAgICAgIGRhdGFi
YXNlIG5hbWUgdGhhdCBhcHBlYXJzIGluIHRoZSBhcmNoaXZlLgogICAgICAgIDwvcGFyYT4KKwor
ICAgICAgIDxwYXJhPgorICAgICAgICBUaGlzIG9wdGlvbiBjYW5ub3QgYmUgdXNlZCB0b2dldGhl
ciB3aXRoIDxvcHRpb24+LS1zaW5nbGUtdHJhbnNhY3Rpb248L29wdGlvbj4uCisgICAgICAgPC9w
YXJhPgogICAgICAgPC9saXN0aXRlbT4KICAgICAgPC92YXJsaXN0ZW50cnk+CiAKQEAgLTU0MSw3
ICs1NDUsOCBAQCBQb3N0Z3JlU1FMIGRvY3VtZW50YXRpb24KICAgICAgICAgZW1pdHRlZCBjb21t
YW5kcyBpbiA8Y29tbWFuZD5CRUdJTjwvY29tbWFuZD4vPGNvbW1hbmQ+Q09NTUlUPC9jb21tYW5k
PikuICBUaGlzCiAgICAgICAgIGVuc3VyZXMgdGhhdCBlaXRoZXIgYWxsIHRoZSBjb21tYW5kcyBj
b21wbGV0ZSBzdWNjZXNzZnVsbHksIG9yIG5vCiAgICAgICAgIGNoYW5nZXMgYXJlIGFwcGxpZWQu
IFRoaXMgb3B0aW9uIGltcGxpZXMKLSAgICAgICAgPG9wdGlvbj4tLWV4aXQtb24tZXJyb3I8L29w
dGlvbj4uCisgICAgICAgIDxvcHRpb24+LS1leGl0LW9uLWVycm9yPC9vcHRpb24+LiBJdCBjYW5u
b3QgYmUgdXNlZCB0b2dldGhlciB3aXRoCisgICAgICAgIDxvcHRpb24+LS1jcmVhdGU8L29wdGlv
bj4gb3Igd2l0aCBtdWx0aXBsZSBqb2JzICg8b3B0aW9uPi0tam9iczwvb3B0aW9uPikuCiAgICAg
ICAgPC9wYXJhPgogICAgICAgPC9saXN0aXRlbT4KICAgICAgPC92YXJsaXN0ZW50cnk+CgpiYXNl
LWNvbW1pdDogOTFkZjA0NjVhNjlkZGQyNDlhNTQ4YTYzZWU5ZDRhZWY2Zjk4NGJmMAotLSAKMi4z
NC4xCgo=
--000000000000ab410b0640031861--