Upgrade to 1.0.0

This page is for operators upgrading an existing Orion deployment from 0.3.0 (the previous release) to 1.0.0. It covers only what breaks or changes behaviour. New capabilities are in the CHANGELOG; new configuration keys are in the Config Reference.

Every item below is written as what changed → how you’ll notice → what to do. Nothing here requires a workflow or channel rewrite; the changes are in the runtime’s request path, deployment defaults, and operational surfaces.

The version-independent procedure — back up, preflight, validate config, migrate, roll — is on Upgrades, along with the policy on how a renamed key fails.

Each change below is collapsed to its heading, so the eleven sections read as a list of what breaks. Open the ones that touch you; Expand all opens the lot.

Before you start

Run this first. It answers the database-backed rows below against your actual estate rather than in the abstract, and exits non-zero if it finds anything. Those rows are 3 and 14, the two channel-config renames, and duplicate channel names. The other rows are config- or client-side and it cannot see them:

orion-server preflight

It is read-only, needs only storage.url, and reports each finding with the checklist row it belongs to. Run it with the 1.0 binary against your 0.3.0 database, before you start the rollout. Config-file and ORION_* problems are reported separately by orion-server validate-config.

Then work through this list. Each row links to the section with the detail.

Take a database backup before upgrading. Migrations run automatically at boot unless you set storage.auto_migrate = false.

Which backend were you actually on?

This matters more than it sounds, because it decides how much of this page applies to you.

• SQLite: the only storage backend that fully worked in 0.3.0. Assume the whole page applies.
• PostgreSQL: the 0.3.0 schema migrated cleanly, but the Rust models decode i64 while the migration created integer (INT4) columns, and sqlx-postgres refuses INT4 → i64. Every repository read failed at runtime, so a 0.3.0 Postgres deployment could exist but could not serve. You still have a schema to migrate. See Database migrations.
• MySQL: the 0.3.0 migration set could not execute through sqlx at all (MySQL-client DELIMITER directives, TEXT columns with literal defaults, TEXT primary keys without prefix lengths). No MySQL deployment can exist to upgrade. Treat MySQL as new in 1.0.0 and start from an empty database.

Recommended after upgrading

None of these are required, but each closes a gap 1.0.0 opened up for you.

Hash your admin API keys at rest. Plaintext keys in admin_auth.api_keys still work unchanged. You can now store a SHA-256 digest instead, and clients keep presenting the plaintext key:

printf '%s' "$ORION_ADMIN_KEY" | shasum -a 256 | awk '{print "sha256:"$1}'   # macOS
printf '%s' "$ORION_ADMIN_KEY" | sha256sum   | awk '{print "sha256:"$1}'     # Linux

[admin_auth]
enabled = true
api_keys = ["sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]

The digest is a plain SHA-256 of the raw key bytes — no salt, no iteration. Use printf '%s', not echo, so you do not hash a trailing newline. A malformed entry fails config validation with admin_auth.api_keys: 'sha256:' entries must be followed by the 64-character hex SHA-256 digest of the key.

Two consequences to plan for:

• Hashing does not change the audit principal, and that is the point: the actor is a key-<16 hex> derived from the key, identical whether the entry is configured in plaintext or sha256: form, so rotating an operator between the two does not rename them in the trail. See Audit log for the format change itself, which does break saved ?principal= filters.
• A plaintext key whose literal text starts with sha256: is now interpreted as the hash-at-rest form, and fails config validation. Rotate it first.

Enable admin auth if you have not. It is what guards /metrics, the trace endpoints, and therefore the full-detail error payloads.

Enable the Kafka DLQ. See section 4.

Set storage.auto_migrate = false in any multi-replica deployment and run orion-server migrate as a deploy step. In a production cluster this is no longer advice. See A production cluster may not migrate at boot.

One fix worth retrying: TLS

TLS was unusable in 0.3.0. Setting server.tls.enabled = true panicked the process at boot with:

Could not automatically determine the process-level CryptoProvider

rustls 0.23 auto-selects a cryptography backend only when exactly one is enabled in the dependency graph, and Orion’s graph enables both. axum-server and reqwest pull rustls/aws-lc-rs, while mongodb and sqlx pull rustls/ring. The server installs the aws-lc-rs provider explicitly before loading certificates as of 1.0.0, and the path now has test coverage.

If you tried HTTPS, hit that panic, and terminated TLS at a proxy instead: it works now.

[server.tls]
enabled = true
cert_path = "/etc/orion/tls/server.crt"
key_path  = "/etc/orion/tls/server.key"

The eleven breaks

Related

• Upgrades: the version-independent procedure.
• orion-server preflight: the scan that finds the stored breaks.
• Server configuration: every key, with its default.
• Releases: what changed in each version.

Last verified 14 September 2026