Message-ID: <3346e4ef343f1ac99ad9db02f2cdbb2fb7507a9f.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>
Cc: pgsql-hackers <pgsql-hackers@postgresql.org>
Date: Tue, 30 Sep 2025 14:36:31 +0200
In-Reply-To: 
 <CAExHW5tvMaJupX9c33NqKQ41D-QoDxeYAnnJS580+N690LrA2A@mail.gmail.com>
References: 
	<CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr=FuGTYVDSjQ@mail.gmail.com>
	 <2ebde3606beab536a8693e8f54c33dc0981b8478.camel@cybertec.at>
	 <CAExHW5tvMaJupX9c33NqKQ41D-QoDxeYAnnJS580+N690LrA2A@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.56.2 (3.56.2-2.fc42) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/3346e4ef343f1ac99ad9db02f2cdbb2fb7507a9f.camel%40cybertec.at>
Precedence: bulk

On Tue, 2025-09-30 at 17:01 +0530, Ashutosh Bapat wrote:
> Thanks a lot for the research and pointing out missing --jobs.
>=20
> > So I think that your suggestion makes sense.
> >=20
> > I tried to improve the English, and I have added the incompatibility
> > with multiple --jobs to the --single-transaction documentation.
> >=20
> > Does that look alright to you?
>=20
> @@ -541,7 +545,9 @@ PostgreSQL documentation
> emitted commands in <command>BEGIN</command>/<command>COMMIT</command>). =
This
> 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
>=20
> 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");
>=20
> It doesn't say anything about switching connections. But it's too low
> level of detail, which we may just eliminate.
>=20
> + multiple <option>--jobs</option>.
>=20
> 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
>=20
> pipe or standard input). Also, multiple
> jobs cannot be used together with the
> option <option>--single-transaction</option>.
>=20
> Attached patch with those changes.

I agree with your simpler version.  I'll mark the patch "ready for committe=
r".

Yours,
Laurenz Albe