> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asobeast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade and roll back

> Pull the new image tag, restart the stack and let the API apply forward migrations on boot. Roll back by restoring a database backup taken before the upgrade.

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

<Steps>
  <Step title="Record what you are on">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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](/operations/backups).
  </Step>
</Steps>

## Upgrade

```bash theme={null}
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](/install/published-images). 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

```bash theme={null}
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.

```bash theme={null}
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.

<Steps>
  <Step title="Stop the applications">
    ```bash theme={null}
    docker compose stop web api
    ```
  </Step>

  <Step title="Restore the pre upgrade archive">
    Drop and recreate the database, then restore the archive you took before the upgrade. See [Restore PostgreSQL](/operations/restore).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](https://github.com/MrAdex77/asobeast/releases) before every upgrade, because an operator facing change appears in a commit subject or a breaking change footer.