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

.. py:module:: db.connection

.. autoapi-nested-parse::

   SQLite connection helpers for the webapp persistence layer.

   This module owns connection-level concerns only: opening the SQLite database,
   creating parent directories, and applying connection PRAGMA defaults.



Functions
---------

.. autoapisummary::

   db.connection.connect_database


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

.. py:function:: connect_database(db_path)

   Open a SQLite connection configured for webapp usage.

   :param db_path: Filesystem path to the SQLite database file.

   :returns: Open ``sqlite3.Connection`` with ``sqlite3.Row`` row factory.

   .. admonition:: Notes

      The connection applies SQLite PRAGMAs tuned for this webapp's
      read-heavy access pattern:
      
      - ``foreign_keys = ON`` to enforce package/table relationships.
      - ``journal_mode = WAL`` to improve concurrent read behavior.
      - ``synchronous = NORMAL`` to balance durability and write latency.
      - ``busy_timeout = 5000`` to reduce transient lock failures.