From d4cd6662b162d229e62250070dceda409ecaddae Mon Sep 17 00:00:00 2001 From: Hou Zhijie Date: Tue, 16 Jan 2024 14:02:32 +0800 Subject: [PATCH v62 6/6] Document the steps to check if the standby is ready for failover --- doc/src/sgml/logical-replication.sgml | 125 ++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index ec2130669e..6539c60843 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -687,6 +687,131 @@ ALTER SUBSCRIPTION + + Logical Replication Failover + + + When the publisher server is the primary server of a streaming replication, + the logical slots on that primary server can be synchronized to the standby + server by specifying failover = true when creating + subscriptions for those publications. Enabling failover ensures a seamless + transition of those subscriptions after the standby is promoted. They can + continue subscribing to publications now on the new primary server without + any data loss. + + + + Because the slot synchronization logic copies asynchronously, it is + necessary to confirm that replication slots have been synced to the standby + server before the failover happens. Furthermore, to ensure a successful + failover, the standby server must not be lagging behind the subscriber. It + is highly recommended to use standby_slot_names to + prevent the subscriber from consuming changes faster than the hot standby. + To confirm that the standby server is indeed ready for failover, follow + these 2 steps: + + + + + + Confirm that all the necessary logical replication slots have been synced to + the standby server. + + + + + Firstly, on the subscriber node, use the following SQL to identify the + slot names that should be synced to the standby that we plan to promote. + +test_sub=# SELECT + array_agg(slotname) AS slots + FROM + (( + SELECT r.srsubid AS subid, CONCAT('pg_' || srsubid || '_sync_' || srrelid || '_' || ctl.system_identifier) AS slotname + FROM pg_control_system() ctl, pg_subscription_rel r, pg_subscription s + WHERE r.srsubstate = 'f' AND s.oid = r.srsubid AND s.subfailover + ) UNION ( + SELECT s.oid AS subid, s.subslotname as slotname + FROM pg_subscription s + WHERE s.subfailover + )); + slots +------- + {sub} +(1 row) + + + + + Next, check that the logical replication slots identified above exist on + the standby server. This step can be skipped if + standby_slot_names has been correctly configured. + +test_standby=# SELECT bool_and(synced AND NOT temporary AND conflict_reason IS NULL) AS failover_ready + FROM pg_replication_slots + WHERE slot_name in ('sub'); + failover_ready +---------------- + t +(1 row) + + + + + + + + Confirm that the standby server is not lagging behind the subscribers. + + + + + Firstly, on the subscriber node check the last replayed WAL. If the + query result is NULL, it indicates that the subscriber has not yet + replayed any WAL. Therefore, the next step can be skipped, as the + standby server must be ahead of the subscriber. + +test_sub=# SELECT + MAX(remote_lsn) AS remote_lsn_on_subscriber + FROM + (( + SELECT (CASE WHEN r.srsubstate = 'f' THEN pg_replication_origin_progress(CONCAT('pg_' || r.srsubid || '_' || r.srrelid), false) + WHEN r.srsubstate IN ('s', 'r') THEN r.srsublsn END) as remote_lsn + FROM pg_subscription_rel r, pg_subscription s + WHERE r.srsubstate IN ('f', 's', 'r') AND s.oid = r.srsubid AND s.subfailover + ) UNION ( + SELECT pg_replication_origin_progress(CONCAT('pg_' || s.oid), false) AS remote_lsn + FROM pg_subscription s + WHERE subfailover + )); + remote_lsn_on_subscriber +-------------------------- + 0/3000388 + + + + + Next, on the standby server check that the last-received WAL location + is ahead of the replayed WAL location on the subscriber identified above. + +test_standby=# SELECT pg_last_wal_receive_lsn() >= '0/3000388'::pg_lsn AS failover_ready; + failover_ready +---------------- + t +(1 row) + + + + + + + + If the result (failover_ready) of both above steps is + true, existing subscriptions will be able to continue without data loss. + + + + Row Filters -- 2.34.1