public inbox for [email protected]
help / color / mirror / Atom feedFrom: Laurenz Albe <[email protected]>
To: Ashutosh Bapat <[email protected]>
To: pgsql-hackers <[email protected]>
Subject: Re: pg_restore documentation and --create/--single-transaction limitation
Date: Tue, 30 Sep 2025 11:30:50 +0200
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr=FuGTYVDSjQ@mail.gmail.com>
References: <CAExHW5ti5igDwOOde6shgfS7JPtCY9gNrkB3xNr=FuGTYVDSjQ@mail.gmail.com>
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
view thread (6+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected]
Subject: Re: pg_restore documentation and --create/--single-transaction limitation
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox