From 9ea5fdcedf9e89e9a518e64020b606963131b23d Mon Sep 17 00:00:00 2001 From: Vignesh C Date: Mon, 27 Oct 2025 09:18:07 +0530 Subject: [PATCH v20251027 3/4] Documentation for sequence synchronization feature. Documentation for sequence synchronization feature. Author: Vignesh C Reviewed-by: Amit Kapila Reviewed-by: shveta malik Reviewed-by: Hou Zhijie Reviewed-by: Masahiko Sawada Reviewed-by: Hayato Kuroda Reviewed-by: Dilip Kumar Reviewed-by: Peter Smith Reviewed-by: Nisha Moond Reviewed-by: Shlok Kyal Discussion: https://www.postgresql.org/message-id/CAA4eK1LC+KJiAkSrpE_NwvNdidw9F2os7GERUeSxSKv71gXysQ@mail.gmail.co --- doc/src/sgml/catalogs.sgml | 2 +- doc/src/sgml/config.sgml | 16 +- doc/src/sgml/func/func-sequence.sgml | 24 +++ doc/src/sgml/logical-replication.sgml | 239 ++++++++++++++++++++-- doc/src/sgml/monitoring.sgml | 5 +- doc/src/sgml/ref/alter_subscription.sgml | 15 ++ doc/src/sgml/ref/create_subscription.sgml | 19 +- 7 files changed, 291 insertions(+), 29 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 6c8a0f173c9..2fc63442980 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -6568,7 +6568,7 @@ SCRAM-SHA-256$<iteration count>:&l (references pg_class.oid) - Reference to relation + Reference to table or sequence diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 0a2a8b49fdb..9d54f8b26ed 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -5191,9 +5191,9 @@ ANY num_sync ( num_sync ( num_sync ( + + pg_get_sequence_data + + pg_get_sequence_data ( regclass ) + record + ( last_value bigint, + is_called bool, + page_lsn pg_lsn ) + + + Returns information about the sequence. last_value + indicates last sequence value set in sequence by nextval or setval, + is_called indicates whether the sequence has been + used, and page_lsn is the LSN corresponding to the + most recent WAL record that modified this sequence relation. + + + This function requires USAGE + or SELECT privilege on the sequence. + + diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index b01f5e998b2..548aab31960 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -113,7 +113,9 @@ Publications may currently only contain tables or sequences. Objects must be added explicitly, except when a publication is created using FOR TABLES IN SCHEMA, FOR ALL TABLES, - or FOR ALL SEQUENCES. + or FOR ALL SEQUENCES. Unlike tables, the current state of + sequences may be synchronized at any time. For more information, refer to + . @@ -1745,6 +1747,209 @@ Publications: + + Replicating Sequences + + + To synchronize sequences from a publisher to a subscriber, first publish + them using + CREATE PUBLICATION ... FOR ALL SEQUENCES and then + at the subscriber side: + + + + + + + use CREATE SUBSCRIPTION + to initially synchronize the published sequences. + + + + + use + ALTER SUBSCRIPTION ... REFRESH PUBLICATION + to synchronize only newly added sequences. + + + + + use + ALTER SUBSCRIPTION ... REFRESH SEQUENCES + to re-synchronize all sequences. + + + + + + + A new sequence synchronization worker will be started + after executing any of the above subscriber commands, and will exit once the + sequences are synchronized. + + + The ability to launch a sequence synchronization worker is limited by the + + max_sync_workers_per_subscription + configuration. + + + + Sequence Definition Mismatches + + During sequence synchronization, the sequence definitions of the publisher + and the subscriber are compared. An ERROR is logged listing all differing + sequences before the process exits. The apply worker detects this failure + and repeatedly respawns the sequence synchronization worker to continue + the synchronization process until all differences are resolved. See also + wal_retrieve_retry_interval. + + + To resolve this, use + ALTER SEQUENCE + to align the subscriber's sequence parameters with those of the publisher. + + + + + Missing Sequences + + During sequence synchronization, if a sequence is dropped on the + publisher, the sequence synchronization worker will identify this and + remove it from sequence synchronization on the subscriber. + + + + + Refreshing Stale Sequences + + Subscriber side sequence values may frequently become out of sync due to + updates on the publisher. + + + To verify, compare the sequence values between the publisher and + subscriber, and if necessary, execute + + ALTER SUBSCRIPTION ... REFRESH SEQUENCES. + + + + + Examples + + + Create some sequences on the publisher. + +test_pub=# CREATE SEQUENCE s1 START WITH 10 INCREMENT BY 1; +CREATE SEQUENCE +test_pub=# CREATE SEQUENCE s2 START WITH 100 INCREMENT BY 10; +CREATE SEQUENCE + + + + Create the same sequences on the subscriber. + +test_sub=# CREATE SEQUENCE s1 START WITH 10 INCREMENT BY 1 +CREATE SEQUENCE +test_sub=# CREATE SEQUENCE s2 START WITH 100 INCREMENT BY 10; +CREATE SEQUENCE + + + + Update the sequences at the publisher side a few times. + +test_pub=# SELECT nextval('s1'); + nextval +--------- + 10 +(1 row) +test_pub=# SELECT nextval('s1'); + nextval +--------- + 11 +(1 row) +test_pub=# SELECT nextval('s2'); + nextval +--------- + 100 +(1 row) +test_pub=# SELECT nextval('s2'); + nextval +--------- + 110 +(1 row) + + + + Create a publication for the sequences. + +test_pub=# CREATE PUBLICATION pub1 FOR ALL SEQUENCES; +CREATE PUBLICATION + + + + Subscribe to the publication. + +test_sub=# CREATE SUBSCRIPTION sub1 +test_sub-# CONNECTION 'host=localhost dbname=test_pub application_name=sub1' +test_sub-# PUBLICATION pub1; +CREATE SUBSCRIPTION + + + + Observe that initial sequence values are synchronized. + +test_sub=# SELECT * FROM s1; + last_value | log_cnt | is_called +------------+---------+----------- + 11 | 31 | t +(1 row) + +test_sub=# SELECT * FROM s2; + last_value | log_cnt | is_called +------------+---------+----------- + 110 | 31 | t +(1 row) + + + + Update the sequences at the publisher side. + +test_pub=# SELECT nextval('s1'); + nextval +--------- + 12 +(1 row) +test_pub=# SELECT nextval('s2'); + nextval +--------- + 120 +(1 row) + + + + Re-synchronize all the sequences at the subscriber side using + + ALTER SUBSCRIPTION ... REFRESH SEQUENCES. + +test_sub=# ALTER SUBSCRIPTION sub1 REFRESH SEQUENCES; +ALTER SUBSCRIPTION + +test_sub=# SELECT * FROM s1; + last_value | log_cnt | is_called +------------+---------+----------- + 12 | 30 | t +(1 row) + +test_sub=# SELECT * FROM s2 + last_value | log_cnt | is_called +------------+---------+----------- + 120 | 30 | t +(1 row) + + + + Conflicts @@ -2090,16 +2295,19 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER - Sequence data is not replicated. The data in serial or identity columns - backed by sequences will of course be replicated as part of the table, - but the sequence itself would still show the start value on the - subscriber. If the subscriber is used as a read-only database, then this - should typically not be a problem. If, however, some kind of switchover - or failover to the subscriber database is intended, then the sequences - would need to be updated to the latest values, either by copying the - current data from the publisher (perhaps - using pg_dump) or by determining a sufficiently high - value from the tables themselves. + Incremental sequence changes are not replicated. Although the data in + serial or identity columns backed by sequences will be replicated as part + of the table, the sequences themselves do not replicate ongoing changes. + On the subscriber, a sequence will retain the last value it synchronized + from the publisher. If the subscriber is used as a read-only database, + then this should typically not be a problem. If, however, some kind of + switchover or failover to the subscriber database is intended, then the + sequences would need to be updated to the latest values, either by + executing + ALTER SUBSCRIPTION ... REFRESH SEQUENCES + or by copying the current data from the publisher (perhaps using + pg_dump) or by determining a sufficiently high value + from the tables themselves. @@ -2423,8 +2631,8 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER max_logical_replication_workers must be set to at least the number of subscriptions (for leader apply - workers), plus some reserve for the table synchronization workers and - parallel apply workers. + workers), plus some reserve for the parallel apply workers, table synchronization workers, and a sequence + synchronization worker. @@ -2437,8 +2645,9 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER max_sync_workers_per_subscription - controls the amount of parallelism of the initial data copy during the - subscription initialization or when new tables are added. + controls how many tables can be synchronized in parallel during + subscription initialization or when new tables are added. One additional + worker is also needed for sequence synchronization. diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index d5f0fb7ba7c..242105e2cba 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -2045,8 +2045,9 @@ description | Waiting for a newly initialized WAL file to reach durable storage Type of the subscription worker process. Possible types are - apply, parallel apply, and - table synchronization. + apply, parallel apply, + table synchronization, and + sequence synchronization. diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml index 8ab3b7fbd37..27c06439f4f 100644 --- a/doc/src/sgml/ref/alter_subscription.sgml +++ b/doc/src/sgml/ref/alter_subscription.sgml @@ -195,6 +195,12 @@ ALTER SUBSCRIPTION name RENAME TO < use ALTER SUBSCRIPTION ... REFRESH SEQUENCES. + + See for recommendations on how + to handle any warnings about sequence definition differences between + the publisher and the subscriber, which might occur when + copy_data = true. + See for details of how copy_data = true can interact with the @@ -225,6 +231,15 @@ ALTER SUBSCRIPTION name RENAME TO < data for all currently subscribed sequences. It does not add or remove sequences from the subscription to match the publication. + + See for + recommendations on how to handle any warnings about sequence definition + differences between the publisher and the subscriber. + + + See for recommendations on how to + identify and handle out-of-sync sequences. + diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index ed82cf1809e..05bf2f2f49f 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -228,7 +228,7 @@ CREATE SUBSCRIPTION subscription_name for more about send/receive - functions). + functions). This parameter is not applicable for sequences. @@ -265,6 +265,12 @@ CREATE SUBSCRIPTION subscription_namecopy_data = true can interact with the origin parameter. + + See + for recommendations on how to handle any warnings about sequence + definition differences between the publisher and the subscriber, + which might occur when copy_data = true. + @@ -280,6 +286,7 @@ CREATE SUBSCRIPTION subscription_name @@ -310,7 +317,8 @@ CREATE SUBSCRIPTION subscription_name setting within this subscription's apply worker processes. The default value - is off. + is off. This parameter is not applicable for + sequences. @@ -340,7 +348,8 @@ CREATE SUBSCRIPTION subscription_name Specifies whether two-phase commit is enabled for this subscription. - The default is false. + The default is false. This parameter is not + applicable for sequences. @@ -417,6 +426,7 @@ CREATE SUBSCRIPTION subscription_nameorigin to any means that the publisher sends changes regardless of their origin. The default is any. + This parameter is not applicable for sequences. See for details of how @@ -449,7 +459,8 @@ CREATE SUBSCRIPTION subscription_name is enabled, and a physical replication slot named pg_conflict_detection is created on the subscriber to prevent the information for detecting - conflicts from being removed. + conflicts from being removed. This parameter is not applicable for + sequences. -- 2.43.0