Upgrade policy
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.
Updating
New versions are pulled from the vendor’s release CDN. The supported way to update is a single command on the server:
aihummer update --check # only report whether a newer version exists
aihummer update # download and apply it--check writes nothing and therefore does not need root. Applying an
update rewrites the install root and restarts the service, so run it with
sudo.
Expected result: --check prints the current and the available version and
exits without changing anything. aihummer update downloads the artifact,
verifies its sha256 checksum and its cosign signature, swaps the binary and
restarts the service — after which aihummer version reports the new version.
If verification fails, the update aborts before the swap: the running
version stays untouched.
Auto-update is on by default
Since 1.2.6 auto-update is enabled out of the box — for the gateway and for every plugin. Previously an instance received no fixes until an operator logged into the server by hand, and that was the most common reason for “we are running an old version”.
By default the instance checks its release channel manifest every few hours and
installs a newer version on its own. The mode and the interval arrive as a
vendor directive and are not operator knobs: they do not appear in the
settings list, and a line in gateway.env is not read for them. The directive is
re-read on every check cycle, so a change of mode takes effect without restarting
the service.
[!NOTE] You can update sooner than the next scheduled check at any time — with the
aihummer updatecommand above. It verifies the checksum and the signature exactly as an automatic update does.
If automatic updates do not suit you, arrange it with the vendor: the mode is changed on their side and reaches the instance signed. Editing the setting on the instance yourself will not work — it is rejected.
Rollback
What rolls back, item by item:
- Binary — can be returned to the previous version (artifacts of earlier releases stay on the CDN; reinstall the version you want).
- Database schema — migrations are forward-safe, so the previous binary works against the newer schema; there is no separate schema rollback.
- Plugins — versions are managed per installation; roll a plugin back from the catalog if you need to.
- Configuration — untouched by an update; restore it from a backup if needed.
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. Reliable delivery plus idempotency keys mean a reply is never sent twice across a restart, which is what makes a rolling restart across your gateways 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.