diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index e4e8c02e6d67f3725f68a6e72d0f375f5d12fe8e..bd239af7eb83c89c58a01a71b0afe4b2a2e0db80 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -106,7 +106,8 @@ PostgreSQL documentation
      <varlistentry>
       <term><option>-c</option></term>
       <term><option>--check</option></term>
-      <listitem><para>check clusters only, don't change any data</para></listitem>
+      <listitem><para>check clusters without performing the upgrade.
+      If <option>--initdb</option> is also specified, initialize the new cluster if needed before checking it.</para></listitem>
      </varlistentry>
 
      <varlistentry>
@@ -262,6 +263,103 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--initdb</option></term>
+      <listitem>
+       <para>
+        Create the new cluster automatically by running
+        <command>initdb</command> before upgrading, instead of requiring the
+        user to have created it manually.
+        The new cluster uses the old cluster's WAL segment size and
+        data-checksum setting, and the encoding and locale of its
+        <literal>template0</literal> database.
+       </para>
+       <para>
+        To initialize the new cluster, the directory specified by <option>-D</option>/<option>--new-datadir</option> must be empty or must not exist.
+        During initialization, <application>pg_upgrade</application> uses <filename>pg_upgrade_output.d</filename> in the current working directory for temporary logs.
+        The new data directory must not be the same as that log directory, be inside it, or contain it.
+        If the new data directory is inside the old data directory, <application>pg_upgrade</application> does not generate the script for deleting the old cluster, because the script would also delete the new cluster.
+       </para>
+       <para>
+        When combined with <option>-c</option>/<option>--check</option>, <option>--initdb</option> initializes the new cluster if the target directory is empty or nonexistent, then runs the compatibility checks on both clusters without performing the upgrade.
+        If the target directory is nonempty, initialization is skipped and the existing cluster is checked instead.
+        The new cluster is retained whether the checks succeed or fail, so the same check command can be run again.
+        After a successful check, run <application>pg_upgrade</application> without <option>--check</option>, <option>--initdb</option>, or <option>--initdb-options</option> to upgrade using that cluster.
+       </para>
+       <para>
+        <option>-O</option>/<option>--new-options</option> continues to pass
+        options to the new cluster's server process; those options are not
+        passed to <command>initdb</command>.  Use
+        <option>--initdb-options</option> for additional initialization options.
+       </para>
+       <para>
+        If initialization fails, <command>initdb</command> performs its normal cleanup.
+        Once initialization succeeds, <application>pg_upgrade</application> leaves the new data directory and any separate WAL directory in place if a later step fails, just as it does without <option>--initdb</option>.
+        See <xref linkend="pgupgrade-step-revert"/> for recovery instructions.
+        To rerun initialization with <option>--initdb</option>, the new data and WAL directories must again be empty or nonexistent.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--initdb-options=</option><replaceable>options</replaceable></term>
+      <listitem>
+       <para>
+        Pass additional arguments to <command>initdb</command>.  Requires
+        <option>--initdb</option>.  This option can be repeated; arguments are
+        appended in command-line order.  For example:
+<programlisting>
+pg_upgrade --initdb --initdb-options='-c huge_pages=off --waldir=/wal/new' ...
+</programlisting>
+        Settings supplied with <command>initdb</command>'s <option>-c</option>
+        are saved in the new <filename>postgresql.conf</filename> and can also
+        affect initialization itself.  In particular, a library specified in
+        <varname>shared_preload_libraries</varname> must support being loaded
+        during initialization, as well as by the new server during upgrade.
+       </para>
+       <para>
+        These options apply only when <application>pg_upgrade</application> initializes the new cluster.
+        When you retry <option>--check --initdb</option> with an already initialized cluster, <application>pg_upgrade</application> prints a notice and skips <command>initdb</command>.
+        Changes to <option>--initdb-options</option> on the retry are not applied to that cluster.
+       </para>
+       <para>
+        Within <replaceable>options</replaceable>, spaces and tabs separate
+        arguments.  Single or double quotes group text into one argument and
+        are removed; adjacent quoted and unquoted text forms one argument.
+        Single quotes preserve their contents literally.  Elsewhere, a
+        backslash escapes a following quote, backslash, space, or tab, and is
+        preserved before other characters.  Unmatched quotes, a trailing
+        unquoted backslash, and newline or carriage-return characters are
+        rejected.  No shell expansion is performed; for example,
+        <literal>$libdir</literal> is passed literally.  The caller's shell
+        quoting rules still apply to the outer command line.  Arguments can
+        appear in command output, log files, and process listings, so use
+        file-based inputs such as <option>--pwfile</option> for passwords.
+       </para>
+       <para>
+        These arguments are passed to <command>initdb</command> after the
+        arguments generated by <application>pg_upgrade</application> and are
+        validated by <command>initdb</command>.
+        <application>pg_upgrade</application> then performs its normal
+        cluster compatibility checks.
+       </para>
+       <para>
+        Group access to the new cluster is disabled by default.
+        To enable it, use <option>--initdb-options='--allow-group-access'</option>.
+        With <option>--link</option> or <option>--swap</option>, transferred relation files retain their existing permissions, even when group access is requested for the new cluster.
+        With <option>--swap</option>, moved database directories also retain their existing permissions.
+       </para>
+       <para>
+        Authentication options, including <option>--auth-local</option> and
+        <option>--auth-host</option>, are passed unchanged.  Provide credentials
+        accepted by both clusters, for example through a protected
+        <link linkend="libpq-pgpass">password file</link>.
+        <application>pg_upgrade</application> does not weaken authentication
+        rules to obtain access.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>--no-statistics</option></term>
       <listitem>
@@ -457,10 +555,22 @@ make prefix=/usr/local/pgsql.new install
 
     <para>
      Initialize the new cluster using <command>initdb</command>.
-     Again, use compatible <command>initdb</command>
-     flags that match the old cluster. Many
-     prebuilt installers do this step automatically. There is no need to
-     start the new cluster.
+     Two <command>initdb</command> settings must match the old cluster, or
+     <application>pg_upgrade</application> will fail with a control-data
+     mismatch: the WAL segment size (<option>--wal-segsize</option>) and the
+     data checksum setting (<option>--data-checksums</option> or
+     <option>--no-data-checksums</option>).  You can read the old cluster's
+     values with
+     <link linkend="app-pgcontroldata"><application>pg_controldata</application></link>.
+     (The encoding and locale need not match: <application>pg_upgrade</application>
+     copies them from the old cluster.)  Many prebuilt installers do this step
+     automatically.  There is no need to start the new cluster.
+    </para>
+    <para>
+     Alternatively, pass <option>--initdb</option> to
+     <application>pg_upgrade</application> to have it run
+     <command>initdb</command> automatically, deriving the required settings
+     from the old cluster.  In that case this manual step can be skipped.
     </para>
    </step>
 
@@ -1064,10 +1174,13 @@ psql --username=postgres --file=script.sql postgres
   <title>Notes</title>
 
   <para>
-   <application>pg_upgrade</application> creates various working files, such
-   as schema dumps, stored within <filename>pg_upgrade_output.d</filename> in
-   the directory of the new cluster. Each run creates a new subdirectory named
-   with a timestamp formatted as per ISO 8601
+   <application>pg_upgrade</application> creates various working files, such as schema dumps, stored within <filename>pg_upgrade_output.d</filename> in the directory of the new cluster.
+   When <option>--initdb</option> initializes the new cluster, early server and initialization logs are written under <filename>pg_upgrade_output.d</filename> in the current working directory, because <command>initdb</command> requires an empty target directory.
+   After initialization succeeds, these temporary logs are removed unless <option>--retain</option> is specified.
+   Subsequent output is written to the new cluster's <filename>pg_upgrade_output.d</filename> directory.
+   If an early step or <command>initdb</command> fails, the logs remain in the current working directory.
+   Each run creates a new subdirectory named with a timestamp formatted as per
+   ISO 8601
    (<literal>%Y%m%dT%H%M%S</literal>), where all its generated files are
    stored.
    <filename>pg_upgrade_output.d</filename> and its contained files will be
diff --git a/src/bin/pg_upgrade/Makefile b/src/bin/pg_upgrade/Makefile
index 771addb675a6dcc52a3ac90ca1252a5e88a83d45..9d8602a9a72841f30cc86eab0ad254721bf76f9f 100644
--- a/src/bin/pg_upgrade/Makefile
+++ b/src/bin/pg_upgrade/Makefile
@@ -3,7 +3,7 @@
 PGFILEDESC = "pg_upgrade - an in-place binary upgrade utility"
 PGAPPICON = win32
 
-EXTRA_INSTALL=contrib/test_decoding src/test/modules/dummy_seclabel src/test/modules/test_extensions
+EXTRA_INSTALL=contrib/test_decoding src/test/modules/dummy_seclabel src/test/modules/test_extensions src/test/modules/test_slru
 
 subdir = src/bin/pg_upgrade
 top_builddir = ../../..
diff --git a/src/bin/pg_upgrade/check.c b/src/bin/pg_upgrade/check.c
index 150c4fc34b9b29773df38af7415e169cefdb14b1..3265569ae39ca0fcfe090ea5d1f8f3c5fcb13cfb 100644
--- a/src/bin/pg_upgrade/check.c
+++ b/src/bin/pg_upgrade/check.c
@@ -758,6 +758,13 @@ report_clusters_compatible(void)
 		/* stops new cluster */
 		stop_postmaster(false);
 
+		/*
+		 * --initdb defers syncing until pg_upgrade finishes.  Sync the
+		 * retained cluster before returning from --check.
+		 */
+		if (user_opts.initdb_new_cluster)
+			sync_new_cluster(true);
+
 		cleanup_output_dirs();
 		exit(0);
 	}
diff --git a/src/bin/pg_upgrade/exec.c b/src/bin/pg_upgrade/exec.c
index a1bdbf373e38543eb2147e54b4d1d776c9360c14..7f0a85dd697d99bcab1729b0da72f3f6f5ac8587 100644
--- a/src/bin/pg_upgrade/exec.c
+++ b/src/bin/pg_upgrade/exec.c
@@ -15,8 +15,6 @@
 #include "fe_utils/version.h"
 #include "pg_upgrade.h"
 
-static void check_data_dir(ClusterInfo *cluster);
-static void check_bin_dir(ClusterInfo *cluster, bool check_versions);
 static void get_bin_version(ClusterInfo *cluster);
 static void check_exec(const char *dir, const char *program, bool check_version);
 
@@ -244,15 +242,10 @@ pid_lock_file_exists(const char *datadir)
 
 
 /*
- * verify_directories()
- *
- * does all the hectic work of verifying directories and executables
- * of old and new server.
- *
- * NOTE: May update the values of all parameters
+ * Check that the current directory is writable
  */
 void
-verify_directories(void)
+check_current_dir_write_permissions(void)
 {
 #ifndef WIN32
 	if (access(".", R_OK | W_OK | X_OK) != 0)
@@ -260,11 +253,6 @@ verify_directories(void)
 	if (win32_check_directory_write_permissions() != 0)
 #endif
 		pg_fatal("You must have read and write access in the current directory.");
-
-	check_bin_dir(&old_cluster, false);
-	check_data_dir(&old_cluster);
-	check_bin_dir(&new_cluster, true);
-	check_data_dir(&new_cluster);
 }
 
 
@@ -329,7 +317,7 @@ check_single_dir(const char *pg_data, const char *subdir)
  *	us) we display an error message and exit()
  *
  */
-static void
+void
 check_data_dir(ClusterInfo *cluster)
 {
 	const char *pg_data = cluster->pgdata;
@@ -361,7 +349,7 @@ check_data_dir(ClusterInfo *cluster)
  *	against the version of this pg_upgrade.  This is for checking the target
  *	bindir.
  */
-static void
+void
 check_bin_dir(ClusterInfo *cluster, bool check_versions)
 {
 	struct stat statBuf;
diff --git a/src/bin/pg_upgrade/info.c b/src/bin/pg_upgrade/info.c
index 5c59cfb32e8b7fc06cc07f42e4d0a394f5ae02c3..d66fc170fa0186f194d84f9d67394eaf5aac7463 100644
--- a/src/bin/pg_upgrade/info.c
+++ b/src/bin/pg_upgrade/info.c
@@ -21,7 +21,6 @@ static void create_rel_filename_map(const char *old_data, const char *new_data,
 static void report_unmatched_relation(const RelInfo *rel, const DbInfo *db,
 									  bool is_new_db);
 static void free_db_and_rel_infos(DbInfoArr *db_arr);
-static void get_template0_info(ClusterInfo *cluster);
 static void get_db_infos(ClusterInfo *cluster);
 static char *get_rel_infos_query(void);
 static void process_rel_infos(DbInfo *dbinfo, PGresult *res, void *arg);
@@ -328,7 +327,7 @@ get_db_rel_and_slot_infos(ClusterInfo *cluster)
  * Get information about template0, which will be copied from the old cluster
  * to the new cluster.
  */
-static void
+void
 get_template0_info(ClusterInfo *cluster)
 {
 	PGconn	   *conn = connectToServer(cluster, "template1");
diff --git a/src/bin/pg_upgrade/meson.build b/src/bin/pg_upgrade/meson.build
index ffbf6ae8d759bf8d95559c735d846ba1869347d3..6288e0798643ada244dae8c2c9c31334b2862280 100644
--- a/src/bin/pg_upgrade/meson.build
+++ b/src/bin/pg_upgrade/meson.build
@@ -69,6 +69,7 @@ tests += {
       't/006_transfer_modes.pl',
       't/007_multixact_conversion.pl',
       't/008_extension_control_path.pl',
+      't/009_initdb_option.pl',
     ],
     'deps': [test_ext],
     'test_kwargs': {'priority': 40}, # pg_upgrade tests are slow
diff --git a/src/bin/pg_upgrade/option.c b/src/bin/pg_upgrade/option.c
index f01d2f92d9548aaf648f247773e684fc60d0e59b..121cb0c9e9c0042d3f7810ebae9edaf9d57c206e 100644
--- a/src/bin/pg_upgrade/option.c
+++ b/src/bin/pg_upgrade/option.c
@@ -9,6 +9,8 @@
 
 #include "postgres_fe.h"
 
+#include <limits.h>
+
 #ifdef WIN32
 #include <io.h>
 #endif
@@ -20,6 +22,7 @@
 #include "utils/pidfile.h"
 
 static void usage(void);
+static void parse_initdb_options(const char *options);
 static void check_required_directory(char **dirpath,
 									 const char *envVarName, bool useCwd,
 									 const char *cmdLineOption, const char *description,
@@ -63,6 +66,8 @@ parseCommandLine(int argc, char *argv[])
 		{"no-statistics", no_argument, NULL, 5},
 		{"set-char-signedness", required_argument, NULL, 6},
 		{"swap", no_argument, NULL, 7},
+		{"initdb", no_argument, NULL, 8},
+		{"initdb-options", required_argument, NULL, 9},
 
 		{NULL, 0, NULL, 0}
 	};
@@ -234,6 +239,15 @@ parseCommandLine(int argc, char *argv[])
 				user_opts.transfer_mode = TRANSFER_MODE_SWAP;
 				break;
 
+			case 8:
+				user_opts.initdb_new_cluster = true;
+				break;
+
+			case 9:
+				user_opts.initdb_options_given = true;
+				parse_initdb_options(optarg);
+				break;
+
 			default:
 				fprintf(stderr, _("Try \"%s --help\" for more information.\n"),
 						os_info.progname);
@@ -244,6 +258,9 @@ parseCommandLine(int argc, char *argv[])
 	if (optind < argc)
 		pg_fatal("too many command-line arguments (first is \"%s\")", argv[optind]);
 
+	if (user_opts.initdb_options_given && !user_opts.initdb_new_cluster)
+		pg_fatal("--initdb-options requires --initdb");
+
 	if (!user_opts.sync_method)
 		user_opts.sync_method = pg_strdup("fsync");
 
@@ -300,6 +317,73 @@ parseCommandLine(int argc, char *argv[])
 }
 
 
+/*
+ * Split --initdb-options without invoking a shell.  Single quotes preserve
+ * every character.  Outside single quotes, backslashes escape only quotes,
+ * backslashes, spaces, and tabs, so ordinary Windows path separators survive.
+ */
+static void
+parse_initdb_options(const char *options)
+{
+	const char *p = options;
+	char	   *argument;
+
+	if (strpbrk(options, "\r\n") != NULL)
+		pg_fatal("--initdb-options must not contain a newline or carriage return");
+
+	argument = pg_malloc(strlen(options) + 1);
+	while (*p)
+	{
+		char	   *out = argument;
+		char		quote = '\0';
+
+		while (*p == ' ' || *p == '\t')
+			p++;
+		if (*p == '\0')
+			break;
+
+		while (*p)
+		{
+			if (quote == '\0' && (*p == ' ' || *p == '\t'))
+				break;
+			if (*p == quote)
+			{
+				quote = '\0';
+				p++;
+			}
+			else if (quote != '\'' && *p == '\\')
+			{
+				p++;
+				if (*p == '\0')
+					pg_fatal("trailing backslash in --initdb-options");
+				if (*p == '\'' || *p == '"' || *p == '\\' ||
+					*p == ' ' || *p == '\t')
+					*out++ = *p++;
+				else
+					*out++ = '\\';
+			}
+			else if (quote == '\0' && (*p == '\'' || *p == '"'))
+				quote = *p++;
+			else
+				*out++ = *p++;
+		}
+
+		if (quote != '\0')
+			pg_fatal("unterminated quote in --initdb-options");
+		*out = '\0';
+
+		if (user_opts.num_initdb_options == INT_MAX - 1)
+			pg_fatal("too many arguments in --initdb-options");
+		user_opts.initdb_options =
+			pg_realloc_array(user_opts.initdb_options, char *,
+							 (size_t) user_opts.num_initdb_options + 1);
+		user_opts.initdb_options[user_opts.num_initdb_options++] =
+			pg_strdup(argument);
+	}
+	pg_free(argument);
+}
+
+
 static void
 usage(void)
 {
@@ -328,6 +412,9 @@ usage(void)
 	printf(_("  --clone                       clone instead of copying files to new cluster\n"));
 	printf(_("  --copy                        copy files to new cluster (default)\n"));
 	printf(_("  --copy-file-range             copy files to new cluster with copy_file_range\n"));
+	printf(_("  --initdb                      create the new cluster with initdb before\n"
+			 "                                checking or upgrading, using old cluster settings\n"));
+	printf(_("  --initdb-options=OPTIONS      options to pass to initdb (requires --initdb)\n"));
 	printf(_("  --no-statistics               do not import statistics from old cluster\n"));
 	printf(_("  --set-char-signedness=OPTION  set new cluster char signedness to \"signed\" or\n"
 			 "                                \"unsigned\"\n"));
@@ -336,7 +423,9 @@ usage(void)
 	printf(_("  -?, --help                    show this help, then exit\n"));
 	printf(_("\n"
 			 "Before running pg_upgrade you must:\n"
-			 "  create a new database cluster (using the new version of initdb)\n"
+			 "  create a new database cluster (using the new version of initdb),\n"
+			 "    unless the --initdb option is given, in which case pg_upgrade\n"
+			 "    creates the new cluster for you\n"
 			 "  shutdown the postmaster servicing the old cluster\n"
 			 "  shutdown the postmaster servicing the new cluster\n"));
 	printf(_("\n"
@@ -422,9 +511,10 @@ check_required_directory(char **dirpath, const char *envVarName, bool useCwd,
  * by querying the running server.  This has limited checking because we
  * can't check for a running server because we can't find postmaster.pid.
  *
- * On entry, cluster->pgdata has been set from command line or env variable,
- * but cluster->pgconfig isn't set.  We fill both variables with corrected
- * values.
+ * On entry, cluster->bindir has already been set, and cluster->pgdata has
+ * been initially set from the command line or env variable.  We fill
+ * cluster->pgconfig, and adjust cluster->pgdata with a corrected value if the
+ * real data directory is in a different location.
  */
 void
 adjust_data_dir(ClusterInfo *cluster)
diff --git a/src/bin/pg_upgrade/pg_upgrade.c b/src/bin/pg_upgrade/pg_upgrade.c
index c0fadb3f31773c80351ec48b92e5fdfff1871c03..5daa8a7cc99832267c1f4b60bab28de0197dba34 100644
--- a/src/bin/pg_upgrade/pg_upgrade.c
+++ b/src/bin/pg_upgrade/pg_upgrade.c
@@ -45,10 +45,13 @@
 
 #include "access/multixact.h"
 #include "catalog/pg_class_d.h"
+#include "catalog/pg_collation_d.h"
 #include "common/file_perm.h"
 #include "common/logging.h"
 #include "common/restricted_token.h"
 #include "fe_utils/string_utils.h"
+#include "fe_utils/version.h"
+#include "mb/pg_wchar.h"
 #include "pg_upgrade.h"
 
 /*
@@ -65,8 +68,13 @@ static void prepare_new_globals(void);
 static void create_new_objects(void);
 static void copy_xact_xlog_xid(void);
 static void set_frozenxids(void);
-static void make_outputdirs(char *pgdata);
-static void setup(char *argv0);
+static void make_outputdirs(const char *output_root);
+static void check_bin_dirs(const char *argv0);
+static void check_clusters_stopped(void);
+static bool check_new_cluster_initdb_target(void);
+static void get_old_cluster_initdb_info(void);
+static void build_new_cluster_initdb_cmd(PQExpBuffer cmd);
+static void create_new_cluster_via_initdb(void);
 static void create_logical_replication_slots(void);
 static void create_conflict_detection_slot(void);
 
@@ -106,9 +114,40 @@ main(int argc, char **argv)
 
 	get_restricted_token();
 
+	/*
+	 * Make sure the user has a clean environment, otherwise, we may confuse
+	 * libpq when we connect to one (or both) of the servers.
+	 */
+	check_pghost_envvar();
+
+	/*
+	 * Resolve old and new binary dirs before adjust_data_dir(), because
+	 * adjust_data_dir() might need to call the binaries.
+	 */
+	check_bin_dirs(argv[0]);
+
 	adjust_data_dir(&old_cluster);
 	adjust_data_dir(&new_cluster);
 
+	if (user_opts.initdb_new_cluster &&
+		check_new_cluster_initdb_target())
+	{
+		/* Match output-file permissions to the cluster being inspected. */
+		if (!GetDataDirectoryCreatePerm(old_cluster.pgdata))
+			pg_fatal("could not read permissions of directory \"%s\": %m",
+					 old_cluster.pgdata);
+		umask(pg_mode_mask);
+
+		/*
+		 * Keep early logs in a temporary directory because initdb requires an
+		 * empty target directory.
+		 */
+		make_outputdirs(".");
+
+		create_new_cluster_via_initdb();
+		cleanup_output_dirs();
+	}
+
 	/*
 	 * Set mask based on PGDATA permissions, needed for the creation of the
 	 * output directories with correct permissions.
@@ -125,7 +164,11 @@ main(int argc, char **argv)
 	 */
 	make_outputdirs(new_cluster.pgdata);
 
-	setup(argv[0]);
+	check_current_dir_write_permissions();
+
+	check_data_dir(&old_cluster);
+	check_data_dir(&new_cluster);
+	check_clusters_stopped();
 
 	output_check_banner();
 
@@ -237,18 +280,7 @@ main(int argc, char **argv)
 		stop_postmaster(false);
 	}
 
-	if (user_opts.do_sync)
-	{
-		prep_status("Sync data directory to disk");
-		exec_prog(UTILITY_LOG_FILE, NULL, true, true,
-				  "\"%s/initdb\" --sync-only %s \"%s\" --sync-method %s",
-				  new_cluster.bindir,
-				  (user_opts.transfer_mode == TRANSFER_MODE_SWAP) ?
-				  "--no-sync-data-files" : "",
-				  new_cluster.pgdata,
-				  user_opts.sync_method);
-		check_ok();
-	}
+	sync_new_cluster(user_opts.transfer_mode != TRANSFER_MODE_SWAP);
 
 	create_script_for_old_cluster_deletion(&deletion_script_file_name);
 
@@ -268,13 +300,35 @@ main(int argc, char **argv)
 	return 0;
 }
 
+/*
+ * Sync the new cluster after shutdown, unless --no-sync is specified.
+ * --check --initdb needs a full sync.  A completed --swap upgrade can skip
+ * syncing data files here because they have already been synced.
+ */
+void
+sync_new_cluster(bool sync_data_files)
+{
+	if (!user_opts.do_sync)
+		return;
+
+	prep_status("Sync data directory to disk");
+	exec_prog(UTILITY_LOG_FILE, NULL, true, true,
+			  "\"%s/initdb\" --sync-only %s \"%s\" --sync-method %s",
+			  new_cluster.bindir,
+			  sync_data_files ? "" : "--no-sync-data-files",
+			  new_cluster.pgdata,
+			  user_opts.sync_method);
+	check_ok();
+}
+
+
 /*
  * Create and assign proper permissions to the set of output directories
  * used to store any data generated internally, filling in log_opts in
  * the process.
  */
 static void
-make_outputdirs(char *pgdata)
+make_outputdirs(const char *output_root)
 {
 	FILE	   *fp;
 	char	  **filename;
@@ -285,8 +339,9 @@ make_outputdirs(char *pgdata)
 	time_t		tt;
 	int			len;
 
+	pg_free(log_opts.rootdir);
 	log_opts.rootdir = (char *) pg_malloc0(MAXPGPATH);
-	len = snprintf(log_opts.rootdir, MAXPGPATH, "%s/%s", pgdata, BASE_OUTPUTDIR);
+	len = snprintf(log_opts.rootdir, MAXPGPATH, "%s/%s", output_root, BASE_OUTPUTDIR);
 	if (len >= MAXPGPATH)
 		pg_fatal("directory path for new cluster is too long");
 
@@ -297,6 +352,7 @@ make_outputdirs(char *pgdata)
 	/* append milliseconds */
 	snprintf(timebuf + strlen(timebuf), sizeof(timebuf) - strlen(timebuf),
 			 ".%03d", (int) (time.tv_usec / 1000));
+	pg_free(log_opts.basedir);
 	log_opts.basedir = (char *) pg_malloc0(MAXPGPATH);
 	len = snprintf(log_opts.basedir, MAXPGPATH, "%s/%s", log_opts.rootdir,
 				   timebuf);
@@ -304,6 +360,7 @@ make_outputdirs(char *pgdata)
 		pg_fatal("directory path for new cluster is too long");
 
 	/* BASE_OUTPUTDIR/$timestamp/dump/ */
+	pg_free(log_opts.dumpdir);
 	log_opts.dumpdir = (char *) pg_malloc0(MAXPGPATH);
 	len = snprintf(log_opts.dumpdir, MAXPGPATH, "%s/%s/%s", log_opts.rootdir,
 				   timebuf, DUMP_OUTPUTDIR);
@@ -311,6 +368,7 @@ make_outputdirs(char *pgdata)
 		pg_fatal("directory path for new cluster is too long");
 
 	/* BASE_OUTPUTDIR/$timestamp/log/ */
+	pg_free(log_opts.logdir);
 	log_opts.logdir = (char *) pg_malloc0(MAXPGPATH);
 	len = snprintf(log_opts.logdir, MAXPGPATH, "%s/%s/%s", log_opts.rootdir,
 				   timebuf, LOG_OUTPUTDIR);
@@ -358,20 +416,13 @@ make_outputdirs(char *pgdata)
 }
 
 
+/*
+ * Resolve the new binary directory from pg_upgrade's path when -B or
+ * PGBINNEW was not specified, then validate both clusters' binaries.
+ */
 static void
-setup(char *argv0)
+check_bin_dirs(const char *argv0)
 {
-	/*
-	 * make sure the user has a clean environment, otherwise, we may confuse
-	 * libpq when we connect to one (or both) of the servers.
-	 */
-	check_pghost_envvar();
-
-	/*
-	 * In case the user hasn't specified the directory for the new binaries
-	 * with -B, default to using the path of the currently executed pg_upgrade
-	 * binary.
-	 */
 	if (!new_cluster.bindir)
 	{
 		char		exec_path[MAXPGPATH];
@@ -384,8 +435,195 @@ setup(char *argv0)
 		new_cluster.bindir = pg_strdup(exec_path);
 	}
 
-	verify_directories();
+	check_bin_dir(&old_cluster, false);
+	check_bin_dir(&new_cluster, true);
+}
+
+
+/*
+ * For --check, reuse a nonempty target and let the normal cluster checks
+ * validate it.  Otherwise, require an empty or nonexistent directory that
+ * does not overlap pg_upgrade_output.d.
+ */
+static bool
+check_new_cluster_initdb_target(void)
+{
+	char	   *absolute_pgdata;
+	char	   *absolute_outputdir;
+	int			dir_status = pg_check_dir(new_cluster.pgdata);
 
+	if (dir_status > 1)
+	{
+		if (user_opts.check)
+		{
+			pg_log(PG_REPORT,
+				   "Using existing new cluster data directory \"%s\"; "
+				   "skipping initdb and --initdb-options.",
+				   new_cluster.pgdata);
+			return false;
+		}
+		pg_fatal("new cluster data directory \"%s\" is not empty; "
+				 "--initdb requires an empty or nonexistent directory",
+				 new_cluster.pgdata);
+	}
+	else if (dir_status < 0)
+		pg_fatal("could not access directory \"%s\": %m", new_cluster.pgdata);
+
+	absolute_pgdata = make_absolute_path(new_cluster.pgdata);
+	absolute_outputdir = make_absolute_path(BASE_OUTPUTDIR);
+	if (!absolute_pgdata || !absolute_outputdir)
+		exit(1);
+	if (path_is_prefix_of_path(absolute_pgdata, absolute_outputdir) ||
+		path_is_prefix_of_path(absolute_outputdir, absolute_pgdata))
+		pg_fatal("new cluster data directory \"%s\" overlaps output directory \"%s\"; "
+				 "--initdb requires separate data and output directories",
+				 absolute_pgdata, absolute_outputdir);
+	free(absolute_pgdata);
+	free(absolute_outputdir);
+	return true;
+}
+
+
+/*
+ * Read the old cluster's control data and template0 settings for initdb.
+ */
+static void
+get_old_cluster_initdb_info(void)
+{
+	old_cluster.major_version = get_pg_version(old_cluster.pgdata,
+											   &old_cluster.major_version_str);
+
+	if (!old_cluster.sockdir)
+		old_cluster.sockdir = user_opts.socketdir ? user_opts.socketdir : ".";
+
+	/*
+	 * Allow a running old server for --check, as check_clusters_stopped()
+	 * does.
+	 */
+	if (pid_lock_file_exists(old_cluster.pgdata))
+	{
+		if (start_postmaster(&old_cluster, false))
+			stop_postmaster(false);
+		else if (!user_opts.check)
+			pg_fatal("There seems to be a postmaster servicing the old cluster.\n"
+					 "Please shutdown that postmaster and try again.");
+		else
+			user_opts.live_check = true;
+	}
+
+	get_sock_dir(&old_cluster);
+	get_control_data(&old_cluster);
+
+	prep_status("Examining old cluster settings");
+	if (!user_opts.live_check)
+		start_postmaster(&old_cluster, true);
+	get_template0_info(&old_cluster);
+	if (!user_opts.live_check)
+		stop_postmaster(false);
+	check_ok();
+}
+
+
+/*
+ * Build the initdb command using the old cluster's settings and any
+ * arguments supplied with --initdb-options.
+ */
+static void
+build_new_cluster_initdb_cmd(PQExpBuffer cmd)
+{
+	DbLocaleInfo *locale = old_cluster.template0;
+	const char *encoding_name = pg_encoding_to_char(locale->db_encoding);
+	char		initdb_path[MAXPGPATH];
+
+	snprintf(initdb_path, sizeof(initdb_path), "%s/initdb", new_cluster.bindir);
+
+	prep_status("Constructing new cluster initdb command");
+
+	initPQExpBuffer(cmd);
+
+	/*
+	 * Build the command with appendShellString() for every value that comes
+	 * from outside our control: the username is from the command line, and
+	 * the encoding and locale strings are read from the old cluster's
+	 * template0. This prevents shell metacharacters in any of them from
+	 * breaking out of their argument when the command is run through the
+	 * shell.
+	 */
+	appendShellString(cmd, initdb_path);
+	appendPQExpBufferStr(cmd, " -N -D ");
+	appendShellString(cmd, new_cluster.pgdata);
+	appendPQExpBufferStr(cmd, " -U ");
+	appendShellString(cmd, os_info.user);
+	appendPQExpBuffer(cmd, " --wal-segsize=%u",
+					  old_cluster.controldata.walseg / (1024 * 1024));
+
+	/*
+	 * Pass --data-checksums or --no-data-checksums explicitly.  Starting from
+	 * PG18, initdb enables checksums by default, so we must mirror the old
+	 * cluster's setting to avoid a mismatch that check_control_data() would
+	 * reject.
+	 */
+	if (old_cluster.controldata.data_checksum_version != 0)
+		appendPQExpBufferStr(cmd, " --data-checksums");
+	else
+		appendPQExpBufferStr(cmd, " --no-data-checksums");
+
+	appendPQExpBufferStr(cmd, " --encoding=");
+	appendShellString(cmd, encoding_name);
+	appendPQExpBufferStr(cmd, " --locale-provider=");
+	appendShellString(cmd, collprovider_name(locale->db_collprovider));
+	appendPQExpBufferStr(cmd, " --lc-collate=");
+	appendShellString(cmd, locale->db_collate);
+	appendPQExpBufferStr(cmd, " --lc-ctype=");
+	appendShellString(cmd, locale->db_ctype);
+
+	if (locale->db_locale)
+	{
+		if (locale->db_collprovider == COLLPROVIDER_ICU)
+		{
+			appendPQExpBufferStr(cmd, " --icu-locale=");
+			appendShellString(cmd, locale->db_locale);
+		}
+		else if (locale->db_collprovider == COLLPROVIDER_BUILTIN)
+		{
+			appendPQExpBufferStr(cmd, " --builtin-locale=");
+			appendShellString(cmd, locale->db_locale);
+		}
+	}
+
+	for (int i = 0; i < user_opts.num_initdb_options; i++)
+	{
+		appendPQExpBufferChar(cmd, ' ');
+		appendShellString(cmd, user_opts.initdb_options[i]);
+	}
+
+	check_ok();
+}
+
+
+/* Initialize the new cluster before checking compatibility with the old cluster. */
+static void
+create_new_cluster_via_initdb(void)
+{
+	PQExpBufferData cmd;
+
+	get_old_cluster_initdb_info();
+	build_new_cluster_initdb_cmd(&cmd);
+
+	prep_status("Creating new cluster with initdb");
+
+	exec_prog(UTILITY_LOG_FILE, NULL, true, true, "%s", cmd.data);
+
+	termPQExpBuffer(&cmd);
+	check_ok();
+}
+
+
+
+
+static void
+check_clusters_stopped(void)
+{
 	/* no postmasters should be running, except for a live check */
 	if (pid_lock_file_exists(old_cluster.pgdata))
 	{
diff --git a/src/bin/pg_upgrade/pg_upgrade.h b/src/bin/pg_upgrade/pg_upgrade.h
index 4cb79bb780e612e54898b1859003345fc8094de2..f0c4dfc7129f78acd51bca0180923f5dc606fa1d 100644
--- a/src/bin/pg_upgrade/pg_upgrade.h
+++ b/src/bin/pg_upgrade/pg_upgrade.h
@@ -32,7 +32,7 @@
 
 /*
  * Base directories that include all the files generated internally, from the
- * root path of the new cluster.  The paths are dynamically built as of
+ * selected output root.  The paths are dynamically built as of
  * BASE_OUTPUTDIR/$timestamp/{LOG_OUTPUTDIR,DUMP_OUTPUTDIR} to ensure their
  * uniqueness in each run.
  */
@@ -314,7 +314,8 @@ typedef struct
  */
 typedef struct
 {
-	bool		check;			/* check clusters only, don't change any data */
+	bool		check;			/* check clusters without performing the
+								 * upgrade */
 	bool		live_check;		/* check clusters only, old server is running */
 	bool		do_sync;		/* flush changes to disk */
 	transferMode transfer_mode; /* copy files or link them? */
@@ -325,6 +326,11 @@ typedef struct
 	int			char_signedness;	/* default char signedness: -1 for initial
 									 * value, 1 for "signed" and 0 for
 									 * "unsigned" */
+	bool		initdb_new_cluster; /* run initdb before compatibility checks */
+	bool		initdb_options_given;	/* --initdb-options given, even if
+										 * empty */
+	char	  **initdb_options; /* additional arguments to initdb */
+	int			num_initdb_options;
 } UserOpts;
 
 typedef struct
@@ -391,7 +397,9 @@ void		generate_old_dump(void);
 
 bool		exec_prog(const char *log_filename, const char *opt_log_file,
 					  bool report_error, bool exit_on_error, const char *fmt, ...) pg_attribute_printf(5, 6);
-void		verify_directories(void);
+void		check_current_dir_write_permissions(void);
+void		check_bin_dir(ClusterInfo *cluster, bool check_versions);
+void		check_data_dir(ClusterInfo *cluster);
 bool		pid_lock_file_exists(const char *datadir);
 
 
@@ -423,6 +431,7 @@ FileNameMap *gen_db_file_maps(DbInfo *old_db,
 							  DbInfo *new_db, int *nmaps, const char *old_pgdata,
 							  const char *new_pgdata);
 void		get_db_rel_and_slot_infos(ClusterInfo *cluster);
+void		get_template0_info(ClusterInfo *cluster);
 int			count_old_cluster_logical_slots(void);
 void		get_subscription_info(ClusterInfo *cluster);
 
@@ -432,6 +441,10 @@ void		parseCommandLine(int argc, char *argv[]);
 void		adjust_data_dir(ClusterInfo *cluster);
 void		get_sock_dir(ClusterInfo *cluster);
 
+/* pg_upgrade.c */
+
+void		sync_new_cluster(bool sync_data_files);
+
 /* relfilenumber.c */
 
 void		transfer_all_new_tablespaces(DbInfoArr *old_db_arr,
diff --git a/src/bin/pg_upgrade/t/002_pg_upgrade.pl b/src/bin/pg_upgrade/t/002_pg_upgrade.pl
index 9590625fc320352bfc7f3bcde62557b264b60eef..be57b2d838cf0e4b28ee670991c315e72f35049c 100644
--- a/src/bin/pg_upgrade/t/002_pg_upgrade.pl
+++ b/src/bin/pg_upgrade/t/002_pg_upgrade.pl
@@ -561,35 +561,12 @@ $oldnode->safe_psql(
 # Upgrade the instance.
 $oldnode->stop;
 
-# Cause a failure at the start of pg_upgrade, this should create the logging
-# directory pg_upgrade_output.d but leave it around.  Keep --check for an
-# early exit.
-command_checks_all(
-	[
-		'pg_upgrade', '--no-sync',
-		'--old-datadir' => $oldnode->data_dir,
-		'--new-datadir' => $newnode->data_dir,
-		'--old-bindir' => $oldbindir . '/does/not/exist/',
-		'--new-bindir' => $newbindir,
-		'--socketdir' => $newnode->host,
-		'--old-port' => $oldnode->port,
-		'--new-port' => $newnode->port,
-		$mode, '--check',
-	],
-	1,
-	[qr{check for ".*?does/not/exist" failed}],
-	[],
-	'run of pg_upgrade --check for new instance with incorrect binary path');
-ok(-d $newnode->data_dir . "/pg_upgrade_output.d",
-	"pg_upgrade_output.d/ not removed after pg_upgrade failure");
-rmtree($newnode->data_dir . "/pg_upgrade_output.d");
-
 # Check that pg_upgrade aborts when encountering an invalid database
 # (However, versions that were out of support by commit c66a7d75e652 don't
 # know how to do this, so skip this test there.)
 SKIP:
 {
-	skip "database invalidation not implemented", 1
+	skip "database invalidation not implemented", 4
 	  if $oldnode->pg_version < 11;
 
 	command_checks_all(
@@ -608,6 +585,12 @@ SKIP:
 		[qr/datconnlimit/],
 		[qr/^$/],
 		'invalid database causes failure');
+
+	# Check that the failure creates the logging directory pg_upgrade_output.d
+	# and leaves it around
+	ok(-d $newnode->data_dir . "/pg_upgrade_output.d",
+		"pg_upgrade_output.d/ not removed after pg_upgrade failure");
+
 	rmtree($newnode->data_dir . "/pg_upgrade_output.d");
 }
 
diff --git a/src/bin/pg_upgrade/t/009_initdb_option.pl b/src/bin/pg_upgrade/t/009_initdb_option.pl
new file mode 100644
index 0000000000000000000000000000000000000000..8438e92c4e634db7d5e326ae7b5c44344b55e7a1
--- /dev/null
+++ b/src/bin/pg_upgrade/t/009_initdb_option.pl
@@ -0,0 +1,502 @@
+# Copyright (c) 2026, PostgreSQL Global Development Group
+
+# Test pg_upgrade's --initdb and --initdb-options options.
+
+use strict;
+use warnings FATAL => 'all';
+
+use Config;
+use Cwd qw(abs_path);
+use PostgreSQL::Test::Cluster;
+use PostgreSQL::Test::Utils;
+use Test::More;
+
+# Use nondefault settings to verify which settings --initdb carries over to the
+# new cluster.
+my $oldnode = PostgreSQL::Test::Cluster->new('old_node');
+$oldnode->init(
+	extra => [
+		'--allow-group-access',
+		'--no-data-checksums',
+		'--wal-segsize' => '2',
+		'--locale' => 'C',
+	]);
+$oldnode->start;
+$oldnode->safe_psql('postgres',
+		"CREATE TABLE t (id int primary key, note text); "
+	  . "INSERT INTO t SELECT g, 'row ' || g FROM generate_series(1, 100) g; "
+	  . "CREATE DATABASE extra_db;");
+my $rows_before = $oldnode->safe_psql('postgres', 'SELECT count(*) FROM t');
+is($rows_before, '100', 'old cluster has expected rows before upgrade');
+
+# Capture the old settings for the post-upgrade comparison.
+my %setting_queries = (
+	data_checksums => 'SHOW data_checksums',
+	wal_segment_size => 'SHOW wal_segment_size',
+	encoding =>
+	  "SELECT pg_encoding_to_char(encoding) FROM pg_database WHERE datname = 'template0'",
+	collation =>
+	  "SELECT datcollate FROM pg_database WHERE datname = 'template0'",
+	ctype => "SELECT datctype FROM pg_database WHERE datname = 'template0'",
+	provider =>
+	  "SELECT datlocprovider FROM pg_database WHERE datname = 'template0'",);
+my %old_settings;
+for my $setting (sort keys %setting_queries)
+{
+	$old_settings{$setting} =
+	  $oldnode->safe_psql('postgres', $setting_queries{$setting});
+}
+$oldnode->stop;
+
+# Leave the new cluster uninitialized so pg_upgrade --initdb creates it.
+my $newnode = PostgreSQL::Test::Cluster->new('new_node');
+
+my $oldbindir = $oldnode->config_data('--bindir');
+my $newbindir = $newnode->config_data('--bindir');
+
+sub upgrade_command
+{
+	my ($old, $new, @extra) = @_;
+	return [
+		'pg_upgrade', '--no-sync', '--initdb',
+		'--old-datadir' => $old->data_dir,
+		'--new-datadir' => $new->data_dir,
+		'--old-bindir' => $oldbindir,
+		'--new-bindir' => $newbindir,
+		'--socketdir' => $new->host,
+		'--old-port' => $old->port,
+		'--new-port' => $new->port,
+		@extra,
+	];
+}
+
+# Configure the connection settings normally written by init(), without
+# changing initdb's pg_hba.conf.
+sub start_new_cluster
+{
+	my ($node) = @_;
+	my $listen = $PostgreSQL::Test::Cluster::use_tcp ? $node->host : '';
+	my $socketdir = $PostgreSQL::Test::Cluster::use_tcp ? '' : $node->host;
+	$node->append_conf('postgresql.conf',
+			'port = '
+		  . $node->port
+		  . "\nlisten_addresses = '$listen'\nunix_socket_directories = '$socketdir'"
+	);
+	$node->start;
+}
+
+ok(!-d $newnode->data_dir,
+	'new cluster data directory does not exist before --initdb');
+
+# Run pg_upgrade --initdb from a writable directory for its
+# pg_upgrade_output.d logs.
+# Pass the server-only option -F through -O to verify that it reaches
+# the new server without being passed to initdb.
+# Repeated --initdb-options must preserve argument order and quoted values in
+# the configuration used after the upgrade.
+chdir ${PostgreSQL::Test::Utils::tmp_check};
+
+command_ok(
+	upgrade_command(
+		$oldnode, $newnode,
+		'--new-options' => '-F',
+		'--initdb-options' =>
+		  '-c huge_pages=try -c custom.initdb_first=first',
+		'--initdb-options' =>
+		  q{-c huge_pages=off --set=custom.initdb_first=last -c "custom.initdb_text=space, apostrophe's $libdir" -c custom.initdb_path=C:\new\path -c custom.initdb_empty=""},
+		'--initdb-options' =>
+		  q{-c 'custom.initdb_single=single quoted $libdir' -c "custom.initdb_escaped=quote\" slash\\\\" -c custom.initdb_join='joined 'pieces -c custom.initdb_space=escaped\ space},
+	),
+	'run of pg_upgrade --initdb with -O creates and upgrades the new cluster'
+);
+
+# Check before the test harness starts the target and overwrites this file.
+like(slurp_file($newnode->data_dir . '/postmaster.opts'),
+	qr/(?:^|\s)"-F"(?:\s|$)/, '-O option reached the target postmaster');
+
+ok(-f $newnode->data_dir . '/PG_VERSION',
+	'new cluster data directory created by --initdb');
+
+# Group access requires an explicit initdb option, even if the old cluster
+# allows it.
+SKIP:
+{
+	skip "unix-style permissions not supported on Windows", 1
+	  if ($windows_os || $Config::Config{osname} eq 'cygwin');
+
+	my $new_mode = (stat($newnode->data_dir))[2] & 0777;
+	is($new_mode, 0700, 'new cluster does not inherit PGDATA group access');
+}
+
+# --initdb logs use pg_upgrade_output.d with the normal cleanup and --retain
+# handling.  Check that no separate <pgdata>.initdb_log directory remains
+# beside the new data directory.
+ok(!-d $newnode->data_dir . '.initdb_log',
+	'--initdb does not leave a sibling log directory');
+
+start_new_cluster($newnode);
+
+my %expected_settings = (
+	huge_pages => 'off',
+	'custom.initdb_first' => 'last',
+	'custom.initdb_text' => q{space, apostrophe's $libdir},
+	'custom.initdb_path' => q{C:\new\path},
+	'custom.initdb_empty' => '',
+	'custom.initdb_single' => q{single quoted $libdir},
+	'custom.initdb_escaped' => "quote\" slash\\",
+	'custom.initdb_join' => 'joined pieces',
+	'custom.initdb_space' => 'escaped space',);
+for my $setting (sort keys %expected_settings)
+{
+	is( $newnode->safe_psql('postgres', "SHOW $setting"),
+		$expected_settings{$setting},
+		"$setting survives initialization and upgrade");
+}
+
+my $rows_after = $newnode->safe_psql('postgres', 'SELECT count(*) FROM t');
+is($rows_after, '100', 'user data survived --initdb upgrade');
+
+my $has_extra = $newnode->safe_psql('postgres',
+	"SELECT count(*) FROM pg_database WHERE datname = 'extra_db'");
+is($has_extra, '1', 'user database carried over by --initdb upgrade');
+
+# The new cluster must match the old checksum, WAL segment, encoding, and
+# locale settings.
+for my $setting (sort keys %setting_queries)
+{
+	is($newnode->safe_psql('postgres', $setting_queries{$setting}),
+		$old_settings{$setting}, "$setting propagated by --initdb");
+}
+
+$newnode->stop;
+
+# Check that pg_upgrade rejects an existing cluster before invoking initdb.
+# The error is reported on stdout.
+command_checks_all(upgrade_command($oldnode, $newnode),
+	1, [qr/is not empty/], [qr/^$/],
+	'--initdb refuses to overwrite an existing cluster');
+
+# Reject overlap with the output directory before creating logs or starting
+# either server, for both a real upgrade and --check.
+my $original_cwd = abs_path('.');
+for my $check (0, 1)
+{
+	for my $target ('.', 'pg_upgrade_output.d', 'pg_upgrade_output.d/new')
+	{
+		my $overlap_cwd = PostgreSQL::Test::Utils::tempdir;
+		chdir $overlap_cwd or die "could not change to $overlap_cwd: $!";
+		my $mode = $check ? '--check --initdb' : '--initdb';
+		command_checks_all(
+			upgrade_command(
+				$oldnode, $newnode,
+				'--new-datadir' => $target,
+				$check ? '--check' : ()),
+			1,
+			[qr/overlaps output directory/],
+			[qr/^$/],
+			"$mode rejects target $target overlapping its output directory");
+		is_deeply([ grep { $_ ne '.' && $_ ne '..' } slurp_dir('.') ],
+			[], "$mode overlap failure leaves the working directory empty");
+		chdir $original_cwd or die "could not change to $original_cwd: $!";
+	}
+}
+
+# Validate the new binaries before initialization.
+my $empty_bindir = PostgreSQL::Test::Utils::tempdir;
+command_checks_all(
+	upgrade_command(
+		$oldnode, $newnode,
+		'--new-datadir' => $newnode->data_dir . '_nonexistent',
+		'--new-bindir' => $empty_bindir),
+	1,
+	[qr/check for .*postgres.* failed/],
+	[qr/^$/],
+	'--initdb fails early when the new binaries are missing');
+
+# --check --initdb initializes the new cluster and runs compatibility checks
+# on both clusters.
+my $checked_target = $newnode->data_dir . '_check';
+command_checks_all(
+	upgrade_command(
+		$oldnode, $newnode,
+		'--new-datadir' => $checked_target,
+		'--check'),
+	0,
+	[qr/Clusters are compatible/],
+	[qr/^$/],
+	'--check --initdb initializes the target and checks both clusters');
+
+ok(-f "$checked_target/PG_VERSION",
+	'successful check retains the new cluster');
+ok( !-f "$checked_target/postmaster.pid",
+	'successful check stops the new server');
+
+# Without -B, --initdb must derive the new bindir from the original argv[0],
+# even when that directory is not in PATH.
+SKIP:
+{
+	skip "restricted PATH test is not portable to Windows", 3 if $windows_os;
+
+	local %ENV = %ENV;
+	$ENV{PATH} = '/usr/bin:/bin';
+	command_checks_all(
+		[
+			abs_path("$newbindir/pg_upgrade"), '--no-sync',
+			'--old-datadir' => $oldnode->data_dir,
+			'--new-datadir' => $newnode->data_dir . '_no_new_bindir',
+			'--old-bindir' => $oldbindir,
+			'--socketdir' => $newnode->host,
+			'--old-port' => $oldnode->port,
+			'--new-port' => $newnode->port,
+			'--initdb',
+			'--check',
+		],
+		0,
+		[qr/Clusters are compatible/],
+		[qr/^$/],
+		'--initdb derives the new bindir from an absolute argv[0]');
+}
+
+# --check --initdb must accept a running old server and leave it running.
+# Use a different port for the new server.
+SKIP:
+{
+	skip "Timing issues with live server detection on Windows", 4
+	  if $windows_os;
+
+	$oldnode->start;
+	command_checks_all(
+		upgrade_command(
+			$oldnode, $newnode,
+			'--new-datadir' => $newnode->data_dir . '_live_check',
+			'--check'),
+		0,
+		[qr/Clusters are compatible/],
+		[qr/^$/],
+		'--check --initdb accepts a live source');
+	is($oldnode->safe_psql('postgres', 'SELECT 1'),
+		'1', 'live source remains running after --check --initdb');
+	$oldnode->stop;
+}
+
+# Both upgrade and --check must reject regproc columns in user tables and
+# retain the initialized new cluster.
+$oldnode->start;
+$oldnode->safe_psql('postgres', 'CREATE TABLE bad (c regproc)');
+$oldnode->stop;
+
+for my $check (0, 1)
+{
+	my $target = $newnode->data_dir . "_incompatible_$check";
+	my $mode = $check ? '--check --initdb' : '--initdb';
+	command_checks_all(
+		upgrade_command(
+			$oldnode, $newnode,
+			'--new-datadir' => $target,
+			$check ? '--check' : ()),
+		1,
+		[qr/failed check: Checking for reg\* data types in user tables/],
+		[qr/^$/],
+		"$mode rejects an incompatible old cluster");
+	ok(-f "$target/PG_VERSION", "failed $mode retains the new cluster");
+}
+
+# Require --initdb even when --initdb-options is empty.
+# Reject invalid quoting and line breaks before examining either cluster.
+command_checks_all(
+	[ 'pg_upgrade', '--initdb-options=' ],
+	1,
+	[qr/--initdb-options requires --initdb/],
+	[qr/^$/],
+	'--initdb-options requires --initdb even for an empty argument');
+
+for my $case (
+	[
+		q{-c 'huge_pages=off}, qr/unterminated quote/,
+		'unclosed single quote'
+	],
+	[
+		q{-c "huge_pages=off}, qr/unterminated quote/,
+		'unclosed double quote'
+	],
+	[ "-c huge_pages=off\\", qr/trailing backslash/, 'trailing escape' ],
+	[ "-c huge_pages=off\n", qr/newline or carriage return/, 'newline' ])
+{
+	command_checks_all(
+		[ 'pg_upgrade', '--initdb', "--initdb-options=$case->[0]" ],
+		1, [ $case->[1] ],
+		[qr/^$/], "reject $case->[2]");
+}
+
+sub option_quote
+{
+	my ($value) = @_;
+	$value =~ s/'/'\\''/g;
+	return "'$value'";
+}
+
+# Detach test-owned WAL junctions before native Perl recursively removes
+# the node. rmdir removes the junction itself, leaving its target intact.
+my @test_wal_junctions;
+
+sub detach_test_wal_junction
+{
+	my ($node, $wal) = @_;
+	return unless $windows_os;
+	return if defined $ENV{PG_TEST_NOCLEAN};
+	return unless PostgreSQL::Test::Utils::all_tests_passing();
+	BAIL_OUT 'WAL junction cleanup requires a stopped node'
+	  if -f $node->data_dir . '/postmaster.pid';
+	ok(rmdir($node->data_dir . '/pg_wal'), 'detach test-owned WAL junction');
+	ok(-d $wal, 'detaching WAL junction preserves its target');
+}
+
+# test_slru rejects LOAD unless preloaded.  The new cluster must preload it
+# for pg_upgrade's loadable-library check to pass.
+my $preload_old = PostgreSQL::Test::Cluster->new('preload_old');
+$preload_old->init;
+$preload_old->append_conf('postgresql.conf',
+	"shared_preload_libraries = 'test_slru'");
+$preload_old->start;
+$preload_old->safe_psql('postgres', 'CREATE EXTENSION test_slru');
+my $quoted_superuser =
+  $preload_old->safe_psql('postgres', 'SELECT quote_ident(current_user)');
+# This password is used only by the temporary test clusters.
+my $password = 'initdb-options-test-password';
+$preload_old->safe_psql('postgres',
+	"ALTER ROLE $quoted_superuser PASSWORD '$password'");
+$preload_old->stop;
+
+my $preload_missing = PostgreSQL::Test::Cluster->new('preload_missing');
+my $preload_missing_wal = $preload_missing->basedir . '/wal';
+command_checks_all(
+	upgrade_command(
+		$preload_old,
+		$preload_missing,
+		'--check',
+		'--initdb-options' => '--waldir=' . option_quote($preload_missing_wal)
+	),
+	1,
+	[qr/references loadable libraries that are missing/],
+	[qr/^$/],
+	'--check --initdb checks required libraries in the new cluster');
+ok( -f $preload_missing->data_dir . '/PG_VERSION',
+	'failed preload check retains the new cluster');
+ok(-d $preload_missing_wal, 'failed preload check retains the WAL directory');
+ok( !-f $preload_missing->data_dir . '/postmaster.pid',
+	'failed preload check stops the new server');
+push @test_wal_junctions, [ $preload_missing, $preload_missing_wal ];
+
+my $credential_dir = PostgreSQL::Test::Utils::tempdir;
+my $pwfile = "$credential_dir/initdb.pw";
+append_to_file($pwfile, "$password\n");
+chmod(0600, $pwfile) or die "could not protect $pwfile: $!";
+my $pgpass = "$credential_dir/pgpass";
+append_to_file($pgpass, "*:*:*:*:$password\n");
+chmod(0600, $pgpass) or die "could not protect $pgpass: $!";
+
+my $auth_options =
+  q{-c shared_preload_libraries=$libdir/test_slru --auth-local=scram-sha-256 --auth-host=scram-sha-256 --pwfile="}
+  . $pwfile . '"';
+
+{
+	local $ENV{PGPASSFILE} = "$credential_dir/no-password-file";
+	delete local $ENV{PGPASSWORD};
+	my $auth_missing = PostgreSQL::Test::Cluster->new('auth_missing');
+	command_checks_all(
+		upgrade_command(
+			$preload_old, $auth_missing,
+			'--initdb-options' => $auth_options),
+		1,
+		[qr/fe_sendauth: no password supplied/],
+		[qr/^$/],
+		'password authentication is not weakened when credentials are missing'
+	);
+	ok( -f $auth_missing->data_dir . '/PG_VERSION',
+		'authentication failure retains the new cluster');
+	ok( !-f $auth_missing->data_dir . '/postmaster.pid',
+		'authentication failure stops the new server');
+}
+
+{
+	local $ENV{PGPASSFILE} = $pgpass;
+	my $preload_new = PostgreSQL::Test::Cluster->new('preload_new');
+	my $wal = $preload_new->basedir . '/wal with spaces';
+	command_ok(
+		upgrade_command(
+			$preload_old,
+			$preload_new,
+			'--initdb-options' => $auth_options
+			  . ' --waldir='
+			  . option_quote($wal)),
+		'initdb options support a preload-only extension and password authentication'
+	);
+	ok(-d $wal, 'initdb uses the requested WAL directory');
+
+	my $hba = slurp_file($preload_new->data_dir . '/pg_hba.conf');
+	my @rules = grep { /\S/ && !/^\s*#/ } split(/\n/, $hba);
+	ok(!(grep { !/\bscram-sha-256\s*$/ } @rules),
+		'all generated authentication rules keep the requested method');
+  SKIP:
+	{
+		skip 'unix-style permissions not supported on Windows', 1
+		  if ($windows_os || $Config::Config{osname} eq 'cygwin');
+		is((stat($preload_new->data_dir))[2] & 0777,
+			0700,
+			'new cluster uses owner-only data directory mode by default');
+	}
+
+	start_new_cluster($preload_new);
+	is( $preload_new->safe_psql('postgres', 'SHOW shared_preload_libraries'),
+		q{$libdir/test_slru},
+		'preload setting preserves literal $libdir');
+	$preload_new->safe_psql('postgres',
+		"SELECT test_slru_page_write(0, 'upgraded')");
+	is( $preload_new->safe_psql('postgres', 'SELECT test_slru_page_read(0)'),
+		'upgraded',
+		'restored preload-only extension is usable');
+	$preload_new->stop;
+	push @test_wal_junctions, [ $preload_new, $wal ];
+}
+
+# Link and swap retain old file modes.
+SKIP:
+{
+	skip 'Unix permissions are not supported on this platform', 1
+	  if $windows_os || $Config::Config{osname} eq 'cygwin';
+
+	subtest 'group access with link and swap' => sub {
+		for my $mode ('--link', '--swap')
+		{
+			my $name = substr($mode, 2);
+			my $old = PostgreSQL::Test::Cluster->new("old_$name");
+			my $new = PostgreSQL::Test::Cluster->new("new_$name");
+			$old->init(extra => ['--allow-group-access']);
+			$old->start;
+			$old->safe_psql('postgres',
+				'CREATE TABLE permissions (id integer); INSERT INTO permissions VALUES (1)'
+			);
+			my $relpath = $old->safe_psql('postgres',
+				"SELECT pg_relation_filepath('permissions')");
+			$old->stop;
+			command_ok(
+				upgrade_command(
+					$old, $new,
+					$mode, '--initdb-options' => '--allow-group-access'),
+				"$mode accepts matching group access settings");
+			is((stat($new->data_dir))[2] & 0777,
+				0750, "$mode preserves data directory permissions");
+			is((stat($new->data_dir . "/$relpath"))[2] & 0777,
+				0640, "$mode preserves relation permissions");
+		}
+		done_testing();
+	};
+}
+
+# Match Cluster.pm: preserve the original cluster layout on a failed test.
+foreach my $junction (@test_wal_junctions)
+{
+	detach_test_wal_junction(@{$junction});
+}
+
+done_testing();
diff --git a/src/bin/pg_upgrade/util.c b/src/bin/pg_upgrade/util.c
index e7d7ab56445224df5abf4ad46782c46cf307486c..47705b6853cfd3763ad249f87d8887a83da201c5 100644
--- a/src/bin/pg_upgrade/util.c
+++ b/src/bin/pg_upgrade/util.c
@@ -57,12 +57,13 @@ end_progress_output(void)
 }
 
 /*
- * Remove any logs generated internally.  To be used once when exiting.
+ * Close the internal log and remove output directories unless --retain is set.
  */
 void
 cleanup_output_dirs(void)
 {
 	fclose(log_opts.internal);
+	log_opts.internal = NULL;
 
 	/* Remove dump and log files? */
 	if (log_opts.retain)
