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

# Rolling back the control plane

> How to roll the control plane back to a previous release: what the dashboard shows and what you run on the server.

Settings > Updates lists the last five releases for a channel (stable, beta, or
both), each with a compatibility verdict against your database. Pick one to see
exactly what a rollback would do. The dashboard never applies it: the control
plane does not replace its own binary, so you run the rollback on the server.

## What the verdict means

| Verdict | Meaning |
| - | - |
| Safe: binary only | The release supports your database schema as it is. Only the program is replaced and your data is untouched. |
| Newer schema | The release is newer than your database and will migrate it forward on start. That is an upgrade. |
| Needs a backup restore | The release is older than your database schema and would refuse to start. The only way back restores a backup and permanently loses everything written after it. |
| Compatibility unknown | The release does not publish its schema version. An older program refuses a newer schema without touching data, and the previous release is restored automatically if it fails to start. |

## From the CLI

```sh theme={"dark"}
levelrail-cli upgrade --list --channel all
levelrail-cli upgrade --rollback-plan v0.2.0-beta.14 --json
```

## Applying on the server

Releases your host kept (the last three it ran) roll back immediately, with no network needed:

```sh theme={"dark"}
sudo levelrail rollback --to v0.2.0-beta.14 --dry-run   # print the plan only
sudo levelrail rollback --to v0.2.0-beta.14             # asks you to type the version
```

A release the host does not have is staged first, with checksum and signature
verification:

```sh theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/glincker/levelrail/main/install.sh \
  | sudo LEVELRAIL_VERSION=v0.2.0-beta.14 sh -s retain
```

The rollback takes a fresh backup, stops the service, swaps the binary, starts
it and waits for health and readiness. If the target is not healthy within
`--timeout` (default 90s), the previous release is put back automatically and
the command tells you so. Every attempt is written to the audit log.

### When a restore is required

```sh theme={"dark"}
sudo levelrail rollback --to v0.1.0 \
  --restore-backup levelrail-20261009T020000Z.db \
  --confirm-data-loss levelrail-20261009T020000Z.db
```

The plan lists each local backup with its time and schema. Everything written
after the chosen backup is lost. Your current database is kept beside it as
`levelrail.db.before-rollback-<time>`. Without a service manager, pass
`--stop-cmd` and `--start-cmd`.

## After an upgrade or rollback

Settings > Updates > Verify runs the control plane's own health checks and
shows a pass or fail result with the failing checks listed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.