From 346e7446656d6be885e090aa774bac958fbc596d Mon Sep 17 00:00:00 2001 From: "Zheng (Zane) Li" Date: Sat, 7 Jan 2023 00:40:24 +0000 Subject: [PATCH 7/7] Document DDL replication and DDL deparser. --- doc/src/sgml/logical-replication.sgml | 1055 +++++++++++++++++++++++++ 1 file changed, 1055 insertions(+) diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index 7b9bb00e5a..25e0470f11 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -1437,6 +1437,1061 @@ test_sub=# SELECT * FROM t1 ORDER BY id; + + DDL Replication + + Data Definition Commands (DDLs) can be replicated using logical replication. + While enabled this feature automatically replicates supported DDL commands + that are successfully executed on a publisher to a subscriber. This is + especially useful if you have lots schema changes over time that need replication. + + + + For example, when enabled a CREATE TABLE command executed on the publisher gets + WAL-logged, and forwarded to the subscriber to replay; a subsequent "ALTER + SUBSCRIPTION ... REFRESH PUBLICATION" is run on the subscrier database so any + following DML changes on the new table can be replicated without a hitch. + + + + DDL replication is disabled by default, it can be enabled at different levels + using the ddl PUBLICATION option. This option currently has two levels and are + only allowed to be set if the PUBLICATION is FOR ALL TABLES. + + + + + + all: this option enables replication of all supported DDL commands. + + + + + + table: this option enables replication of Table DDL commands, + which include: + + + + CREATE/ALTER/DROP TABLE + + + + + + CREATE TABLE AS + + + + + + + + + + Examples - Setup DDL Replication on the Publisher + + + Create a new publication with all ddl replication enabled: + +CREATE PUBLICATION mypub FOR ALL TABLES with (ddl = 'all'); + + + + Enable table ddl replication for an existing Publication: + +ALTER PUBLICATION mypub SET (ddl = 'table'); + + + + + + Supported DDL commands + + + The DDL commands supported for logical replication are listed in the following + matrix. Note that global commands can be executed at any database and are currently + not supported for replication, global commands include ROLE statements, Database + statements, TableSpace statements and some of the GrantStmt/RevokeStmt if the target + object is a global object. + + + + DDL Replication Support by Command Tag + + + + + + + Command Tag + For Replication + Notes + + + + + ALTER AGGREGATE + X + + + + ALTER CAST + X + + + + ALTER COLLATION + X + + + + ALTER CONVERSION + X + + + + ALTER DATABASE + - + + + + ALTER DEFAULT PRIVILEGES + X + + + + ALTER DOMAIN + X + + + + ALTER EVENT TRIGGER + - + + + + ALTER EXTENSION + X + + + + ALTER FOREIGN DATA WRAPPER + X + + + + ALTER FOREIGN TABLE + X + + + + ALTER FUNCTION + X + + + + ALTER INDEX + X + + + + ALTER LANGUAGE + X + + + + ALTER LARGE OBJECT + - + + + + ALTER MATERIALIZED VIEW + X + + + + ALTER OPERATOR + X + + + + ALTER OPERATOR CLASS + X + + + + ALTER OPERATOR FAMILY + X + + + + ALTER POLICY + X + + + + ALTER PROCEDURE + X + + + + ALTER PUBLICATION + - + + + + ALTER ROLE + - + + + + ALTER ROUTINE + X + + + + ALTER RULER + X + + + + ALTER SCHEMA + X + + + + ALTER SEQUENCE + X + + + + ALTER SERVER + X + + + + ALTER STATISTICS + X + + + + ALTER SUBSCRIPTION + - + + + + ALTER SYSTEM + - + + + + ALTER TABLE + X + + + + ALTER TABLESPACE + - + + + + ALTER TEXT SEARCH CONFIGURATION + X + + + + ALTER TEXT SEARCH DICTIONARY + X + + + + ALTER TEXT SEARCH PARSER + X + + + + ALTER TEXT SEARCH TEMPLATE + X + + + + ALTER TRANSFORM + - + + + + ALTER TRIGGER + X + + + + ALTER TYPE + X + + + + ALTER USER MAPPING + X + + + + ALTER VIEW + X + + + + ANALYZE + - + + + + BEGIN + - + + + + CALL + - + + + + CHECKPOINT + - + + + + CLOSE + - + + + + CLOSE CURSOR + - + + + + CLOSE CURSOR ALL + - + + + + CLUSTER + - + + + + COMMENT + X + + + + COMMIT + - + + + + COMMIT PREPARED + - + + + + COPY + - + + + + COPY FROM + - + + + + CREATE ACCESS METHOD + X + + + + CREATE AGGREGATE + X + + + + CREATE CAST + X + + + + CREATE COLLATION + X + + + + CREATE CONSTRAINT + X + + + + CREATE CONVERSION + X + + + + CREATE DATABASE + - + + + + CREATE DOMAIN + X + + + + CREATE EVENT TRIGGER + - + + + + CREATE EXTENSION + X + + + + CREATE FOREIGN DATA WRAPPER + X + + + + CREATE FOREIGN TABLE + X + + + + CREATE FUNCTION + X + + + + CREATE INDEX + X + + + + CREATE LANGUAGE + X + + + + CREATE MATERIALIZED VIEW + X + + + + CREATE OPERATOR + X + + + + CREATE OPERATOR CLASS + X + + + + CREATE OPERATOR FAMILY + X + + + + CREATE POLICY + X + + + + CREATE PROCEDURE + X + + + + CREATE PUBLICATION + - + + + + CREATE ROLE + - + + + + CREATE RULE + X + + + + CREATE SCHEMA + X + + + + CREATE SEQUENCE + X + + + + CREATE SERVER + X + + + + CREATE STATISTICS + X + + + + CREATE SUBSCRIPTION + - + + + + CREATE TABLE + X + + + + CREATE TABLE AS + X + + + + CREATE TABLESPACE + - + + + + CREATE TEXT SEARCH CONFIGURATION + X + + + + CREATE TEXT SEARCH DICTIONARY + X + + + + CREATE TEXT SEARCH PARSER + X + + + + CREATE TEXT SEARCH TEMPLATE + X + + + + CREATE TRANSFORM + X + + + + CREATE TRIGGER + X + + + + CREATE TYPE + X + + + + CREATE USER MAPPING + X + + + + CREATE VIEW + X + + + + DEALLOCATE + - + + + + DEALLOCATE ALL + - + + + + DECLARE CURSOR + - + + + + DELETE + - + + + + DISCARD + - + + + + DISCARD ALL + X + + + + DISCARD PLANS + - + + + + DISCARD SEQUENCES + - + + + + DISCARD TEMP + - + + + + DO + - + + + + DROP ACCESS METHOD + X + + + + DROP AGGREGATE + X + + + + DROP CAST + X + + + + DROP COLLATION + X + + + + DROP CONSTRAINT + X + + + + DROP CONVERSION + X + + + + DROP DATABASE + - + + + + DROP DOMAIN + X + + + + DROP EVENT TRIGGER + - + + + + DROP EXTENSION + X + + + + DROP FOREIGN DATA WRAPPER + X + + + + DROP FOREIGN TABLE + X + + + + DROP FUNCTION + X + + + + DROP INDEX + X + + + + DROP LANGUAGE + X + + + + DROP MATERIALIZED VIEW + X + + + + DROP OPERATOR + X + + + + DROP OPERATOR CLASS + X + + + + DROP OPERATOR FAMILY + X + + + + DROP OWNED + - + + + + DROP POLICY + X + + + + DROP PROCEDURE + X + + + + DROP PUBLICATION + - + + + + DROP ROLE + - + + + + DROP ROUTINE + X + + + + DROP RULE + X + + + + DROP SCHEMA + X + + + + DROP SEQUENCE + X + + + + DROP SERVER + X + + + + DROP STATISTICS + X + + + + DROP SUBSCRIPTION + - + + + + DROP TABLE + X + + + + DROP TABLESPACE + - + + + + DROP TEXT SEARCH CONFIGURATION + X + + + + DROP TEXT SEARCH DICTIONARY + X + + + + DROP TEXT SEARCH PARSER + X + + + + DROP TEXT SEARCH TEMPLATE + X + + + + DROP TRANSFORM + X + + + + DROP TRIGGER + X + + + + DROP TYPE + X + + + + DROP USER MAPPING + X + + + + DROP VIEW + X + + + + EXECUTE + - + + + + EXPLAIN + - + + + + FETCH + - + + + + GRANT + X + + + + GRANT ROLE + - + + + + IMPORT FOREIGN SCHEMA + X + + + + INSERT + - + + + + LISTEN + - + + + + LOAD + - + + + + LOCK TABLE + - + + + + MERGE + - + + + + MOVE + - + + + + NOTIFY + - + + + + PREPARE + - + + + + PREPARE TRANSACTION + - + + + + REASSIGN OWNED + - + + + + REFRESH MATERIALIZED VIEW + X + + + + REINDEX + - + + + + RELEASE + - + + + + RESET + - + + + + REVOKE + X + + + + REVOKE ROLE + - + + + + ROLLBACK + - + + + + ROLLBACK PREPARED + - + + + + SAVEPOINT + - + + + + SECURITY LABEL + X + + + + SET + - + + + + SET CONSTRAINTS + - + + + + SHOW + - + + + + START TRANSACTION + - + + + + UNLISTEN + - + + + + UPDATE + - + + + + VACUUM + - + + +
+ + + + DDL Deparser + + The DDL deparser utility is invoked during the replication of DDLs. The DDL + deparser is capable of converting a DDL command into formatted JSON blob, with + the necessary information to reconstruct the DDL commands at the destination. The + benefit of using the deparser output compared to the original command string + includes: + + + + Every database object in the deparsed output is schema-qualified, so that + there are no ambiguities even in the face of search_path changes. + + + + + + The structured JSON and the formatted output makes it possible for + machine editing. This can be useful if the subscriber is on a different + PG version and has certain DDL syntax differences which need to be + resolved before apply. + + + + + + + + The DDL deparser exposes two SQL functions: + + + + ddl_deparse_to_json: given a CollectedCommand from event trigger, + returns a JSON representation of it. The command is expanded fully + so that there are no ambiguities even in the face of search_path + changes. + + + + + + + + ddl_deparse_expand_command: Expand JSON format DDL generated by + ddl_deparse_to_json to a plain DDL command. + + + + + + + + Conflicts -- 2.38.1