> ## 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 an installation

> Which versions upgrade directly to the current release, what the API container does to your database on boot, and how the upgrade path is proven in CI before it reaches you.

The API container runs `prisma migrate deploy` on boot. A migration that cannot apply to your data stops the container rather than warning, so an upgrade either completes or the old version keeps running. Nothing is applied halfway.

This page states which versions upgrade directly, and how that claim is tested.

## Supported upgrade baselines

| From                 | To      | Supported                            |
| -------------------- | ------- | ------------------------------------ |
| `0.4.0`              | current | Yes, proven on every pull request    |
| `0.5.x`              | current | Yes                                  |
| Earlier than `0.4.0` | current | Not tested. Upgrade to `0.4.0` first |

`0.4.0` is the oldest baseline the project verifies. Migrations are additive and forward only, so an older database will usually still apply, but nobody checks it and you would be the first to find out.

## What the upgrade does

Migrations run in order against your existing rows. They never rewrite history:

* Existing rows are preserved. The drill fails the build if any table's row count changes across an upgrade.
* `_prisma_migrations` records what has already been applied, so a restart never replays a migration.
* An applied migration is never edited. A correction ships as a new forward migration.

## Before you upgrade

Take a backup. See [Back up your data](/operations/backups). A backup taken shortly before the daily pipeline window is the cheapest point, because the least work is in flight.

Then pull the new image and restart. Watch the API container's first log lines: `prisma migrate deploy` reports each migration it applies.

## How the upgrade path is proven

Every pull request runs an upgrade drill in CI. It builds a database at the `0.4.0` schema, loads a fixture carrying multi store and multi market data, applies every migration added since, and then asserts:

* `prisma migrate status` reports the database up to date.
* `prisma migrate diff` reports no drift between the migrations and the schema.
* Per table row counts are identical before and after. A migration that resolved a collision by deleting rows fails here.
* The API boots against the upgraded database and serves authenticated reads across apps, keywords, rankings, reviews, changes, actions and alerts.
* Data retention prunes only what its windows allow, and never prunes open or snoozed actions by age.

The baseline is a variable, so the same drill covers a new baseline once one is declared:

```bash theme={null}
UPGRADE_FROM_TAG=v0.4.0 \
  DATABASE_URL=postgresql://asobeast:asobeast@localhost:5432/asobeast_upgrade \
  apps/api/test/upgrade/run-drill.sh
```

The script refuses to run unless the database name ends in `_upgrade`, because it drops the public schema before it starts.

## If a migration fails

The container exits and your data is untouched, because a failed migration is rolled back. Roll back to the previous image tag to restore service, then report the failure with the migration name and the database error code from the container log. See [Troubleshooting](/operations/troubleshooting).