Game Database Schema Readiness

Purpose

Game database schema readiness prevents live authority from running against a partial or drifted shared schema. It checks the Postgres database produced by login-server migrations before game-server startup proceeds and again through /ready.

Where It Runs

The game server runs schema readiness during database connection/startup assembly and in the readiness HTTP handler. /health can show the process is alive, but /ready is the signal that DB, schema, Redis, and drain state are safe for traffic.

Required Migration Versions

The current game readiness contract expects migration versions 1, 3, 5, 6, 10, 11, 14, 17, 18, 19, 21, 23, 24, 25, 26 when the corresponding runtime features are active.

Contracted Tables

Readiness covers character records, inventory, currencies, gameplay state, equipment state, event idempotency, combat rewards, persistence retry jobs and dead letters, encounter memory, farming tile state, command audit, and admin audit.

Contracted Indexes

Important indexes include due retry-job leasing, active persistence dead letters, farming scene lookup, command/admin audit lookup, and encounter eligibility. Missing indexes are readiness failures because they can change runtime behavior under load.

What A Failure Means

A failure can mean _sqlx_migrations is missing, a migration was not applied, a required table or column drifted, a default is absent, or an index was dropped. Treat it as a stop sign, not a warning.

Repair Workflow

Run the login-server migrations against the database, inspect any drift deliberately, and retry game startup or /ready. Do not patch readiness to ignore a missing schema feature unless the runtime code that depends on it has also been removed.

Updating The Contract

Schema changes should move as a bundle: migration SQL, schema contract sidecar, game-server readiness constants, and tests. If a feature can run without a schema addition, document that fallback in the feature page.