Maintenance Operations

This page describes the supported procedure for applying schema migrations and restarting Nitro Repo in a production environment.

Applying database migrations

Nitro uses SQL files under crates/core/migrations. To apply them manually:

1. Back up the database using your standard tooling.
2. Connect to Postgres with the same user Nitro runs under. Example using psql:

   psql "$DATABASE_URL"

3. Run the pending migration scripts in chronological order. Each migration consists of an *.up.sql file. For example:

   \i crates/core/migrations/20251115103000_repository_indexes.up.sql

   Repeat for each newer migration. Keep the session open so you can roll back with the matching *.down.sql if needed.
4. Verify with SELECT or \d that the new indexes/tables exist.

Tip: If you manage Postgres with a migration runner (e.g., sqlx-cli or just migrate), use that wrapper instead of applying SQL manually.

Restarting Nitro Repo services

After migrations, rebuild and restart the services:

1. Stop the running stack:

   docker compose down

2. Rebuild (if code changed):

   ./dev.sh

   or run npm --prefix site run build && cargo build --features frontend
3. Start:

   docker compose up -d

4. Check logs for migration output:

   docker compose logs nitro_repo

Keep maintenance windows short: apply migrations first, then restart services once the schema is in place so requests hitting old binaries do not fail mid-migration.