Skip to content

docs(cluster_setup): cover synchronous replication and switchover - #388

Open
qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/cluster-sync-replication
Open

qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/cluster-sync-replication

Conversation

@qwer381

@qwer381 qwer381 commented Nov 11, 2026 •

Copy link
Copy Markdown

Closes #384

What this changes

CN|EN/modules/ROOT/pages/master/cluster_setup.adoc gains four sections after the existing "Using the cluster" chapter. The existing text is untouched — the CN page is +191 −0 and the EN page is +192 −1; the single deletion is the missing end-of-file newline (the EN page ends with a code fence that has no line terminator, so appending a section requires adding one, otherwise the new == heading is glued to the fence and the section renders broken).

  1. == 同步复制 / == Synchronous replication — synchronous_standby_names with both notations, and what each one does to pg_stat_replication.sync_state (sync vs quorum), plus the lag columns.
  2. == 主备切换演练 / == Promotion drill — pg_ctl promote and SELECT pg_promote(wait => true, wait_seconds => 60), the read-only check before promotion, the split-brain check afterwards (pg_is_in_recovery(), pg_stat_replication, slot activity) and pg_rewind to bring the old primary back.
  3. == Oracle 兼容端口在主备上的一致性 / == Keeping ivorysql.port consistent across nodes — the Oracle-compatible listener is a socket per node: connecting on 5533 gives compatible_mode = pg, connecting on 1621 gives oracle on the same instance. A standby that only changes port either collides with whatever owns 1521 (FATAL: could not create any Oracle TCP/IP sockets) or serves Oracle semantics on the wrong port.
  4. == 复制状态监控 / == Monitoring replication — how to read write_lag / flush_lag / replay_lag, sync_priority, sync_state, and what "no rows in pg_stat_replication" means on the new primary.

The promotion section also documents the trap that costs the most time in practice: a standby built with pg_basebackup -R inherits synchronous_standby_names, so right after promotion — with no standby attached — every commit waits in wait_event_type = IPC / wait_event = SyncRep and statement_timeout = '8s' does not interrupt it. The fix is two separate statements, because a single -c with a semicolon fails with ERROR: ALTER SYSTEM cannot run inside a transaction block:

ALTER SYSTEM SET synchronous_standby_names = '';
SELECT pg_reload_conf();

How it was verified

Everything quoted in the patch was produced on IvorySQL 5.6 (PostgreSQL 18.6 (IvorySQL 5.6)), one primary + one standby on the same host, port 5532/5533 and ivorysql.port 1621/1622; the raw psql and log transcripts were kept as evidence. pg_rewind is the only command shown with placeholders (<old_primary_data_dir>, <new_primary_ip>) — it is not re-run in this patch, and the text says the old primary must be stopped first.

Rendering: both files convert with asciidoctor.js 4.2.1 with zero warnings, and the section structure is symmetric between CN and EN.

Checklist

  • CLA signed and on file (individual CLA emailed to cla@ivorysql.org on 2026-11-10)
  • Only cluster_setup.adoc (CN + EN) touched, no nav.adoc change
  • Bilingual: every added section exists in both languages

The cluster_setup page only described a single asynchronous standby: a
replication user, wal_level=replica, pg_basebackup -R, and a raw
pg_stat_replication dump. Nothing covered synchronous replication, how to
promote a standby, what has to be cleaned up afterwards, or how the
Oracle-compatible listener behaves on a standby.

Add four sections to the CN and EN pages:

- synchronous replication: both synchronous_standby_names notations, what
  they turn sync_state into (sync vs quorum), and the lag columns;
- promotion drill: pg_ctl promote / pg_promote(), the read-only check, the
  split-brain check, and pg_rewind to re-attach the old primary;
- per-node ivorysql.port consistency: the same instance answers with
  compatible_mode=pg or oracle depending on which listener the client
  reaches, so a standby that only sets port either fails to bind the
  Oracle socket or serves the wrong semantics;
- replication monitoring: sync_priority, sync_state, and the lag columns.

The promotion section documents the trap that costs the most time: a
standby built with pg_basebackup -R inherits synchronous_standby_names, so
right after promotion every commit waits in wait_event_type=IPC,
wait_event=SyncRep and statement_timeout does not interrupt it. Clearing
the parameter needs two separate statements because ALTER SYSTEM cannot
run inside the same transaction as the reload.
@github-actions
github-actions Bot temporarily deployed to pull request November 11, 2026 16:47 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 12, 2026 •

Copy link
Copy Markdown
Author

CI is green and the rendered result has been verified on the deploy preview.

  • build-and-deploy: success (job completed), mergeStateStatus=clean, base master @ 7d4ad9d.
  • Preview check (both languages, HTTP 200): /cn/ivorysql-doc/master/cluster_setup.html and /en/ivorysql-doc/master/cluster_setup.html.
  • Rendered content matches the patch: the four new sections (synchronous replication, failover drill, Oracle-compatible port consistency across primary and standby, replication monitoring); no {asterisk} leftovers and no nested-markup artifacts.
  • nav position was verified against the live sidebar order, not just the diff.

Nothing else is pending on my side -- happy to adjust wording or split anything if you prefer a different shape for this section.

@qwer381
qwer381 force-pushed the docs/cluster-sync-replication branch from c216b1e to 4c8affa Compare November 13, 2026 05:53
@github-actions
github-actions Bot temporarily deployed to pull request November 13, 2026 05:56 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

This branch was previously deployed

1 inactive deployment
pull request — 4c8affa9 Deployed Nov 13, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants