Run migrations and upgrade

SupaCloud uses sqlx numbered migrations in server/migrations/. The server runs every pending migration automatically on boot — you do not run migrations manually. This guide covers the safe upgrade sequence: back up first, pull the new image, restart.

Note

Migrations are numbered sequentially and applied in order. The server tracks which migrations have already run and only executes new ones. Never edit or delete an applied migration file.

Before you start

• You need write access to the host running the Docker Compose stack.

• Confirm the stack is healthy before upgrading:

  docker compose -f docker-compose.yml -f compose.standalone.yml ps

  All services should show healthy or running. Do not upgrade a degraded stack.

1. Back up the PostgreSQL volume

Database state lives in the postgres-data Docker volume. Back it up before pulling a new image.

1. Stop the server (leave Postgres running so the dump is consistent):

   docker compose -f docker-compose.yml -f compose.standalone.yml stop server

2. Dump the database to a local file:

   docker compose -f docker-compose.yml -f compose.standalone.yml \
     exec postgres \
     pg_dump -U supacloud supacloud \
     > supacloud-backup-$(date +%Y%m%d-%H%M%S).sql

   Replace supacloud with your POSTGRES_USER / POSTGRES_DB values from .env if you changed them from the defaults.

3. Verify the dump file is non-empty before continuing.

Caution

Never skip the backup step. Migrations that alter or rename tables cannot be rolled back automatically once the server has started against the new schema. The highest migration number on main is currently 203 — always check server/migrations/ in the release you are upgrading to so you know what schema changes are coming.

2. Pull the new image and restart

1. Pull the new image:

   docker compose -f docker-compose.yml -f compose.standalone.yml pull server

2. Start the stack:

   docker compose -f docker-compose.yml -f compose.standalone.yml up -d

   The server service waits for the postgres health check, then runs all pending migrations before opening the HTTP port. Watch the log to confirm:

   docker compose -f docker-compose.yml -f compose.standalone.yml logs -f server

   You should see a line similar to:

   Database migrations complete

3. Confirm the stack is healthy:

   docker compose -f docker-compose.yml -f compose.standalone.yml ps

What to do if a migration fails

If the server exits with Migration failed: in its log:

1. Do not force-restart the server in a loop — each restart re-attempts the same migration and may leave the schema in a partial state.

2. Restore from the backup you took in step 1, then investigate the error before retrying:

   docker compose -f docker-compose.yml -f compose.standalone.yml \
     exec postgres \
     psql -U supacloud supacloud < supacloud-backup-YYYYMMDD-HHMMSS.sql

3. Open an issue with the full migration error message and the migration filename (format: NNN_description.sql).

Related

• Self-host with Docker Compose — initial setup
• Environment variables — DATABASE_URL and other required variables
• Secret provisioning — moving secrets out of .env