| Lists: | pgsql-docs |
|---|
| From: | Florin Irion <irionr(at)gmail(dot)com> |
|---|---|
| To: | pgsql-docs(at)lists(dot)postgresql(dot)org |
| Subject: | pg_dump shared locks documentation |
| Date: | 2022-03-15 14:19:47 |
| Message-ID: | [email protected] |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Lists: | pgsql-docs |
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
| Attachment | Content-Type | Size |
|---|---|---|
| 0001-doc-Specify-correctly-the-locks-pg_dump-takes.patch | text/plain | 3.0 KB |
| From: | Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> |
|---|---|
| To: | Florin Irion <irionr(at)gmail(dot)com> |
| Cc: | pgsql-docs(at)lists(dot)postgresql(dot)org |
| Subject: | Re: pg_dump shared locks documentation |
| Date: | 2022-03-15 15:06:57 |
| Message-ID: | [email protected] |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Lists: | pgsql-docs |
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
| From: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> |
|---|---|
| To: | Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> |
| Cc: | Florin Irion <irionr(at)gmail(dot)com>, pgsql-docs(at)lists(dot)postgresql(dot)org |
| Subject: | Re: pg_dump shared locks documentation |
| Date: | 2022-03-15 15:55:09 |
| Message-ID: | [email protected] |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Lists: | pgsql-docs |
Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)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
| From: | Florin Irion <irionr(at)gmail(dot)com> |
|---|---|
| To: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> |
| Cc: | pgsql-docs(at)lists(dot)postgresql(dot)org |
| Subject: | Re: pg_dump shared locks documentation |
| Date: | 2022-03-15 22:21:41 |
| Message-ID: | [email protected] |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Lists: | pgsql-docs |
On 15/03/22 16:55, Tom Lane wrote:
> Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)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
| Attachment | Content-Type | Size |
|---|---|---|
| v2-0001-Specify-correctly-the-locks-pg_dump-takes.patch | text/plain | 1.4 KB |
| From: | Nathan Bossart <nathandbossart(at)gmail(dot)com> |
|---|---|
| To: | Florin Irion <irionr(at)gmail(dot)com> |
| Cc: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org>, pgsql-docs(at)lists(dot)postgresql(dot)org |
| Subject: | Re: pg_dump shared locks documentation |
| Date: | 2022-03-30 22:19:29 |
| Message-ID: | 20220330221929.GA47505@nathanxps13 |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Lists: | pgsql-docs |
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