Re: pg_restore documentation and --create/--single-transaction limitation

On Tue, Sep 30, 2025 at 6:06 PM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at> wrote:
>
> On Tue, 2025-09-30 at 17:01 +0530, Ashutosh Bapat wrote:
> > 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>). 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
> >
> > 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.
>
> I agree with your simpler version. I'll mark the patch "ready for committer".

Thanks.

--
Best Wishes,
Ashutosh Bapat