Feedback-ID: ia2694551:Fastmail
Date: Wed, 18 May 2022 18:42:38 +0200
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Justin Pryzby <pryzby@telsasoft.com>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	Amit Langote <amitlangote09@gmail.com>,
	Japin Li <japinli@hotmail.com>, Zhihong Yu <zyu@yugabyte.com>,
	Simon Riggs <simon.riggs@enterprisedb.com>,
	pgsql-hackers@lists.postgresql.org,
	Tomas Vondra <tomas.vondra@enterprisedb.com>,
	Daniel Westermann <dwe@dbi-services.com>,
	Erik Rijkers <er@xs4all.nl>,
	Jaime Casanova <jcasanov@systemguards.com.ec>,
	Andres Freund <andres@anarazel.de>
Subject: Re: support for MERGE
Message-ID: <202205181642.3dlxbkt3f64g@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="2wzyrvwjlnwluax2"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20220511163350.GL19626@telsasoft.com>
Archived-At: 
 <https://www.postgresql.org/message-id/202205181642.3dlxbkt3f64g%40alvherre.pgsql>
Precedence: bulk


--2wzyrvwjlnwluax2
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On 2022-May-11, Justin Pryzby wrote:

> I suggest to reference the mvcc docs from the merge docs, or to make the merge
> docs themselves include the referenced information.
> 
> diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
> index f68aa09736c..99dd5814f36 100644
> --- a/doc/src/sgml/ref/merge.sgml
> +++ b/doc/src/sgml/ref/merge.sgml
> @@ -544,6 +544,7 @@ MERGE <replaceable class="parameter">total_count</replaceable>
>     <command>UPDATE</command> if a concurrent <command>INSERT</command>
>     occurs.  There are a variety of differences and restrictions between
>     the two statement types and they are not interchangeable.
> +   See <xref linkend="mvcc"/> for more information.

Reading the paragraph, I think it may be better to do it the other way
around: first mention that concurrency is described in the MVCC page,
then explain that INSERT ON CONFLICT also exists.  What do you think of
the attached?

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/

--2wzyrvwjlnwluax2
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: attachment;
	filename="v2-0001-Link-to-MVCC-docs-in-MERGE-docs.patch"

From 5bad2c5a4bcd2bf04751f980f947c1050aeafd03 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Wed, 18 May 2022 18:41:04 +0200
Subject: [PATCH v2] Link to MVCC docs in MERGE docs.

---
 doc/src/sgml/mvcc.sgml      | 2 +-
 doc/src/sgml/ref/merge.sgml | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 341fea524a..4446e1c484 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -425,7 +425,7 @@ COMMIT;
    <para>
     <command>MERGE</command> allows the user to specify various
     combinations of <command>INSERT</command>, <command>UPDATE</command>
-    or <command>DELETE</command> subcommands. A <command>MERGE</command>
+    and <command>DELETE</command> subcommands. A <command>MERGE</command>
     command with both <command>INSERT</command> and <command>UPDATE</command>
     subcommands looks similar to <command>INSERT</command> with an
     <literal>ON CONFLICT DO UPDATE</literal> clause but does not
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index f68aa09736..6b94c863b5 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -539,6 +539,8 @@ MERGE <replaceable class="parameter">total_count</replaceable>
   </para>
 
   <para>
+   See <xref linkend="mvcc"/> for more details on the behavior of
+   <command>MERGE</command> under concurrency.
    You may also wish to consider using <command>INSERT ... ON CONFLICT</command>
    as an alternative statement which offers the ability to run an
    <command>UPDATE</command> if a concurrent <command>INSERT</command>
-- 
2.30.2


--2wzyrvwjlnwluax2--