pg_dump shared locks documentation

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

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

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

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