Date: Wed, 18 May 2022 11:57:15 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Alvaro Herrera <alvherre@alvh.no-ip.org>
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: <20220518165715.GJ19626@telsasoft.com>
References: <20220511163350.GL19626@telsasoft.com>
 <202205181642.3dlxbkt3f64g@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <202205181642.3dlxbkt3f64g@alvherre.pgsql>
User-Agent: Mutt/1.9.4 (2018-02-28)
Archived-At: 
 <https://www.postgresql.org/message-id/20220518165715.GJ19626%40telsasoft.com>
Precedence: bulk

On Wed, May 18, 2022 at 06:42:38PM +0200, Alvaro Herrera wrote:
> 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?

Hmm, it seems odd to put "see also" first.

My original complaint is that 1) merge.sgml doesn't include the detailed
information; but 3) mentions it vaguely without linking to it: "There are a
variety of differences and restrictions between the two statement types and
they are not interchangeable."

I prefer my original, but the most important thing is to include the link at
*somewhere*.

-- 
Justin