# PostgreSQL Migration

PG_PLAN.md §3 migrated `galaxy/user` from a Redis-only durable store to the
steady-state split codified in `ARCHITECTURE.md §Persistence Backends`:
PostgreSQL is the source of truth for table-shaped business state, and Redis
keeps only the two streams that publish auxiliary domain events
(`user:domain_events`) and trusted user-lifecycle events
(`user:lifecycle_events`).

This document records the schema decisions and the non-obvious agreements
behind them. Use it together with the migration script
(`internal/adapters/postgres/migrations/00001_init.sql`) and the runtime
wiring (`internal/app/runtime.go`).

## Outcomes

- Schema `user` (provisioned externally) holds the durable state: `accounts`,
  `blocked_emails`, `entitlement_records`, `entitlement_snapshots`,
  `sanction_records`, `sanction_active`, `limit_records`, `limit_active`.
- The runtime opens one PostgreSQL pool via `pkg/postgres.OpenPrimary`,
  applies embedded goose migrations strictly before any HTTP listener
  becomes ready, and exits non-zero when migration or ping fails.
- The runtime opens one shared `*redis.Client` via
  `pkg/redisconn.NewMasterClient` and passes it to both stream publishers
  (`internal/adapters/redis/domainevents`,
  `internal/adapters/redis/lifecycleevents`); the publishers no longer hold
  their own connection topology fields.
- `internal/adapters/redis/userstore/` and the entire
  `internal/adapters/redisstate/` package are removed. The Redis Lua scripts,
  Watch/Multi optimistic-concurrency loops, and ZSET indexes are gone.
- Configuration drops `USERSERVICE_REDIS_USERNAME`,
  `USERSERVICE_REDIS_TLS_ENABLED`, and `USERSERVICE_REDIS_KEYSPACE_PREFIX`.
  `USERSERVICE_REDIS_ADDR` is replaced by
  `USERSERVICE_REDIS_MASTER_ADDR` + optional
  `USERSERVICE_REDIS_REPLICA_ADDRS`. Postgres-specific knobs live under
  `USERSERVICE_POSTGRES_*` per the architectural rule.

## Decisions

### 1. One schema, externally-provisioned role

**Decision.** The `user` schema and the matching `userservice` role are
created outside the migration sequence (in tests, by
`integration/internal/harness/postgres_container.go::EnsureRoleAndSchema`;
in production, by an ops init script not in scope for this stage). The
embedded migration `00001_init.sql` only contains DDL for tables and
indexes and assumes it runs as the schema owner with `search_path=user`.

**Why.** Mixing role creation, schema creation, and table DDL into one
script forces every consumer of the migration to run as a superuser. The
schema-per-service architectural rule
(`ARCHITECTURE.md §Persistence Backends`) lines up neatly with the
operational split: ops provisions roles and schemas, the service applies
schema-scoped migrations.

### 2. `entitlement_snapshots` stays denormalised

**Decision.** A dedicated `entitlement_snapshots` table holds exactly one
row per `user_id` mirroring the current effective fields (`plan_code`,
`is_paid`, `starts_at`, `ends_at`, `source`, `actor_*`, `reason_code`,
`updated_at`). Lifecycle operations (`Grant`, `Extend`, `Revoke`,
`RepairExpired`) write the history row and the snapshot row inside one
transaction.

**Why.** The lobby-eligibility hot-path reads exactly one row per user; a
JOIN over `entitlement_records` to compute the current segment would add
latency and wire-format complexity. Keeping the snapshot denormalised
matches the previous Redis shape where the hot read returned a
pre-materialised JSON blob, which preserves the existing service-layer
contract and the public REST envelope.

### 3. `sanction_active` / `limit_active` are the source of truth for "active"

**Decision.** The active state of a sanction or a user-specific limit is
expressed by a small dedicated table (`sanction_active`, `limit_active`)
whose primary key is `(user_id, code)`. Each row references the matching
history record by `record_id`. Lifecycle operations maintain both tables
inside one transaction.

**Why.** The lobby-eligibility hot path needs to enumerate active
sanctions/limits without scanning the full history. Encoding "active"
as a partial index on `removed_at IS NULL` would still require dedup
because a user can apply, remove, and re-apply the same code. Two narrow
tables let the same predicates that the Redis adapter encoded as
`active` keys remain index-only.

### 4. Eligibility flags are computed predicates, not stored columns

**Decision.** No `can_login`, `can_create_private_game`, `can_join_game`
columns or indexes exist. The admin listing surface (and the lobby
eligibility snapshot) compute these from `entitlement_snapshots` and
`sanction_active` at read time.

**Why.** Stage 21 expanded the eligibility marker catalogue and Stage 22
added `permanent_block`. Each addition would have required schema work
plus a backfill if eligibility flags were materialised columns. Computed
predicates push that complexity into one place — the SQL query — and
keep the schema small.

### 5. Atomic flows use explicit `BEGIN … COMMIT` with per-row `FOR UPDATE`

**Decision.** Composite operations (`AuthDirectoryStore.{Resolve,
Ensure, Block*}`, `EntitlementLifecycleStore.{Grant, Extend, Revoke,
RepairExpired}`, `PolicyLifecycleStore.{ApplySanction, RemoveSanction,
SetLimit, RemoveLimit}`) execute inside `store.withTx` and acquire row
locks with `SELECT … FOR UPDATE` on the rows they intend to mutate.
Optimistic-replacement guards (`Expected*Record`, `Expected*Snapshot`)
are validated against the locked rows before the write goes through;
mismatches surface as `ports.ErrConflict`.

**Why.** PostgreSQL's default `READ COMMITTED` isolation plus row-level
locks gives us the serialisation property the previous Redis
WATCH/MULTI loops achieved without needing the application to retry on
optimistic-failure errors. The explicit `FOR UPDATE` keeps intent
visible; ad-hoc CTE patterns would obscure the locking shape.

### 6. Query layer is `go-jet/jet/v2`

**Decision.** All `userstore` packages build SQL through the jet
builder API (`pgtable.<Table>.INSERT/SELECT/UPDATE/DELETE` plus the
`pg.AND/OR/SET/...` DSL). `cmd/jetgen` (invoked via `make jet`) brings
up a transient PostgreSQL container, applies the embedded migrations,
and runs `github.com/go-jet/jet/v2/generator/postgres.GenerateDB`
against the provisioned schema; the generated table/model code lives
under `internal/adapters/postgres/jet/user/{model,table}/*.go` and is
committed to the repo, so build consumers do not need Docker.
Statements are run through the `database/sql` API
(`stmt.Sql() → db.Exec/Query/QueryRow`); manual `rowScanner` helpers
preserve domain-type marshalling.

**Why.** Aligns with `PG_PLAN.md` §Library stack ("Query layer:
`github.com/go-jet/jet/v2` (PostgreSQL dialect). Generated code lives
under each service `internal/adapters/postgres/jet/`, regenerated via
a `make jet` target and committed to the repo"). Constructs the jet
builder does not cover natively (`FOR UPDATE`, keyset-pagination
row-comparison, partial UNIQUE WHERE in `CREATE INDEX`) are expressed
through the per-DSL helpers (`.FOR(pg.UPDATE())`, `OR/AND` expansion
of `(created_at, user_id) < (…)`). The ports contract and the schema
do not change.

### 7. Redis publishers share one `*redis.Client`

**Decision.** `internal/app/runtime.go` constructs one
`redisconn.NewMasterClient(cfg.Redis.Conn)` and passes it to both
`domainevents.New(client, cfg)` and `lifecycleevents.New(client,
cfg)`. The publishers no longer carry connection-topology fields and
no longer close the client; the runtime owns it.

**Why.** Each subsequent PG_PLAN stage (Mail, Notification, Lobby)
ships a similar duo of stream publishers; sharing one client is the
shape we want all stages to converge on. Per-publisher clients
multiplied TCP connections, ping points, and OpenTelemetry
instrumentation hooks for no functional benefit.

### 8. Mandatory Redis password in tests as well

**Decision.** Unit tests for the publishers configure
`miniredis.RequireAuth("integration")` and pass a matching password
through their direct `redis.NewClient(...)` construction. The runtime
contract test
(`runtime_contract_test.go::newRuntimeContractHarness`) does the same
plus boots a Postgres container.

**Why.** The architectural rule forbids password-less Redis
connections; carrying the constraint into tests prevents the rule
from drifting.

### 9. Listing surface keeps storage-thin pagination

**Decision.** `UserListStore.ListUserIDs` paginates only on
`(created_at DESC, user_id DESC)` with keyset cursors carried by the
opaque page token. Filter matrix evaluation (paid_state,
declared_country, sanction_code, limit_code, can_*) is performed by
the service-layer `adminusers.Lister`, which loads each candidate
through the per-user loader. This mirrors the previous Redis
behaviour exactly.

**Why.** Pushing the filter matrix into SQL is desirable — it eliminates
candidate over-fetching — but doing it without changing the public
`UserListStore.ListUserIDs` contract (which returns a page of
`UserID`, not full records) requires a JOIN-driven query. That work
is a non-breaking optimisation and is intentionally deferred so this
stage focuses on the storage cut-over rather than throughput
improvements. The page-token wire format is preserved bit-for-bit so
already-issued tokens keep working.

## Cross-References

- `PG_PLAN.md §3` (Stage 3 — User Service migration / pilot).
- `ARCHITECTURE.md §Persistence Backends`.
- `internal/adapters/postgres/migrations/00001_init.sql` and
  `internal/adapters/postgres/migrations/migrations.go`.
- `internal/adapters/postgres/userstore/{store,accounts,blocked_emails,
  auth_directory,entitlement_store,policy_store,list_store,page_token,
  helpers}.go` plus the testcontainers-backed unit suite under
  `userstore/{harness,store}_test.go`.
- `internal/adapters/postgres/jet/user/{model,table}/*.go` (committed
  generated code) plus `cmd/jetgen/main.go` and the `make jet`
  Makefile target that regenerate it.
- `internal/config/config.go` (`PostgresConfig`, `RedisConfig` reshape).
- `internal/app/runtime.go` (PG pool open + migration + shared Redis
  client wiring).
- `internal/adapters/redis/{domainevents,lifecycleevents}/publisher.go`
  (refactored to accept the shared `*redis.Client`).
- `runtime_contract_test.go::startPostgresForContractTest` (shows the
  inline Postgres bootstrap used by the existing runtime contract).