Upgrading

Open Astra handles database migrations automatically on startup. Most upgrades are a single command: run the new version and the gateway applies any pending migrations before accepting traffic.

⚠Always back up your database before upgrading. Migrations are applied automatically and are not automatically reversible.

Recommended process

bash

# 1. Back up the database before upgrading
pg_dump -U $PGUSER -d $PGDATABASE -F c -f astra_pre_upgrade.dump

# 2. Check release notes for breaking changes

# 3. Apply the upgrade
npx astra@latest

# 4. Verify
npx astra doctor

Upgrading npx astra

bash

# Upgrade via npx (zero-config install)
npx astra@latest

# Or pin to a specific version
npx astra@0.9.4

The gateway downloads the new version, waits for Docker services to be healthy, and then applies any pending migrations. Downtime is typically under 10 seconds for non-breaking releases.

Upgrading Docker Compose

bash

# Pull latest images
docker compose pull

# Restart containers with the new images
docker compose up -d

# Migrations run automatically on gateway start
# Watch logs to confirm:
docker compose logs -f gateway

Migrations run on container startup — you do not need to run them separately. Watch the gateway logs to confirm all migrations succeed before sending traffic.

Upgrading the standalone CLI

bash

# If you installed the standalone CLI globally
npm install -g @openastra/cli@latest

# Verify the new version
astra --version

Migration safety

Migration type	Zero-downtime?	Notes
Add column (nullable)	Yes	Safe to apply while gateway is running
Add column (non-null default)	Yes	Default fills existing rows; migration is fast
Add index	Yes	Created `CONCURRENTLY` where possible
Drop column / rename	No	Gateway must be stopped during migration; rare — always listed in release notes
New table	Yes	Additive; no impact on existing queries
HNSW index rebuild	No	Memory retrieval degrades until index is built; listed in release notes when it applies

Rolling back

Open Astra does not ship automatic down-migrations. To roll back a bad upgrade:

Stop the gateway
Restore the pre-upgrade database dump: pg_restore -U $PGUSER -d $PGDATABASE -c astra_pre_upgrade.dump
Run the previous version: npx astra@previous-version

Breaking changes and rollback procedures are documented in the release notes for any release that requires them.

See also: Health Check to verify the upgrade succeeded, Backup & Recovery for full backup procedures.