Upgrade policy — AiHummer Docs

Stability is a product principle, not an afterthought. AiHummer follows SemVer, applies forward-safe database migrations automatically, and can self-update from a CDN — so upgrades are routine rather than risky.

Versioning (SemVer)

Releases follow Semantic Versioning. The version is reported by /healthz and by aihummer version, so you can always confirm exactly what is running before and after an upgrade.

Migrations are forward-safe and automatic

On startup the gateway applies pending database migrations automatically. Two properties keep this safe:

Forward-safe. Migrations are written so a newer binary works against the schema it migrates to, which is what makes auto-apply and rolling upgrades safe.
Single-applier via advisory lock. Migrations run under a PostgreSQL advisory lock, so when several gateways start at once only one applies them and the rest wait — never a double migration.

[!NOTE] Migrations always run on the owner database pool. The restricted RLS role (AIHUMMER_DB_APP_URL) is for serving traffic, not for schema changes.

Self-update from the CDN

The gateway can update itself from the release CDN. The behaviour is governed by three environment variables:

Variable	Purpose
`AIHUMMER_AUTO_UPDATE`	`off` \| `check` \| `apply` — disabled, notify-only, or auto-apply
`AIHUMMER_UPDATE_CHANNEL`	Release channel to track (e.g. stable / alfa / beta / dev)
`AIHUMMER_DOWNLOAD_BASE_URL`	Base URL the update is pulled from

Updates are discovered through the channel’s latest.json on the CDN. You can also drive updates manually with the CLI:

aihummer update --check   # report whether a newer version is available
aihummer update           # download and apply the update

# gateway.env — notify-only on the stable channel
AIHUMMER_AUTO_UPDATE=check
AIHUMMER_UPDATE_CHANNEL=stable

[!TIP] Start with AIHUMMER_AUTO_UPDATE=check to be notified of new releases, and move to apply once you trust the channel for unattended rollouts.

Zero-downtime rollouts

AiHummer is built to upgrade without an outage:

Run 2+ gateways behind a proxy. Roll them one at a time; the readiness probe (/readyz) keeps a restarting node out of rotation until it is serving.
The scheduler is single-leader. Background scheduling elects a single leader via a PostgreSQL advisory lock, so running multiple gateways does not duplicate scheduled work.
Delivery is idempotent. The guaranteed-delivery outbox plus idempotency keys mean a reply is never sent twice across a restart, which is what makes rolling a fleet safe.

Where to next

Probes that gate a rolling restart: systemd & health checks.
Back up before a major upgrade: Backups & disaster recovery.
Watch the rollout: Observability.