Subject: [PATCH] pg_upgrade: add --initdb option to create the new cluster automatically

From: Bohyun Lee <[email-masked]>
Date: Fri, 10 Jul 2026 12:41:56 +0200

Hi,

This patch adds an --initdb option to pg_upgrade that automates the initdb
step currently required before running pg_upgrade.

Problem
—————
Before running pg_upgrade, users must manually run initdb with options that
exactly match the old cluster: WAL segment size, data checksum setting,
encoding, and locale. Getting these right is error-prone. A mismatch
results in a confusing check_control_data() failure after the user has
already invested time in setting up the new cluster. A related question was
raised before [1], where Jeff Davis discussed whether pg_upgrade should
perform initdb itself rather than requiring a pre-initialized cluster.

Solution
————
With --initdb, pg_upgrade handles this automatically. It derives the WAL
segment size and checksum setting from pg_control and invokes initdb with
the correct flags. The option refuses to proceed if the new cluster already
exists.

Testing
————
All existing pg_upgrade TAP tests pass. A new test, t/007_initdb_option.pl,
verifies the happy path end-to-end and checks that --initdb refuses to
overwrite an existing cluster.

Branch: https://github.com/LeeBohyun/postgres/tree/pg_upgrade_initdb
<https://github.com/LeeBohyun/postgres/treepg_upgrade_initdb>

Patch attached.

[1]
https://www.postgresql.org/message-id/2a7feb71dbdcea31478b3974b8075982ac2326d2.camel%40j-davis.com

Regards,
Bohyun Lee