Upgrade and roll back

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

Record what you are on

git rev-parse HEAD

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.

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

git pull
docker compose config --quiet
docker compose build --pull
docker compose up -d --wait
docker compose ps
docker compose logs --no-color --tail=200 api web

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, recreate the containers on the new tag with the docker run sequence from Run a published release. The checked in docker-compose.yml builds both applications from source and declares no image, so docker compose pull cannot move it onto a published tag. A supported pull based Compose file arrives with 1.0.0.

Verify the upgrade

curl --fail --silent --show-error http://127.0.0.1:3000/api/health
curl --fail --silent --show-error http://127.0.0.1:3000/api/backend/health

Then check representative row counts against what you expect.

docker compose exec -T postgres psql --username asobeast --dbname asobeast --command 'select count(*) from "App";'
docker compose exec -T postgres psql --username asobeast --dbname asobeast --command 'select count(*) from "Keyword";'

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.

Stop the applications

docker compose stop web api

Restore the pre upgrade archive

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

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.

Surface	Covered by the promise
The HTTP contract	Yes
`@asobeast/shared` contract types	Yes
The MCP tool surface	Yes
Environment variables	No
The database schema	No, changes ship as forward migrations
Internal modules	No

Until 1.0.0 is tagged, feature work is frozen and the 0.5.x line carries fixes, tests, measured performance work, behaviour preserving refactors, documentation, packaging, continuous integration and maintenance. 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.

Get started

Install

Concepts

Guides

Configuration

Operations

Reference

Upgrade and roll back

Before you upgrade

Upgrade

Verify the upgrade

Roll back

What does 1.0.0 promise?

​Before you upgrade

​Upgrade

​Verify the upgrade

​Roll back

​What does 1.0.0 promise?

Before you upgrade

Upgrade

Verify the upgrade

Roll back

What does 1.0.0 promise?