Postgres major upgrades

You’ll be able to move a Postgres service from one major version to another, say 16 to 17, and keep its data.

Why it needs a step

Postgres cannot read a data folder written by another major version. Builds of the same major (18.5 and 18.6) share a data format, so only a major change needs the data dumped with the old server and loaded into a new one. That is what doze migrate does.

If you change version and start the stack without migrating, the service does not start. Its error says so: “its data is Postgres 16’s, but doze.hcl now says version 17 … Bring the stack down and run doze migrate <name>”.

Move it

The examples use Larder, a made-up grocery service whose Postgres block is called postgres.

1. Change the version in doze.hcl.

   module postgres "postgres" {
     version = 17
   }

2. Bring the stack down.

   In the app

   Flip the stack’s switch off on the Library.

   In a terminal

   doze down

3. Run the migration. There is no button for this in the app; run it in a terminal, in the folder with doze.hcl:

   doze migrate postgres

4. Bring the stack up.

   In the app

   Flip the switch back on.

   In a terminal

   doze up

What doze migrate does

1. Fetches both Postgres versions if this machine does not have them.
2. Starts the old version on the old data, on a private socket, and dumps everything with the new version’s pg_dumpall.
3. Renames the old data folder to <name>.pg16-<date>-<time>, beside where it was. It is never deleted.
4. Makes a fresh cluster with the new version and loads the dump into it.

It prints where the old data and the dump are kept:

✓ postgres is on Postgres 17 now. The Postgres 16 data is kept at …/clusters/postgres.pg16-20261107-141502, and the dump at …/clusters/postgres-pg16-dump.sql; delete them when you are sure.
  Bring the stack up: doze up

Both sit in the project’s state folder, under clusters/; see Files and storage. Delete them yourself when the new version has done its job for a while.

When something goes wrong

• A step fails. If the dump fails, nothing was changed. If making the new cluster or loading the dump fails, doze puts the old data back where it was and says so. Your doze.hcl still says the new version: set it back to start on the old data.
• Some statements did not load. doze lists them after the ✓ line, with what psql said. The usual cause is an extension that the new major does not have yet. See Postgres extensions.
• The stack is up. doze migrate refuses and changes nothing; bring it down first.
• The service has no data yet. There is nothing to move; it starts on the declared version.

doze migrate works on Postgres only. The other modules keep their data across the versions they offer, or have no such step.