From b807f59828fbc02fea612e1cbc0066c6dfa3be9b Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Fri, 12 May 2017 08:57:01 -0400 Subject: Rework the options syntax for logical replication commands For CREATE/ALTER PUBLICATION/SUBSCRIPTION, use similar option style as other statements that use a WITH clause for options. Author: Petr Jelinek --- doc/src/sgml/logical-replication.sgml | 7 +- doc/src/sgml/ref/alter_publication.sgml | 39 ++--- doc/src/sgml/ref/alter_subscription.sgml | 71 +++++---- doc/src/sgml/ref/create_publication.sgml | 57 +++----- doc/src/sgml/ref/create_subscription.sgml | 236 +++++++++++++++--------------- 5 files changed, 203 insertions(+), 207 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index e87e3dcd36d..36c157c43f9 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -222,8 +222,9 @@ When creating a subscription, the replication slot already exists. In - that case, the subscription can be created using the NOCREATE - SLOT option to associate with the existing slot. + that case, the subscription can be created using + the create_slot = false option to associate with the + existing slot. @@ -231,7 +232,7 @@ When creating a subscription, the remote host is not reachable or in an unclear state. In that case, the subscription can be created using - the NOCONNECT option. The remote host will then not + the connect = false option. The remote host will then not be contacted at all. This is what pg_dump uses. The remote replication slot will then have to be created manually before the subscription can be activated. diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml index 05bd57d9cab..7b8f114f541 100644 --- a/doc/src/sgml/ref/alter_publication.sgml +++ b/doc/src/sgml/ref/alter_publication.sgml @@ -21,17 +21,10 @@ PostgreSQL documentation -ALTER PUBLICATION name WITH ( option [, ... ] ) - -where option can be: - - PUBLISH INSERT | NOPUBLISH INSERT - | PUBLISH UPDATE | NOPUBLISH UPDATE - | PUBLISH DELETE | NOPUBLISH DELETE - 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 SET ( publication_parameter [= value] [, ... ] ) ALTER PUBLICATION name OWNER TO { new_owner | CURRENT_USER | SESSION_USER } ALTER PUBLICATION name RENAME TO new_name @@ -44,8 +37,7 @@ ALTER PUBLICATION name RENAME TO . Properties not mentioned in the - command retain their previous settings. Database superusers can change any - of these settings for any role. + command retain their previous settings. @@ -80,29 +72,24 @@ ALTER PUBLICATION name RENAME TO - PUBLISH INSERT - NOPUBLISH INSERT - PUBLISH UPDATE - NOPUBLISH UPDATE - PUBLISH DELETE - NOPUBLISH DELETE + table_name - These clauses alter properties originally set by - . See there for more information. + Name of an existing table. If ONLY is specified before the + table name, only that table is affected. If ONLY is not + specified, the table and all its descendant tables (if any) are + affected. Optionally, * can be specified after the table + name to explicitly indicate that descendant tables are included. - table_name + SET ( publication_parameter [= value] [, ... ] ) - Name of an existing table. If ONLY is specified before the - table name, only that table is affected. If ONLY is not - specified, the table and all its descendant tables (if any) are - affected. Optionally, * can be specified after the table - name to explicitly indicate that descendant tables are included. + This clause alters publication parameters originally set by + . See there for more information. @@ -131,9 +118,9 @@ ALTER PUBLICATION name RENAME TO Examples - Change the publication to not publish inserts: + Change the publication to publish only deletes and updates: -ALTER PUBLICATION noinsert WITH (NOPUBLISH INSERT); +ALTER PUBLICATION noinsert SET (publish = 'update, delete'); diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml index 5dae4aebd63..6320de06edd 100644 --- a/doc/src/sgml/ref/alter_subscription.sgml +++ b/doc/src/sgml/ref/alter_subscription.sgml @@ -21,23 +21,12 @@ PostgreSQL documentation -ALTER SUBSCRIPTION name WITH ( suboption [, ... ] ) - -where suboption can be: - - SLOT NAME = slot_name - | SYNCHRONOUS_COMMIT = synchronous_commit - -ALTER SUBSCRIPTION name SET PUBLICATION publication_name [, ...] { REFRESH WITH ( puboption [, ... ] ) | NOREFRESH } -ALTER SUBSCRIPTION name REFRESH PUBLICATION [ WITH ( puboption [, ... ] ) ] - -where puboption can be: - - COPY DATA | NOCOPY DATA - ALTER SUBSCRIPTION name CONNECTION 'conninfo' +ALTER SUBSCRIPTION name SET PUBLICATION publication_name [, ...] { REFRESH [ WITH ( refresh_option value [, ... ] ) ] | SKIP REFRESH } +ALTER SUBSCRIPTION name REFRESH PUBLICATION [ WITH ( refresh_option value [, ... ] ) ] ALTER SUBSCRIPTION name ENABLE ALTER SUBSCRIPTION name DISABLE +ALTER SUBSCRIPTION name SET ( subscription_parameter [= value] [, ... ] ) ALTER SUBSCRIPTION name OWNER TO { new_owner | CURRENT_USER | SESSION_USER } ALTER SUBSCRIPTION name RENAME TO new_name @@ -73,11 +62,9 @@ ALTER SUBSCRIPTION name RENAME TO < CONNECTION 'conninfo' - SLOT NAME = slot_name - SYNCHRONOUS_COMMIT = synchronous_commit - These clauses alter properties originally set by + This clause alters the connection property originally set by . See there for more information. @@ -91,11 +78,17 @@ ALTER SUBSCRIPTION name RENAME TO < Changes list of subscribed publications. See for more information. + - When REFRESH is specified, this command will also - act like REFRESH PUBLICATION. When - NOREFRESH is specified, the comamnd will not try to - refresh table information. + When REFRESH is specified, this command will also act + like REFRESH + PUBLICATION. refresh_option specifies + additional options for the refresh operation, as described + under REFRESH PUBLICATION. When + SKIP REFRESH is specified, the command will not try + to refresh table information. Note that + either REFRESH or SKIP REFRESH + must be specified. @@ -104,16 +97,28 @@ ALTER SUBSCRIPTION name RENAME TO < REFRESH PUBLICATION - Fetch missing table information from publisher. This will start + Fetch missing table information from publisher. This will start replication of tables that were added to the subscribed-to publications since the last invocation of REFRESH PUBLICATION or since CREATE SUBSCRIPTION. + - The COPY DATA and NOCOPY DATA - options specify if the existing data in the publications that are being - subscribed to should be copied. COPY DATA is the - default. + refresh_option specifies additional options for the + refresh operation. The supported options are: + + + + copy_data (boolean) + + + Specifies whether the existing data in the publications that are + being subscribed to should be copied once the replication starts. + The default is true. + + + + @@ -138,6 +143,18 @@ ALTER SUBSCRIPTION name RENAME TO < + + SET ( subscription_parameter [= value] [, ... ] ) + + + This clause alters parameters originally set by + . See there for more + information. The allowed options are slot_name and + synchronous_commit + + + + new_owner @@ -165,7 +182,7 @@ ALTER SUBSCRIPTION name RENAME TO < Change the publication subscribed by a subscription to insert_only: -ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only; +ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only REFRESH; diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml index 521376ef4ba..48be4763747 100644 --- a/doc/src/sgml/ref/create_publication.sgml +++ b/doc/src/sgml/ref/create_publication.sgml @@ -24,13 +24,8 @@ PostgreSQL documentation CREATE PUBLICATION name [ FOR TABLE [ ONLY ] table_name [ * ] [, ...] | FOR ALL TABLES ] - [ WITH ( option [, ... ] ) ] + [ WITH ( publication_parameter [= value] [, ... ] ) ] -where option can be: - - PUBLISH INSERT | NOPUBLISH INSERT - | PUBLISH UPDATE | NOPUBLISH UPDATE - | PUBLISH DELETE | NOPUBLISH DELETE @@ -97,37 +92,29 @@ CREATE PUBLICATION name - PUBLISH INSERT - NOPUBLISH INSERT - - - These clauses determine whether the new publication will send - the INSERT operations to the subscribers. - PUBLISH INSERT is the default. - - - - - - PUBLISH UPDATE - NOPUBLISH UPDATE + WITH ( publication_parameter [= value] [, ... ] ) - These clauses determine whether the new publication will send - the UPDATE operations to the subscribers. - PUBLISH UPDATE is the default. - - - + This clause specifies optional parameters for a publication. The + following parameters are supported: + + + + publish (string) + + + This parameter determines which DML operations will be published by + the new publication to the subscribers. The value is + comma-separated list of operations. The allowed operations are + insert, update, and + delete. The default is to publish all actions, + and so the default value for this option is + 'insert, update, delete'. + + + + - - PUBLISH DELETE - NOPUBLISH DELETE - - - These clauses determine whether the new publication will send - the DELETE operations to the subscribers. - PUBLISH DELETE is the default. @@ -203,7 +190,7 @@ CREATE PUBLICATION alltables FOR ALL TABLES; operations in one table: CREATE PUBLICATION insert_only FOR TABLE mydata - WITH (NOPUBLISH UPDATE, NOPUBLISH DELETE); + WITH (publish = 'insert'); diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index 63824684031..f2da662499c 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -23,17 +23,8 @@ PostgreSQL documentation CREATE SUBSCRIPTION subscription_name CONNECTION 'conninfo' - PUBLICATION { publication_name [, ...] } - [ WITH ( option [, ... ] ) ] - -where option can be: - - | ENABLED | DISABLED - | CREATE SLOT | NOCREATE SLOT - | SLOT NAME = slot_name - | COPY DATA | NOCOPY DATA - | SYNCHRONOUS_COMMIT = synchronous_commit - | NOCONNECT + PUBLICATION publication_name [, ...] + [ WITH ( subscription_parameter [= value] [, ... ] ) ] @@ -59,7 +50,7 @@ CREATE SUBSCRIPTION subscription_name CREATE SUBSCRIPTION cannot be executed inside a - transaction block when CREATE SLOT is specified. + transaction block when the parameter create_slot is specified. @@ -97,116 +88,129 @@ CREATE SUBSCRIPTION subscription_namePUBLICATION publication_name - Name(s) of the publications on the publisher to subscribe to. - - - - - - ENABLED - DISABLED - - - Specifies whether the subscription should be actively replicating or - if it should be just setup but not started yet. Note that the - replication slot as described above is created in either case. - ENABLED is the default. - - - - - - CREATE SLOT - NOCREATE SLOT - - - Specifies whether the command should create the replication slot on the - publisher. CREATE SLOT is the default. - - - - - - SLOT NAME = slot_name - - - Name of the replication slot to use. The default behavior is to use - subscription_name for slot name. - - - - When SLOT NAME is set to - NONE, there will be no replication slot associated - with the subscription. This can be used if the replication slot will be - created later manually. Such subscriptions must also have both - ENABLED and CREATE SLOT set - to false. - - - - - - COPY DATA - NOCOPY DATA - - - Specifies if the existing data in the publications that are being - subscribed to should be copied once the replication starts. - COPY DATA is the default. + Names of the publications on the publisher to subscribe to. - SYNCHRONOUS_COMMIT = synchronous_commit + WITH ( subscription_parameter [= value] [, ... ] ) - The value of this parameter overrides the - setting. The default value is - off. - - - - It is safe to use off for logical replication: If the - subscriber loses transactions because of missing synchronization, the - data will be resent from the publisher. - - - - A different setting might be appropriate when doing synchronous logical - replication. The logical replication workers report the positions of - writes and flushes to the publisher, and when using synchronous - replication, the publisher will wait for the actual flush. This means - that setting SYNCHRONOUS_COMMIT for the subscriber - to off when the subscription is used for synchronous - replication might increase the latency for COMMIT on - the publisher. In this scenario, it can be advantageous to set - SYNCHRONOUS_COMMIT to local or - higher. - - - - - - NOCONNECT - - - Instructs CREATE SUBSCRIPTION to skip the initial - connection to the provider. This will change default values of other - options to DISABLED, - NOCREATE SLOT, and NOCOPY DATA. - - - It's not allowed to combine NOCONNECT and - ENABLED, CREATE SLOT, or - COPY DATA. - - - Since no connection is made when this option is specified, the tables - are not subscribed, so after you enable the subscription nothing will - be replicated. It is required to run - ALTER SUBSCRIPTION ... REFRESH PUBLICATION in order for - tables to be subscribed. + This clause specifies optional parameters for a subscription. The + following parameters are supported: + + + + copy_data (boolean) + + + Specifies whether the existing data in the publications that are + being subscribed to should be copied once the replication starts. + The default is true. + + + + + + create_slot (boolean) + + + Specifies whether the command should create the replication slot on + the publisher. The default is true. + + + + + + enabled (boolean) + + + Specifies whether the subscription should be actively replicating, + or whether it should be just setup but not started yet. The default + is true. + + + + + + slot_name (string) + + + Name of the replication slot to use. The default behavior is to + use the name of the subscription for the slot name. + + + + When slot_name is set to + NONE, there will be no replication slot + associated with the subscription. This can be used if the + replication slot will be created later manually. Such + subscriptions must also have both enabled and + create_slot set to false. + + + + + + synchronous_commit (enum) + + + The value of this parameter overrides the + setting. The default + value is off. + + + + It is safe to use off for logical replication: + If the subscriber loses transactions because of missing + synchronization, the data will be resent from the publisher. + + + + A different setting might be appropriate when doing synchronous + logical replication. The logical replication workers report the + positions of writes and flushes to the publisher, and when using + synchronous replication, the publisher will wait for the actual + flush. This means that setting + synchronous_commit for the subscriber to + off when the subscription is used for + synchronous replication might increase the latency for + COMMIT on the publisher. In this scenario, it + can be advantageous to set synchronous_commit + to local or higher. + + + + + + connect (boolean) + + + Specifies whether the CREATE SUBSCRIPTION + should connect to the publisher at all. Setting this to + false will change default values of + enabled, create_slot and + copy_data to false. + + + + It is not allowed to combine connect set to + false and enabled, + create_slot, or copy_data + set to true. + + + + Since no connection is made when this option is specified, the + tables are not subscribed, and so after you enable the subscription + nothing will be replicated. It is required to run + ALTER SUBSCRIPTION ... REFRESH PUBLICATION in order + for tables to be subscribed. + + + + @@ -246,7 +250,7 @@ CREATE SUBSCRIPTION mysub CREATE SUBSCRIPTION mysub CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' PUBLICATION insert_only - WITH (DISABLED); + WITH (enabled = false); -- cgit v1.2.3