Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

fix(rds): mount Postgres 18+ data volume at /var/lib/postgresql (#467)

Neal Whittingtoncf9e03d71ade
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88fb3a56..e79e0119 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ Versioning follows [Semantic Versioning](https://semver.org/).
---
+## [Unreleased]
+
+### Fixed
+- **RDS Postgres 18+ container refused to start** — MiniStack mounted the RDS data volume (or tmpfs) at `/var/lib/postgresql/data` for every Postgres major, but the official `postgres:18+` image moved to a major-version-specific on-disk layout and refuses to start with the pre-18 path ([docker-library/postgres#1259](https://github.com/docker-library/postgres/pull/1259)). `CreateDBInstance Engine=postgres EngineVersion=18.x` returned "available" from the RDS API while the spawned `postgres:18-alpine` container exited immediately with a layout-mismatch error. The mount path is now chosen per major: `/var/lib/postgresql/data` for < 18 (unchanged), `/var/lib/postgresql` for ≥ 18. MySQL / MariaDB / Aurora MySQL unaffected. Also adds `postgres 18.3`, `17.5`, `16.4` to the `DescribeDBEngineVersions` matrix (and aurora-postgresql equivalents). Reported by @whittin3.
+
+### Changed
+- **RDS containers now mount only the engine-appropriate data path.** Previously both `/var/lib/postgresql/data` and `/var/lib/mysql` were mounted on every RDS container regardless of engine — harmless but wasteful, and opaque when debugging. Docker `volumes` / `tmpfs` kwargs now reflect only the active engine.
+
+---
+
## [1.3.14] — 2026-04-24
### Added
diff --git a/ministack/services/rds.py b/ministack/services/rds.py
index a8852db9..194354c8 100644
--- a/ministack/services/rds.py
+++ b/ministack/services/rds.py
@@ -362,7 +362,7 @@ def _create_db_instance(p):
host_port = _next_port()
endpoint_port = host_port
ms_network = _get_ministack_network(docker_client)
- image, env, container_port = _docker_image_for_engine(
+ image, env, container_port, data_path = _docker_image_for_engine(
engine, engine_version, master_user, master_pass, db_name
)
if image:
@@ -376,15 +376,17 @@ def _create_db_instance(p):
)
if ms_network:
container_kwargs["network"] = ms_network
+ # Mount only the engine-appropriate data path. Previously both
+ # postgres and mysql paths were mounted unconditionally, which
+ # is harmless but wasteful and complicates the Postgres 18+
+ # layout change (where the path differs from earlier majors).
if RDS_PERSIST:
container_kwargs["volumes"] = {
- f"ministack-rds-{db_id}-data": {"bind": "/var/lib/postgresql/data", "mode": "rw"},
- f"ministack-rds-{db_id}-mysql": {"bind": "/var/lib/mysql", "mode": "rw"},
+ f"ministack-rds-{db_id}-data": {"bind": data_path, "mode": "rw"},
}
else:
container_kwargs["tmpfs"] = {
- "/var/lib/postgresql/data": f"rw,noexec,nosuid,size={RDS_TMPFS_SIZE}",
- "/var/lib/mysql": f"rw,noexec,nosuid,size={RDS_TMPFS_SIZE}",
+ data_path: f"rw,noexec,nosuid,size={RDS_TMPFS_SIZE}",
}
container = docker_client.containers.run(**container_kwargs)
docker_container_id = container.id
@@ -2010,6 +2012,7 @@ def _describe_engine_versions(p):
version_filter = _p(p, "EngineVersion")
versions_map = {
"postgres": [
+ ("18.3", "18"), ("17.5", "17"), ("16.4", "16"),
("15.3", "15"), ("14.8", "14"), ("13.11", "13"), ("12.15", "12"),
],
"mysql": [
@@ -2019,6 +2022,8 @@ def _describe_engine_versions(p):
("10.6.14", "10.6"), ("10.5.21", "10.5"),
],
"aurora-postgresql": [
+ ("18.3", "aurora-postgresql18"), ("17.5", "aurora-postgresql17"),
+ ("16.4", "aurora-postgresql16"),
("15.3", "aurora-postgresql15"), ("14.8", "aurora-postgresql14"),
],
"aurora-mysql": [
@@ -2555,13 +2560,29 @@ def _license_model(engine):
def _docker_image_for_engine(engine, engine_version, user, password, db_name):
- """Return (image, env_dict, container_port) or (None, None, None)."""
+ """Return (image, env_dict, container_port, data_path) or all-None.
+
+ data_path is the in-container path where the engine's data volume should
+ be mounted. Postgres 18+ reorganised its on-disk layout so that data
+ lives under a major-version-specific subdirectory; the official
+ postgres:18+ image refuses to start with a volume mounted at
+ /var/lib/postgresql/data (the pre-18 path) and points operators at
+ /var/lib/postgresql instead. We pick the right path per major so both
+ `postgres:17-alpine` and `postgres:18-alpine` start cleanly.
+ See https://github.com/docker-library/postgres/pull/1259 for context.
+ """
if "postgres" in engine or "aurora-postgresql" in engine:
major = engine_version.split(".")[0]
+ try:
+ major_int = int(major)
+ except ValueError:
+ major_int = 0
+ data_path = "/var/lib/postgresql" if major_int >= 18 else "/var/lib/postgresql/data"
return (
apply_image_prefix(f"postgres:{major}-alpine"),
{"POSTGRES_USER": user, "POSTGRES_PASSWORD": password, "POSTGRES_DB": db_name},
5432,
+ data_path,
)
if "mysql" in engine or "aurora-mysql" in engine:
return (
@@ -2570,6 +2591,7 @@ def _docker_image_for_engine(engine, engine_version, user, password, db_name):
"MYSQL_DATABASE": db_name,
"MYSQL_USER": user, "MYSQL_PASSWORD": password},
3306,
+ "/var/lib/mysql",
)
if "mariadb" in engine:
return (
@@ -2578,8 +2600,9 @@ def _docker_image_for_engine(engine, engine_version, user, password, db_name):
"MYSQL_DATABASE": db_name,
"MYSQL_USER": user, "MYSQL_PASSWORD": password},
3306,
+ "/var/lib/mysql",
)
- return None, None, None
+ return None, None, None, None
def _default_parameters_for_family(family):
diff --git a/tests/test_rds.py b/tests/test_rds.py
index 7f941813..6e9e6f4d 100644
--- a/tests/test_rds.py
+++ b/tests/test_rds.py
@@ -1073,3 +1073,132 @@ def test_rds_enable_http_endpoint_not_found(rds):
ResourceArn="arn:aws:rds:us-east-1:123456789012:cluster:no-such-cluster"
)
assert exc.value.response["Error"]["Code"] == "DBClusterNotFoundFault"
+
+
+# ── Postgres 18+ mount-path compatibility ──────────────────
+
+
+def test_docker_image_for_engine_postgres_pre_18_uses_data_subdir():
+ """Postgres < 18 keeps the pre-existing mount path /var/lib/postgresql/data."""
+ from ministack.services.rds import _docker_image_for_engine
+
+ for version in ("12.15", "13.11", "14.8", "15.3", "16.4", "17.5"):
+ image, env, port, data_path = _docker_image_for_engine(
+ "postgres", version, "admin", "pw", "mydb"
+ )
+ major = version.split(".")[0]
+ assert image == f"postgres:{major}-alpine"
+ assert port == 5432
+ assert data_path == "/var/lib/postgresql/data", (
+ f"postgres {version} should mount at /var/lib/postgresql/data"
+ )
+ assert env["POSTGRES_USER"] == "admin"
+ assert env["POSTGRES_PASSWORD"] == "pw"
+ assert env["POSTGRES_DB"] == "mydb"
+
+
+def test_docker_image_for_engine_postgres_18_uses_new_layout():
+ """Postgres 18+ must mount at /var/lib/postgresql (not /data).
+
+ The official postgres:18+ image moved to a major-version-specific on-disk
+ layout and refuses to start with the old pre-18 mount path. Regression
+ test for fix/rds-postgres-18-mount-layout.
+ """
+ from ministack.services.rds import _docker_image_for_engine
+
+ for version in ("18.0", "18.3", "19.1"):
+ image, env, port, data_path = _docker_image_for_engine(
+ "postgres", version, "admin", "pw", "mydb"
+ )
+ major = version.split(".")[0]
+ assert image == f"postgres:{major}-alpine"
+ assert port == 5432
+ assert data_path == "/var/lib/postgresql", (
+ f"postgres {version} should mount at /var/lib/postgresql (new layout)"
+ )
+
+
+def test_docker_image_for_engine_aurora_postgres_18_uses_new_layout():
+ """aurora-postgresql 18+ follows the same layout switch as vanilla postgres."""
+ from ministack.services.rds import _docker_image_for_engine
+
+ _, _, _, data_path_17 = _docker_image_for_engine(
+ "aurora-postgresql", "17.5", "admin", "pw", "mydb"
+ )
+ _, _, _, data_path_18 = _docker_image_for_engine(
+ "aurora-postgresql", "18.3", "admin", "pw", "mydb"
+ )
+ assert data_path_17 == "/var/lib/postgresql/data"
+ assert data_path_18 == "/var/lib/postgresql"
+
+
+def test_docker_image_for_engine_mysql_unchanged():
+ """MySQL / MariaDB / Aurora MySQL keep /var/lib/mysql — the Postgres 18
+ layout change does not touch them."""
+ from ministack.services.rds import _docker_image_for_engine
+
+ for engine, version in [
+ ("mysql", "8.0.33"),
+ ("aurora-mysql", "8.0.mysql_aurora.3.03.0"),
+ ("mariadb", "10.6.14"),
+ ]:
+ _, _, port, data_path = _docker_image_for_engine(
+ engine, version, "admin", "pw", "mydb"
+ )
+ assert port == 3306
+ assert data_path == "/var/lib/mysql"
+
+
+def test_docker_image_for_engine_malformed_version_defaults_to_pre_18():
+ """An unparseable major version falls back to the pre-18 layout rather
+ than crashing. Real AWS RDS only accepts numeric majors, but defensive
+ fallback keeps the emulator forgiving."""
+ from ministack.services.rds import _docker_image_for_engine
+
+ _, _, _, data_path = _docker_image_for_engine(
+ "postgres", "garbage.3", "admin", "pw", "mydb"
+ )
+ assert data_path == "/var/lib/postgresql/data"
+
+
+def test_docker_image_for_engine_unknown_engine_returns_nones():
+ """Unknown engine returns (None, None, None, None) — the 4-arity tuple
+ must be preserved so call sites can safely destructure."""
+ from ministack.services.rds import _docker_image_for_engine
+
+ result = _docker_image_for_engine("oracle", "19.0", "admin", "pw", "mydb")
+ assert result == (None, None, None, None)
+
+
+def test_rds_describe_postgres_18_engine_version(rds):
+ """DescribeDBEngineVersions exposes the Postgres 18 entry so Terraform's
+ validation (and callers that list supported versions) sees it."""
+ resp = rds.describe_db_engine_versions(Engine="postgres", EngineVersion="18.3")
+ versions = resp["DBEngineVersions"]
+ assert len(versions) == 1
+ assert versions[0]["EngineVersion"] == "18.3"
+ assert versions[0]["DBParameterGroupFamily"] == "18"
+
+
+def test_rds_create_db_instance_postgres_18(rds):
+ """CreateDBInstance accepts EngineVersion=18.3 and round-trips it through
+ DescribeDBInstances. Covers the API layer regardless of whether Docker
+ is available to actually start the underlying Postgres 18 container."""
+ rds.create_db_instance(
+ DBInstanceIdentifier="pg18-test",
+ DBInstanceClass="db.t3.micro",
+ Engine="postgres",
+ EngineVersion="18.3",
+ MasterUsername="admin",
+ MasterUserPassword="password123",
+ DBName="testdb",
+ AllocatedStorage=20,
+ )
+ try:
+ resp = rds.describe_db_instances(DBInstanceIdentifier="pg18-test")
+ inst = resp["DBInstances"][0]
+ assert inst["Engine"] == "postgres"
+ assert inst["EngineVersion"] == "18.3"
+ assert "Address" in inst["Endpoint"]
+ finally:
+ rds.delete_db_instance(DBInstanceIdentifier="pg18-test", SkipFinalSnapshot=True)