Skip to content

Commit b807f59

Browse files
peterepetere
committed
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 <petr.jelinek@2ndquadrant.com>
1 parent 734cb4c commit b807f59

24 files changed

+358
-416
lines changed

‎doc/src/sgml/logical-replication.sgml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -222,16 +222,17 @@
222222
<listitem>
223223
<para>
224224
When creating a subscription, the replication slot already exists. In
225-
that case, the subscription can be created using the <literal>NOCREATE
226-
SLOT</literal> option to associate with the existing slot.
225+
that case, the subscription can be created using
226+
the <literal>create_slot = false</literal> option to associate with the
227+
existing slot.
227228
</para>
228229
</listitem>
229230

230231
<listitem>
231232
<para>
232233
When creating a subscription, the remote host is not reachable or in an
233234
unclear state. In that case, the subscription can be created using
234-
the <literal>NOCONNECT</literal> option. The remote host will then not
235+
the <literal>connect = false</literal> option. The remote host will then not
235236
be contacted at all. This is what <application>pg_dump</application>
236237
uses. The remote replication slot will then have to be created
237238
manually before the subscription can be activated.

‎doc/src/sgml/ref/alter_publication.sgml‎

Lines changed: 13 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,10 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> WITH ( <replaceable class="PARAMETER">option</replaceable> [, ... ] )
25-
26-
<phrase>where <replaceable class="PARAMETER">option</replaceable> can be:</phrase>
27-
28-
PUBLISH INSERT | NOPUBLISH INSERT
29-
| PUBLISH UPDATE | NOPUBLISH UPDATE
30-
| PUBLISH DELETE | NOPUBLISH DELETE
31-
3224
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> ADD TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...]
3325
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> SET TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...]
3426
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> DROP TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...]
27+
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
3528
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER }
3629
ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
3730
</synopsis>
@@ -44,8 +37,7 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
4437
The first variant of this command listed in the synopsis can change
4538
all of the publication properties specified in
4639
<xref linkend="sql-createpublication">. Properties not mentioned in the
47-
command retain their previous settings. Database superusers can change any
48-
of these settings for any role.
40+
command retain their previous settings.
4941
</para>
5042

5143
<para>
@@ -80,29 +72,24 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
8072
</varlistentry>
8173

8274
<varlistentry>
83-
<term><literal>PUBLISH INSERT</literal></term>
84-
<term><literal>NOPUBLISH INSERT</literal></term>
85-
<term><literal>PUBLISH UPDATE</literal></term>
86-
<term><literal>NOPUBLISH UPDATE</literal></term>
87-
<term><literal>PUBLISH DELETE</literal></term>
88-
<term><literal>NOPUBLISH DELETE</literal></term>
75+
<term><replaceable class="parameter">table_name</replaceable></term>
8976
<listitem>
9077
<para>
91-
These clauses alter properties originally set by
92-
<xref linkend="SQL-CREATEPUBLICATION">. See there for more information.
78+
Name of an existing table. If <literal>ONLY</> is specified before the
79+
table name, only that table is affected. If <literal>ONLY</> is not
80+
specified, the table and all its descendant tables (if any) are
81+
affected. Optionally, <literal>*</> can be specified after the table
82+
name to explicitly indicate that descendant tables are included.
9383
</para>
9484
</listitem>
9585
</varlistentry>
9686

9787
<varlistentry>
98-
<term><replaceable class="parameter">table_name</replaceable></term>
88+
<term><literal>SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
9989
<listitem>
10090
<para>
101-
Name of an existing table. If <literal>ONLY</> is specified before the
102-
table name, only that table is affected. If <literal>ONLY</> is not
103-
specified, the table and all its descendant tables (if any) are
104-
affected. Optionally, <literal>*</> can be specified after the table
105-
name to explicitly indicate that descendant tables are included.
91+
This clause alters publication parameters originally set by
92+
<xref linkend="SQL-CREATEPUBLICATION">. See there for more information.
10693
</para>
10794
</listitem>
10895
</varlistentry>
@@ -131,9 +118,9 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
131118
<title>Examples</title>
132119

133120
<para>
134-
Change the publication to not publish inserts:
121+
Change the publication to publish only deletes and updates:
135122
<programlisting>
136-
ALTER PUBLICATION noinsert WITH (NOPUBLISH INSERT);
123+
ALTER PUBLICATION noinsert SET (publish = 'update, delete');
137124
</programlisting>
138125
</para>
139126

‎doc/src/sgml/ref/alter_subscription.sgml‎

Lines changed: 44 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -21,23 +21,12 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> WITH ( <replaceable class="PARAMETER">suboption</replaceable> [, ... ] )
25-
26-
<phrase>where <replaceable class="PARAMETER">suboption</replaceable> can be:</phrase>
27-
28-
SLOT NAME = <replaceable class="PARAMETER">slot_name</replaceable>
29-
| SYNCHRONOUS_COMMIT = <replaceable class="PARAMETER">synchronous_commit</replaceable>
30-
31-
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET PUBLICATION <replaceable class="PARAMETER">publication_name</replaceable> [, ...] { REFRESH WITH ( <replaceable class="PARAMETER">puboption</replaceable> [, ... ] ) | NOREFRESH }
32-
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> REFRESH PUBLICATION [ WITH ( <replaceable class="PARAMETER">puboption</replaceable> [, ... ] ) ]
33-
34-
<phrase>where <replaceable class="PARAMETER">puboption</replaceable> can be:</phrase>
35-
36-
COPY DATA | NOCOPY DATA
37-
3824
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> CONNECTION '<replaceable>conninfo</replaceable>'
25+
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 }
26+
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> REFRESH PUBLICATION [ WITH ( <replaceable class="PARAMETER">refresh_option</replaceable> <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ]
3927
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> ENABLE
4028
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> DISABLE
29+
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
4130
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER }
4231
ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
4332
</synopsis>
@@ -73,11 +62,9 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
7362

7463
<varlistentry>
7564
<term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
76-
<term><literal>SLOT NAME = <replaceable class="parameter">slot_name</replaceable></literal></term>
77-
<term><literal>SYNCHRONOUS_COMMIT = <replaceable class="PARAMETER">synchronous_commit</replaceable></literal></term>
7865
<listitem>
7966
<para>
80-
These clauses alter properties originally set by
67+
This clause alters the connection property originally set by
8168
<xref linkend="SQL-CREATESUBSCRIPTION">. See there for more
8269
information.
8370
</para>
@@ -91,11 +78,17 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
9178
Changes list of subscribed publications. See
9279
<xref linkend="SQL-CREATESUBSCRIPTION"> for more information.
9380
</para>
81+
9482
<para>
95-
When <literal>REFRESH</literal> is specified, this command will also
96-
act like <literal>REFRESH PUBLICATION</literal>. When
97-
<literal>NOREFRESH</literal> is specified, the comamnd will not try to
98-
refresh table information.
83+
When <literal>REFRESH</literal> is specified, this command will also act
84+
like <literal>REFRESH
85+
PUBLICATION</literal>. <literal>refresh_option</literal> specifies
86+
additional options for the refresh operation, as described
87+
under <literal>REFRESH PUBLICATION</literal>. When
88+
<literal>SKIP REFRESH</literal> is specified, the command will not try
89+
to refresh table information. Note that
90+
either <literal>REFRESH</literal> or <literal>SKIP REFRESH</literal>
91+
must be specified.
9992
</para>
10093
</listitem>
10194
</varlistentry>
@@ -104,16 +97,28 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
10497
<term><literal>REFRESH PUBLICATION</literal></term>
10598
<listitem>
10699
<para>
107-
Fetch missing table information from publisher. This will start
100+
Fetch missing table information from publisher. This will start
108101
replication of tables that were added to the subscribed-to publications
109102
since the last invocation of <command>REFRESH PUBLICATION</command> or
110103
since <command>CREATE SUBSCRIPTION</command>.
111104
</para>
105+
112106
<para>
113-
The <literal>COPY DATA</literal> and <literal>NOCOPY DATA</literal>
114-
options specify if the existing data in the publications that are being
115-
subscribed to should be copied. <literal>COPY DATA</literal> is the
116-
default.
107+
<literal>refresh_option</literal> specifies additional options for the
108+
refresh operation. The supported options are:
109+
110+
<variablelist>
111+
<varlistentry>
112+
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
113+
<listitem>
114+
<para>
115+
Specifies whether the existing data in the publications that are
116+
being subscribed to should be copied once the replication starts.
117+
The default is <literal>true</literal>.
118+
</para>
119+
</listitem>
120+
</varlistentry>
121+
</variablelist>
117122
</para>
118123
</listitem>
119124
</varlistentry>
@@ -138,6 +143,18 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
138143
</listitem>
139144
</varlistentry>
140145

146+
<varlistentry>
147+
<term><literal>SET ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
148+
<listitem>
149+
<para>
150+
This clause alters parameters originally set by
151+
<xref linkend="SQL-CREATESUBSCRIPTION">. See there for more
152+
information. The allowed options are <literal>slot_name</literal> and
153+
<literal>synchronous_commit</literal>
154+
</para>
155+
</listitem>
156+
</varlistentry>
157+
141158
<varlistentry>
142159
<term><replaceable class="parameter">new_owner</replaceable></term>
143160
<listitem>
@@ -165,7 +182,7 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
165182
Change the publication subscribed by a subscription to
166183
<literal>insert_only</literal>:
167184
<programlisting>
168-
ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only;
185+
ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only REFRESH;
169186
</programlisting>
170187
</para>
171188

‎doc/src/sgml/ref/create_publication.sgml‎

Lines changed: 22 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,8 @@ PostgreSQL documentation
2424
CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
2525
[ FOR TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ...]
2626
| FOR ALL TABLES ]
27-
[ WITH ( <replaceable class="parameter">option</replaceable> [, ... ] ) ]
27+
[ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
2828

29-
<phrase>where <replaceable class="parameter">option</replaceable> can be:</phrase>
30-
31-
PUBLISH INSERT | NOPUBLISH INSERT
32-
| PUBLISH UPDATE | NOPUBLISH UPDATE
33-
| PUBLISH DELETE | NOPUBLISH DELETE
3429
</synopsis>
3530
</refsynopsisdiv>
3631

@@ -97,37 +92,29 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
9792
</varlistentry>
9893

9994
<varlistentry>
100-
<term><literal>PUBLISH INSERT</literal></term>
101-
<term><literal>NOPUBLISH INSERT</literal></term>
102-
<listitem>
103-
<para>
104-
These clauses determine whether the new publication will send
105-
the <command>INSERT</command> operations to the subscribers.
106-
<literal>PUBLISH INSERT</literal> is the default.
107-
</para>
108-
</listitem>
109-
</varlistentry>
110-
111-
<varlistentry>
112-
<term><literal>PUBLISH UPDATE</literal></term>
113-
<term><literal>NOPUBLISH UPDATE</literal></term>
95+
<term><literal>WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
11496
<listitem>
11597
<para>
116-
These clauses determine whether the new publication will send
117-
the <command>UPDATE</command> operations to the subscribers.
118-
<literal>PUBLISH UPDATE</literal> is the default.
119-
</para>
120-
</listitem>
121-
</varlistentry>
98+
This clause specifies optional parameters for a publication. The
99+
following parameters are supported:
100+
101+
<variablelist>
102+
<varlistentry>
103+
<term><literal>publish</literal> (<type>string</type>)</term>
104+
<listitem>
105+
<para>
106+
This parameter determines which DML operations will be published by
107+
the new publication to the subscribers. The value is
108+
comma-separated list of operations. The allowed operations are
109+
<literal>insert</literal>, <literal>update</literal>, and
110+
<literal>delete</literal>. The default is to publish all actions,
111+
and so the default value for this option is
112+
<literal>'insert, update, delete'</literal>.
113+
</para>
114+
</listitem>
115+
</varlistentry>
116+
</variablelist>
122117

123-
<varlistentry>
124-
<term><literal>PUBLISH DELETE</literal></term>
125-
<term><literal>NOPUBLISH DELETE</literal></term>
126-
<listitem>
127-
<para>
128-
These clauses determine whether the new publication will send
129-
the <command>DELETE</command> operations to the subscribers.
130-
<literal>PUBLISH DELETE</literal> is the default.
131118
</para>
132119
</listitem>
133120
</varlistentry>
@@ -203,7 +190,7 @@ CREATE PUBLICATION alltables FOR ALL TABLES;
203190
operations in one table:
204191
<programlisting>
205192
CREATE PUBLICATION insert_only FOR TABLE mydata
206-
WITH (NOPUBLISH UPDATE, NOPUBLISH DELETE);
193+
WITH (publish = 'insert');
207194
</programlisting>
208195
</para>
209196
</refsect1>

0 commit comments

Comments
 (0)