mud_server.db.schema
====================

.. py:module:: mud_server.db.schema

.. autoapi-nested-parse::

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

.. autoapisummary::

   mud_server.db.schema.HOT_PATH_INDEX_STATEMENTS


Functions
---------

.. autoapisummary::

   mud_server.db.schema.ensure_character_state_columns
   mud_server.db.schema.create_session_invariant_triggers
   mud_server.db.schema.init_database


Module Contents
---------------

.. py:data:: HOT_PATH_INDEX_STATEMENTS
   :value: ('CREATE INDEX IF NOT EXISTS idx_characters_user_world ON characters(user_id, world_id)',...


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.

   :param skip_superuser: When True, skip bootstrap superuser creation.