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 it fails instead, see If a migration fails. When you run pinned images instead of building from source, upgrade with docker-compose.pull.yml. Set the new tag from the releases page 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. On published images, run every Compose command below and in the restore block with -f docker-compose.pull.yml. Plain docker compose in a clone reads docker-compose.yml instead and starts the checked out source rather than the tag you set.
1

Stop the applications

2

Switch to the previous version

Check out the previous code revision and run docker compose build, or set the previous ASOBEAST_IMAGE_TAG in the root .env. Do this before the restore, because the restore starts the stack with whatever image is current, and the newer one would apply its migrations to the restored data again.
3

Restore the pre upgrade archive

Drop and recreate the database, restore the archive you took before the upgrade and verify both health URLs. See Restore PostgreSQL.

​
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 October 14, 2026