Upgrading

This guide covers how to upgrade RAT to a new version, what to expect during the upgrade process, and how to roll back if something goes wrong.

Version Scheme

RAT follows Semantic Versioning (SemVer):

v2.MAJOR.MINOR

Releases are tagged in Git with the version number (e.g., v2.1.0).

Upgrade Process

# Check your current version
curl -s http://localhost:8080/health | jq .version
 
# View release notes on GitHub
gh release list --repo squat-collective/rat
gh release view v2.2.0 --repo squat-collective/rat

# Dump Postgres
docker compose exec postgres pg_dump -U rat rat > backup-$(date +%Y%m%d).sql

docker compose pull

curl -fsSL https://raw.githubusercontent.com/squat-collective/rat/main/install/install.sh | bash -s -- --version=2.2.0 --dir=.

docker compose up -d

# Check health
curl -s http://localhost:8080/health | jq .
 
# Check version
curl -s http://localhost:8080/health | jq .version

# Check your current version
curl -s http://localhost:8080/health | jq .version
 
# View release notes on GitHub
gh release list --repo squat-collective/rat
gh release view v2.2.0 --repo squat-collective/rat

make backup

git fetch origin
git checkout v2.2.0   # checkout the target version tag

git pull origin main

make build

make rebuild

make restart

# Check health
curl -s http://localhost:8080/health | jq .
 
# Check version
curl -s http://localhost:8080/health | jq .version
 
# Run smoke test
make smoke-test

Database Migrations

RAT runs database migrations automatically on startup. When ratd starts, it:

1. Connects to PostgreSQL
2. Checks the current schema version in the schema_migrations table
3. Applies any pending migrations in order
4. Continues with normal startup

Migration Behavior

Checking Migration Status

The schema_migrations table tracks which migrations have been applied:

docker compose -f infra/docker-compose.yml exec postgres \
  psql -U rat -d rat -c "SELECT * FROM schema_migrations ORDER BY version;"

Breaking Changes Policy

RAT follows these rules for breaking changes:

1. Deprecation first: Features are deprecated for at least one minor version before removal
2. Migration provided: Database schema changes include automatic migrations
3. Configuration changes documented: New, renamed, or removed environment variables are listed in release notes
4. API versioning: Breaking API changes increment the API version (/api/v1 → /api/v2). Old versions are supported for at least one major release
5. Proto compatibility: Protobuf changes are checked with buf breaking in CI. Backward-incompatible changes require a new proto version

Types of Breaking Changes

Rollback Procedure

If an upgrade causes problems, you can roll back to the previous version.

make down

git checkout v2.1.0   # your previous working version

make restore BACKUP_DIR=./backups/<pre-upgrade-timestamp>

make build

make up

curl -s http://localhost:8080/health | jq .
make smoke-test

Zero-Downtime Upgrades

For environments that cannot tolerate downtime, consider this approach:

Rolling Update (Multiple Replicas)

If you run multiple ratd replicas behind a load balancer:

1. Build new images
2. Restart one replica at a time
3. Wait for the new replica to become healthy before restarting the next
4. The load balancer routes traffic to healthy replicas during the update

Blue-Green Deployment

1. Stand up a complete second stack (blue) with the new version
2. Restore data from a backup to the blue stack
3. Switch the load balancer from green (old) to blue (new)
4. If problems occur, switch back to green

This approach requires double the infrastructure but provides the safest upgrade path.

Upgrade Checklist

• Read release notes for all versions between current and target
• Create backup (make backup)
• Verify backup integrity (spot-check files, dump size)
• Pull latest code and checkout target version
• Rebuild images (make build)
• Restart services (make restart)
• Check health (curl http://localhost:8080/health)
• Run smoke test (make smoke-test)
• Verify pipelines in the portal
• Monitor logs for errors for 30 minutes
• Remove old backup after confirming stability (optional)

Version Compatibility Matrix

When upgrading, all RAT services must run the same version. Do not mix versions across services.