From 5defdef8aa0535b8e9365ea9cceee60d5731395f Mon Sep 17 00:00:00 2001
From: Dean Rasheed <dean.a.rasheed@gmail.com>
Date: Fri, 9 Dec 2022 10:00:01 +0000
Subject: Update MERGE docs to mention that ONLY is supported.

Commit 7103ebb7aa added support for MERGE, which included support for
inheritance hierarchies, but didn't document the fact that ONLY could
be specified before the source and/or target tables to exclude tables
inheriting from the tables specified.

Update merge.sgml to mention this, and while at it, add some
regression tests to cover it.

Dean Rasheed, reviewed by Nathan Bossart.

Backpatch to 15, where MERGE was added.

Discussion: https://postgr.es/m/CAEZATCU0XM-bJCvpJuVRU3UYNRqEBS6g4-zH%3Dj9Ye0caX8F6uQ%40mail.gmail.com
---
 doc/src/sgml/ref/merge.sgml | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index e07addaea42..0995fe0c046 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -22,13 +22,13 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 [ WITH <replaceable class="parameter">with_query</replaceable> [, ...] ]
-MERGE INTO <replaceable class="parameter">target_table_name</replaceable> [ [ AS ] <replaceable class="parameter">target_alias</replaceable> ]
+MERGE INTO [ ONLY ] <replaceable class="parameter">target_table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">target_alias</replaceable> ]
 USING <replaceable class="parameter">data_source</replaceable> ON <replaceable class="parameter">join_condition</replaceable>
 <replaceable class="parameter">when_clause</replaceable> [...]
 
 <phrase>where <replaceable class="parameter">data_source</replaceable> is:</phrase>
 
-{ <replaceable class="parameter">source_table_name</replaceable> | ( <replaceable class="parameter">source_query</replaceable> ) } [ [ AS ] <replaceable class="parameter">source_alias</replaceable> ]
+{ [ ONLY ] <replaceable class="parameter">source_table_name</replaceable> [ * ] | ( <replaceable class="parameter">source_query</replaceable> ) } [ [ AS ] <replaceable class="parameter">source_alias</replaceable> ]
 
 <phrase>and <replaceable class="parameter">when_clause</replaceable> is:</phrase>
 
@@ -129,6 +129,14 @@ DELETE
     <listitem>
      <para>
       The name (optionally schema-qualified) of the target table to merge into.
+      If <literal>ONLY</literal> is specified before the table name, matching
+      rows are updated or deleted in the named table only.  If
+      <literal>ONLY</literal> is not specified, matching rows are also updated
+      or deleted in any tables inheriting from the named table.  Optionally,
+      <literal>*</literal> can be specified after the table name to explicitly
+      indicate that descendant tables are included.  The
+      <literal>ONLY</literal> keyword and <literal>*</literal> option do not
+      affect insert actions, which always insert into the named table only.
      </para>
     </listitem>
    </varlistentry>
@@ -151,7 +159,12 @@ DELETE
     <listitem>
      <para>
       The name (optionally schema-qualified) of the source table, view, or
-      transition table.
+      transition table.  If <literal>ONLY</literal> is specified before the
+      table name, matching rows are included from the named table only.  If
+      <literal>ONLY</literal> is not specified, matching rows are also included
+      from any tables inheriting from the named table.  Optionally,
+      <literal>*</literal> can be specified after the table name to explicitly
+      indicate that descendant tables are included.
      </para>
     </listitem>
    </varlistentry>
-- 
cgit v1.2.3