From 3c129e1caf17c4c9d4df0bbd39b2a471d3f47fbe Mon Sep 17 00:00:00 2001 From: Vignesh C Date: Fri, 3 Sep 2021 17:46:08 +0530 Subject: [PATCH v43 4/4] Add documentation for the schema publication feature of logical replication The following schema publication documentation is added: * Create/alter publication syntax, with examples * pg_publication_namespace system table Author: Vignesh C Reviewed-by: Amit Kapila, Hou Zhijie, Greg Nancarrow, Masahiko Sawada, Peter Eisentraut, Tom Lane, Peter Smith, Ajin Cherian, Rahila Syed, Bharath Rupireddy Tested-by: Tang Haiying Discussion: https://www.postgresql.org/message-id/CALDaNm0OANxuJ6RXqwZsM1MSY4s19nuH3734j4a72etDwvBETQ%40mail.gmail.com --- doc/src/sgml/catalogs.sgml | 72 +++++++++++++++++++++- doc/src/sgml/ref/alter_publication.sgml | 77 +++++++++++++++++++----- doc/src/sgml/ref/create_publication.sgml | 67 ++++++++++++++++++--- 3 files changed, 190 insertions(+), 26 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index fd6910ddbe..7bf132f8cd 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -240,6 +240,11 @@ publications for logical replication + + pg_publication_namespace + schema to publication mapping + + pg_publication_rel relation to publication mapping @@ -6176,6 +6181,67 @@ SCRAM-SHA-256$<iteration count>:&l + + <structname>pg_publication_namespace</structname> + + + pg_publication_namespace + + + + The catalog pg_publication_namespace contains the + mapping between schemas and publications in the database. This is a + many-to-many mapping. + + + + <structname>pg_publication_namespace</structname> Columns + + + + + Column Type + + + Description + + + + + + + + oid oid + + + Row identifier + + + + + + pnpubid oid + (references pg_publication.oid) + + + Reference to publication + + + + + + pnnspid oid + (references pg_namespace.oid) + + + Reference to schema + + + + +
+ + <structname>pg_publication_rel</structname> @@ -11278,9 +11344,9 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx information about the mapping between publications and the tables they contain. Unlike the underlying catalog pg_publication_rel, - this view expands - publications defined as FOR ALL TABLES, so for such - publications there will be a row for each eligible table. + this view expands publications defined as FOR ALL TABLES + and FOR ALL TABLES IN SCHEMA, so for such publications + there will be a row for each eligible table. diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml index faa114b2c6..2f38a69cf8 100644 --- a/doc/src/sgml/ref/alter_publication.sgml +++ b/doc/src/sgml/ref/alter_publication.sgml @@ -21,12 +21,17 @@ PostgreSQL documentation -ALTER PUBLICATION name ADD TABLE [ ONLY ] table_name [ * ] [, ...] -ALTER PUBLICATION name SET TABLE [ ONLY ] table_name [ * ] [, ...] -ALTER PUBLICATION name DROP TABLE [ ONLY ] table_name [ * ] [, ...] +ALTER PUBLICATION name ADD publication_object [, ...] +ALTER PUBLICATION name SET publication_object [, ...] +ALTER PUBLICATION name DROP publication_object [, ...] ALTER PUBLICATION name SET ( publication_parameter [= value] [, ... ] ) ALTER PUBLICATION name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ALTER PUBLICATION name RENAME TO new_name + +where publication_object is one of: + + TABLE [ ONLY ] table_name [ * ] [, ... ] + ALL TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ] @@ -39,14 +44,15 @@ ALTER PUBLICATION name RENAME TO - The first three variants change which tables are part of the publication. - The SET TABLE clause will replace the list of tables in - the publication with the specified one. The ADD TABLE - and DROP TABLE clauses will add and remove one or more - tables from the publication. Note that adding tables to a publication that - is already subscribed to will require a ALTER SUBSCRIPTION - ... REFRESH PUBLICATION action on the subscribing side in order - to become effective. + The first three variants change which tables/schemas are part of the + publication. The SET clause will replace the list of + tables/schemas in the publication with the specified list; the existing + tables/schemas that were present in the publication will be removed. The + ADD and DROP clauses will add and + remove one or more tables/schemas from the publication. Note that adding + tables/schemas to a publication that is already subscribed to will require a + ALTER SUBSCRIPTION ... REFRESH PUBLICATION action on the + subscribing side in order to become effective. @@ -63,11 +69,22 @@ ALTER PUBLICATION name RENAME TO You must own the publication to use ALTER PUBLICATION. Adding a table to a publication additionally requires owning that table. - To alter the owner, you must also be a direct or indirect member of the new - owning role. The new owner must have CREATE privilege on - the database. Also, the new owner of a FOR ALL TABLES - publication must be a superuser. However, a superuser can change the - ownership of a publication regardless of these restrictions. + The ADD ALL TABLES IN SCHEMA and + SET ALL TABLES IN SCHEMA to a publication requires the + invoking user to be a superuser. To alter the owner, you must also be a + direct or indirect member of the new owning role. The new owner must have + CREATE privilege on the database. Also, the new owner + of a FOR ALL TABLES publication must be a superuser. + However, a superuser can change the ownership of a publication regardless + of these restrictions. + + + + Adding/Setting a table that is part of schema specified in + ALL TABLES IN SCHEMA, adding/setting a schema to a + publication that already has a table that is part of specified schema or + adding/setting a table to a publication that already has a table's schema as + part of specified schema is not supported. @@ -97,6 +114,15 @@ ALTER PUBLICATION name RENAME TO + + schema_name + + + Name of an existing schema. + + + + SET ( publication_parameter [= value] [, ... ] ) @@ -142,6 +168,25 @@ ALTER PUBLICATION noinsert SET (publish = 'update, delete'); ALTER PUBLICATION mypublication ADD TABLE users, departments; + + + Add schemas marketing and + sales to the publication + sales_publication: + +ALTER PUBLICATION sales_publication ADD ALL TABLES IN SCHEMA marketing, sales; + + + + + Add tables users, + departments and schema + production to the publication + production_publication: + +ALTER PUBLICATION production_publication ADD TABLE users, departments, ALL TABLES IN SCHEMA production; + + diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml index ff82fbca55..2c6bdfbac0 100644 --- a/doc/src/sgml/ref/create_publication.sgml +++ b/doc/src/sgml/ref/create_publication.sgml @@ -22,9 +22,14 @@ PostgreSQL documentation CREATE PUBLICATION name - [ FOR TABLE [ ONLY ] table_name [ * ] [, ...] - | FOR ALL TABLES ] + [ FOR ALL TABLES + | FOR publication_object [, ... ] ] [ WITH ( publication_parameter [= value] [, ... ] ) ] + +where publication_object is one of: + + TABLE [ ONLY ] table_name [ * ] [, ... ] + ALL TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ] @@ -86,6 +91,11 @@ CREATE PUBLICATION name partition are also published via publications that its ancestors are part of. + + + Specifying a table that is part of a schema specified by + FOR ALL TABLES IN SCHEMA is not supported. + @@ -99,6 +109,28 @@ CREATE PUBLICATION name + + FOR ALL TABLES IN SCHEMA + + + Marks the publication as one that replicates changes for all tables in + the specified list of schemas, including tables created in the future. + + + + Specifying a schema along with a table which belongs to the specified + schema using FOR TABLE is not supported. + + + + Only persistent base tables and partitioned tables present in the schema + will be included as part of the publication. Temporary tables, unlogged + tables, foreign tables, materialized views, and regular views from the + schema will not be part of the publication. + + + + WITH ( publication_parameter [= value] [, ... ] ) @@ -153,9 +185,10 @@ CREATE PUBLICATION name Notes - If neither FOR TABLE nor FOR ALL - TABLES is specified, then the publication starts out with an - empty set of tables. That is useful if tables are to be added later. + If FOR TABLE, FOR ALL TABLES or + FOR ALL TABLES IN SCHEMA is not specified, then the + publication starts out with an empty set of tables. That is useful if + tables or schemas are to be added later. @@ -171,8 +204,9 @@ CREATE PUBLICATION name To add a table to a publication, the invoking user must have ownership - rights on the table. The FOR ALL TABLES clause requires - the invoking user to be a superuser. + rights on the table. The FOR ALL TABLES and + FOR ALL TABLES IN SCHEMA clauses require the invoking + user to be a superuser. @@ -222,6 +256,25 @@ CREATE PUBLICATION alltables FOR ALL TABLES; CREATE PUBLICATION insert_only FOR TABLE mydata WITH (publish = 'insert'); + + + + + Create a publication that publishes all changes for tables + users, departments and + that publishes all changes for all the tables present in the schema + production: + +CREATE PUBLICATION production_publication FOR TABLE users, departments, ALL TABLES IN SCHEMA production; + + + + + Create a publication that publishes all changes for all the tables present in + the schemas marketing and + sales: + +CREATE PUBLICATION sales_publication FOR ALL TABLES IN SCHEMA marketing, sales; -- 2.30.2