pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedpg_dump shared locks documentation
5+ messages / 4 participants
[nested] [flat]
* pg_dump shared locks documentation
@ 2022-03-15 14:19 Florin Irion <irionr@gmail.com>
2022-03-15 15:06 ` Re: pg_dump shared locks documentation Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 5+ messages in thread
From: Florin Irion @ 2022-03-15 14:19 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hi,
In the `pg_dump` documentation we talk about "shared locks", but IIUC, we actually take `AccessShareLock`s.
This might be misunderstood with the `ShareLock`.
There are 5 occurrences. 4 in `--jobs=njobs` and 1 in `--lock-wait-timeout=timeout` sections.
Cheers,
Florin Irion
From 63adb1d3a252d78a115a0bae3e9c6bc08b7ae83f Mon Sep 17 00:00:00 2001
From: Florin Irion <florin.irion@enterprisedb.com>
Date: Tue, 15 Mar 2022 15:09:11 +0100
Subject: [PATCH] doc: Specify correctly the locks pg_dump takes
The pg_dump leader and worker processes take `AccessShareLock`s,
clarify it in the docs so that it can not be misunderstood with
`ShareLock`s.
---
doc/src/sgml/ref/pg_dump.sgml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 2f0042fd96..5f95b16e98 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -372,17 +372,17 @@ PostgreSQL documentation
<para>
Requesting exclusive locks on database objects while running a parallel dump could
cause the dump to fail. The reason is that the <application>pg_dump</application> leader process
- requests shared locks on the objects that the worker processes are going to dump later
+ requests access share locks on the objects that the worker processes are going to dump later
in order to
make sure that nobody deletes them and makes them go away while the dump is running.
If another client then requests an exclusive lock on a table, that lock will not be
- granted but will be queued waiting for the shared lock of the leader process to be
+ granted but will be queued waiting for the access share lock of the leader process to be
released. Consequently any other access to the table will not be granted either and
will queue after the exclusive lock request. This includes the worker process trying
to dump the table. Without any precautions this would be a classic deadlock situation.
To detect this conflict, the <application>pg_dump</application> worker process requests another
- shared lock using the <literal>NOWAIT</literal> option. If the worker process is not granted
- this shared lock, somebody else must have requested an exclusive lock in the meantime
+ access share lock using the <literal>NOWAIT</literal> option. If the worker process is not granted
+ this access share lock, somebody else must have requested an exclusive lock in the meantime
and there is no way to continue with the dump, so <application>pg_dump</application> has no choice
but to abort the dump.
</para>
@@ -870,7 +870,7 @@ PostgreSQL documentation
<term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
<listitem>
<para>
- Do not wait forever to acquire shared table locks at the beginning of
+ Do not wait forever to acquire access share table locks at the beginning of
the dump. Instead fail if unable to lock a table within the specified
<replaceable class="parameter">timeout</replaceable>. The timeout may be
specified in any of the formats accepted by <command>SET
--
2.34.0
Attachments:
[text/plain] 0001-doc-Specify-correctly-the-locks-pg_dump-takes.patch (3.0K, ../../d0f30cc2-3c76-1d43-f291-7c4b2872d653@gmail.com/2-0001-doc-Specify-correctly-the-locks-pg_dump-takes.patch)
download | inline diff:
From 63adb1d3a252d78a115a0bae3e9c6bc08b7ae83f Mon Sep 17 00:00:00 2001
From: Florin Irion <florin.irion@enterprisedb.com>
Date: Tue, 15 Mar 2022 15:09:11 +0100
Subject: [PATCH] doc: Specify correctly the locks pg_dump takes
The pg_dump leader and worker processes take `AccessShareLock`s,
clarify it in the docs so that it can not be misunderstood with
`ShareLock`s.
---
doc/src/sgml/ref/pg_dump.sgml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 2f0042fd96..5f95b16e98 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -372,17 +372,17 @@ PostgreSQL documentation
<para>
Requesting exclusive locks on database objects while running a parallel dump could
cause the dump to fail. The reason is that the <application>pg_dump</application> leader process
- requests shared locks on the objects that the worker processes are going to dump later
+ requests access share locks on the objects that the worker processes are going to dump later
in order to
make sure that nobody deletes them and makes them go away while the dump is running.
If another client then requests an exclusive lock on a table, that lock will not be
- granted but will be queued waiting for the shared lock of the leader process to be
+ granted but will be queued waiting for the access share lock of the leader process to be
released. Consequently any other access to the table will not be granted either and
will queue after the exclusive lock request. This includes the worker process trying
to dump the table. Without any precautions this would be a classic deadlock situation.
To detect this conflict, the <application>pg_dump</application> worker process requests another
- shared lock using the <literal>NOWAIT</literal> option. If the worker process is not granted
- this shared lock, somebody else must have requested an exclusive lock in the meantime
+ access share lock using the <literal>NOWAIT</literal> option. If the worker process is not granted
+ this access share lock, somebody else must have requested an exclusive lock in the meantime
and there is no way to continue with the dump, so <application>pg_dump</application> has no choice
but to abort the dump.
</para>
@@ -870,7 +870,7 @@ PostgreSQL documentation
<term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
<listitem>
<para>
- Do not wait forever to acquire shared table locks at the beginning of
+ Do not wait forever to acquire access share table locks at the beginning of
the dump. Instead fail if unable to lock a table within the specified
<replaceable class="parameter">timeout</replaceable>. The timeout may be
specified in any of the formats accepted by <command>SET
--
2.34.0
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: pg_dump shared locks documentation
2022-03-15 14:19 pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
@ 2022-03-15 15:06 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-03-15 15:55 ` Re: pg_dump shared locks documentation Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 5+ messages in thread
From: Alvaro Herrera @ 2022-03-15 15:06 UTC (permalink / raw)
To: Florin Irion <irionr@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On 2022-Mar-15, Florin Irion wrote:
> In the `pg_dump` documentation we talk about "shared locks", but IIUC,
> we actually take `AccessShareLock`s. This might be misunderstood with
> the `ShareLock`.
This might be a bit excessive to have in the main text. What about
adding a footnote to point out the exact lock level that is meant, with
a link to the server doc page that explains each lock level?
Something like this:
> Requesting exclusive locks on database objects while running a parallel dump could
> cause the dump to fail. The reason is that the <application>pg_dump</application> leader process
> - requests shared locks on the objects that the worker processes are going to dump later
> + requests shared locks<footnote>The precise lock level used is <literal>ACCESS SHARE</literal>.
> + See <xref ... /> for more information.</footnote> on the objects that the worker processes are
> going to dump later
...
> @@ -870,7 +870,7 @@ PostgreSQL documentation
> <term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
> <listitem>
> <para>
> - Do not wait forever to acquire shared table locks at the beginning of
Same here.
--
Álvaro Herrera
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: pg_dump shared locks documentation
2022-03-15 14:19 pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
2022-03-15 15:06 ` Re: pg_dump shared locks documentation Alvaro Herrera <alvherre@alvh.no-ip.org>
@ 2022-03-15 15:55 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-03-15 22:21 ` Re: pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2022-03-15 15:55 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Florin Irion <irionr@gmail.com>; pgsql-docs@lists.postgresql.org
Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> This might be a bit excessive to have in the main text. What about
> adding a footnote to point out the exact lock level that is meant, with
> a link to the server doc page that explains each lock level?
I dunno how well <footnote> will render in man-page format.
How about just inserting a parenthetical remark at the first usage?
... leader process requests shared locks (ACCESS SHARE) on the ...
Possibly we could make the "ACCESS SHARE" be a <link> without causing
problems in man format.
regards, tom lane
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: pg_dump shared locks documentation
2022-03-15 14:19 pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
2022-03-15 15:06 ` Re: pg_dump shared locks documentation Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-03-15 15:55 ` Re: pg_dump shared locks documentation Tom Lane <tgl@sss.pgh.pa.us>
@ 2022-03-15 22:21 ` Florin Irion <irionr@gmail.com>
2022-03-30 22:19 ` Re: pg_dump shared locks documentation Nathan Bossart <nathandbossart@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Florin Irion @ 2022-03-15 22:21 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: pgsql-docs@lists.postgresql.org
On 15/03/22 16:55, Tom Lane wrote:
> Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
>> This might be a bit excessive to have in the main text. What about
>> adding a footnote to point out the exact lock level that is meant, with
>> a link to the server doc page that explains each lock level?
>
> I dunno how well <footnote> will render in man-page format.
> How about just inserting a parenthetical remark at the first usage?
>
> ... leader process requests shared locks (ACCESS SHARE) on the ...
>
> Possibly we could make the "ACCESS SHARE" be a <link> without causing
> problems in man format.
>
> regards, tom lane
Makes sense.
I tried the footnote and in fact, it doesn't render well in the man page. It just adds a blank line(at least how I tried it).
So, I made the link to ACCESS SHARE, pointing to section 13.3.1. "Table-Level Locks" , was this what you had in mind?
V2 attached.
Thank you for looking into this.
Florin Irion
From 13c57e5218b605bd9d101e966b8edb486daac091 Mon Sep 17 00:00:00 2001
From: Florin Irion <florin.irion@enterprisedb.com>
Date: Tue, 15 Mar 2022 22:43:34 +0100
Subject: [PATCH v2] Specify correctly the locks pg_dump takes
The pg_dump leader and worker processes take `AccessShareLock`s,
clarify it in the docs so that it can not be misunderstood with
`ShareLock`s.
---
doc/src/sgml/ref/pg_dump.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 2f0042fd96..07edd459cf 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -372,8 +372,8 @@ PostgreSQL documentation
<para>
Requesting exclusive locks on database objects while running a parallel dump could
cause the dump to fail. The reason is that the <application>pg_dump</application> leader process
- requests shared locks on the objects that the worker processes are going to dump later
- in order to
+ requests shared locks (<link linkend="locking-tables">ACCESS SHARE</link>) on the
+ objects that the worker processes are going to dump later in order to
make sure that nobody deletes them and makes them go away while the dump is running.
If another client then requests an exclusive lock on a table, that lock will not be
granted but will be queued waiting for the shared lock of the leader process to be
--
2.34.0
Attachments:
[text/plain] v2-0001-Specify-correctly-the-locks-pg_dump-takes.patch (1.4K, ../../f84cbf9e-cf4b-a9eb-9667-5fadd913d5ca@gmail.com/2-v2-0001-Specify-correctly-the-locks-pg_dump-takes.patch)
download | inline diff:
From 13c57e5218b605bd9d101e966b8edb486daac091 Mon Sep 17 00:00:00 2001
From: Florin Irion <florin.irion@enterprisedb.com>
Date: Tue, 15 Mar 2022 22:43:34 +0100
Subject: [PATCH v2] Specify correctly the locks pg_dump takes
The pg_dump leader and worker processes take `AccessShareLock`s,
clarify it in the docs so that it can not be misunderstood with
`ShareLock`s.
---
doc/src/sgml/ref/pg_dump.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 2f0042fd96..07edd459cf 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -372,8 +372,8 @@ PostgreSQL documentation
<para>
Requesting exclusive locks on database objects while running a parallel dump could
cause the dump to fail. The reason is that the <application>pg_dump</application> leader process
- requests shared locks on the objects that the worker processes are going to dump later
- in order to
+ requests shared locks (<link linkend="locking-tables">ACCESS SHARE</link>) on the
+ objects that the worker processes are going to dump later in order to
make sure that nobody deletes them and makes them go away while the dump is running.
If another client then requests an exclusive lock on a table, that lock will not be
granted but will be queued waiting for the shared lock of the leader process to be
--
2.34.0
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: pg_dump shared locks documentation
2022-03-15 14:19 pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
2022-03-15 15:06 ` Re: pg_dump shared locks documentation Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-03-15 15:55 ` Re: pg_dump shared locks documentation Tom Lane <tgl@sss.pgh.pa.us>
2022-03-15 22:21 ` Re: pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
@ 2022-03-30 22:19 ` Nathan Bossart <nathandbossart@gmail.com>
0 siblings, 0 replies; 5+ messages in thread
From: Nathan Bossart @ 2022-03-30 22:19 UTC (permalink / raw)
To: Florin Irion <irionr@gmail.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Alvaro Herrera <alvherre@alvh.no-ip.org>; pgsql-docs@lists.postgresql.org
On Tue, Mar 15, 2022 at 11:21:41PM +0100, Florin Irion wrote:
> So, I made the link to ACCESS SHARE, pointing to section 13.3.1. "Table-Level Locks" , was this what you had in mind?
>
> V2 attached.
LGTM. I've marked the commitfest entry as ready-for-committer.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2022-03-30 22:19 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-03-15 14:19 pg_dump shared locks documentation Florin Irion <irionr@gmail.com>
2022-03-15 15:06 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-03-15 15:55 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-03-15 22:21 ` Florin Irion <irionr@gmail.com>
2022-03-30 22:19 ` Nathan Bossart <nathandbossart@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox