Upgrading

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

On startup, the gateway connects to Postgres
It checks the _sqlx_migrations table for already-applied migrations
Any new migrations are applied in order
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

Claude Code AWS Gateway