Skip to content

Update postgres #19217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 9, 2025
Merged

Update postgres #19217

merged 1 commit into from
Jun 9, 2025

Conversation

yosifkit
Copy link
Member

@yosifkit yosifkit commented Jun 6, 2025

Changes:

Docs:

Changes:

- docker-library/postgres@6ec0e42: Merge pull request docker-library/postgres#1259 from infosiftr/pgdata-cluster
- docker-library/postgres@2c6fe8d: Add logic to error out on detection of "old databases"
- docker-library/postgres@b9a533c: Change `PGDATA` in 18+ to `/var/lib/postgresql/MAJOR/docker`
- docker-library/postgres@c257dcc: Merge pull request docker-library/postgres#1344 from reneleonhardt/chore/add-postgres-18
- docker-library/postgres@d1e97f2: add postgres 18 beta1
Copy link

github-actions bot commented Jun 6, 2025

Diff for 0090ad9:
diff --git a/_bashbrew-cat b/_bashbrew-cat
index 59afc04..a697ae9 100644
--- a/_bashbrew-cat
+++ b/_bashbrew-cat
@@ -3,100 +3,120 @@ GitRepo: https://github.com/docker-library/postgres.git
 
 Tags: 13.21, 13, 13.21-bookworm, 13-bookworm
 Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, mips64le, ppc64le, s390x
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 13/bookworm
 
 Tags: 13.21-alpine3.21, 13-alpine3.21
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 13/alpine3.21
 
 Tags: 13.21-alpine3.22, 13-alpine3.22, 13.21-alpine, 13-alpine
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 13/alpine3.22
 
 Tags: 13.21-bullseye, 13-bullseye
 Architectures: amd64, arm32v7, arm64v8, i386
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 13/bullseye
 
 Tags: 14.18, 14, 14.18-bookworm, 14-bookworm
 Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, mips64le, ppc64le, s390x
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 14/bookworm
 
 Tags: 14.18-alpine3.21, 14-alpine3.21
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 14/alpine3.21
 
 Tags: 14.18-alpine3.22, 14-alpine3.22, 14.18-alpine, 14-alpine
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 14/alpine3.22
 
 Tags: 14.18-bullseye, 14-bullseye
 Architectures: amd64, arm32v7, arm64v8, i386
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 14/bullseye
 
 Tags: 15.13, 15, 15.13-bookworm, 15-bookworm
 Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, mips64le, ppc64le, s390x
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 15/bookworm
 
 Tags: 15.13-alpine3.21, 15-alpine3.21
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 15/alpine3.21
 
 Tags: 15.13-alpine3.22, 15-alpine3.22, 15.13-alpine, 15-alpine
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 15/alpine3.22
 
 Tags: 15.13-bullseye, 15-bullseye
 Architectures: amd64, arm32v7, arm64v8, i386
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 15/bullseye
 
 Tags: 16.9, 16, 16.9-bookworm, 16-bookworm
 Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, mips64le, ppc64le, s390x
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 16/bookworm
 
 Tags: 16.9-alpine3.21, 16-alpine3.21
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 16/alpine3.21
 
 Tags: 16.9-alpine3.22, 16-alpine3.22, 16.9-alpine, 16-alpine
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 16/alpine3.22
 
 Tags: 16.9-bullseye, 16-bullseye
 Architectures: amd64, arm32v7, arm64v8, i386
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 16/bullseye
 
 Tags: 17.5, 17, latest, 17.5-bookworm, 17-bookworm, bookworm
 Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, mips64le, ppc64le, s390x
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 17/bookworm
 
 Tags: 17.5-alpine3.21, 17-alpine3.21, alpine3.21
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 17/alpine3.21
 
 Tags: 17.5-alpine3.22, 17-alpine3.22, alpine3.22, 17.5-alpine, 17-alpine, alpine
 Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
-GitCommit: 172d9e7dbcff681ed65899f9bb01ba8bcc5fc063
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 17/alpine3.22
 
 Tags: 17.5-bullseye, 17-bullseye, bullseye
 Architectures: amd64, arm32v7, arm64v8, i386
-GitCommit: d9c4773ca5dc96692188c458f281d217d78b14d9
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
 Directory: 17/bullseye
+
+Tags: 18beta1, 18beta1-bookworm
+Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, mips64le, ppc64le, s390x
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
+Directory: 18/bookworm
+
+Tags: 18beta1-alpine3.21
+Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
+Directory: 18/alpine3.21
+
+Tags: 18beta1-alpine3.22, 18beta1-alpine
+Architectures: amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, riscv64, s390x
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
+Directory: 18/alpine3.22
+
+Tags: 18beta1-bullseye
+Architectures: amd64, arm32v7, arm64v8, i386
+GitCommit: 2c6fe8daca9d2ccc143afe6b1cdbc1eb80379d3f
+Directory: 18/bullseye
diff --git a/_bashbrew-list b/_bashbrew-list
index c11ecb5..33f5541 100644
--- a/_bashbrew-list
+++ b/_bashbrew-list
@@ -58,6 +58,12 @@ postgres:17.5-alpine3.21
 postgres:17.5-alpine3.22
 postgres:17.5-bookworm
 postgres:17.5-bullseye
+postgres:18beta1
+postgres:18beta1-alpine
+postgres:18beta1-alpine3.21
+postgres:18beta1-alpine3.22
+postgres:18beta1-bookworm
+postgres:18beta1-bullseye
 postgres:alpine
 postgres:alpine3.21
 postgres:alpine3.22
diff --git a/_bashbrew-list-build-order b/_bashbrew-list-build-order
index 5c69527..86b2993 100644
--- a/_bashbrew-list-build-order
+++ b/_bashbrew-list-build-order
@@ -14,6 +14,10 @@ postgres:16-alpine
 postgres:16-alpine3.21
 postgres:16-bookworm
 postgres:16-bullseye
+postgres:18beta1-alpine
+postgres:18beta1-alpine3.21
+postgres:18beta1-bookworm
+postgres:18beta1-bullseye
 postgres:alpine
 postgres:alpine3.21
 postgres:bookworm
diff --git a/postgres_13-alpine/docker-ensure-initdb.sh b/postgres_13-alpine/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-alpine/docker-ensure-initdb.sh
+++ b/postgres_13-alpine/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine/docker-entrypoint.sh b/postgres_13-alpine/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-alpine/docker-entrypoint.sh
+++ b/postgres_13-alpine/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine3.21/docker-ensure-initdb.sh b/postgres_13-alpine3.21/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_13-alpine3.21/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine3.21/docker-entrypoint.sh b/postgres_13-alpine3.21/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-alpine3.21/docker-entrypoint.sh
+++ b/postgres_13-alpine3.21/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-bookworm/docker-ensure-initdb.sh b/postgres_13-bookworm/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-bookworm/docker-ensure-initdb.sh
+++ b/postgres_13-bookworm/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-bookworm/docker-entrypoint.sh b/postgres_13-bookworm/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-bookworm/docker-entrypoint.sh
+++ b/postgres_13-bookworm/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-bullseye/docker-ensure-initdb.sh b/postgres_13-bullseye/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-bullseye/docker-ensure-initdb.sh
+++ b/postgres_13-bullseye/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-bullseye/docker-entrypoint.sh b/postgres_13-bullseye/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-bullseye/docker-entrypoint.sh
+++ b/postgres_13-bullseye/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-alpine/docker-ensure-initdb.sh b/postgres_14-alpine/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_14-alpine/docker-ensure-initdb.sh
+++ b/postgres_14-alpine/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-alpine/docker-entrypoint.sh b/postgres_14-alpine/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_14-alpine/docker-entrypoint.sh
+++ b/postgres_14-alpine/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-alpine3.21/docker-ensure-initdb.sh b/postgres_14-alpine3.21/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_14-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_14-alpine3.21/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-alpine3.21/docker-entrypoint.sh b/postgres_14-alpine3.21/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_14-alpine3.21/docker-entrypoint.sh
+++ b/postgres_14-alpine3.21/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-bookworm/docker-ensure-initdb.sh b/postgres_14-bookworm/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_14-bookworm/docker-ensure-initdb.sh
+++ b/postgres_14-bookworm/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-bookworm/docker-entrypoint.sh b/postgres_14-bookworm/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_14-bookworm/docker-entrypoint.sh
+++ b/postgres_14-bookworm/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-bullseye/docker-ensure-initdb.sh b/postgres_14-bullseye/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_14-bullseye/docker-ensure-initdb.sh
+++ b/postgres_14-bullseye/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-bullseye/docker-entrypoint.sh b/postgres_14-bullseye/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_14-bullseye/docker-entrypoint.sh
+++ b/postgres_14-bullseye/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-alpine/docker-ensure-initdb.sh b/postgres_15-alpine/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_15-alpine/docker-ensure-initdb.sh
+++ b/postgres_15-alpine/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-alpine/docker-entrypoint.sh b/postgres_15-alpine/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_15-alpine/docker-entrypoint.sh
+++ b/postgres_15-alpine/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-alpine3.21/docker-ensure-initdb.sh b/postgres_15-alpine3.21/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_15-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_15-alpine3.21/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-alpine3.21/docker-entrypoint.sh b/postgres_15-alpine3.21/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_15-alpine3.21/docker-entrypoint.sh
+++ b/postgres_15-alpine3.21/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-bookworm/docker-ensure-initdb.sh b/postgres_15-bookworm/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_15-bookworm/docker-ensure-initdb.sh
+++ b/postgres_15-bookworm/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-bookworm/docker-entrypoint.sh b/postgres_15-bookworm/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_15-bookworm/docker-entrypoint.sh
+++ b/postgres_15-bookworm/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-bullseye/docker-ensure-initdb.sh b/postgres_15-bullseye/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_15-bullseye/docker-ensure-initdb.sh
+++ b/postgres_15-bullseye/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-bullseye/docker-entrypoint.sh b/postgres_15-bullseye/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_15-bullseye/docker-entrypoint.sh
+++ b/postgres_15-bullseye/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-alpine/docker-ensure-initdb.sh b/postgres_16-alpine/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_16-alpine/docker-ensure-initdb.sh
+++ b/postgres_16-alpine/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-alpine/docker-entrypoint.sh b/postgres_16-alpine/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_16-alpine/docker-entrypoint.sh
+++ b/postgres_16-alpine/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-alpine3.21/docker-ensure-initdb.sh b/postgres_16-alpine3.21/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_16-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_16-alpine3.21/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-alpine3.21/docker-entrypoint.sh b/postgres_16-alpine3.21/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_16-alpine3.21/docker-entrypoint.sh
+++ b/postgres_16-alpine3.21/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-bookworm/docker-ensure-initdb.sh b/postgres_16-bookworm/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_16-bookworm/docker-ensure-initdb.sh
+++ b/postgres_16-bookworm/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-bookworm/docker-entrypoint.sh b/postgres_16-bookworm/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_16-bookworm/docker-entrypoint.sh
+++ b/postgres_16-bookworm/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-bullseye/docker-ensure-initdb.sh b/postgres_16-bullseye/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_16-bullseye/docker-ensure-initdb.sh
+++ b/postgres_16-bullseye/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_16-bullseye/docker-entrypoint.sh b/postgres_16-bullseye/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_16-bullseye/docker-entrypoint.sh
+++ b/postgres_16-bullseye/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_alpine/Dockerfile b/postgres_18beta1-alpine/Dockerfile
similarity index 93%
copy from postgres_alpine/Dockerfile
copy to postgres_18beta1-alpine/Dockerfile
index 5c303bd..248d5cb 100644
--- a/postgres_alpine/Dockerfile
+++ b/postgres_18beta1-alpine/Dockerfile
@@ -51,9 +51,9 @@ ENV LANG en_US.utf8
 
 RUN mkdir /docker-entrypoint-initdb.d
 
-ENV PG_MAJOR 17
-ENV PG_VERSION 17.5
-ENV PG_SHA256 fcb7ab38e23b264d1902cb25e6adafb4525a6ebcbd015434aeef9eda80f528d8
+ENV PG_MAJOR 18
+ENV PG_VERSION 18beta1
+ENV PG_SHA256 0b7c83df6195398aa67dbf5c002e7fa4082be393aae99aa69926d483f98eb885
 
 ENV DOCKER_PG_LLVM_DEPS \
 		llvm19-dev \
@@ -190,10 +190,13 @@ RUN set -eux; \
 
 RUN install --verbose --directory --owner postgres --group postgres --mode 3777 /var/run/postgresql
 
-ENV PGDATA /var/lib/postgresql/data
-# this 1777 will be replaced by 0700 at runtime (allows semi-arbitrary "--user" values)
-RUN install --verbose --directory --owner postgres --group postgres --mode 1777 "$PGDATA"
-VOLUME /var/lib/postgresql/data
+#
+# NOTE: in 18+, PGDATA has changed to match the pg_ctlcluster standard directory structure, and the VOLUME has moved from /var/lib/postgresql/data to /var/lib/postgresql
+#
+ENV PGDATA /var/lib/postgresql/18/docker
+RUN ln -svT . /var/lib/postgresql/data # https://github.com/docker-library/postgres/pull/1259#issuecomment-2215477494
+VOLUME /var/lib/postgresql
+# ("/var/lib/postgresql" is already pre-created with suitably usable permissions above)
 
 COPY docker-entrypoint.sh docker-ensure-initdb.sh /usr/local/bin/
 RUN ln -sT docker-ensure-initdb.sh /usr/local/bin/docker-enforce-initdb.sh
diff --git a/postgres_13-alpine3.21/docker-ensure-initdb.sh b/postgres_18beta1-alpine/docker-ensure-initdb.sh
similarity index 98%
copy from postgres_13-alpine3.21/docker-ensure-initdb.sh
copy to postgres_18beta1-alpine/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_18beta1-alpine/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine3.21/docker-entrypoint.sh b/postgres_18beta1-alpine/docker-entrypoint.sh
similarity index 90%
copy from postgres_13-alpine3.21/docker-entrypoint.sh
copy to postgres_18beta1-alpine/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-alpine3.21/docker-entrypoint.sh
+++ b/postgres_18beta1-alpine/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_alpine3.21/Dockerfile b/postgres_18beta1-alpine3.21/Dockerfile
similarity index 93%
copy from postgres_alpine3.21/Dockerfile
copy to postgres_18beta1-alpine3.21/Dockerfile
index c3c81bd..e9eff8d 100644
--- a/postgres_alpine3.21/Dockerfile
+++ b/postgres_18beta1-alpine3.21/Dockerfile
@@ -51,9 +51,9 @@ ENV LANG en_US.utf8
 
 RUN mkdir /docker-entrypoint-initdb.d
 
-ENV PG_MAJOR 17
-ENV PG_VERSION 17.5
-ENV PG_SHA256 fcb7ab38e23b264d1902cb25e6adafb4525a6ebcbd015434aeef9eda80f528d8
+ENV PG_MAJOR 18
+ENV PG_VERSION 18beta1
+ENV PG_SHA256 0b7c83df6195398aa67dbf5c002e7fa4082be393aae99aa69926d483f98eb885
 
 ENV DOCKER_PG_LLVM_DEPS \
 		llvm19-dev \
@@ -190,10 +190,13 @@ RUN set -eux; \
 
 RUN install --verbose --directory --owner postgres --group postgres --mode 3777 /var/run/postgresql
 
-ENV PGDATA /var/lib/postgresql/data
-# this 1777 will be replaced by 0700 at runtime (allows semi-arbitrary "--user" values)
-RUN install --verbose --directory --owner postgres --group postgres --mode 1777 "$PGDATA"
-VOLUME /var/lib/postgresql/data
+#
+# NOTE: in 18+, PGDATA has changed to match the pg_ctlcluster standard directory structure, and the VOLUME has moved from /var/lib/postgresql/data to /var/lib/postgresql
+#
+ENV PGDATA /var/lib/postgresql/18/docker
+RUN ln -svT . /var/lib/postgresql/data # https://github.com/docker-library/postgres/pull/1259#issuecomment-2215477494
+VOLUME /var/lib/postgresql
+# ("/var/lib/postgresql" is already pre-created with suitably usable permissions above)
 
 COPY docker-entrypoint.sh docker-ensure-initdb.sh /usr/local/bin/
 RUN ln -sT docker-ensure-initdb.sh /usr/local/bin/docker-enforce-initdb.sh
diff --git a/postgres_13-alpine3.21/docker-ensure-initdb.sh b/postgres_18beta1-alpine3.21/docker-ensure-initdb.sh
similarity index 98%
copy from postgres_13-alpine3.21/docker-ensure-initdb.sh
copy to postgres_18beta1-alpine3.21/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_18beta1-alpine3.21/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine3.21/docker-entrypoint.sh b/postgres_18beta1-alpine3.21/docker-entrypoint.sh
similarity index 90%
copy from postgres_13-alpine3.21/docker-entrypoint.sh
copy to postgres_18beta1-alpine3.21/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-alpine3.21/docker-entrypoint.sh
+++ b/postgres_18beta1-alpine3.21/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_14-bookworm/Dockerfile b/postgres_18beta1-bookworm/Dockerfile
similarity index 93%
copy from postgres_14-bookworm/Dockerfile
copy to postgres_18beta1-bookworm/Dockerfile
index e9a0e21..88e3634 100644
--- a/postgres_14-bookworm/Dockerfile
+++ b/postgres_18beta1-bookworm/Dockerfile
@@ -86,10 +86,10 @@ RUN set -ex; \
 	gpgconf --kill all; \
 	rm -rf "$GNUPGHOME"
 
-ENV PG_MAJOR 14
+ENV PG_MAJOR 18
 ENV PATH $PATH:/usr/lib/postgresql/$PG_MAJOR/bin
 
-ENV PG_VERSION 14.18-1.pgdg120+1
+ENV PG_VERSION 18~beta1-1.pgdg120+1
 
 RUN set -ex; \
 	\
@@ -156,6 +156,8 @@ RUN set -ex; \
 	sed -ri 's/#(create_main_cluster) .*$/\1 = false/' /etc/postgresql-common/createcluster.conf; \
 	apt-get install -y --no-install-recommends \
 		"postgresql-$PG_MAJOR=$PG_VERSION" \
+# https://github.com/docker-library/postgres/pull/1344#issuecomment-2936578203 (JIT is a separate package in 18+)
+		"postgresql-$PG_MAJOR-jit=$PG_VERSION" \
 	; \
 	\
 	rm -rf /var/lib/apt/lists/*; \
@@ -181,10 +183,13 @@ RUN set -eux; \
 
 RUN install --verbose --directory --owner postgres --group postgres --mode 3777 /var/run/postgresql
 
-ENV PGDATA /var/lib/postgresql/data
-# this 1777 will be replaced by 0700 at runtime (allows semi-arbitrary "--user" values)
-RUN install --verbose --directory --owner postgres --group postgres --mode 1777 "$PGDATA"
-VOLUME /var/lib/postgresql/data
+#
+# NOTE: in 18+, PGDATA has changed to match the pg_ctlcluster standard directory structure, and the VOLUME has moved from /var/lib/postgresql/data to /var/lib/postgresql
+#
+ENV PGDATA /var/lib/postgresql/18/docker
+RUN ln -svT . /var/lib/postgresql/data # https://github.com/docker-library/postgres/pull/1259#issuecomment-2215477494
+VOLUME /var/lib/postgresql
+# ("/var/lib/postgresql" is already pre-created with suitably usable permissions above)
 
 COPY docker-entrypoint.sh docker-ensure-initdb.sh /usr/local/bin/
 RUN ln -sT docker-ensure-initdb.sh /usr/local/bin/docker-enforce-initdb.sh
diff --git a/postgres_13-alpine3.21/docker-ensure-initdb.sh b/postgres_18beta1-bookworm/docker-ensure-initdb.sh
similarity index 98%
copy from postgres_13-alpine3.21/docker-ensure-initdb.sh
copy to postgres_18beta1-bookworm/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_18beta1-bookworm/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine3.21/docker-entrypoint.sh b/postgres_18beta1-bookworm/docker-entrypoint.sh
similarity index 90%
copy from postgres_13-alpine3.21/docker-entrypoint.sh
copy to postgres_18beta1-bookworm/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-alpine3.21/docker-entrypoint.sh
+++ b/postgres_18beta1-bookworm/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_15-bullseye/Dockerfile b/postgres_18beta1-bullseye/Dockerfile
similarity index 93%
copy from postgres_15-bullseye/Dockerfile
copy to postgres_18beta1-bullseye/Dockerfile
index ec325d7..b2ec63d 100644
--- a/postgres_15-bullseye/Dockerfile
+++ b/postgres_18beta1-bullseye/Dockerfile
@@ -86,10 +86,10 @@ RUN set -ex; \
 	gpgconf --kill all; \
 	rm -rf "$GNUPGHOME"
 
-ENV PG_MAJOR 15
+ENV PG_MAJOR 18
 ENV PATH $PATH:/usr/lib/postgresql/$PG_MAJOR/bin
 
-ENV PG_VERSION 15.13-1.pgdg110+1
+ENV PG_VERSION 18~beta1-1.pgdg110+1
 
 RUN set -ex; \
 	\
@@ -156,6 +156,8 @@ RUN set -ex; \
 	sed -ri 's/#(create_main_cluster) .*$/\1 = false/' /etc/postgresql-common/createcluster.conf; \
 	apt-get install -y --no-install-recommends \
 		"postgresql-$PG_MAJOR=$PG_VERSION" \
+# https://github.com/docker-library/postgres/pull/1344#issuecomment-2936578203 (JIT is a separate package in 18+)
+		"postgresql-$PG_MAJOR-jit=$PG_VERSION" \
 	; \
 	\
 	rm -rf /var/lib/apt/lists/*; \
@@ -181,10 +183,13 @@ RUN set -eux; \
 
 RUN install --verbose --directory --owner postgres --group postgres --mode 3777 /var/run/postgresql
 
-ENV PGDATA /var/lib/postgresql/data
-# this 1777 will be replaced by 0700 at runtime (allows semi-arbitrary "--user" values)
-RUN install --verbose --directory --owner postgres --group postgres --mode 1777 "$PGDATA"
-VOLUME /var/lib/postgresql/data
+#
+# NOTE: in 18+, PGDATA has changed to match the pg_ctlcluster standard directory structure, and the VOLUME has moved from /var/lib/postgresql/data to /var/lib/postgresql
+#
+ENV PGDATA /var/lib/postgresql/18/docker
+RUN ln -svT . /var/lib/postgresql/data # https://github.com/docker-library/postgres/pull/1259#issuecomment-2215477494
+VOLUME /var/lib/postgresql
+# ("/var/lib/postgresql" is already pre-created with suitably usable permissions above)
 
 COPY docker-entrypoint.sh docker-ensure-initdb.sh /usr/local/bin/
 RUN ln -sT docker-ensure-initdb.sh /usr/local/bin/docker-enforce-initdb.sh
diff --git a/postgres_13-alpine3.21/docker-ensure-initdb.sh b/postgres_18beta1-bullseye/docker-ensure-initdb.sh
similarity index 98%
copy from postgres_13-alpine3.21/docker-ensure-initdb.sh
copy to postgres_18beta1-bullseye/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_13-alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_18beta1-bullseye/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_13-alpine3.21/docker-entrypoint.sh b/postgres_18beta1-bullseye/docker-entrypoint.sh
similarity index 90%
copy from postgres_13-alpine3.21/docker-entrypoint.sh
copy to postgres_18beta1-bullseye/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_13-alpine3.21/docker-entrypoint.sh
+++ b/postgres_18beta1-bullseye/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_alpine/docker-ensure-initdb.sh b/postgres_alpine/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_alpine/docker-ensure-initdb.sh
+++ b/postgres_alpine/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_alpine/docker-entrypoint.sh b/postgres_alpine/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_alpine/docker-entrypoint.sh
+++ b/postgres_alpine/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_alpine3.21/docker-ensure-initdb.sh b/postgres_alpine3.21/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_alpine3.21/docker-ensure-initdb.sh
+++ b/postgres_alpine3.21/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_alpine3.21/docker-entrypoint.sh b/postgres_alpine3.21/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_alpine3.21/docker-entrypoint.sh
+++ b/postgres_alpine3.21/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_bookworm/docker-ensure-initdb.sh b/postgres_bookworm/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_bookworm/docker-ensure-initdb.sh
+++ b/postgres_bookworm/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_bookworm/docker-entrypoint.sh b/postgres_bookworm/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_bookworm/docker-entrypoint.sh
+++ b/postgres_bookworm/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_bullseye/docker-ensure-initdb.sh b/postgres_bullseye/docker-ensure-initdb.sh
index ae1f6b6..e9b15ef 100755
--- a/postgres_bullseye/docker-ensure-initdb.sh
+++ b/postgres_bullseye/docker-ensure-initdb.sh
@@ -33,6 +33,7 @@ fi
 # only run initialization on an empty data directory
 if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 	docker_verify_minimum_env
+	docker_error_old_databases
 
 	# check dir permissions to reduce likelihood of half-initialized database
 	ls /docker-entrypoint-initdb.d/ > /dev/null
diff --git a/postgres_bullseye/docker-entrypoint.sh b/postgres_bullseye/docker-entrypoint.sh
index ae40666..5a62870 100755
--- a/postgres_bullseye/docker-entrypoint.sh
+++ b/postgres_bullseye/docker-entrypoint.sh
@@ -154,6 +154,29 @@ docker_verify_minimum_env() {
 		EOWARN
 	fi
 }
+# similar to the above, but errors if there are any "old" databases detected (usually due to upgrades without pg_upgrade)
+docker_error_old_databases() {
+	if [ -n "${OLD_DATABASES[0]:-}" ]; then
+		cat >&2 <<-EOE
+			Error: in 18+, these Docker images are configured to store database data in a
+			       format which is compatible with "pg_ctlcluster" (specifically, using
+			       major-version-specific directory names).  This better reflects how
+			       PostgreSQL itself works, and how upgrades are to be performed.
+
+			       See also https://github.com/docker-library/postgres/pull/1259
+
+			       Counter to that, there appears to be PostgreSQL data in:
+			         ${OLD_DATABASES[*]}
+
+			       This is usually the result of upgrading the Docker image without upgrading
+			       the underlying database using "pg_upgrade" (which requires both versions).
+
+			       See https://github.com/docker-library/postgres/issues/37 for a (long)
+			       discussion around this process, and suggestions for how to do so.
+		EOE
+		exit 1
+	fi
+}
 
 # usage: docker_process_init_files [file [file [...]]]
 #    ie: docker_process_init_files /always-initdb.d/*
@@ -230,9 +253,17 @@ docker_setup_env() {
 
 	declare -g DATABASE_ALREADY_EXISTS
 	: "${DATABASE_ALREADY_EXISTS:=}"
+	declare -ag OLD_DATABASES=()
 	# look specifically for PG_VERSION, as it is expected in the DB dir
 	if [ -s "$PGDATA/PG_VERSION" ]; then
 		DATABASE_ALREADY_EXISTS='true'
+	elif [ "$PGDATA" = "/var/lib/postgresql/$PG_MAJOR/docker" ]; then
+		# https://github.com/docker-library/postgres/pull/1259
+		for d in /var/lib/postgresql /var/lib/postgresql/data /var/lib/postgresql/*/docker; do
+			if [ -s "$d/PG_VERSION" ]; then
+				OLD_DATABASES+=( "$d" )
+			fi
+		done
 	fi
 }
 
@@ -319,6 +350,7 @@ _main() {
 		# only run initialization on an empty data directory
 		if [ -z "$DATABASE_ALREADY_EXISTS" ]; then
 			docker_verify_minimum_env
+			docker_error_old_databases
 
 			# check dir permissions to reduce likelihood of half-initialized database
 			ls /docker-entrypoint-initdb.d/ > /dev/null

Relevant Maintainers:

@tianon
Copy link
Member

tianon commented Jun 6, 2025

IMO we should wait to merge this on Monday just in case I've got some funky logic in there somewhere (I don't see any, but it's possible).

@tianon tianon merged commit bb5c01b into docker-library:master Jun 9, 2025
29 checks passed
@tianon tianon deleted the postgres branch June 9, 2025 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants