# 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`.