Skip to content
Migrations

Migrations

Schema changes applied by the one-shot Compose migrate service. File rules and the expand-then-contract order are in migrations.md. The modules are on postgres.

Where the files are

infrastructure/postgres/migrations/ holds 0001_init.sql through 0020_app_session_issuer_grants.sql.

PiecePath
CLIinfrastructure/postgres/migrate-cli.ts (unset-migrate)
Package binunset-migrate → ./migrate-cli.ts in infrastructure/postgres/package.json
Runnermigrate and migrateThenSyncPasswords in infrastructure/postgres/migrate.ts
Image entrypointENTRYPOINT ["node", "infrastructure/postgres/migrate-cli.ts"] in deployment/images/migrate.Dockerfile

The root package.json scripts are check, typecheck, lint, format, guards, notes:index, test, test:images, budgets, semgrep:fixtures, dev:up, dev:down, dev:source:up, dev:source:down, local:up and local:down. Starting the stack with dev:up, dev:source:up or local:up starts migrate.

Compose service

deployment/compose.dev.yaml, deployment/compose.dev.source.yaml and deployment/compose.local.yaml name the service migrate. compose.dev.yaml sets image to the lock ref. The source file and local set build to deployment/images/migrate.Dockerfile with context ... The image and network rows are on compose.

Shared settings in all three files:

KeyValue
user65532:65532
PG_HOSTpostgres
PG_DATABASEunset
PG_USERmigrator
PG_PASSWORD_FILE/run/secrets/migrate_pg_password
PG_SSLMODEdisable
UNSET_ENVdev
UNSET_COMMIT0000000000000000000000000000000000000000
restartno
depends_on.postgresservice_healthy
secretsmigrate_pg_password, pg_web_password, pg_api_password, pg_indexer_password

web in all three files has depends_on.migrate of service_completed_successfully.

What one run does

migrate-cli.ts calls bootOrExit(migrateConfig), then migrateThenSyncPasswords with secretsDir ROLE_PASSWORDS_DIR (/run/secrets). migrateThenSyncPasswords returns the migrate failure when migrate is not ok, and calls syncRolePasswords only when it is.

migrateConfig requires UNSET_ENV (dev, test or prod), UNSET_COMMIT (40 hex digits) and postgresFields. bootOrExit exits 78 on ConfigError (EX_CONFIG in shared/config/load.ts).

ResultExit
migrate ok and password sync ok0
migrate failurefailure.exit: 1 error, 2 an applied file was edited, 3 a gap in the versions (MigrateFailure in migrate.ts)
password sync failure1 (migrate-cli.ts sets that when step is passwords)

MIGRATE_LOCK_ID in migrate.ts is 0x756e7365. The same file’s MigrateOptions default for lockWaitMs is 60 seconds, and the default retryDelaysMs is 1, 2, 4, 8 and 16 seconds.