galaxy-game/user/docs/postgres-migration.md

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).