Migrations

Use this page when readiness reports a schema mismatch or a migration command fails.

Symptoms

• readyz returns ORL-5002.
• oriel-migrate.service fails.
• migrate status reports dirty state.
• A new binary starts and then refuses to serve.

Checks

oriel --config /etc/oriel/oriel.toml migrate status

Run doctor for both dependency and schema checks:

oriel --config /etc/oriel/oriel.toml doctor

Common states

State	Meaning	Fix
Pending migrations	Database is behind binary	Run oriel migrate up.
Dirty migration	A migration failed mid-apply	Inspect database and migration ledger before manual repair.
Store unreachable	Migration cannot connect	Fix DSN, credentials, network, or database process.
Binary older than schema	Rollback mismatch	Restore matching binary or restore databases from backup.

Recovery

For normal pending migrations:

oriel --config /etc/oriel/oriel.toml migrate up

For destructive rollback:

oriel --config /etc/oriel/oriel.toml migrate down --steps 1 --yes

Use destructive rollback only with an explicit backup and restore plan.

See Migrations and upgrades for the normal upgrade sequence.