Hi, here are some review comments for patch v20240720-0003.
This review is a WIP. This post is only about the docs (*.sgml) of patch 0003.
======
doc/src/sgml/ref/alter_subscription.sgml
1. REFRESH PUBLICATION and copy_data
nitpicks:
- IMO the "synchronize the sequence data" info was misleading because
synchronization should only occur when copy_data=true.
- I also felt it was strange to mention pg_subscription_rel for
sequences, but not for tables. I modified this part too.
- Then I moved the information about re/synchronization of sequences
into the "copy_data" part.
- And added another link to ALTER SUBSCRIPTION ... REFRESH PUBLICATION SEQUENCES
Anyway, in summary, I have updated this page quite a lot according to
my understanding. Please take a look at the attached nitpick for my
suggestions.
nitpick - /The supported options are:/The only supported option is:/
~~~
2. REFRESH PUBLICATION SEQUENCES
nitpick - tweaked the wording
nitpicK - typo /syncronizes/synchronizes/
======
3. catalogs.sgml
IMO something is missing in Section "1.55. pg_subscription_rel".
Currently, this page only talks of relations/tables, but I think it
should mention "sequences" here too, particularly since now we are
linking to here from ALTER SUBSCRIPTION when talking about sequences.
======
99.
Please see the attached diffs patch which implements any nitpicks
mentioned above.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
diff --git a/doc/src/sgml/ref/alter_subscription.sgml
b/doc/src/sgml/ref/alter_subscription.sgml
index ba8c2b1..666d9b0 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -153,7 +153,7 @@ 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 the publisher. This will start
replication of tables that were added to the subscribed-to publications
since <link linkend="sql-createsubscription">
<command>CREATE SUBSCRIPTION</command></link> or
@@ -161,29 +161,26 @@ ALTER SUBSCRIPTION <replaceable
class="parameter">name</replaceable> RENAME TO <
</para>
<para>
- It also fetches the missing sequence information from the publisher and
- synchronize the sequence data for newly added sequences with the
- publisher. This will start synchronizing of sequences that were added to
- the subscribed-to publications since <link
linkend="sql-createsubscription">
- <command>CREATE SUBSCRIPTION</command></link> or the last invocation of
- <command>REFRESH PUBLICATION</command>. Additionally, it will remove any
- sequences that are no longer part of the publication from the
- <link linkend="catalog-pg-subscription-rel">pg_subscription_rel</link>
- system catalog. Sequences that have already been synchronized will not be
- re-synchronized.
+ Also, fetch missing sequence information from the publisher.
+ </para>
+
+ <para>
+ The system catalog <link
linkend="catalog-pg-subscription-rel">pg_subscription_rel</link>
+ is updated to record all tables and sequences known to the subscription,
+ that are still part of the publication.
</para>
<para>
<replaceable>refresh_option</replaceable> specifies additional options
for the
- refresh operation. The supported options are:
+ refresh operation. The only supported option is:
<variablelist>
<varlistentry>
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether to copy pre-existing data for tables and sequences
- in the publications that are being subscribed to when the replication
+ Specifies whether to copy pre-existing data for tables and
synchronize
+ sequences in the publications that are being subscribed to when the
replication
starts. The default is <literal>true</literal>.
</para>
<para>
@@ -191,6 +188,11 @@ ALTER SUBSCRIPTION <replaceable
class="parameter">name</replaceable> RENAME TO <
filter <literal>WHERE</literal> clause has since been modified.
</para>
<para>
+ Previously subscribed sequences are not re-synchronized. To do that,
+ see <link
linkend="sql-altersubscription-params-refresh-publication-sequences">
+ <command>ALTER SUBSCRIPTION ... REFRESH PUBLICATION
SEQUENCES</command></link>
+ </para>
+ <para>
See <xref linkend="sql-createsubscription-notes"/> for details of
how <literal>copy_data = true</literal> can interact with the
<link
linkend="sql-createsubscription-params-with-origin"><literal>origin</literal></link>
@@ -212,11 +214,11 @@ ALTER SUBSCRIPTION <replaceable
class="parameter">name</replaceable> RENAME TO <
<term><literal>REFRESH PUBLICATION SEQUENCES</literal></term>
<listitem>
<para>
- Fetch missing sequences information from publisher and re-synchronize the
+ Fetch missing sequence information from the publisher, then
re-synchronize
sequence data with the publisher. Unlike <link
linkend="sql-altersubscription-params-refresh-publication">
<literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal></link>
which
- only syncronizes the newly added sequences, this option will also
- re-synchronize the sequence data for sequences that were previously
added.
+ only synchronizes newly added sequences, <literal>REFRESH PUBLICATION
SEQUENCES</literal>
+ will re-synchronize the sequence data for all subscribed sequences.
</para>
</listitem>
</varlistentry>
