Version Migration Guide

How to upgrade Aira SDKs and self-hosted deployments — version bumping, database migrations, and breaking changes policy.

Checking your current version

Every Aira deployment reports its version via the health endpoint:

curl https://your-domain/api/v1/health

{
  "status": "healthy",
  "version": "3.7.0",
  "components": {
    "database": "healthy",
    "signing": "healthy"
  }
}

For the SDKs, check the installed version:

# Python
pip show aira-sdk | grep Version

# TypeScript
npm list aira-sdk

SDK version bumping

Python

# Upgrade to the latest version
pip install --upgrade aira-sdk

# Pin to a specific version
pip install aira-sdk==3.7.0

# In requirements.txt — pin the minor version
aira-sdk>=3.7.0,<3.8.0

TypeScript

# Upgrade to the latest version
npm install aira-sdk@latest

# Pin to a specific version
npm install aira-sdk@3.7.0

# In package.json — pin the minor version
"aira-sdk": "^3.7.0"

We recommend pinning to a minor version range (e.g., >=3.7.0,<3.8.0 or ^3.7.0). This gives you patch-level fixes automatically while protecting against breaking changes.

Self-hosted upgrade

Self-hosted deployments include an upgrade script that handles pulling the new version, running database migrations, and restarting services.

Standard upgrade

cd /opt/aira    # or wherever you installed Aira
./upgrade.sh

The script performs these steps:

Pull the latest release (or a specified version).
Back up the current database (automatic pg_dump).
Run migrations — Alembic migrations are applied automatically.
Restart the Aira API and worker services.
Health check — confirms the new version is running.

Upgrade to a specific version

./upgrade.sh --version 3.7.0

Dry run

Preview what the upgrade will do without making changes:

./upgrade.sh --dry-run

This shows which migrations will run and which services will restart, but does not modify anything.

Always take a database backup before upgrading, even though upgrade.sh creates one automatically. For production deployments, test the upgrade in a staging environment first.

Database migrations

Database schema changes are handled by Alembic and run automatically during upgrade.sh. You should not need to run migrations manually, but if you do:

cd /opt/aira
alembic upgrade head

To check the current migration status:

alembic current

To see pending migrations:

alembic history --verbose

Rollback

If a migration causes issues, roll back to the previous revision:

alembic downgrade -1

Or roll back to a specific revision:

alembic downgrade abc123def

Rolling back migrations may cause data loss if the migration added columns that already contain data. Always check the migration file before rolling back.

Breaking changes policy

Aira follows Semantic Versioning:

Version bump	What changes	Example
Patch (3.7.0 -> 3.7.1)	Bug fixes, security patches. No API changes.	Fix receipt timestamp formatting
Minor (3.7.0 -> 3.8.0)	New features, new endpoints. Existing API is unchanged.	Add drift detection endpoint
Major (3.x -> 4.0)	Breaking changes. Existing API may change.	Rename `action_type` to `type`

Deprecation process

Before removing or changing any API behavior:

Deprecation notice — The feature is marked as deprecated in the changelog and API responses include a Deprecation header.
Migration window — At least 3 minor versions (or 90 days, whichever is longer) before removal.
Removal — The feature is removed in the next major version.

Deprecated features continue to work during the migration window. API responses include a warning:

Deprecation: The "action_type" field will be renamed to "type" in v4.0. See https://docs.airaproof.com/docs/changelog

Staying informed

Changelog — Every release is documented at /docs/changelog.
Release notes — Published at /docs/releases.
Webhooks — Subscribe to the system.version_update event to get notified when a new version is available (self-hosted only).

Upgrade checklist

Use this checklist when upgrading:

Check the changelog for breaking changes.
Update the SDK in a feature branch and run your test suite.
For self-hosted: run ./upgrade.sh --dry-run first.
For self-hosted: verify the backup was created.
After upgrade, call /health to confirm the new version.
Smoke-test the authorize/notarize flow.
Monitor error rates for 30 minutes after deployment.

Version Migration Guide

On this page