Skip to content
Oriel

Migrations and upgrades

Oriel applies metadata migrations before ClickHouse migrations. Down migrations exist for controlled rollback, but they are destructive and require --yes.

Before you upgrade

Section titled “Before you upgrade”
  • Backup plan for PostgreSQL metadata and ClickHouse telemetry
  • New Oriel binary available
  • Same config file that the service uses

Release candidates can include metadata or ClickHouse migrations. Before testing an RC, take the same PostgreSQL metadata and ClickHouse telemetry backups you would take for a stable upgrade. Treat rollback as a restore operation unless you have already validated the matching down migrations against disposable data.

Apply migrations

Section titled “Apply migrations”

Check migration state:

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

Apply pending migrations:

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

Target one store when needed:

Terminal window
oriel --config /etc/oriel/oriel.toml migrate up --store metadata
oriel --config /etc/oriel/oriel.toml migrate up --store clickhouse

Systemd deployments run oriel-migrate.service before oriel.service.

Verify schema state

Section titled “Verify schema state”
Terminal window
oriel --config /etc/oriel/oriel.toml doctor
curl -fsS http://localhost:6743/readyz

Readiness fails with ORL-5002 when a node is serving against an incompatible schema.

Roll back or recover

Section titled “Roll back or recover”

Down migrations exist but destroy data and require --yes:

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

Use down migrations only with a deliberate restore plan. Prefer restoring from database backups when an upgrade needs to be reverted.