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>