From ee7e8f3838733f09a67e1421f0d7c6498cd68ab0 Mon Sep 17 00:00:00 2001 From: Dean Rasheed Date: Sun, 26 Feb 2023 09:06:04 +0000 Subject: [PATCH] Doc: Miscellaneous doc updates for MERGE. Update a few places in the documentation that should mention MERGE among the list of applicable commands. In a couple of places, a slightly more detailed description of what happens for MERGE seems appropriate. Reviewed by Alvaro Herrera. Discussion: http://postgr.es/m/CAEZATCWqHLcxab89ATMQZNGFG_mxDPM%2BjzkSbXKD3JYPfRGvtw%40mail.gmail.com --- doc/src/sgml/arch-dev.sgml | 16 ++++++++++++---- doc/src/sgml/ddl.sgml | 3 ++- doc/src/sgml/high-availability.sgml | 3 ++- doc/src/sgml/perform.sgml | 8 +++++--- doc/src/sgml/plpgsql.sgml | 3 ++- doc/src/sgml/protocol.sgml | 7 +++++++ doc/src/sgml/queries.sgml | 12 +++++++----- doc/src/sgml/ref/create_publication.sgml | 6 ++++++ doc/src/sgml/ref/explain.sgml | 6 ++++-- doc/src/sgml/ref/prepare.sgml | 3 ++- doc/src/sgml/ref/set_transaction.sgml | 11 +++++++---- doc/src/sgml/xfunc.sgml | 3 ++- 12 files changed, 58 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml index 0c7a53c961..976db1e599 100644 --- a/doc/src/sgml/arch-dev.sgml +++ b/doc/src/sgml/arch-dev.sgml @@ -530,13 +530,15 @@ - The executor mechanism is used to evaluate all four basic SQL query + The executor mechanism is used to evaluate all five basic SQL query types: SELECT, INSERT, - UPDATE, and DELETE. + UPDATE, DELETE, and + MERGE. For SELECT, the top-level executor code only needs to send each row returned by the query plan tree off to the client. INSERT ... SELECT, - UPDATE, and DELETE + UPDATE, DELETE, and + MERGE are effectively SELECTs under a special top-level plan node called ModifyTable. @@ -552,7 +554,13 @@ mark the old row deleted. For DELETE, the only column that is actually returned by the plan is the TID, and the ModifyTable node simply uses the TID to visit each - target row and mark it deleted. + target row and mark it deleted. For MERGE, the + planner joins the source and target relations, and includes all + column values required by any of the WHEN clauses, + plus the TID of the target row; this data is fed up to the + ModifyTable node, which uses the information to + work out which WHEN clause to execute, and then + inserts, updates or deletes the target row, as required. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 8dc8d7a0ce..5179125510 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1804,7 +1804,8 @@ REVOKE ALL ON accounts FROM PUBLIC; view, or other table-like object. Also allows use of COPY TO. This privilege is also needed to reference existing column values in - UPDATE or DELETE. + UPDATE, DELETE, + or MERGE. For sequences, this privilege also allows use of the currval function. For large objects, this privilege allows the object to be read. diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index f180607528..9d0deaeeb8 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1611,7 +1611,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' Data Manipulation Language (DML): INSERT, - UPDATE, DELETE, COPY FROM, + UPDATE, DELETE, + MERGE, COPY FROM, TRUNCATE. Note that there are no allowed actions that result in a trigger being executed during recovery. This restriction applies even to diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml index 54f329cf6b..90822b3f4c 100644 --- a/doc/src/sgml/perform.sgml +++ b/doc/src/sgml/perform.sgml @@ -788,9 +788,10 @@ ROLLBACK; As seen in this example, when the query is an INSERT, - UPDATE, or DELETE command, the actual work of + UPDATE, DELETE, or + MERGE command, the actual work of applying the table changes is done by a top-level Insert, Update, - or Delete plan node. The plan nodes underneath this node perform + Delete, or Merge plan node. The plan nodes underneath this node perform the work of locating the old rows and/or computing the new data. So above, we see the same sort of bitmap table scan we've seen already, and its output is fed to an Update node that stores the updated rows. @@ -803,7 +804,8 @@ ROLLBACK; - When an UPDATE or DELETE command affects an + When an UPDATE, DELETE, or + MERGE command affects an inheritance hierarchy, the output might look like this: diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 8897a5450a..7c8a49fe43 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1044,7 +1044,8 @@ INSERT INTO mytable VALUES (1,'one'), (2,'two'); PL/pgSQL variable values can be automatically inserted into optimizable SQL commands, which are SELECT, INSERT, - UPDATE, DELETE, and certain + UPDATE, DELETE, + MERGE, and certain utility commands that incorporate one of these, such as EXPLAIN and CREATE TABLE ... AS SELECT. In these commands, diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 93fc7167d4..73b7f4432f 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -4115,6 +4115,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" rows is the number of rows updated. + + For a MERGE command, the tag is + MERGE rows where + rows is the number of rows inserted, + updated, or deleted. + + For a SELECT or CREATE TABLE AS command, the tag is SELECT rows diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 45741e773b..6986ec5c92 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -2064,8 +2064,8 @@ SELECT select_list FROM table_expression in a WITH clause can be a SELECT, INSERT, UPDATE, or DELETE; and the WITH clause itself is attached to a primary statement that can - also be a SELECT, INSERT, UPDATE, or - DELETE. + be a SELECT, INSERT, UPDATE, + DELETE, or MERGE. @@ -2587,7 +2587,8 @@ SELECT * FROM w AS w1 JOIN w AS w2 ON w1.f = w2.f; The examples above only show WITH being used with SELECT, but it can be attached in the same way to - INSERT, UPDATE, or DELETE. + INSERT, UPDATE, + DELETE, or MERGE. In each case it effectively provides temporary table(s) that can be referred to in the main command. @@ -2597,8 +2598,9 @@ SELECT * FROM w AS w1 JOIN w AS w2 ON w1.f = w2.f; Data-Modifying Statements in <literal>WITH</literal> - You can use data-modifying statements (INSERT, - UPDATE, or DELETE) in WITH. This + You can use most data-modifying statements (INSERT, + UPDATE, or DELETE, but not + MERGE) in WITH. This allows you to perform several different operations in the same query. An example is: diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml index 370dac2ccf..a2946feaa3 100644 --- a/doc/src/sgml/ref/create_publication.sgml +++ b/doc/src/sgml/ref/create_publication.sgml @@ -306,6 +306,12 @@ CREATE PUBLICATION name UPDATE, or it may not be published at all. + + For a MERGE command, the publication will publish an + INSERT, UPDATE, or DELETE + for each row inserted, updated, or deleted. + + ATTACHing a table into a partition tree whose root is published using a publication with publish_via_partition_root diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index d4895b9d7d..0fce622423 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -94,7 +94,8 @@ EXPLAIN [ ANALYZE ] [ VERBOSE ] statementEXPLAIN ANALYZE on an INSERT, UPDATE, - DELETE, CREATE TABLE AS, + DELETE, MERGE, + CREATE TABLE AS, or EXECUTE statement without letting the command affect your data, use this approach: @@ -272,7 +273,8 @@ ROLLBACK; Any SELECT, INSERT, UPDATE, - DELETE, VALUES, EXECUTE, + DELETE, MERGE, + VALUES, EXECUTE, DECLARE, CREATE TABLE AS, or CREATE MATERIALIZED VIEW AS statement, whose execution plan you wish to see. diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml index f9e0cdc69a..8ee9439f61 100644 --- a/doc/src/sgml/ref/prepare.sgml +++ b/doc/src/sgml/ref/prepare.sgml @@ -116,7 +116,8 @@ PREPARE name [ ( Any SELECT, INSERT, UPDATE, - DELETE, or VALUES statement. + DELETE, MERGE, or VALUES + statement. diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml index d394e622f8..727a92757e 100644 --- a/doc/src/sgml/ref/set_transaction.sgml +++ b/doc/src/sgml/ref/set_transaction.sgml @@ -121,7 +121,8 @@ SET SESSION CHARACTERISTICS AS TRANSACTION transa The transaction isolation level cannot be changed after the first query or data-modification statement (SELECT, INSERT, DELETE, - UPDATE, FETCH, or + UPDATE, MERGE, + FETCH, or COPY) of a transaction has been executed. See for more information about transaction isolation and concurrency control. @@ -131,8 +132,9 @@ SET SESSION CHARACTERISTICS AS TRANSACTION transa The transaction access mode determines whether the transaction is read/write or read-only. Read/write is the default. When a transaction is read-only, the following SQL commands are - disallowed: INSERT, UPDATE, - DELETE, and COPY FROM if the + disallowed: INSERT, UPDATE, + DELETE, MERGE, and + COPY FROM if the table they would write to is not a temporary table; all CREATE, ALTER, and DROP commands; COMMENT, @@ -169,7 +171,8 @@ SET SESSION CHARACTERISTICS AS TRANSACTION transa start of a transaction, before the first query or data-modification statement (SELECT, INSERT, DELETE, - UPDATE, FETCH, or + UPDATE, MERGE, + FETCH, or COPY) of the transaction. Furthermore, the transaction must already be set to SERIALIZABLE or REPEATABLE READ isolation level (otherwise, the snapshot diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index e2a5496c34..9620ea9ae3 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -186,7 +186,8 @@ language can be packaged together and defined as a function. Besides SELECT queries, the commands can include data modification queries (INSERT, - UPDATE, and DELETE), as well as + UPDATE, DELETE, and + MERGE), as well as other SQL commands. (You cannot use transaction control commands, e.g., COMMIT, SAVEPOINT, and some utility commands, e.g., VACUUM, in SQL functions.)