mud_server.db.connection
========================

.. py:module:: mud_server.db.connection

.. autoapi-nested-parse::

   SQLite connection primitives for the MUD server DB layer.

   This module owns connection creation and low-level SQLite runtime pragmas so
   repository code can stay focused on queries and transaction intent.



Functions
---------

.. autoapisummary::

   mud_server.db.connection.get_db_path
   mud_server.db.connection.configure_connection
   mud_server.db.connection.get_connection
   mud_server.db.connection.connection_scope


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

.. py:function:: get_db_path()

   Resolve the absolute SQLite database path from runtime configuration.


.. py:function:: configure_connection(connection)

   Apply connection-level SQLite pragmas required by the application.

   .. admonition:: Notes

      - ``foreign_keys=ON`` is required because SQLite does not enforce
        foreign-key constraints by default.
      - ``busy_timeout`` reduces transient lock failures during short-lived
        concurrent writes in tests and local multi-process development.


.. py:function:: get_connection()

   Create and configure a new SQLite connection.


.. py:function:: connection_scope(*, write = False)

   Yield a configured connection with guaranteed cleanup semantics.

   :param write: When True, commit on success and rollback on exceptions.

   :Yields: Configured SQLite connection ready for cursor operations.

   Behavior:
       - Always closes the connection in ``finally``.
       - For write scopes, commits at the end of a successful block.
       - For write scopes, attempts rollback before re-raising failures.