Database Migrations

ButtrBase uses versioned database migrations to manage schema changes safely.

Running Migrations

~~~bash

Apply all pending migrations

docker exec buttrbase buttrbase migrate up

Roll back the last migration

docker exec buttrbase buttrbase migrate down

Check migration status

docker exec buttrbase buttrbase migrate status ~~~

Migration Files

Migrations are stored in /app/migrations/ and follow the naming convention:

~~~ YYYYMMDDHHMMSS_description.sql ~~~

Zero-Downtime Migrations

ButtrBase follows these practices for zero-downtime migrations:

1. Add columns as nullable first, then backfill. 2. Never drop columns in the same release that removes code references. 3. Use shadow tables for large table rewrites. 4. Index concurrently to avoid table locks.

Backup Before Migration

~~~bash pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql docker exec buttrbase buttrbase migrate up ~~~