Skip to main content
Every schema change ships as a forward Prisma migration. There are no down migrations, so a rollback means restoring a database archive taken before the upgrade, not reversing one. That single rule shapes the whole page. Take the backup first, because after the migration runs it is the only way back.

​
Before you upgrade

1

Record what you are on

Note the Compose project name as well. It defaults to the repository directory name, and volumes are prefixed with it, such as production_pgdata. Keep it stable across upgrades.
2

Take a verified backup

A backup is not proven until it restores. Create the archive and confirm PostgreSQL can read its table of contents before you continue. See Back up PostgreSQL.

​
Upgrade

The API applies every pending migration on boot, so --wait returning success means the schema is current and both services are healthy. When you run pinned images instead of building from source, upgrade with docker-compose.pull.yml. Set the new tag and bring the stack up; the API applies every pending migration on boot exactly as it does from source.
Put the tag in the root .env instead of the command line when you want it to persist across restarts. The checked in docker-compose.yml builds both applications from source and declares no image, so docker compose pull cannot move that file onto a published tag. See Run a published release for the tag shapes and for the docker run sequence when you want no Compose file at all.

​
Verify the upgrade

Then check representative row counts against what you expect.

​
Roll back

A migration can make older application code incompatible with the migrated schema. Restoring only the previous image is therefore not a rollback. Restore both.
1

Stop the applications

2

Restore the pre upgrade archive

Drop and recreate the database, then restore the archive you took before the upgrade. See Restore PostgreSQL.
3

Start the previous revision

Check out the previous code revision, or set the previous pinned image tag, then bring the stack back up and verify both health URLs.

​
What does 1.0.0 promise?

1.0.0 promises compatibility for three surfaces throughout the 1.x line. Breaking any of them requires 2.0.0. The promise starts at 1.0.0 and holds for every later 1.x release. Additive change is allowed inside it, so a new endpoint, a new optional response field or a new MCP tool can arrive in a minor release. Removal, renaming and narrowing cannot. Release Please owns tags, versions and CHANGELOG.md. Read the release notes before every upgrade, because an operator facing change appears in a commit subject or a breaking change footer.
Last modified on August 24, 2026