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 existsaihummer 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.
[!NOTE]
Automatic updates are enabled by the vendor, not by you. The auto-update
mode and schedule are part of release servicing and are set by a signed
vendor directive. There are no switches for them in the Web UI or in
aihummer settings, and auto-update variables written into gateway.env are
not read by the gateway — if you see them there, they have no effect. To
update on your own schedule, use the aihummer update command above.
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.
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:
```bash
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.
> [!NOTE]
> **Automatic updates are enabled by the vendor, not by you.** The auto-update
> mode and schedule are part of release servicing and are set by a signed
> vendor directive. There are no switches for them in the Web UI or in
> `aihummer settings`, and auto-update variables written into `gateway.env` are
> **not read** by the gateway — if you see them there, they have no effect. To
> update on your own schedule, use the `aihummer update` command above.
### 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](/en/v1.0/operations/systemd-health).
- Back up before a major upgrade:
[Backups & disaster recovery](/en/v1.0/operations/backups-dr).
- Watch the rollout:
[Observability](/en/v1.0/operations/observability).
