Replacing a PostgreSQL 16 Docker image with PostgreSQL 18 does not migrate the database. The new image supplies a different server version; PostgreSQL still needs a supported major-version migration, such as pg_upgrade, logical dump and restore, or a suitable replication procedure. You must also adjust the persistent-volume layout for the PostgreSQL 18 Docker Official Image. Those are separate changes: fixing the container path does not convert the database files.
What changes when you swap the image?
A Docker image tag selects the PostgreSQL server executable and the container’s filesystem conventions. It does not translate a PostgreSQL 16 cluster into PostgreSQL 18’s storage format. PostgreSQL’s upgrade guide explains that major releases can change internal storage formats, which is why a major-version upgrade requires a migration procedure rather than simply starting the old data directory with a new server. PostgreSQL: Upgrading a PostgreSQL Cluster.
As an Amazon Associate I earn from qualifying purchases.
PostgreSQL 16 to 18 crosses major versions. By contrast, minor releases within a compatible major line generally retain the same data-directory format and can use updated executables with the server stopped. That distinction does not make a major-version image swap safe.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Why the PostgreSQL 18 volume path is different
The Docker Official Image changed its data-directory conventions in PostgreSQL 18. Its documentation says, “The PGDATA environment variable of the image was changed to be version specific in PostgreSQL 18 and above.” The PostgreSQL 18 default PGDATA is /var/lib/postgresql/18/docker, and the declared volume is /var/lib/postgresql. PostgreSQL 17 and earlier use /var/lib/postgresql/data as the data-volume mount point. See the Docker Official Image documentation for PostgreSQL.
#1 Best Overall
| Image generation | Default data location | Documented volume mount point |
|---|---|---|
| PostgreSQL 17 and earlier | /var/lib/postgresql/data |
/var/lib/postgresql/data |
| PostgreSQL 18 and later | /var/lib/postgresql/18/docker by default |
/var/lib/postgresql |
If an older image is given a mount at /var/lib/postgresql, that mount may not cover its actual data directory. The container can then write to an anonymous volume that is not reused when you recreate it. Conversely, moving files into the PostgreSQL 18 directory structure only changes their location; it does not perform a major-version conversion.
The parent-volume layout for PostgreSQL 18 supports version-specific subdirectories and can accommodate workflows such as pg_upgrade --link. The image documentation says that when adapting existing data to this layout, the files should be moved into a PG_MAJOR/docker subdirectory. Treat this as volume organization, not as the database upgrade itself.
Rank #2
Choose a migration method before changing persistent storage
There is no universal best method: database size, downtime tolerance, extensions, filesystem layout, and deployment topology matter. The official documentation describes the approaches, but does not establish workload-specific timing or space estimates.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute| Method | What it does | Downtime and disk implications | Key considerations |
|---|---|---|---|
pg_upgrade |
Builds system tables for the new cluster and, after compatibility checks, reuses old user data files. | Downtime and temporary space depend on the selected transfer mode and workload; no general duration or space figure is established. | Requires old and new PostgreSQL binaries and both cluster directories. Copy is the default; link and clone options have conditions. Link mode requires the relevant directories on the same filesystem, and once the new cluster has started, the old cluster may no longer be safe to start. |
| Logical dump and restore | Exports database objects and data logically, then loads them into a new cluster; pg_dumpall is one available utility. |
Downtime and space requirements depend on the database and procedure; no general figures are established. | Requires planning for the dump, restore, and application cutover. It is a logical migration, not a filesystem copy. |
| Replication workflow | Uses a deployment-appropriate replication procedure to move changes or data to a new cluster. | Downtime depends on the specific topology and cutover plan; no general figure is established. | Can suit particular topology and downtime requirements, but the exact PostgreSQL procedure must be selected for the deployment. |
Official guidance: pg_upgrade, PostgreSQL backup and restore, and major-version upgrade methods.
Rank #3
What to check if you use pg_upgrade
pg_upgrade checks whether the old cluster can be upgraded to the new version and creates the new cluster’s system tables. It does not make every external component compatible. In particular, it cannot verify binary compatibility of external modules; the needed extension shared objects must be installed for the new cluster, and extension updates should be run when directed by the upgrade procedure. Consult the official pg_upgrade documentation.
- Have the old and new server binaries available, along with the old and new cluster directories.
- Run
pg_upgrade --checkbefore performing the upgrade, and use the selected transfer mode’s check where applicable. - Confirm that required extensions and custom modules are available and compatible with PostgreSQL 18.
- Understand the transfer mode’s filesystem and rollback implications before proceeding; do not assume the old cluster remains a safe fallback after link mode starts the new cluster.
A safe sequence for a Docker-based upgrade
The exact commands depend on your Compose configuration, custom PGDATA, named or bind volumes, extensions, architecture, and filesystem. Use the PostgreSQL procedure for your deployment rather than treating these steps as a copy-paste command recipe.
Quick Recap
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
- Identify the actual versions. Confirm the running server version and the intended target; here, 16 to 18 is a major-version upgrade.
- Secure a recovery route. Create a backup and retain it before altering persistent storage or running migration steps. Do not assume a backup is restorable unless you have verified it.
- Select the migration method. Choose
pg_upgrade, logical dump and restore, or a replication method that fits the workload and topology. - Check compatibility. Review extensions, custom modules, application dependencies, and the PostgreSQL 18 release guidance relevant to your setup.
- Align Docker storage separately. For the PostgreSQL 18 Docker Official Image defaults, mount
/var/lib/postgresql; its defaultPGDATAis/var/lib/postgresql/18/docker. Do not mistake a mount-path edit for the migration step. - Run preflight checks and migrate. Follow the selected method’s documented checks and execution steps before starting the new cluster against migrated data.
- Validate before removing the old cluster. Confirm that the service and application behave as expected, and keep the recovery route until you are satisfied with the result.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
