Onyx follows semantic versioning. Database migrations run automatically via Alembic on startup, so most upgrades are a pull-and-restart operation.
Always back up your Postgres database and review the GitHub release notes before upgrading, especially across major versions. Docker Compose upgrade
Back up Postgres
docker exec onyx-relational_db-1 pg_dumpall -U postgres > onyx-backup- $( date +%F ) .sql
Store the dump somewhere safe before proceeding.
Pull the latest images
This downloads updated images without stopping running containers.
Restart services
Alembic migrations run automatically when api_server starts. Watch the logs to confirm: docker compose logs -f api_server
Look for Alembic upgrade complete before sending traffic.
Verify
All services should show Up. Check the admin panel to confirm the version number updated. Helm (Kubernetes) upgrade
Review value changes
Check the chart’s CHANGELOG or release notes for any new required values.
Upgrade the release
helm upgrade onyx onyx/onyx \ --namespace onyx \ --values values.yaml
Monitor rollout
kubectl rollout status deployment/onyx-api-server -n onyx kubectl logs -n onyx -l app=api-server --tail=50
Rollback If the upgrade causes issues, roll back to the previous image tag:
# Docker Compose — pin the previous version in .env ONYX_VERSION = v0.x.y docker compose up -d # Helm helm rollback onyx 1 --namespace onyx
Alembic does not automatically reverse migrations on rollback. If the new version added schema changes, restore from your Postgres backup instead of running the old image against the new schema.
Upgrade checklist
Read the release notes on GitHub for breaking changes
Back up Postgres with pg_dumpall
Note your current image tags so you can roll back
Schedule during low-traffic hours for production
Confirm all containers/pods are healthy
Test chat with your default LLM
Run a connector sync and verify documents appear
Check the Admin → System Info panel for the new version
