Skip to content

Commit ffffeeb

Browse files
alvherrealvherre
committed
Link to MVCC docs in MERGE docs
In addition, this moves the new paragraph in the MVCC page upwards, for a more consistent flow; some minor markup mistakes, style issues and typos are fixed too. Per comments from Justin Pryzby. Discussion: https://postgr.es/m/20220511163350.GL19626@telsasoft.com
1 parent a059e15 commit ffffeeb

File tree

2 files changed

+40
-35
lines changed

2 files changed

+40
-35
lines changed

‎doc/src/sgml/mvcc.sgml

+36-35
Original file line numberDiff line numberDiff line change
@@ -359,8 +359,8 @@
359359
behaves similarly. In Read Committed mode, each row proposed for insertion
360360
will either insert or update. Unless there are unrelated errors, one of
361361
those two outcomes is guaranteed. If a conflict originates in another
362-
transaction whose effects are not yet visible to the <command>INSERT
363-
</command>, the <command>UPDATE</command> clause will affect that row,
362+
transaction whose effects are not yet visible to the <command>INSERT</command>,
363+
the <command>UPDATE</command> clause will affect that row,
364364
even though possibly <emphasis>no</emphasis> version of that row is
365365
conventionally visible to the command.
366366
</para>
@@ -373,6 +373,37 @@
373373
the case in Read Committed mode.
374374
</para>
375375

376+
<para>
377+
<command>MERGE</command> allows the user to specify various
378+
combinations of <command>INSERT</command>, <command>UPDATE</command>
379+
and <command>DELETE</command> subcommands. A <command>MERGE</command>
380+
command with both <command>INSERT</command> and <command>UPDATE</command>
381+
subcommands looks similar to <command>INSERT</command> with an
382+
<literal>ON CONFLICT DO UPDATE</literal> clause but does not
383+
guarantee that either <command>INSERT</command> or
384+
<command>UPDATE</command> will occur.
385+
If <command>MERGE</command> attempts an <command>UPDATE</command> or
386+
<command>DELETE</command> and the row is concurrently updated but
387+
the join condition still passes for the current target and the
388+
current source tuple, then <command>MERGE</command> will behave
389+
the same as the <command>UPDATE</command> or
390+
<command>DELETE</command> commands and perform its action on the
391+
updated version of the row. However, because <command>MERGE</command>
392+
can specify several actions and they can be conditional, the
393+
conditions for each action are re-evaluated on the updated version of
394+
the row, starting from the first action, even if the action that had
395+
originally matched appears later in the list of actions.
396+
On the other hand, if the row is concurrently updated or deleted so
397+
that the join condition fails, then <command>MERGE</command> will
398+
evaluate the condition's <literal>NOT MATCHED</literal> actions next,
399+
and execute the first one that succeeds.
400+
If <command>MERGE</command> attempts an <command>INSERT</command>
401+
and a unique index is present and a duplicate row is concurrently
402+
inserted, then a uniqueness violation error is raised;
403+
<command>MERGE</command> does not attempt to avoid such
404+
errors by evaluating <literal>MATCHED</literal> conditions.
405+
</para>
406+
376407
<para>
377408
Because of the above rules, it is possible for an updating command to see
378409
an inconsistent snapshot: it can see the effects of concurrent updating
@@ -422,37 +453,6 @@ COMMIT;
422453
<literal>11</literal>, which no longer matches the criteria.
423454
</para>
424455

425-
<para>
426-
<command>MERGE</command> allows the user to specify various
427-
combinations of <command>INSERT</command>, <command>UPDATE</command>
428-
or <command>DELETE</command> subcommands. A <command>MERGE</command>
429-
command with both <command>INSERT</command> and <command>UPDATE</command>
430-
subcommands looks similar to <command>INSERT</command> with an
431-
<literal>ON CONFLICT DO UPDATE</literal> clause but does not
432-
guarantee that either <command>INSERT</command> or
433-
<command>UPDATE</command> will occur.
434-
If MERGE attempts an <command>UPDATE</command> or
435-
<command>DELETE</command> and the row is concurrently updated but
436-
the join condition still passes for the current target and the
437-
current source tuple, then <command>MERGE</command> will behave
438-
the same as the <command>UPDATE</command> or
439-
<command>DELETE</command> commands and perform its action on the
440-
updated version of the row. However, because <command>MERGE</command>
441-
can specify several actions and they can be conditional, the
442-
conditions for each action are re-evaluated on the updated version of
443-
the row, starting from the first action, even if the action that had
444-
originally matched appears later in the list of actions.
445-
On the other hand, if the row is concurrently updated or deleted so
446-
that the join condition fails, then <command>MERGE</command> will
447-
evaluate the condition's <literal>NOT MATCHED</literal> actions next,
448-
and execute the first one that succeeds.
449-
If <command>MERGE</command> attempts an <command>INSERT</command>
450-
and a unique index is present and a duplicate row is concurrently
451-
inserted, then a uniqueness violation is raised.
452-
<command>MERGE</command> does not attempt to avoid the
453-
error by executing an <command>UPDATE</command>.
454-
</para>
455-
456456
<para>
457457
Because Read Committed mode starts each command with a new snapshot
458458
that includes all transactions committed up to that instant,
@@ -516,8 +516,9 @@ COMMIT;
516516
</para>
517517

518518
<para>
519-
<command>UPDATE</command>, <command>DELETE</command>, <command>SELECT
520-
FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands
519+
<command>UPDATE</command>, <command>DELETE</command>,
520+
<command>MERGE</command>, <command>SELECT FOR UPDATE</command>,
521+
and <command>SELECT FOR SHARE</command> commands
521522
behave the same as <command>SELECT</command>
522523
in terms of searching for target rows: they will only find target rows
523524
that were committed as of the transaction start time. However, such a

‎doc/src/sgml/ref/merge.sgml

+4
Original file line numberDiff line numberDiff line change
@@ -539,6 +539,10 @@ MERGE <replaceable class="parameter">total_count</replaceable>
539539
</para>
540540

541541
<para>
542+
When <command>MERGE</command> is run concurrently with other commands
543+
that modify the target table, the usual transaction isolation rules
544+
apply; see <xref linkend="transaction-iso"/> for an explanation
545+
on the behavior at each isolation level.
542546
You may also wish to consider using <command>INSERT ... ON CONFLICT</command>
543547
as an alternative statement which offers the ability to run an
544548
<command>UPDATE</command> if a concurrent <command>INSERT</command>

0 commit comments

Comments
 (0)