public inbox for [email protected]help / color / mirror / Atom feed
pg_restore documentation and --create/--single-transaction limitation 6+ messages / 2 participants [nested] [flat]
* pg_restore documentation and --create/--single-transaction limitation @ 2025-03-24 11:41 Ashutosh Bapat <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Ashutosh Bapat @ 2025-03-24 11:41 UTC (permalink / raw) To: pgsql-hackers Hi All, 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. -- Best Wishes, Ashutosh Bapat Attachments: [text/x-patch] 0001-pg_restore-documentation-correction-20250324.patch (1.5K, 2-0001-pg_restore-documentation-correction-20250324.patch) download | inline diff: From e9efa27688cb0f85825fd7cda02118818a1edeae Mon Sep 17 00:00:00 2001 From: Ashutosh Bapat <[email protected]> Date: Mon, 24 Mar 2025 16:59:16 +0530 Subject: [PATCH] pg_restore documentation correction --create and --single-transaction switches cannot be specified together. But --pg_restore documentation does not mention this. Fix the documentation. Author: Ashutosh Bapat --- doc/src/sgml/ref/pg_restore.sgml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 35140187807..1ae28cb8efb 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -148,6 +148,10 @@ PostgreSQL documentation <command>CREATE DATABASE</command> commands. All data is restored into the database name that appears in the archive. </para> + + <para> + This option cannot be used with <option>--single-transaction</option>. + </para> </listitem> </varlistentry> @@ -618,7 +622,8 @@ 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>. This option cannot be used with + <option>--create</option>. </para> </listitem> </varlistentry> base-commit: 19c6eb06c51f4da70e2ea0f1bdb64a0142e8e2aa -- 2.34.1 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_restore documentation and --create/--single-transaction limitation @ 2025-09-30 09:30 Laurenz Albe <[email protected]> parent: Ashutosh Bapat <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Laurenz Albe @ 2025-09-30 09:30 UTC (permalink / raw) To: Ashutosh Bapat <[email protected]>; pgsql-hackers 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 together"); pg_fatal("options -s/--schema-only and -a/--data-only cannot be used together"); 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 together"); 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 together"); pg_fatal("options --statistics-only and --no-statistics cannot be used together"); pg_fatal("options --statistics and --no-statistics cannot be used together"); 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 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 Attachments: [text/x-patch] v2-0001-Document-incompatible-pg_restore-options.patch (1.9K, 2-v2-0001-Document-incompatible-pg_restore-options.patch) download | inline diff: From 2e4a84f6f546308dd82bf66ffd67621608cc05be Mon Sep 17 00:00:00 2001 From: Laurenz Albe <[email protected]> Date: Tue, 30 Sep 2025 11:22:42 +0200 Subject: [PATCH v2] Document incompatible pg_restore options Most of the incumpatibilities (such as --file and --dbname) are pretty obvious and need no explanation. But it may not be obvious that --single-transaction cannot be used together with --create or multiple --jobs, so let's mention that in the documentation. Author: Ashutosh Bapat <[email protected]> Reviewed-By: Laurenz Albe <[email protected]> Discussion: https://postgr.es/m/CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr%3DFuGTYVDSjQ%40mail.gmail.com --- doc/src/sgml/ref/pg_restore.sgml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index a468a38361a..93b2f1659b3 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -160,6 +160,10 @@ PostgreSQL documentation <command>CREATE DATABASE</command> commands. All data is restored into the database name that appears in the archive. </para> + + <para> + This option cannot be used together with <option>--single-transaction</option>. + </para> </listitem> </varlistentry> @@ -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 + multiple <option>--jobs</option>. </para> </listitem> </varlistentry> -- 2.51.0 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_restore documentation and --create/--single-transaction limitation @ 2025-09-30 11:31 Ashutosh Bapat <[email protected]> parent: Laurenz Albe <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Ashutosh Bapat @ 2025-09-30 11:31 UTC (permalink / raw) To: Laurenz Albe <[email protected]>; +Cc: pgsql-hackers On Tue, Sep 30, 2025 at 3:00 PM Laurenz Albe <[email protected]> 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 together"); > pg_fatal("options -s/--schema-only and -a/--data-only cannot be used together"); > 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 together"); > 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 together"); > pg_fatal("options --statistics-only and --no-statistics cannot be used together"); > pg_fatal("options --statistics and --no-statistics cannot be used together"); > 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 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. 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. -- Best Wishes, Ashutosh Bapat Attachments: [text/x-patch] 0001-Document-more-incompatible-pg_restore-optio-20250930.patch (1.9K, 2-0001-Document-more-incompatible-pg_restore-optio-20250930.patch) download | inline diff: From 2c5ec02d93eeb84b6d9a110dead98116f98f1896 Mon Sep 17 00:00:00 2001 From: Laurenz Albe <[email protected]> Date: Tue, 30 Sep 2025 11:22:42 +0200 Subject: [PATCH] Document more incompatible pg_restore options Most of the pairs of incompatible options (such as --file and --dbname) are pretty obvious and need no explanation. But it may not be obvious that --single-transaction cannot be used together with --create or multiple jobs, so let's mention that in the documentation. Author: Ashutosh Bapat <[email protected]> Reviewed-By: Laurenz Albe <[email protected]> Discussion: https://postgr.es/m/CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr%3DFuGTYVDSjQ%40mail.gmail.com --- doc/src/sgml/ref/pg_restore.sgml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index a468a38361a..0d6797450b4 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -160,6 +160,10 @@ PostgreSQL documentation <command>CREATE DATABASE</command> commands. All data is restored into the database name that appears in the archive. </para> + + <para> + This option cannot be used together with <option>--single-transaction</option>. + </para> </listitem> </varlistentry> @@ -541,7 +545,8 @@ 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> or with multiple jobs (<option>--jobs</option>). </para> </listitem> </varlistentry> base-commit: 91df0465a69ddd249a548a63ee9d4aef6f984bf0 -- 2.34.1 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_restore documentation and --create/--single-transaction limitation @ 2025-09-30 12:36 Laurenz Albe <[email protected]> parent: Ashutosh Bapat <[email protected]> 0 siblings, 2 replies; 6+ messages in thread From: Laurenz Albe @ 2025-09-30 12:36 UTC (permalink / raw) To: Ashutosh Bapat <[email protected]>; +Cc: pgsql-hackers 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". Yours, Laurenz Albe ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_restore documentation and --create/--single-transaction limitation @ 2025-09-30 14:36 Ashutosh Bapat <[email protected]> parent: Laurenz Albe <[email protected]> 1 sibling, 0 replies; 6+ messages in thread From: Ashutosh Bapat @ 2025-09-30 14:36 UTC (permalink / raw) To: Laurenz Albe <[email protected]>; +Cc: pgsql-hackers On Tue, Sep 30, 2025 at 6:06 PM Laurenz Albe <[email protected]> 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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_restore documentation and --create/--single-transaction limitation @ 2026-03-30 03:15 Ashutosh Bapat <[email protected]> parent: Laurenz Albe <[email protected]> 1 sibling, 0 replies; 6+ messages in thread From: Ashutosh Bapat @ 2026-03-30 03:15 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: Laurenz Albe <[email protected]>; pgsql-hackers On Sun, Mar 29, 2026 at 11:39 PM Tom Lane <[email protected]> wrote: > > Laurenz Albe <[email protected]> writes: > > On Tue, 2025-09-30 at 17:01 +0530, Ashutosh Bapat wrote: > >> Attached patch with those changes. > > > I agree with your simpler version. I'll mark the patch "ready for committer". > > Pushed. I changed "or" to "nor" which I thought read better. > Thanks a lot Tom. -- Best Wishes, Ashutosh Bapat ^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2026-03-30 03:15 UTC | newest] Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2025-03-24 11:41 pg_restore documentation and --create/--single-transaction limitation Ashutosh Bapat <[email protected]> 2025-09-30 09:30 ` Laurenz Albe <[email protected]> 2025-09-30 11:31 ` Ashutosh Bapat <[email protected]> 2025-09-30 12:36 ` Laurenz Albe <[email protected]> 2025-09-30 14:36 ` Ashutosh Bapat <[email protected]> 2026-03-30 03:15 ` Ashutosh Bapat <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox