database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-27 12:41:57 +03:00
Code Activity

Rework the options syntax for logical replication commands

Browse Source 
For CREATE/ALTER PUBLICATION/SUBSCRIPTION, use similar option style as
other statements that use a WITH clause for options.

Author: Petr Jelinek <petr.jelinek@2ndquadrant.com>
This commit is contained in:
Peter Eisentraut
2017-05-12 08:57:01 -04:00
parent 734cb4c2e7
commit b807f59828
24 changed files with 352 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
doc/src/sgml/logical-replication.sgml
View File

@ -222,8 +222,9 @@
<listitem>
<para>
When creating a subscription, the replication slot already exists. In
that case, the subscription can be created using the <literal>NOCREATE
SLOT</literal> option to associate with the existing slot.
that case, the subscription can be created using
the <literal>create_slot = false</literal> option to associate with the
existing slot.
</para>
</listitem>
@ -231,7 +232,7 @@
<para>
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 <literal>NOCONNECT</literal> option. The remote host will then not
the <literal>connect = false</literal> option. The remote host will then not
be contacted at all. This is what <application>pg_dump</application>
uses. The remote replication slot will then have to be created
manually before the subscription can be activated.

41
doc/src/sgml/ref/alter_publication.sgml
View File

@ -21,17 +21,10 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> WITH ( <replaceable class="PARAMETER">option</replaceable> [, ... ] )
<phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>
PUBLISH INSERT | NOPUBLISH INSERT
| PUBLISH UPDATE | NOPUBLISH UPDATE
| PUBLISH DELETE | NOPUBLISH DELETE
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> ADD TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...]
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> SET TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...]
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> DROP TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...]
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER }
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
</synopsis>
@ -44,8 +37,7 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
The first variant of this command listed in the synopsis can change
all of the publication properties specified in
<xref linkend="sql-createpublication">. 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.
</para>
<para>
@ -79,21 +71,6 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PUBLISH INSERT</literal></term>
<term><literal>NOPUBLISH INSERT</literal></term>
<term><literal>PUBLISH UPDATE</literal></term>
<term><literal>NOPUBLISH UPDATE</literal></term>
<term><literal>PUBLISH DELETE</literal></term>
<term><literal>NOPUBLISH DELETE</literal></term>
<listitem>
<para>
These clauses alter properties originally set by
<xref linkend="SQL-CREATEPUBLICATION">. See there for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">table_name</replaceable></term>
<listitem>
@ -107,6 +84,16 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
This clause alters publication parameters originally set by
<xref linkend="SQL-CREATEPUBLICATION">. See there for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">new_owner</replaceable></term>
<listitem>
@ -131,9 +118,9 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
<title>Examples</title>
<para>
Change the publication to not publish inserts:
Change the publication to publish only deletes and updates:
<programlisting>
ALTER PUBLICATION noinsert WITH (NOPUBLISH INSERT);
ALTER PUBLICATION noinsert SET (publish = 'update, delete');
</programlisting>
</para>

71
doc/src/sgml/ref/alter_subscription.sgml
View File

@ -21,23 +21,12 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> WITH ( <replaceable class="PARAMETER">suboption</replaceable> [, ... ] )
<phrase>where <replaceable class="PARAMETER">suboption</replaceable> can be:</phrase>
SLOT NAME = <replaceable class="PARAMETER">slot_name</replaceable>
| SYNCHRONOUS_COMMIT = <replaceable class="PARAMETER">synchronous_commit</replaceable>
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET PUBLICATION <replaceable class="PARAMETER">publication_name</replaceable> [, ...] { REFRESH WITH ( <replaceable class="PARAMETER">puboption</replaceable> [, ... ] ) | NOREFRESH }
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> REFRESH PUBLICATION [ WITH ( <replaceable class="PARAMETER">puboption</replaceable> [, ... ] ) ]
<phrase>where <replaceable class="PARAMETER">puboption</replaceable> can be:</phrase>
COPY DATA | NOCOPY DATA
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> CONNECTION '<replaceable>conninfo</replaceable>'
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET PUBLICATION <replaceable class="PARAMETER">publication_name</replaceable> [, ...] { REFRESH [ WITH ( <replaceable class="PARAMETER">refresh_option</replaceable> <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ] | SKIP REFRESH }
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> REFRESH PUBLICATION [ WITH ( <replaceable class="PARAMETER">refresh_option</replaceable> <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ]
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> ENABLE
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> DISABLE
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER }
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
</synopsis>
@ -73,11 +62,9 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
<varlistentry>
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
<term><literal>SLOT NAME = <replaceable class="parameter">slot_name</replaceable></literal></term>
<term><literal>SYNCHRONOUS_COMMIT = <replaceable class="PARAMETER">synchronous_commit</replaceable></literal></term>
<listitem>
<para>
These clauses alter properties originally set by
This clause alters the connection property originally set by
<xref linkend="SQL-CREATESUBSCRIPTION">. See there for more
information.
</para>
@ -91,11 +78,17 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
Changes list of subscribed publications. See
<xref linkend="SQL-CREATESUBSCRIPTION"> for more information.
</para>
<para>
When <literal>REFRESH</literal> is specified, this command will also
act like <literal>REFRESH PUBLICATION</literal>. When
<literal>NOREFRESH</literal> is specified, the comamnd will not try to
refresh table information.
When <literal>REFRESH</literal> is specified, this command will also act
like <literal>REFRESH
PUBLICATION</literal>. <literal>refresh_option</literal> specifies
additional options for the refresh operation, as described
under <literal>REFRESH PUBLICATION</literal>. When
<literal>SKIP REFRESH</literal> is specified, the command will not try
to refresh table information. Note that
either <literal>REFRESH</literal> or <literal>SKIP REFRESH</literal>
must be specified.
</para>
</listitem>
</varlistentry>
@ -104,16 +97,28 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
<term><literal>REFRESH PUBLICATION</literal></term>
<listitem>
<para>
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 <command>REFRESH PUBLICATION</command> or
since <command>CREATE SUBSCRIPTION</command>.
</para>
<para>
The <literal>COPY DATA</literal> and <literal>NOCOPY DATA</literal>
options specify if the existing data in the publications that are being
subscribed to should be copied. <literal>COPY DATA</literal> is the
default.
<literal>refresh_option</literal> specifies additional options for the
refresh operation. The supported options are:
<variablelist>
<varlistentry>
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the existing data in the publications that are
being subscribed to should be copied once the replication starts.
The default is <literal>true</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
@ -138,6 +143,18 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SET ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
This clause alters parameters originally set by
<xref linkend="SQL-CREATESUBSCRIPTION">. See there for more
information. The allowed options are <literal>slot_name</literal> and
<literal>synchronous_commit</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">new_owner</replaceable></term>
<listitem>
@ -165,7 +182,7 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
Change the publication subscribed by a subscription to
<literal>insert_only</literal>:
<programlisting>
ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only;
ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only REFRESH;
</programlisting>
</para>

55
doc/src/sgml/ref/create_publication.sgml
View File

@ -24,13 +24,8 @@ PostgreSQL documentation
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
[ FOR TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ...]
| FOR ALL TABLES ]
[ WITH ( <replaceable class="parameter">option</replaceable> [, ... ] ) ]
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
<phrase>where <replaceable class="parameter">option</replaceable> can be:</phrase>
PUBLISH INSERT | NOPUBLISH INSERT
| PUBLISH UPDATE | NOPUBLISH UPDATE
| PUBLISH DELETE | NOPUBLISH DELETE
</synopsis>
</refsynopsisdiv>
@ -97,37 +92,29 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
</varlistentry>
<varlistentry>
<term><literal>PUBLISH INSERT</literal></term>
<term><literal>NOPUBLISH INSERT</literal></term>
<term><literal>WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
These clauses determine whether the new publication will send
the <command>INSERT</command> operations to the subscribers.
<literal>PUBLISH INSERT</literal> is the default.
</para>
</listitem>
</varlistentry>
This clause specifies optional parameters for a publication. The
following parameters are supported:
<varlistentry>
<term><literal>PUBLISH UPDATE</literal></term>
<term><literal>NOPUBLISH UPDATE</literal></term>
<listitem>
<para>
These clauses determine whether the new publication will send
the <command>UPDATE</command> operations to the subscribers.
<literal>PUBLISH UPDATE</literal> is the default.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term><literal>publish</literal> (<type>string</type>)</term>
<listitem>
<para>
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
<literal>insert</literal>, <literal>update</literal>, and
<literal>delete</literal>. The default is to publish all actions,
and so the default value for this option is
<literal>'insert, update, delete'</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<varlistentry>
<term><literal>PUBLISH DELETE</literal></term>
<term><literal>NOPUBLISH DELETE</literal></term>
<listitem>
<para>
These clauses determine whether the new publication will send
the <command>DELETE</command> operations to the subscribers.
<literal>PUBLISH DELETE</literal> is the default.
</para>
</listitem>
</varlistentry>
@ -203,7 +190,7 @@ CREATE PUBLICATION alltables FOR ALL TABLES;
operations in one table:
<programlisting>
CREATE PUBLICATION insert_only FOR TABLE mydata
WITH (NOPUBLISH UPDATE, NOPUBLISH DELETE);
WITH (publish = 'insert');
</programlisting>
</para>
</refsect1>

220
doc/src/sgml/ref/create_subscription.sgml
View File

@ -23,17 +23,8 @@ PostgreSQL documentation
<synopsis>
CREATE SUBSCRIPTION <replaceable class="PARAMETER">subscription_name</replaceable>
CONNECTION '<replaceable class="PARAMETER">conninfo</replaceable>'
PUBLICATION { <replaceable class="PARAMETER">publication_name</replaceable> [, ...] }
[ WITH ( <replaceable class="PARAMETER">option</replaceable> [, ... ] ) ]
<phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>
| ENABLED | DISABLED
| CREATE SLOT | NOCREATE SLOT
| SLOT NAME = <replaceable class="PARAMETER">slot_name</replaceable>
| COPY DATA | NOCOPY DATA
| SYNCHRONOUS_COMMIT = <replaceable class="PARAMETER">synchronous_commit</replaceable>
| NOCONNECT
PUBLICATION <replaceable class="PARAMETER">publication_name</replaceable> [, ...]
[ WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
</synopsis>
</refsynopsisdiv>
@ -59,7 +50,7 @@ CREATE SUBSCRIPTION <replaceable class="PARAMETER">subscription_name</replaceabl
<para>
<command>CREATE SUBSCRIPTION</command> cannot be executed inside a
transaction block when <literal>CREATE SLOT</literal> is specified.
transaction block when the parameter <literal>create_slot</literal> is specified.
</para>
<para>
@ -97,116 +88,129 @@ CREATE SUBSCRIPTION <replaceable class="PARAMETER">subscription_name</replaceabl
<term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
<listitem>
<para>
Name(s) of the publications on the publisher to subscribe to.
Names of the publications on the publisher to subscribe to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENABLED</literal></term>
<term><literal>DISABLED</literal></term>
<term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
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.
<literal>ENABLED</literal> is the default.
</para>
</listitem>
</varlistentry>
This clause specifies optional parameters for a subscription. The
following parameters are supported:
<varlistentry>
<term><literal>CREATE SLOT</literal></term>
<term><literal>NOCREATE SLOT</literal></term>
<listitem>
<para>
Specifies whether the command should create the replication slot on the
publisher. <literal>CREATE SLOT</literal> is the default.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the existing data in the publications that are
being subscribed to should be copied once the replication starts.
The default is <literal>true</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SLOT NAME = <replaceable class="parameter">slot_name</replaceable></literal></term>
<listitem>
<para>
Name of the replication slot to use. The default behavior is to use
<literal>subscription_name</> for slot name.
</para>
<varlistentry>
<term><literal>create_slot</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the command should create the replication slot on
the publisher. The default is <literal>true</literal>.
</para>
</listitem>
</varlistentry>
<para>
When <literal>SLOT NAME</literal> is set to
<literal>NONE</literal>, 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
<literal>ENABLED</literal> and <literal>CREATE SLOT</literal> set
to <literal>false</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>enabled</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the subscription should be actively replicating,
or whether it should be just setup but not started yet. The default
is <literal>true</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>COPY DATA</literal></term>
<term><literal>NOCOPY DATA</literal></term>
<listitem>
<para>
Specifies if the existing data in the publications that are being
subscribed to should be copied once the replication starts.
<literal>COPY DATA</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>slot_name</literal> (<type>string</type>)</term>
<listitem>
<para>
Name of the replication slot to use. The default behavior is to
use the name of the subscription for the slot name.
</para>
<varlistentry>
<term><literal>SYNCHRONOUS_COMMIT = <replaceable class="PARAMETER">synchronous_commit</replaceable></literal></term>
<listitem>
<para>
The value of this parameter overrides the
<xref linkend="guc-synchronous-commit"> setting. The default value is
<literal>off</literal>.
</para>
<para>
When <literal>slot_name</literal> is set to
<literal>NONE</literal>, 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 <literal>enabled</literal> and
<literal>create_slot</literal> set to <literal>false</literal>.
</para>
</listitem>
</varlistentry>
<para>
It is safe to use <literal>off</literal> for logical replication: If the
subscriber loses transactions because of missing synchronization, the
data will be resent from the publisher.
</para>
<varlistentry>
<term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
<listitem>
<para>
The value of this parameter overrides the
<xref linkend="guc-synchronous-commit"> setting. The default
value is <literal>off</literal>.
</para>
<para>
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 <literal>SYNCHRONOUS_COMMIT</literal> for the subscriber
to <literal>off</literal> when the subscription is used for synchronous
replication might increase the latency for <command>COMMIT</command> on
the publisher. In this scenario, it can be advantageous to set
<literal>SYNCHRONOUS_COMMIT</literal> to <literal>local</literal> or
higher.
</para>
</listitem>
</varlistentry>
<para>
It is safe to use <literal>off</literal> for logical replication:
If the subscriber loses transactions because of missing
synchronization, the data will be resent from the publisher.
</para>
<varlistentry>
<term><literal>NOCONNECT</literal></term>
<listitem>
<para>
Instructs <command>CREATE SUBSCRIPTION</command> to skip the initial
connection to the provider. This will change default values of other
options to <literal>DISABLED</literal>,
<literal>NOCREATE SLOT</literal>, and <literal>NOCOPY DATA</literal>.
</para>
<para>
It's not allowed to combine <literal>NOCONNECT</literal> and
<literal>ENABLED</literal>, <literal>CREATE SLOT</literal>, or
<literal>COPY DATA</literal>.
</para>
<para>
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
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</> in order for
tables to be subscribed.
<para>
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
<literal>synchronous_commit</literal> for the subscriber to
<literal>off</literal> when the subscription is used for
synchronous replication might increase the latency for
<command>COMMIT</command> on the publisher. In this scenario, it
can be advantageous to set <literal>synchronous_commit</literal>
to <literal>local</literal> or higher.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the <command>CREATE SUBSCRIPTION</command>
should connect to the publisher at all. Setting this to
<literal>false</literal> will change default values of
<literal>enabled</literal>, <literal>create_slot</literal> and
<literal>copy_data</literal> to <literal>false</literal>.
</para>
<para>
It is not allowed to combine <literal>connect</literal> set to
<literal>false</literal> and <literal>enabled</literal>,
<literal>create_slot</literal>, or <literal>copy_data</literal>
set to <literal>true</literal>.
</para>
<para>
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
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</> in order
for tables to be subscribed.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
@ -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);
</programlisting>
</para>
</refsect1>