diff --git a/docker-compose.yml b/docker-compose.yml
index a801a0ce7c..bd1e060f22 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,15 +8,28 @@ x-logging: &default-logging
     compress: "true"
 
 services:
+  ## UPGRADING FROM POSTGRES 16: db_data holds a cluster 18 cannot read, so the
+  ## container exits with an explanatory error rather than coming up blank. Migrating
+  ## means dumping the WHOLE cluster (pg_dumpall), never just the windmill database:
+  ## Windmill keeps datatable, DuckLake and wm_fork_* databases beside it and grants
+  ## its RLS policies to cluster-level roles, and a single-database dump loses both
+  ## silently. Full procedure, and why 16 is still a valid choice until Nov 2028:
+  ## https://www.windmill.dev/docs/advanced/self_host#upgrade-postgresql-to-18
   db:
     deploy:
       # To use an external database, set replicas to 0 and set DATABASE_URL to the external database url in the .env file
       replicas: 1
-    image: postgres:16
+    image: postgres:18
     shm_size: 1g
     restart: unless-stopped
     volumes:
-      - db_data:/var/lib/postgresql/data
+      # From 18 on the official image keeps the cluster in a major-version
+      # subdirectory (/var/lib/postgresql/18/docker), so the mount has to be the
+      # parent directory: that is what lets pg_upgrade see an old and a new
+      # cluster inside a single mount point. Mounting the pre-18 .../data path
+      # instead makes the image exit rather than start, which is what turns a
+      # stale 16 cluster into a loud failure instead of an empty instance.
+      - db_data:/var/lib/postgresql
     expose:
       - 5432
     environment: