Revise MERGE documentation

Add a note about the additional privileges required after the fix in
4989ce72644b (wording per Tom Lane); also change marked-up mentions of
"target_table_name" to be simply "the target table" or the like.  Also,
note that "join_condition" is scouted for requisite privileges.

Backpatch to 15.

Discussion: https://postgr.es/m/202402211653[email protected]

diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index f643e6254d1d7bac8c5034550f3e735683965a37..8e1b7c7fe5556c1f24da82355b160e6bd75cfdeb 100644 (file)
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -57,7 +57,7 @@ DELETE
 
   
    MERGE performs actions that modify rows in the
-   target_table_name,
+   target table identified as target_table_name,
    using the data_source.
    MERGE provides a single SQL
    statement that can conditionally INSERT,
@@ -68,7 +68,7 @@ DELETE
   
    First, the MERGE command performs a join
    from data_source to
-   target_table_name
+   the target table
    producing zero or more candidate change rows.  For each candidate change
    row, the status of MATCHED or NOT MATCHED
    is set just once, after which WHEN clauses are evaluated
@@ -83,7 +83,7 @@ DELETE
    DELETE commands of the same names. The syntax of
    those commands is different, notably that there is no WHERE
    clause and no table name is specified.  All actions refer to the
-   target_table_name,
+   target table,
    though modifications to other tables may be made using triggers.
   
 
@@ -98,23 +98,27 @@ DELETE
    There is no separate MERGE privilege.
    If you specify an update action, you must have the
    UPDATE privilege on the column(s)
-   of the target_table_name
+   of the target table
    that are referred to in the SET clause.
    If you specify an insert action, you must have the INSERT
-   privilege on the target_table_name.
+   privilege on the target table.
    If you specify a delete action, you must have the DELETE
-   privilege on the target_table_name.
+   privilege on the target table.
+   If you specify a DO NOTHING action, you must have
+   the SELECT privilege on at least one column
+   of the target table.
+   You will also need SELECT privilege on any column(s)
+   of the data_source and
+   of the target table referred to
+   in any condition (including join_condition)
+   or expression.
    Privileges are tested once at statement start and are checked
    whether or not particular WHEN clauses are executed.
-   You will require the SELECT privilege on any column(s)
-   of the data_source and
-   target_table_name referred to
-   in any condition or expression.
   
 
   
    MERGE is not supported if the
-   target_table_name is a
+   target table is a
    materialized view, foreign table, or if it has any
    rules defined on it.
   
@@ -175,7 +179,7 @@ DELETE
      
       A query (SELECT statement or VALUES
       statement) that supplies the rows to be merged into the
-      target_table_name.
+      target table.
       Refer to the 
       statement or 
       statement for a description of the syntax.
@@ -203,16 +207,15 @@ DELETE
       boolean (similar to a WHERE
       clause) that specifies which rows in the
       data_source
-      match rows in the
-      target_table_name.
+      match rows in the target table.
      
      
       
-       Only columns from target_table_name
+       Only columns from the target table
        that attempt to match data_source
        rows should appear in join_condition.
        join_condition subexpressions that
-       only reference target_table_name
+       only reference the target table's
        columns can affect which action is taken, often in surprising ways.
       
      
@@ -228,7 +231,7 @@ DELETE
      
       If the WHEN clause specifies WHEN MATCHED
       and the candidate change row matches a row in the
-      target_table_name,
+      target table,
       the WHEN clause is executed if the
       condition is
       absent or it evaluates to true.
@@ -237,7 +240,7 @@ DELETE
       Conversely, if the WHEN clause specifies
       WHEN NOT MATCHED
       and the candidate change row does not match a row in the
-      target_table_name,
+      target table,
       the WHEN clause is executed if the
       condition is
       absent or it evaluates to true.
@@ -280,10 +283,10 @@ DELETE
       or null if there is none.
      
      
-      If target_table_name
+      If the target table
       is a partitioned table, each row is routed to the appropriate partition
       and inserted into it.
-      If target_table_name
+      If the target table
       is a partition, an error will occur if any input row violates the
       partition constraint.
      
@@ -304,7 +307,7 @@ DELETE
     
      
       The specification of an UPDATE action that updates
-      the current row of the target_table_name.
+      the current row of the target table.
       Column names may not be specified more than once.
      
      
@@ -318,7 +321,7 @@ DELETE
     
      
       Specifies a DELETE action that deletes the current row
-      of the target_table_name.
+      of the target table.
       Do not include the table name or any other clauses, as you would normally
       do with a  command.
      
@@ -329,8 +332,7 @@ DELETE
     column_name
     
      
-      The name of a column in the 
-      class="parameter">target_table_name.  The column name
+      The name of a column in the target table.  The column name
       can be qualified with a subfield name or array subscript, if
       needed.  (Inserting into only some fields of a composite
       column leaves the other fields null.)