From 7f0bdc1850d5f0ceb378c9323b445c68121b4988 Mon Sep 17 00:00:00 2001 From: Bohyun Lee Date: Mon, 17 Aug 2026 13:13:59 +0200 Subject: [PATCH v6 1/2] doc: pg_upgrade: state which initdb settings must match the old cluster The manual "Initialize the new cluster" step said only to use "compatible initdb flags that match the old cluster", which is vague. Spell out the two settings pg_upgrade actually enforces through its control-data check: the WAL segment size (--wal-segsize) and the data checksum setting (--data-checksums/--no-data-checksums), and point to pg_controldata for reading the old cluster's values. Note that the encoding and locale need not match, since pg_upgrade copies them from the old cluster's template0. --- doc/src/sgml/ref/pgupgrade.sgml | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index e4e8c02e6d..d5c2239683 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -457,10 +457,16 @@ make prefix=/usr/local/pgsql.new install Initialize the new cluster using initdb. - Again, use compatible initdb - flags that match the old cluster. Many - prebuilt installers do this step automatically. There is no need to - start the new cluster. + Two initdb settings must match the old cluster, or + pg_upgrade will fail with a control-data + mismatch: the WAL segment size () and the + data checksum setting ( or + ). You can read the old cluster's + values with + pg_controldata. + (The encoding and locale need not match: pg_upgrade + copies them from the old cluster.) Many prebuilt installers do this step + automatically. There is no need to start the new cluster. -- 2.50.1 (Apple Git-155)