mud_server.db.schema

Schema creation and invariant trigger wiring for the SQLite backend.

The schema layer is intentionally isolated from gameplay/query code so schema changes are reviewable without wading through unrelated repository logic.

Attributes

HOT_PATH_INDEX_STATEMENTS

Functions

ensure_character_state_columns(cursor)	Ensure state snapshot columns exist on the characters table.
create_session_invariant_triggers(conn)	Create triggers that enforce account-first session invariants.
init_database(*[, skip_superuser])	Initialize the SQLite database schema and baseline triggers.

Module Contents

mud_server.db.schema.HOT_PATH_INDEX_STATEMENTS = ('CREATE INDEX IF NOT EXISTS idx_characters_user_world ON characters(user_id, world_id)',...

mud_server.db.schema.ensure_character_state_columns(cursor)

Ensure state snapshot columns exist on the characters table.

SQLite cannot alter table definitions declaratively inside CREATE TABLE for pre-existing databases. We therefore perform additive ALTER TABLE operations for each required column.

mud_server.db.schema.create_session_invariant_triggers(conn)

Create triggers that enforce account-first session invariants.

Invariant model: - Account-only session: character_id IS NULL and world_id IS NULL - In-world session: character_id IS NOT NULL and world_id IS NOT NULL

with character ownership and world consistency constraints.

These triggers intentionally protect integrity for both Python helper paths and direct SQL writes.

mud_server.db.schema.init_database(*, skip_superuser=False)

Initialize the SQLite database schema and baseline triggers.

Behavior: - Creates required tables and indexes if missing. - Seeds the default world row when absent. - Ensures character snapshot columns are present. - Installs session invariant triggers. - Optionally creates a bootstrap superuser from environment variables.

Parameters:

skip_superuser (bool) – When True, skip bootstrap superuser creation.