galaxy-game/PG_PLAN.md

PostgreSQL Migration Plan

This plan has been already implemented and stays here for historical reasons.

It should NOT be threated as source of truth for service functionality.

Context

The Galaxy Game project currently uses Redis as the only persistence backend across all implemented services (user, mail, notification, lobby, gateway, authsession). Redis serves both kinds of state: ephemeral and runtime-coordination state (where it shines — Streams, caches, replay keys, runtime queues, session caches, leases) and table-shaped business state where it is a poor fit (durable user accounts, entitlements/sanctions, mail audit records, notification routes/idempotency, lobby memberships and invites). Replication and standby for Redis are not configured anywhere. There is no SQL/migration tooling in the repo at all.

We migrate to a Redis + PostgreSQL split where each backend owns the data it serves best. PostgreSQL becomes the source of truth for table-shaped business state, gives us ACID transactions, mature physical/logical replication, and backup/restore via pg_dump and WAL archiving. Redis remains the source of truth for streams, pub/sub, caches, leases, replay keys, rate limits, session caches, runtime queues, and stream consumer offsets.

The plan migrates only services already implemented and explicitly excludes galaxy/game. It targets steady-state architecture rules first (one authoritative document, ARCHITECTURE.md), then walks each service end to end — code, tests, service-local README/docs, and integration suites — so that no intermediate commit leaves docs and code in conflict.

Confirmed decisions (with project owner)

1. Documentation strategy: ARCHITECTURE.md is updated as the very first stage with the architecture-wide rules. Each per-service README and per- service docs/ change inside that service's own stage, paired with code and tests. This keeps ARCHITECTURE.md ≡ policy, README ≡ current state, and ensures any commit can be checked out without code/doc divergence.
2. Service scope: full migration of durable storage to PostgreSQL for user, mail, notification, lobby. Only Redis configuration refactor (master/replica + mandatory password, drop TLS_ENABLED / USERNAME) for gateway and authsession — these services intentionally stay Redis- only. geoprofile has no implementation; its PLAN.md and README.md absorb the new persistence rules so future implementation follows them.
3. Idempotency and retry-schedule placement: idempotency records and retry schedule queues live in PostgreSQL on the same table as the durable record they protect ((producer, idempotency_key) UNIQUE on records, next_attempt_at column on deliveries / routes). One source of truth, no dual-write hazard between PG and Redis ZSETs.
4. Stack: github.com/jackc/pgx/v5 driver, exposed as *sql.DB via github.com/jackc/pgx/v5/stdlib. github.com/go-jet/jet/v2 for type-safe query building + code generation, generated against a testcontainers PostgreSQL instance with migrations applied (Makefile target per service). github.com/pressly/goose/v3 library API for embedded migrations applied at service startup; the goose CLI may be used for local development and rollback investigations but is not in the service binary path.
5. Code: all postgres queries must use pre-generated code with jet and appropriate builders rather than raw SQL queries, unless this usage cannot achive the goal of businness-scenario due to lack of go-jet functionality.

Architectural rules (target steady-state)

These rules land in ARCHITECTURE.md in Stage 0 and govern every subsequent service stage.

Backend assignment

PostgreSQL is the source of truth for:

• Domain entities with table-shaped business state (accounts, entitlement_records, sanction_records, limit_records, blocked_emails, deliveries, attempts, dead_letters, malformed_commands, notification_records, notification_routes, games, applications, invites, memberships, race_names).
• Idempotency records (UNIQUE constraint on the durable table, not a separate kv).
• Retry scheduling state (next_attempt_at column + supporting index on the durable table).
• Audit history records that must outlive any Redis snapshot.

Redis is the source of truth for:

• Redis Streams used as the event bus (user:domain_events, user:lifecycle_events, gm:lobby_events, runtime:job_results, notification:intents, gateway:client-events, mail:delivery_commands).
• Stream consumer offsets (small runtime coordination state, rebuildable).
• Caches and projections (gateway session cache).
• Replay reservation keys.
• Rate limit counters.
• Runtime coordination locks/leases (e.g. notification route_leases).
• Authentication challenge state and active session tokens (TTL-bounded; loss is recoverable by re-authentication).
• Ephemeral per-game runtime aggregates that are deleted at game finish (lobby game_turn_stats, gap_activated_at, capability evaluation marker).

Database topology

• Single PostgreSQL database galaxy.
• Schema-per-service: user, mail, notification, lobby. Reserved for later: geoprofile. Not allocated unless needed: gateway, authsession.
• Per-service PostgreSQL role with grants restricted to its own schema (defense-in-depth, simple to express in the initial migration).
• Authentication: username + password only. sslmode=disable. No client certificates, no SCRAM channel binding, no custom auth plugins.
• Each service connects to one primary plus zero-or-more read-only replicas. In this iteration only the primary is used; the replica pool is wired but receives no traffic. Future read-routing is non-breaking.

Redis topology

• Each service connects to one master Redis plus zero-or-more replica Redis hosts.
• All connections use a mandatory password. USERNAME/ACL not used. TLS off.
• In this iteration only the master is used; the replica list is wired but unused — non-breaking switch later when the app starts routing reads.
• Existing env vars *_REDIS_TLS_ENABLED, *_REDIS_USERNAME are removed (hard rename; no backward-compat shim — fresh project, no production deploys to migrate).

Library stack

• Driver: github.com/jackc/pgx/v5 (modern, actively maintained), exposed to database/sql via github.com/jackc/pgx/v5/stdlib so go-jet's qrm.Queryable interface is satisfied without changes.
• 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.
• Migrations: github.com/pressly/goose/v3 library API; migration files embedded via //go:embed *.sql; applied at startup, before opening any HTTP/gRPC listener; non-zero exit on failure.
• Test infrastructure: github.com/testcontainers/testcontainers-go plus the modules/postgres submodule; the same setup is reused by make jet to host a transient instance for jet codegen.

Migration discipline

• Forward-only sequence-numbered files: 00001_init.sql, 00002_*.sql, …
• Lowercase snake_case names; goose -- +goose Up / -- +goose Down markers; statements that need transaction-wrapping use -- +goose StatementBegin / -- +goose StatementEnd.
• Migrations apply at service startup; service exits non-zero on failure.
• Per-service decision record at galaxy/<service>/docs/postgres-migration.md captures schema decisions and any non-trivial deviation from the rules.

Per-service code organisation

galaxy/<service>/
  internal/
    adapters/
      postgres/
        migrations/         # *.sql files + migrations.go (//go:embed)
        jet/                # generated; commit-checked
        <portname>/         # adapter implementations matching internal/ports
    config/
      config.go             # adds Postgres + new Redis schema
  Makefile                  # `jet` target: testcontainers + goose + jet

Test patterns

• Per-service unit tests against a real PostgreSQL via testcontainers-go; replace the corresponding miniredis test path where storage moved to PG.
• Shared port-test suites (e.g. lobby/internal/ports/racenamedirtest/) gain a Postgres harness; they remain backend-agnostic in shape.
• integration/internal/harness/postgres_container.go is added; integration suites that need PG declare it next to their existing Redis container.
• Stub adapters (*stub/) are kept where the in-memory port is useful for tests that don't need a real backend. Redis adapters that previously implemented these ports are removed (no dead code).

Configuration env vars (target)

For each service <S> ∈ { USERSERVICE, MAIL, NOTIFICATION, LOBBY, GATEWAY, AUTHSESSION }:

• <S>_REDIS_MASTER_ADDR (required)
• <S>_REDIS_REPLICA_ADDRS (optional, comma-separated; default empty)
• <S>_REDIS_PASSWORD (required)
• <S>_REDIS_DB (default 0)
• <S>_REDIS_OPERATION_TIMEOUT (default 250ms)

For PG-backed services (USERSERVICE, MAIL, NOTIFICATION, LOBBY):

• <S>_POSTGRES_PRIMARY_DSN (required; e.g. postgres://userservice:secret@postgres:5432/galaxy?search_path=user&sslmode=disable)
• <S>_POSTGRES_REPLICA_DSNS (optional, comma-separated)
• <S>_POSTGRES_OPERATION_TIMEOUT (default 1s)
• <S>_POSTGRES_MAX_OPEN_CONNS (default 25)
• <S>_POSTGRES_MAX_IDLE_CONNS (default 5)
• <S>_POSTGRES_CONN_MAX_LIFETIME (default 30m)

DSN sets search_path=<schema> so unqualified table references resolve into the service-owned schema; sslmode=disable is set explicitly per the "no TLS" requirement.

Service-prefix-specific stream/keyspace env vars (*_REDIS_DOMAIN_EVENTS_STREAM, *_REDIS_LIFECYCLE_EVENTS_STREAM, *_REDIS_KEYSPACE_PREFIX, MAIL_REDIS_COMMAND_STREAM, etc.) keep their current names and semantics — they describe stream/key shapes, not connection topology.

---

Stages

Each stage is independently executable and shippable.

Stage 0 — Architecture-wide rules and PG_PLAN.md materialisation

This stage is implemented.

Goal: land the steady-state rules in ARCHITECTURE.md and place PG_PLAN.md at the project root so subsequent /stage-implementation invocations have an authoritative reference.

Actions:

1. Write the contents of this plan file to /Users/id/src/go/galaxy/PG_PLAN.md.
2. Add a new section to ARCHITECTURE.md (e.g. §9 Persistence Backends) capturing every rule under the Architectural rules heading above: backend assignment, database/Redis topology, library stack, migration discipline, code organisation, test patterns, env-var conventions.
3. Add a short Migration Window sub-section to ARCHITECTURE.md noting that until all PG_PLAN.md stages complete, each service's README.md continues to describe its actual current state — this caveat is removed in Stage 9.
4. Adjust ARCHITECTURE.md §8 (publisher rules) so cross-references distinguish "Redis Stream" (event bus, stays Redis) from "PG-backed table" (durable record).

Files (modified / new):

• /Users/id/src/go/galaxy/PG_PLAN.md — new
• /Users/id/src/go/galaxy/ARCHITECTURE.md — modified

Out of scope: zero service code, zero per-service README/docs, zero go.mod changes, zero new dependencies in service modules.

Verification:

• git diff --stat reports two paths only: PG_PLAN.md, ARCHITECTURE.md.
• ARCHITECTURE.md reads coherently end to end, with the new section cross-referenced from §8 and from any other place that today says "Redis is the v1 backend".
• Manual: read PG_PLAN.md top to bottom, confirm every architectural decision matches the section in ARCHITECTURE.md.

---

Stage 1 — Shared infrastructure packages (pkg/postgres, pkg/redisconn)

This stage is implemented.

Goal: provide one canonical helper each for Postgres and Redis so per- service stages don't reinvent connection/migration wiring. No service consumes them yet.

Files (new):

• pkg/postgres/config.go — Config struct (PrimaryDSN, ReplicaDSNs, OperationTimeout, MaxOpenConns, MaxIdleConns, ConnMaxLifetime); helper LoadFromEnv(prefix string) (Config, error) that reads <prefix>_POSTGRES_*.
• pkg/postgres/open.go — OpenPrimary(ctx, cfg) (*sql.DB, error) and OpenReplicas(ctx, cfg) ([]*sql.DB, error) using pgx.ConnConfig → stdlib.OpenDB(...); configures pool sizes and per-statement context timeout.
• pkg/postgres/migrate.go — RunMigrations(ctx context.Context, db *sql.DB, fs embed.FS) error wrapping goose.SetBaseFS(fs) + goose.UpContext.
• pkg/postgres/otel.go — Instrument(db *sql.DB, telemetry telemetry.Runtime) applying otelsql.RegisterDBStatsMetrics and statement spans.
• pkg/postgres/postgres_test.go — testcontainers-backed smoke test: open primary, run a one-line migration, insert/select.
• pkg/redisconn/config.go — Config struct (MasterAddr, ReplicaAddrs, Password, DB, OperationTimeout); helper LoadFromEnv(prefix string) (Config, error) that reads <prefix>_REDIS_* (the new shape only; rejects deprecated TLS/USERNAME vars with a clear error).
• pkg/redisconn/client.go — NewMasterClient(cfg) *redis.Client and NewReplicaClients(cfg) []*redis.Client (latter returns nil/empty when replicas not configured).
• pkg/redisconn/otel.go — Instrument(client *redis.Client, telemetry telemetry.Runtime) applying redisotel.InstrumentTracing / InstrumentMetrics.
• pkg/redisconn/redisconn_test.go — miniredis-backed config and master client tests.

Files (touched):

• pkg/go.mod — add github.com/jackc/pgx/v5, github.com/jackc/pgx/v5/stdlib, github.com/pressly/goose/v3, github.com/testcontainers/testcontainers-go/modules/postgres, github.com/XSAM/otelsql (for db instrumentation; alternative: go.nhat.io/otelsql — pick one in implementation).
• go.work — confirm pkg/ is registered (already is).

Verification:

• cd /Users/id/src/go/galaxy/pkg && go test ./postgres/... ./redisconn/... passes locally with Docker available.
• go vet ./... clean.

---

Stage 2 — Integration test harness extension

This stage is implemented.

Goal: extend integration/internal/harness/ with a Postgres container helper and a service-bootstrap helper that builds the per-service DSN with the right search_path. All existing integration suites stay green.

Files (new):

• integration/internal/harness/postgres_container.go — StartPostgresContainer(t testing.TB) *PostgresRuntime. The runtime exposes BaseDSN(), DSNForSchema(schema, role string) string, and EnsureRoleAndSchema(ctx, schema, role, password string) error so each test can prepare an isolated schema for the service it is booting.
• integration/internal/harness/postgres_container_test.go — smoke test.

Files (touched):

• integration/internal/harness/binary.go — extend Process/launch helpers with WithPostgres(rt *PostgresRuntime, schema, role string) that injects the right <S>_POSTGRES_PRIMARY_DSN. (Existing API already takes env map[string]string; this is a thin wrapper.)
• integration/go.mod — add the testcontainers Postgres module.

Out of scope: no integration suite is yet wired to Postgres; each service stage wires in its suites.

Verification:

• cd integration && go test ./internal/harness/... passes.
• cd integration && go test ./... still green for all existing suites (Redis-only services remain Redis-only).

---

Stage 3 — User Service migration (pilot)

Goal: replace User Service's Redis durable storage with PostgreSQL. The two Redis Streams (user:domain_events, user:lifecycle_events) remain on Redis. This stage is the pilot; subsequent service stages copy its shape.

Schema (user schema):

• accounts (user_id PK, email UNIQUE, user_name UNIQUE, display_name, preferred_language, time_zone, declared_country, created_at, updated_at, deleted_at).
• blocked_emails (email PK, reason_code, blocked_at, actor_type, actor_id, resolved_user_id).
• entitlement_records (record_id PK, user_id FK, plan_code, is_paid, starts_at, ends_at, source, actor_type, actor_id, reason_code, updated_at).
• entitlement_snapshots (user_id PK FK → accounts, …current effective values mirroring Redis snapshot shape).
• sanction_records (record_id PK, user_id FK, sanction_code, scope, reason_code, actor_type, actor_id, applied_at, expires_at, removed_at, removed_by_type, removed_by_id, removed_reason_code).
• sanction_active (user_id, sanction_code, record_id) PRIMARY KEY (user_id, sanction_code).
• limit_records, limit_active — analogous to sanctions.
• Indexes: accounts(created_at DESC, user_id DESC) for newest-first pagination; accounts(declared_country); entitlement_snapshots(plan_code, is_paid); entitlement_snapshots(ends_at) WHERE is_paid AND ends_at IS NOT NULL; sanction_active(sanction_code); limit_active(limit_code). Eligibility flags become computed predicates on these columns.

Files (new):

• galaxy/user/internal/adapters/postgres/migrations/00001_init.sql — full schema with grants (GRANT USAGE ON SCHEMA user TO userservice; GRANT … ON ALL TABLES …;).
• galaxy/user/internal/adapters/postgres/migrations/migrations.go — //go:embed *.sql and a Migrations() embed.FS accessor.
• galaxy/user/internal/adapters/postgres/jet/... — generated code (commit-checked).
• galaxy/user/internal/adapters/postgres/userstore/store.go — Postgres implementation of ports.UserAccountStore and ports.AuthDirectoryStore.
• galaxy/user/internal/adapters/postgres/userstore/entitlement_store.go — Postgres implementation of EntitlementSnapshotStore and EntitlementHistoryStore.
• galaxy/user/internal/adapters/postgres/userstore/policy_store.go — Postgres implementation of SanctionStore and LimitStore.
• galaxy/user/internal/adapters/postgres/userstore/list_store.go — Postgres implementation of UserListStore (pagination + filters expressed as SQL).
• galaxy/user/internal/adapters/postgres/userstore/store_test.go and siblings — testcontainers-backed unit tests covering the same matrix the current Redis tests cover.
• galaxy/user/Makefile — jet target.
• galaxy/user/docs/postgres-migration.md — decision record (schema shape, why we keep entitlement_snapshots denormalised, eligibility expressed as SQL predicates, schema role grants).

Files (touched):

• galaxy/user/internal/config/config.go — add Postgres config; refactor Redis config to master/replica/password (drop TLS_ENABLED, USERNAME).
• galaxy/user/internal/config/config_test.go — update to new env shape.
• galaxy/user/internal/app/runtime.go — open Postgres pool, run migrations on startup before listeners open, wire postgres adapters into services. Redis client now serves only the two stream publishers.
• galaxy/user/README.md — replace "Redis-backed user state" with the new persistence model, update env-var section.
• galaxy/user/docs/runbook.md, galaxy/user/docs/runtime.md, galaxy/user/docs/examples.md — update storage references and config sections.
• galaxy/user/go.mod — add github.com/jackc/pgx/v5{,/stdlib}, github.com/pressly/goose/v3, github.com/go-jet/jet/v2, github.com/testcontainers/testcontainers-go/modules/postgres. Use pkg/postgres, pkg/redisconn.

Files (deleted):

• galaxy/user/internal/adapters/redis/userstore/ — entire directory.
• The portions of galaxy/user/internal/adapters/redisstate/keyspace.go that defined account/entitlement/sanction/limit/index keys (keep only what domainevents and lifecycleevents publishers still require — if none, delete the file outright).

Files retained on Redis:

• galaxy/user/internal/adapters/redis/domainevents/publisher.go.
• galaxy/user/internal/adapters/redis/lifecycleevents/publisher.go.

Touched integration suites (each gets a Postgres container in addition to the existing Redis one):

• integration/authsessionuser/
• integration/gatewayauthsessionuser/
• integration/gatewayauthsessionusermail/
• integration/notificationuser/
• integration/lobbyuser/

Verification:

• cd galaxy/user && make jet && go test ./... (Docker needed).
• cd integration && go test ./authsessionuser/... ./gatewayauthsessionuser/... ./gatewayauthsessionusermail/... ./notificationuser/... ./lobbyuser/...
• Manual smoke against a docker-compose stack (PG + Redis with passwords) using flows from galaxy/user/docs/examples.md.

---

Stage 4 — Mail Service migration

This stage is implemented.

Goal: move durable mail storage (deliveries, attempts, dead letters, malformed commands, payloads, idempotency, attempt schedule) into PostgreSQL. Keep Redis only for the inbound mail:delivery_commands stream and its consumer offset.

Schema (mail schema):

• deliveries (delivery_id PK, source, status, recipient_envelope JSONB, subject, text_body, html_body, payload_mode, template_id, idempotency_source, idempotency_key, locale_fallback_used, next_attempt_at, attempt_count, max_attempts, created_at, updated_at).
  • INDEX (status, next_attempt_at) for the scheduler.
  • UNIQUE (idempotency_source, idempotency_key) — the idempotency record IS this row (no separate kv).
  • INDEX (created_at DESC) for operator listings; INDEX on status, source, template_id, recipient as needed.
• attempts (delivery_id FK, attempt_no, status, provider_summary, scheduled_for_ms, started_at_ms, completed_at_ms, PRIMARY KEY (delivery_id, attempt_no)).
• dead_letters (delivery_id PK FK, final_attempt_count, max_attempts, failure_classification, failure_message, created_at_ms).
• delivery_payloads (delivery_id PK FK, template_variables JSONB).
• malformed_commands (stream_entry_id PK, failure_code, failure_message, raw_fields JSONB, recorded_at_ms; INDEX created_at).

Files: mirror Stage 3 (postgres adapter package, migrations, jet codegen, Makefile, decision record, removal of corresponding internal/adapters/redisstate/* files for migrated entities, retention of stream offset and consumer wiring on Redis).

Worker change: the mail attempt scheduler loop replaces ZRANGEBYSCORE over mail:attempt_schedule with SELECT … FROM deliveries WHERE status IN ('queued','retry_pending') AND next_attempt_at <= now() ORDER BY next_attempt_at LIMIT N FOR UPDATE SKIP LOCKED.

Files (deleted):

• galaxy/mail/internal/adapters/redisstate/auth_acceptance_store.go
• galaxy/mail/internal/adapters/redisstate/generic_acceptance_store.go
• galaxy/mail/internal/adapters/redisstate/attempt_execution_store.go
• galaxy/mail/internal/adapters/redisstate/operator_store.go
• galaxy/mail/internal/adapters/redisstate/malformed_command_store.go
• galaxy/mail/internal/adapters/redisstate/render_store.go
• The portions of galaxy/mail/internal/adapters/redisstate/keyspace.go no longer used (mail:attempt_schedule, mail:idempotency:*, all delivery/attempt/dead-letter/index keys).

Files retained on Redis:

• galaxy/mail/internal/adapters/redisstate/stream_offset_store.go (offset for mail:delivery_commands consumer).
• The command stream consumer wiring itself.

Touched integration suites:

• integration/authsessionmail/
• integration/gatewayauthsessionmail/
• integration/gatewayauthsessionusermail/
• integration/notificationmail/

Verification: per Stage 3 pattern; plus end-to-end smoke that pushes a delivery through retry_pending → provider_accepted using the SMTP stub.

---

Stage 5 — Notification Service migration

This stage is implemented.

Goal: move durable notification storage (records, routes, idempotency, dead letters, malformed intents) into PostgreSQL. Keep Redis for the inbound notification:intents stream, the outbound gateway:client-events stream, the outbound mail:delivery_commands stream, the corresponding stream offsets, and the short-lived per-route lease (route_leases:*).

Schema (notification schema):

• records (notification_id PK, notification_type, producer, audience_kind, recipient_user_ids JSONB, payload JSONB, idempotency_key, request_fingerprint, request_id, trace_id, occurred_at_ms, accepted_at_ms, updated_at_ms).
  • UNIQUE (producer, idempotency_key) — idempotency record IS this row.
• routes (notification_id, route_id, channel, recipient_ref, status, attempt_count, max_attempts, next_attempt_at_ms, resolved_email, resolved_locale, last_error_classification, last_error_message, last_error_at_ms, created_at_ms, updated_at_ms, published_at_ms, dead_lettered_at_ms, skipped_at_ms, PRIMARY KEY (notification_id, route_id)).
  • INDEX (status, next_attempt_at_ms) for the scheduler.
• dead_letters (notification_id, route_id PK FK, channel, recipient_ref, final_attempt_count, max_attempts, failure_classification, failure_message, recovery_hint, created_at_ms).
• malformed_intents (stream_entry_id PK, notification_type, producer, idempotency_key, failure_code, failure_message, raw_fields JSONB, recorded_at_ms).

Worker change: route publisher selects work via the same FOR UPDATE SKIP LOCKED pattern as Mail. The Redis lease is still used as a short-lived, per-process exclusivity hint atop the SQL claim.

Files (deleted):

• galaxy/notification/internal/adapters/redisstate/acceptance_store.go
• galaxy/notification/internal/adapters/redisstate/route_state_store.go
• galaxy/notification/internal/adapters/redisstate/malformed_intent_store.go
• The portions of galaxy/notification/internal/adapters/redisstate/keyspace.go no longer used (records, routes, idempotency, dead_letters, malformed_intents).

Files retained on Redis:

• galaxy/notification/internal/adapters/redisstate/stream_offset_store.go.
• Route lease key generator (still under redisstate/, narrowed to leases only).
• All stream consumer/publisher wiring.

Touched integration suites:

• integration/notificationgateway/
• integration/notificationmail/
• integration/notificationuser/

---

Stage 6A — Lobby Service: core enrollment entities

Goal: move Game, Application, Invite, Membership records and their indexes into PostgreSQL. RaceNameDirectory, GameTurnStats, GapActivation, EvaluationGuard, StreamOffset remain on Redis until later sub-stages.

Schema (lobby schema, partial):

• games (game_id PK, owner_id, kind ('public'|'private'), status, created_at, updated_at, runtime_snapshot JSONB, runtime_binding JSONB, …other denormalised game settings).
  • INDEX (status, created_at).
  • INDEX (owner_id) WHERE kind = 'private'.
• applications (application_id PK, game_id FK, user_id, status, canonical_key, submitted_at, decided_at).
  • PARTIAL UNIQUE INDEX (user_id, game_id) WHERE status = 'active' — enforces the single-active constraint at the DB level (replaces lobby:user_game_application:*:*).
  • INDEX (game_id), INDEX (user_id).
• invites (invite_id PK, game_id FK, inviter_id, invitee_id, race_name, status, created_at, expires_at, decided_at).
  • INDEX (game_id), INDEX (invitee_id), INDEX (inviter_id).
  • INDEX (status, expires_at) for any expiration scanner if needed.
• memberships (membership_id PK, game_id FK, user_id, status, joined_at, canonical_key, …).
  • INDEX (game_id), INDEX (user_id).

Files (new):

• galaxy/lobby/internal/adapters/postgres/migrations/00001_core_entities.sql.
• galaxy/lobby/internal/adapters/postgres/migrations/migrations.go.
• galaxy/lobby/internal/adapters/postgres/jet/....
• galaxy/lobby/internal/adapters/postgres/gamestore/store.go.
• galaxy/lobby/internal/adapters/postgres/applicationstore/store.go.
• galaxy/lobby/internal/adapters/postgres/invitestore/store.go.
• galaxy/lobby/internal/adapters/postgres/membershipstore/store.go.
• Test files for each store using the existing test patterns.
• galaxy/lobby/Makefile (jet target).
• galaxy/lobby/docs/postgres-migration.md (decision record covering this sub-stage and what is intentionally left for 6B/6C).

Files (touched):

• galaxy/lobby/internal/config/config.go — add Postgres config; refactor Redis config to the new shape.
• galaxy/lobby/internal/app/runtime.go — open Postgres pool, run migrations on startup, wire core PG-backed stores into services. RaceNameDirectory and stats/guard stores still wired to Redis until 6B/6C.
• galaxy/lobby/README.md and galaxy/lobby/docs/runbook.md — updated to describe core entities on PG, RND/stats still on Redis until 6B/6C.

Files (deleted):

• galaxy/lobby/internal/adapters/redisstate/gamestore.go, applicationstore.go, invitestore.go, membershipstore.go.
• The corresponding sections of redisstate/keyspace.go.

Stub adapters retained: gamestub/, applicationstub/, invitestub/, membershipstub/ stay — they are pure in-memory ports useful for tests that don't need real PG.

Touched integration suites:

• integration/lobbyuser/
• integration/lobbynotification/

Verification: per Stage 3 pattern; plus the existing lobby HTTP contract tests against the public/internal ports.

---

Stage 6B — Lobby Service: RaceNameDirectory

This stage is implemented.

Goal: replace the Lua-backed Redis RaceNameDirectory with a PG implementation that preserves the two-tier model (registered / reservation / pending_registration) and atomic registration semantics via SQL transactions and (where required) advisory locks.

Schema (additions to lobby schema):

• race_names (canonical_key PK, holder_user_id, binding_kind ('registered' | 'reserved' | 'pending_registration'), source_game_id, eligible_until_ms, registered_at_ms, reserved_at_ms).
  • INDEX (holder_user_id) for ListRegistered/ListReservations/ ListPendingRegistrations queries.
  • PARTIAL INDEX (eligible_until_ms) WHERE binding_kind = 'pending_registration' for the expiration scanner.
  • The confusable-pair policy is enforced at write time inside BEGIN … COMMIT transactions; Reserve/Register/ MarkPendingRegistration use SELECT … FOR UPDATE on the canonical keys involved (or PG advisory locks keyed by hashtext(canonical_key)) to serialise concurrent attempts.

Files (new):

• galaxy/lobby/internal/adapters/postgres/migrations/00002_race_names.sql.
• galaxy/lobby/internal/adapters/postgres/racenamedir/directory.go — Postgres implementation of ports.RaceNameDirectory.
• galaxy/lobby/internal/adapters/postgres/racenamedir/directory_test.go — runs the existing shared suite at galaxy/lobby/internal/ports/racenamedirtest/suite.go.

Files (touched):

• galaxy/lobby/internal/app/runtime.go — wire PG RND.
• galaxy/lobby/internal/ports/racenamedirtest/suite.go — only shape-preserving updates if the suite assumed Redis-only behaviour (e.g. SCAN-based list ordering).
• galaxy/lobby/README.md, galaxy/lobby/docs/runbook.md — RND now PG- backed; canonical_lookup cache no longer needed (PG indexed lookup is fast enough; remove the Redis cache key from redisstate/keyspace.go).

Files (deleted):

• galaxy/lobby/internal/adapters/redisstate/racenamedir.go and the embedded Lua scripts.
• galaxy/lobby/internal/adapters/racenamestub/ stays (useful for unit tests that don't need PG).

Worker change: the pending-registration expiration worker switches from ZRANGEBYSCORE on lobby:race_names:pending_index to SELECT … FROM race_names WHERE binding_kind='pending_registration' AND eligible_until_ms <= now().

Verification: shared port suite (racenamedirtest) green against PG adapter; lobby unit tests green; integration/lobbyuser/, integration/lobbynotification/ green.

---

Stage 6C — Lobby Service: workers, ephemeral stores, cleanup

This stage is implemented.

Goal: finish the lobby migration. Confirm what stays Redis-only, update workers that touch both backends, drop dead Redis adapters.

Stays on Redis (per architectural rules):

• GameTurnStatsStore — ephemeral per-game aggregate, deleted at game finish, rebuildable from GM events.
• EvaluationGuardStore — ephemeral marker.
• GapActivationStore — short-lived gap-window timestamp cache.
• StreamOffsetStore — runtime coordination per the architectural rule.
• All stream consumers and publishers (gm:lobby_events, runtime:job_results, user:lifecycle_events, notification:intents).

This is documented in galaxy/lobby/docs/postgres-migration.md.

Files (touched):

• galaxy/lobby/internal/worker/gmevents/consumer.go — write durable updates via PG-backed GameStore.
• galaxy/lobby/internal/worker/runtimejobresult/consumer.go — same.
• galaxy/lobby/internal/adapters/userlifecycle/consumer.go (and the worker that drives it) — RND release, membership/application/invite cascade all flow through PG.
• galaxy/lobby/internal/worker/pendingregistration/worker.go — PG-based scan, no Redis ZSET.
• galaxy/lobby/internal/worker/enrollmentautomation/worker.go — uses PG GameStore.GetByStatus("enrollment_open").
• galaxy/lobby/internal/adapters/redisstate/keyspace.go — pruned to the remaining Redis keys (turn stats, gap activation, evaluation guard, stream offsets, lifecycle stream consumer state).
• galaxy/lobby/README.md, galaxy/lobby/docs/runtime.md, galaxy/lobby/docs/runbook.md, galaxy/lobby/docs/examples.md — finalised storage descriptions.

Files (deleted):

• Anything left in galaxy/lobby/internal/adapters/redisstate/ whose only consumer was a port now PG-backed (see 6A/6B deletions).

Verification:

• All previously-green lobby unit tests pass with PG-backed adapters.
• integration/lobbyuser/, integration/lobbynotification/ pass.
• grep -rn "redisstate" galaxy/lobby/internal/ returns only the keys intentionally retained on Redis.

---

Stage 7 — Gateway and Auth/Session: Redis configuration refactor

This stage is implemented.

Goal: apply the new Redis configuration shape (master/replica/password, drop TLS/USERNAME) to Gateway and Auth/Session. No PG migration; these services intentionally stay Redis-only.

Files (touched):

• galaxy/gateway/internal/config/config.go — switch RedisConfig fields to the pkg/redisconn.Config shape; update the three prefixes: GATEWAY_SESSION_CACHE_REDIS_*, GATEWAY_REPLAY_REDIS_*, GATEWAY_SESSION_EVENTS_REDIS_*. Drop TLS_ENABLED, USERNAME.
• galaxy/gateway/internal/session/redis.go, galaxy/gateway/internal/replay/redis.go, galaxy/gateway/internal/events/subscriber.go — adopt new client constructor via pkg/redisconn.
• galaxy/gateway/internal/config/config_test.go, galaxy/gateway/internal/session/redis_test.go, galaxy/gateway/internal/replay/redis_test.go — updated to new env shape.
• galaxy/authsession/internal/config/config.go — same pattern; drop TLS, USERNAME.
• galaxy/authsession/internal/adapters/redis/sessionstore/store.go, challengestore/store.go, projectionpublisher/publisher.go, sendemailcodeabuse/protector.go, configprovider/store.go — adopt new client.
• galaxy/authsession/internal/config/config_test.go — updated.
• galaxy/gateway/README.md, galaxy/authsession/README.md, galaxy/gateway/docs/runbook.md, galaxy/authsession/docs/runbook.md — note that Redis-only is intentional and reference the ARCHITECTURE.md rule on TTL-bounded auth state.

No deletions of business logic; only env-var refactor and adapter plumbing through pkg/redisconn.

Touched integration suites:

• integration/gatewayauthsession/
• integration/authsession/
• (every suite that boots gateway or authsession picks up the new env vars via the harness; confirm none still pass *_REDIS_TLS_ENABLED).

Verification:

• cd galaxy/gateway && go test ./...
• cd galaxy/authsession && go test ./...
• cd integration && go test ./gatewayauthsession/... ./authsession/...

---

Stage 8 — GeoProfile: documentation only

Goal: ensure the GeoProfile plan and README reflect the new persistence rules so its future implementation follows them. No code exists yet.

Files (touched):

• galaxy/geoprofile/PLAN.md — add a stage referencing pkg/postgres and pkg/redisconn; specify that observed-country aggregates, declared_country history and review records will live in a geoprofile schema, while ephemeral per-session signals (if any) stay on Redis.
• galaxy/geoprofile/README.md — note ownership of the geoprofile schema and the stack choices.

No code change.

---

Stage 9 — Final sweep

Goal: confirm no dead Redis adapter code, no orphaned stub, no broken doc reference. Remove the Migration Window caveat from ARCHITECTURE.md once all stages are done.

Activities:

• Walk every PG-backed service: grep -rn "redis" galaxy/<svc>/internal/adapters/ and verify every match belongs to a still-active stream/cache/runtime use case.
• Walk integration suites: confirm each one provisions only the containers it actually needs; no stale env vars.
• Update ARCHITECTURE.md to drop the Migration Window sub-section.
• Combine sequences of migration .sql files into a single first file. Rewrite SQL-code, not just concat. The reason is that project still in in development state and all schema updates can go directly in the only and first step of relevant migrations. This should be represented in ARCHITECTURE.md as well.
• One round of go test ./... in every module plus cd integration && go test ./....

Verification:

• All tests pass in every module.
• No file matches // TODO.*postgres or // TODO.*migrate.
• git grep -n REDIS_TLS_ENABLED REDIS_USERNAME returns nothing under galaxy/ (these env vars are fully retired).

---

Verification strategy (whole project)

After each stage:

• cd /Users/id/src/go/galaxy/pkg && go test ./...
• cd /Users/id/src/go/galaxy/<changed_service> && go test ./... (with Docker available for testcontainers).
• cd /Users/id/src/go/galaxy/integration && go test ./<affected_suites>/...
• Manual smoke against a docker-compose stack (PG + Redis, both with passwords) using the example flows in each service's docs/examples.md.

After Stage 9:

• cd /Users/id/src/go/galaxy/integration && go test ./... end to end against real PG + real Redis.
• Confirm git grep -nE 'REDIS_(TLS_ENABLED|USERNAME)' returns nothing under galaxy/.
• Confirm git grep -n 'TODO.*(postgres|migrate)' returns nothing.

Out of scope

• galaxy/game — explicitly excluded by the project owner.
• Production deployment manifests (Helm/k8s) — local docker-compose is enough for development.
• Backup/restore tooling configuration — pg_dump and WAL archiving are available out of the box; operational setup is not part of this plan.
• Sentinel/Cluster Redis topology code paths — config exposes replica addresses for future use; no failover routing implemented yet.
• Read-traffic routing to PG replicas — config exposes *_POSTGRES_REPLICA_DSNS for future use; no routing implemented yet.
• golangci-lint config addition — not part of this migration.
• CI pipeline — no .github/workflows/ exists; not added by this plan.

Risks and notes

• go-jet codegen requires a live database. The make jet target per service uses testcontainers-go to bring up a transient PG, applies the same goose migrations the service applies at startup, then runs jet -dsn=… -path=internal/adapters/postgres/jet. Generated code is committed; consumers don't need Docker just to build.
• Schema-per-service vs single-DB cross-service joins: there are no cross-schema joins in this plan. Each service reads only its own schema; cross-service data flows go via Redis Streams (event bus) or HTTP contracts (User Service is queried by Lobby for eligibility) — same as today. The DB-level role grants enforce this.
• Pending registration expiration worker: under Redis it scanned a global ZSET; under PG it does an indexed scan. The partial index on eligible_until_ms WHERE binding_kind='pending_registration' keeps the scan cheap.
• Idempotency under crash: with idempotency expressed as a UNIQUE constraint on the durable record, recovery is "the row either exists or it doesn't" — no Redis-loss window where duplicates can sneak through.
• lib/pq vs pgx (revisit): confirmed pgx/v5 + jet via stdlib adapter. The make jet target will pass -source=postgres to jet (the dialect is independent of which Go driver runs the queries at runtime).
• No backward-compat shim for env vars: *_REDIS_TLS_ENABLED and *_REDIS_USERNAME are retired in one cut. Any external dev environment that sets these will start failing fast at startup with a clear error emitted by pkg/redisconn.LoadFromEnv.