Skip to main content
InternalMarkdown

ADR 0023. TypeORM Owns Nest Data Access and DDL

Status​

Accepted.

Context​

The Nest control plane used raw pg via DbService and hand-maintained schema/schema.sql + numbered SQL migrations. Applying schema changes required manual psql. ADR 0021 named schema/schema.sql as the system-of-record DDL path; that conflicts with wanting Nest-owned migrations and typed repositories.

Decision​

  1. Use TypeORM (@nestjs/typeorm) as the Nest data layer for PlayerPal Postgres: entities + repositories / EntityManager, synchronize: false.
  2. TypeORM migrations under services/api/src/db/migrations/ are the canonical DDL for playerpal-db. Fresh volumes start empty; the API entrypoint (or task db:migrate) runs migrations before serving.
  3. Move former schema/schema.sql and schema/migrations/*.sql to schema/historical/ (do not extend). Keep schema/seeds/demo.sql for task db:seed.
  4. Do not put TypeORM in the Go worker; workers may consume SQL dumps later.
  5. Never store player email, name, or phone (ADR 0012). Opaque IAM subjects (iam_subject, session iam_user_id) are not PII and must not appear on /v1/me.

Consequences​

  • Local: task db:migrate then task db:seed (or rebuild API so entrypoint migrates).
  • Existing volumes: prefer task down:volumes once, or rely on idempotent baseline CREATE IF NOT EXISTS + EnsureColumns migration.
  • ADR 0021 item 3 is amended: Postgres remains the system of record; DDL path is TypeORM, not schema/schema.sql.