From 172d7f7e666ee0612b7d56d7b73a7ebc98476a66 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Mon, 26 Feb 2024 18:19:03 +0100 Subject: [PATCH] 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.zuh6objy3z72@alvherre.pgsql --- doc/src/sgml/ref/merge.sgml | 50 +++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml index f643e6254d..8e1b7c7fe5 100644 --- 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 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.)