---
stage: 09
title: PostgreSQL schema, migrations, jet
---

# Stage 09 — PostgreSQL schema, migrations, jet

This decision record captures the schema and code-generation pipeline
landed for Game Master at PLAN Stage 09. It is a service-local mirror
of [`../../rtmanager/docs/postgres-migration.md`](../../rtmanager/docs/postgres-migration.md)
but only documents the decisions specific to Stage 09; the stage-24
[`postgres-migration.md`](postgres-migration.md) reorganisation will
later subsume and supersede this record.

## Context

[`../PLAN.md` Stage 09](../PLAN.md) finalises the persistence schema
and the code-generation pipeline. Stage 08 already opens, instruments,
and pings the PostgreSQL pool but does not apply any migrations. The
durable surface for runtime state, engine version registry, player
mappings, and the audit log is described in
[`../README.md` §Persistence Layout](../README.md). Stage 09 ships:

- `internal/adapters/postgres/migrations/00001_init.sql` plus the
  matching embed package;
- `cmd/jetgen` — a testcontainers-driven regeneration pipeline for
  the go-jet/v2 query builder code;
- the generated jet code under
  `internal/adapters/postgres/jet/gamemaster/{model,table}/`,
  committed verbatim;
- the `postgres.RunMigrations` call in `internal/app/runtime.go`,
  applied after the PostgreSQL pool ping and before any listener is
  built.

The reference precedent is `rtmanager`, the most recently landed
PG-backed service in the workspace.

## Decisions

### 1. Schema and role provisioning are excluded from `00001_init.sql`

**Decision.** The `gamemaster` schema and the matching
`gamemasterservice` role are created outside the migration sequence
(in tests by [`../cmd/jetgen/main.go`](../cmd/jetgen/main.go)
`provisionRoleAndSchema`; in production by an ops init script not in
scope for this stage). The embedded migration `00001_init.sql` only
contains DDL for the four service-owned tables and indexes and assumes
it runs as the schema owner with `search_path=gamemaster`.

**Why.** [`../../ARCHITECTURE.md` §Database topology](../../ARCHITECTURE.md)
mandates that each service connects with its own role whose grants are
restricted to its own schema. Mixing role creation, schema creation,
and table DDL into one script forces the migration to run as a
superuser on every replica boot and effectively relaxes the per-service
role boundary. The `rtmanager` precedent settled on the split first;
GM follows it for the same architectural reason. This is a deliberate
deviation from PLAN Stage 09's literal `CREATE SCHEMA IF NOT EXISTS
gamemaster;` instruction, called out in the comment header at the top
of `00001_init.sql`.

### 2. Natural primary keys mirror the platform identifiers

**Decision.** Every PK is a natural identifier already owned by another
component:

- `runtime_records.game_id` — Lobby's platform identifier;
- `engine_versions.version` — semver string from the registry;
- `player_mappings (game_id, user_id)` — composite, both columns owned
  by Lobby/User Service.
- `operation_log.id` — `bigserial`, the only synthetic PK because the
  audit table has no natural identity per row.

**Why.** The same reasoning as in
[`../../rtmanager/docs/postgres-migration.md` §2](../../rtmanager/docs/postgres-migration.md)
applies: surrogate keys would force every cross-service join through a
lookup table, while the natural keys keep the persistence layer
pin-compatible with the contracts (every `register-runtime` envelope
already names `game_id`, every Lobby resolve names `version`, every
player command names `user_id`).

### 3. Defense-in-depth CHECK constraints on every status enum

**Decision.** Five CHECK constraints reproduce the Go-level enums in
the schema:

- `runtime_records_status_chk` — seven runtime statuses
  (`starting`, `running`, `generation_in_progress`, `generation_failed`,
  `stopped`, `engine_unreachable`, `finished`);
- `engine_versions_status_chk` — `active | deprecated`;
- `operation_log_op_kind_chk` — nine operation kinds
  (`register_runtime`, `turn_generation`, `force_next_turn`, `banish`,
  `stop`, `patch`, `engine_version_create`, `engine_version_update`,
  `engine_version_deprecate`);
- `operation_log_op_source_chk` — three op sources
  (`gateway_player`, `lobby_internal`, `admin_rest`);
- `operation_log_outcome_chk` — `success | failure`.

The Go-level enums in the domain layer (added in Stage 10) remain the
source of truth for application code.

**Why.** The same defense-in-depth argument as for `rtmanager`: the
storage boundary catches an adapter regression that would otherwise
persist an unexpected string. Operator-side queries (`SELECT … WHERE
op_kind = 'patch'`) benefit from the enum being verifiable directly in
psql without consulting the Go source. PostgreSQL's `CREATE TYPE … AS
ENUM` was rejected because adding values to a PG enum type requires
`ALTER TYPE` outside a transaction and complicates the single-init
pre-launch policy (decision §6).

### 4. Indexes derive from concrete query shapes

**Decision.** Three secondary indexes ship with `00001_init.sql`:

- `runtime_records (status, next_generation_at)` — drives the
  scheduler ticker scan
  (`WHERE status='running' AND next_generation_at <= now()` once per
  second);
- `player_mappings (game_id, race_name)` UNIQUE — enforces the
  one-race-per-game invariant at the storage boundary;
- `operation_log (game_id, started_at DESC)` — drives audit reads
  ordered by recency.

The README §Persistence Layout list also mentions `player_mappings
(game_id)`, which is intentionally **not** added: the composite
primary key on `(game_id, user_id)` already serves as a leftmost-prefix
index for `WHERE game_id = $1`, and a one-column duplicate would only
double the write cost for no plan-stability gain. The README's
indexes list is corrected in the same patch to drop the redundant
entry.

**Why.** Each remaining index has a single concrete read shape behind
it. The composite ordering on `(status, next_generation_at)` lets the
planner satisfy the scheduler scan with one index sweep. The descending
ordering on `(game_id, started_at DESC)` matches the
`ListByGame ORDER BY started_at DESC` shape already established by
`rtmanager.operationlogstore.ListByGame`.

### 5. `next_generation_at` is nullable

**Decision.** `runtime_records.next_generation_at timestamptz` admits
NULL; `runtime_records.skip_next_tick boolean NOT NULL DEFAULT false`
does not.

**Why.** A row enters the table at register-runtime with
`status='starting'` and no scheduled tick yet — the tick is only
computed once the engine `/admin/init` succeeds and the CAS flips the
status to `running`. NULL captures «no tick scheduled» without forcing
a sentinel value into the column. The scheduler index
`(status, next_generation_at)` still works correctly: the predicate
`next_generation_at <= now()` is undefined for NULL inputs, and PG
excludes those rows from the result set, which is the desired
behaviour. `skip_next_tick` is a boolean knob set or cleared by the
force-next-turn flow; NULL would be a third state with no semantic, so
the column is NOT NULL with a `false` default.

### 6. Single-init pre-launch policy applies as documented

**Decision.** `00001_init.sql` evolves in place until first production
deploy. Adding a column, an index, or a new table during the
pre-launch development window edits this file directly rather than
producing `00002_*.sql`. The runtime applies the migration on every
boot; if the schema is already at head, `pkg/postgres`'s goose
adapter exits zero.

**Why.** The schema-per-service architectural rule
([`../../ARCHITECTURE.md` §Persistence Backends](../../ARCHITECTURE.md))
endorses a single-init policy for pre-launch services. The pre-launch
window allows non-additive changes (column rename, type narrowing,
CHECK tightening) that a multi-step migration sequence would force into
awkward two-step rewrites. Once the service ships to production, the
next schema change becomes `00002_*.sql` and the policy lifts.

### 7. `cmd/jetgen` is a one-to-one mirror of `rtmanager/cmd/jetgen`

**Decision.** [`../cmd/jetgen/main.go`](../cmd/jetgen/main.go) follows
the same shape as
[`../../rtmanager/cmd/jetgen/main.go`](../../rtmanager/cmd/jetgen/main.go):
spin a `postgres:16-alpine` testcontainer, open it as superuser,
provision the role and schema, open a second pool with
`search_path=gamemaster`, apply the embedded goose migrations, then
invoke `github.com/go-jet/jet/v2/generator/postgres.GenerateDB` with
schema=gamemaster. Constants differ (`gamemasterservice`,
`gamemaster`, `galaxy_gamemaster`) but the algorithm and helper shape
are intentionally identical.

**Why.** Two PG-backed services should not diverge on a dev-only code
generator that nothing else in the workspace relies on. Mirroring
`rtmanager` keeps `make -C <service> jet` interchangeable for
operators and minimises the cognitive overhead of moving between
services.

### 8. Generated jet code is committed

**Decision.** The output of `make -C gamemaster jet` lands under
[`../internal/adapters/postgres/jet/gamemaster/{model,table}/`](../internal/adapters/postgres/jet/gamemaster)
and is committed verbatim.

**Why.** `go build ./...` from the repository root must work without
Docker; CI runners and contributor machines without a local Docker
daemon must still pass `go test ./gamemaster/...` for the non-PG-store
parts of the module. The generation pipeline itself remains available
behind `make jet` for everyone who wants to regenerate.

### 9. Migrations apply synchronously before any listener opens

**Decision.** [`../internal/app/runtime.go`](../internal/app/runtime.go)
calls `postgres.RunMigrations(ctx, pgPool, migrations.FS(), ".")`
immediately after the `postgres.Ping` succeeds and before
`newWiring`/`internalhttp.NewServer` are constructed. A non-zero exit
on migration failure follows the `pkg/postgres` policy.

**Why.** [`../README.md` §Startup dependencies](../README.md)
specifies that «embedded goose migrations apply synchronously before
any listener opens». Repeated process boots against a head schema
return goose's «no work to do» success — this is how the policy stays
operationally cheap, since a freshly-spawned replica re-applies the
same `00001_init.sql` with no work and proceeds straight to opening
its listeners.

## Files landed

- [`../internal/adapters/postgres/migrations/00001_init.sql`](../internal/adapters/postgres/migrations/00001_init.sql)
  — full schema for the four service tables plus indexes and CHECK
  constraints.
- [`../internal/adapters/postgres/migrations/migrations.go`](../internal/adapters/postgres/migrations/migrations.go)
  — `//go:embed *.sql` and `FS()` exporter.
- [`../cmd/jetgen/main.go`](../cmd/jetgen/main.go) — testcontainers +
  goose + jet pipeline.
- [`../internal/adapters/postgres/jet/gamemaster/`](../internal/adapters/postgres/jet/gamemaster)
  — generated model and table packages.
- [`../internal/app/runtime.go`](../internal/app/runtime.go) — wired
  `postgres.RunMigrations` call after the pool ping.
- [`../Makefile`](../Makefile) — refreshed `jet` target comment now
  that the pipeline is real.
- [`../go.mod`](../go.mod), [`../go.sum`](../go.sum) — promoted
  `github.com/go-jet/jet/v2`, `github.com/testcontainers/testcontainers-go`,
  and `github.com/testcontainers/testcontainers-go/modules/postgres`
  to direct dependencies.
- [`../README.md`](../README.md) — corrected §Persistence Layout
  indexes list (dropped redundant `player_mappings (game_id)` entry)
  and added a §References pointer to this record.

## Verification

- `cd gamemaster && go mod tidy` — no missing dependency, no
  superfluous indirect.
- `make -C gamemaster jet` — bring up `postgres:16-alpine`, apply
  `00001_init.sql`, regenerate `internal/adapters/postgres/jet/...`;
  `git status` is clean after a second run.
- `go build ./gamemaster/...` succeeds (including the generated jet
  code).
- `go test ./gamemaster/...` passes — existing contract, freeze, and
  config/telemetry/HTTP tests are unaffected.
- Manual smoke against a local PostgreSQL with an empty `gamemaster`
  schema and a `gamemasterservice` role: the process applies the
  migration, `/readyz` returns `200`, and a second boot exits zero on
  the «no work to do» path.