pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedMinor typo in 13.3.5. Advisory Locks
5+ messages / 3 participants
[nested] [flat]
* Minor typo in 13.3.5. Advisory Locks
@ 2023-03-28 14:37 PG Doc comments form <noreply@postgresql.org>
2023-03-28 20:45 ` Re: Minor typo in 13.3.5. Advisory Locks Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2023-03-28 14:37 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: zacharymschultz@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/15/explicit-locking.html
Description:
After the code snippet in the 6th paragraph of 13.3.5. Advisory Locks
(https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
I believe there is a mistake in this sentence (I've surrounded it with
asterisks):
"In the above queries, the second *form* is dangerous because the
LIMIT...".
I believe that "form" in the above sentence is actually meant to be "from",
referencing the second line of code and its FROM clause in the snippet.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Minor typo in 13.3.5. Advisory Locks
2023-03-28 14:37 Minor typo in 13.3.5. Advisory Locks PG Doc comments form <noreply@postgresql.org>
@ 2023-03-28 20:45 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-03-31 08:25 ` Re: Minor typo in 13.3.5. Advisory Locks Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2023-03-28 20:45 UTC (permalink / raw)
To: zacharymschultz@gmail.com; +Cc: pgsql-docs@lists.postgresql.org
PG Doc comments form <noreply@postgresql.org> writes:
> Page: https://www.postgresql.org/docs/15/explicit-locking.html
> After the code snippet in the 6th paragraph of 13.3.5. Advisory Locks
> (https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
> I believe there is a mistake in this sentence (I've surrounded it with
> asterisks):
> "In the above queries, the second *form* is dangerous because the
> LIMIT...".
> I believe that "form" in the above sentence is actually meant to be "from",
> referencing the second line of code and its FROM clause in the snippet.
No, I think "form" is exactly what was meant. Maybe we should have
said "second query" or something like that, though.
regards, tom lane
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Minor typo in 13.3.5. Advisory Locks
2023-03-28 14:37 Minor typo in 13.3.5. Advisory Locks PG Doc comments form <noreply@postgresql.org>
2023-03-28 20:45 ` Re: Minor typo in 13.3.5. Advisory Locks Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-03-31 08:25 ` Daniel Gustafsson <daniel@yesql.se>
2023-03-31 12:35 ` Re: Minor typo in 13.3.5. Advisory Locks Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2023-03-31 08:25 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: zacharymschultz@gmail.com; pgsql-docs@lists.postgresql.org
> On 28 Mar 2023, at 22:45, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> PG Doc comments form <noreply@postgresql.org> writes:
>> Page: https://www.postgresql.org/docs/15/explicit-locking.html
>
>> After the code snippet in the 6th paragraph of 13.3.5. Advisory Locks
>> (https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
>> I believe there is a mistake in this sentence (I've surrounded it with
>> asterisks):
>
>> "In the above queries, the second *form* is dangerous because the
>> LIMIT...".
>
>> I believe that "form" in the above sentence is actually meant to be "from",
>> referencing the second line of code and its FROM clause in the snippet.
>
> No, I think "form" is exactly what was meant.
Agreed, I think that was the indended spelling.
> Maybe we should have said "second query" or something like that, though.
Reading this section I agree that the mix of ok/danger in the same example can
be tad misleading though. Something like the attached is what I would prefer
as a reader.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] adv_lock_limit.diff (1.7K, ../../76AEBCC7-5C7C-4A30-B3C3-8FAB1883C789@yesql.se/2-adv_lock_limit.diff)
download | inline diff:
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index b87ad5cc53..5f5e2bc55e 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1582,16 +1582,8 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
In certain cases using advisory locking methods, especially in queries
involving explicit ordering and <literal>LIMIT</literal> clauses, care must be
taken to control the locks acquired because of the order in which SQL
- expressions are evaluated. For example:
-<screen>
-SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok
-SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!
-SELECT pg_advisory_lock(q.id) FROM
-(
- SELECT id FROM foo WHERE id > 12345 LIMIT 100
-) q; -- ok
-</screen>
- In the above queries, the second form is dangerous because the
+ expressions are evaluated. For example,
+ this query is dangerous because the
<literal>LIMIT</literal> is not guaranteed to be applied before the locking
function is executed. This might cause some locks to be acquired
that the application was not expecting, and hence would fail to release
@@ -1599,6 +1591,17 @@ SELECT pg_advisory_lock(q.id) FROM
From the point of view of the application, such locks
would be dangling, although still viewable in
<structname>pg_locks</structname>.
+<screen>
+SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!
+</screen>
+ The below forms are safe:
+<screen>
+SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok
+SELECT pg_advisory_lock(q.id) FROM
+(
+ SELECT id FROM foo WHERE id > 12345 LIMIT 100
+) q; -- ok
+</screen>
</para>
<para>
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Minor typo in 13.3.5. Advisory Locks
2023-03-28 14:37 Minor typo in 13.3.5. Advisory Locks PG Doc comments form <noreply@postgresql.org>
2023-03-28 20:45 ` Re: Minor typo in 13.3.5. Advisory Locks Tom Lane <tgl@sss.pgh.pa.us>
2023-03-31 08:25 ` Re: Minor typo in 13.3.5. Advisory Locks Daniel Gustafsson <daniel@yesql.se>
@ 2023-03-31 12:35 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-03-31 20:43 ` Re: Minor typo in 13.3.5. Advisory Locks Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2023-03-31 12:35 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: zacharymschultz@gmail.com; pgsql-docs@lists.postgresql.org
Daniel Gustafsson <daniel@yesql.se> writes:
> Reading this section I agree that the mix of ok/danger in the same example can
> be tad misleading though. Something like the attached is what I would prefer
> as a reader.
I think in your rewrite, "this query" is dangling a bit because there's
several sentences more before the query actually appears. I suggest
ordering things more like:
expressions are evaluated. For example,
this query is dangerous because the
<literal>LIMIT</literal> is not guaranteed to be applied before the locking
function is executed:
<screen>
SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!
</screen>
This might cause some locks to be acquired
that the application was not expecting, and hence would fail to
...
On the other hand, these queries are safe:
<screen>
SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok
...
Separately from that: now that I look at this example, it's really
quite safe for any plausible plan shape. It used to be dangerous if
you had an ORDER BY, but there's no ORDER BY, and even if there were
we fixed that in 9118d03a8. Do we want to choose another example, and
if so what? The "not guaranteed" wording isn't really wrong, but an
example that doesn't do what we're saying it does isn't good either.
regards, tom lane
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Minor typo in 13.3.5. Advisory Locks
2023-03-28 14:37 Minor typo in 13.3.5. Advisory Locks PG Doc comments form <noreply@postgresql.org>
2023-03-28 20:45 ` Re: Minor typo in 13.3.5. Advisory Locks Tom Lane <tgl@sss.pgh.pa.us>
2023-03-31 08:25 ` Re: Minor typo in 13.3.5. Advisory Locks Daniel Gustafsson <daniel@yesql.se>
2023-03-31 12:35 ` Re: Minor typo in 13.3.5. Advisory Locks Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-03-31 20:43 ` Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 5+ messages in thread
From: Daniel Gustafsson @ 2023-03-31 20:43 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: zacharymschultz@gmail.com; pgsql-docs@lists.postgresql.org
> On 31 Mar 2023, at 14:35, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Daniel Gustafsson <daniel@yesql.se> writes:
>> Reading this section I agree that the mix of ok/danger in the same example can
>> be tad misleading though. Something like the attached is what I would prefer
>> as a reader.
>
> I think in your rewrite, "this query" is dangling a bit because there's
> several sentences more before the query actually appears. I suggest
> ordering things more like:
>
> expressions are evaluated. For example,
> this query is dangerous because the
> <literal>LIMIT</literal> is not guaranteed to be applied before the locking
> function is executed:
> <screen>
> SELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!
> </screen>
> This might cause some locks to be acquired
> that the application was not expecting, and hence would fail to
> ...
> On the other hand, these queries are safe:
> <screen>
> SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- ok
> ...
Yes, I like this version a lot better than what I proposed.
> Separately from that: now that I look at this example, it's really
> quite safe for any plausible plan shape. It used to be dangerous if
> you had an ORDER BY, but there's no ORDER BY, and even if there were
> we fixed that in 9118d03a8. Do we want to choose another example, and
> if so what? The "not guaranteed" wording isn't really wrong, but an
> example that doesn't do what we're saying it does isn't good either.
Off the cuff I don't have any better suggestions, need to do some more
thinking.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2023-03-31 20:43 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-03-28 14:37 Minor typo in 13.3.5. Advisory Locks PG Doc comments form <noreply@postgresql.org>
2023-03-28 20:45 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-03-31 08:25 ` Daniel Gustafsson <daniel@yesql.se>
2023-03-31 12:35 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-03-31 20:43 ` Daniel Gustafsson <daniel@yesql.se>
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