Upgrading

April 2, 2026 ยท View on GitHub

This guide covers how to upgrade CCAG to a new version, handle database migrations, and roll back if needed.

Checking for Updates

Current Version

Check the currently deployed version:

# The image tag is the 8-character commit SHA
# Check what's running in ECS via the AWS console or:
aws ecs describe-services --cluster CCAG --services CCAG \
  --query 'services[0].taskDefinition' --output text

Available Updates

Check for new releases on GitHub:

git fetch origin
git log HEAD..origin/main --oneline

Docker Compose

Pre-built images are published to GitHub Container Registry on every release.

Update to latest

docker compose pull        # Pull latest image from GHCR
docker compose up -d       # Restart with new image

Pin to a specific version

Set CCAG_VERSION in your .env file or pass it directly:

CCAG_VERSION=1.1.0 docker compose up -d

Check available versions

gh release list --repo antkawam/claude-code-aws-gateway

CDK (ECS Fargate)

CDK deployments pull from GHCR by default. Deploy a specific release version:

cd infra
npx cdk deploy -c environment=prod -c imageTag=1.1.0

To review what changed between versions, check the release notes.

Database Migrations

CCAG uses sqlx migrations stored in the migrations/ directory. Migrations are applied automatically on startup. No manual intervention is needed.

How It Works

  1. On startup, the gateway connects to Postgres
  2. It checks the _sqlx_migrations table for already-applied migrations
  3. Any new migrations are applied in order
  4. The gateway continues startup after all migrations complete

Migration Safety

  • Migrations are append-only. Existing migration files must not be modified.
  • Each migration runs in a transaction
  • If a migration fails, the gateway exits with an error and the failed migration is not marked as applied
  • ECS will restart the task, retrying the migration

Checking Migration Status

Connect to the database and query:

SELECT version, description, installed_on, success
FROM _sqlx_migrations
ORDER BY version;

Breaking Changes Policy

CCAG follows these principles for breaking changes:

  • API compatibility: The Anthropic Messages API translation is always backward compatible. New Anthropic API features are added; existing behavior is preserved.
  • Admin API: Changes to admin endpoints are noted in commit messages. The admin API is not yet versioned.
  • Configuration: New environment variables use sensible defaults. Existing variables retain their behavior.
  • Database schema: Migrations handle schema changes automatically. No manual SQL is required.

When a breaking change is unavoidable, it will be documented in the release notes with migration instructions.

Rollback Procedure

If an upgrade causes issues, you can roll back to a previous version.

Option 1: Redeploy a Previous Image

The quickest rollback. Deploy a known-good image:

# Find the previous image tag (8-char commit SHA)
git log --oneline -5

# Deploy the previous image directly via CDK
cd infra
npx cdk deploy -c environment=prod -c imageTag=abcd1234

Option 2: Fast Rollback (Skip CloudFormation)

For immediate rollback without CloudFormation:

# Update the ECS service task definition directly (bypasses CDK)
# See infra/README.md for details on direct ECS task definition updates

This directly updates the ECS service task definition, bypassing CDK.

Option 3: Git Revert and Redeploy

For a permanent rollback:

git revert HEAD
# Rebuild and redeploy (see infra/README.md for full deployment steps)

Database Rollback Considerations

CCAG migrations are forward-only. If a migration introduced schema changes:

  • The previous application version must still be compatible with the new schema (migrations are designed to be backward-compatible where possible)
  • If the schema is incompatible, you must manually reverse the migration in the database before rolling back the application

See Also