dqlite-dbapi 0.2.1__tar.gz → 0.2.2__tar.gz

{dqlite_dbapi-0.2.1 → dqlite_dbapi-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dqlite-dbapi
-Version: 0.2.1
+Version: 0.2.2
 Summary: PEP 249 (DB-API 2.0) compliant interface for dqlite
 Project-URL: Homepage, https://github.com/letsdiscodev/python-dqlite-dbapi
 Project-URL: Repository, https://github.com/letsdiscodev/python-dqlite-dbapi
@@ -22,8 +22,8 @@ Classifier: Topic :: Database :: Database Engines/Servers
 Classifier: Topic :: Database :: Front-Ends
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: dqlite-client<0.3.0,>=0.2.1
-Requires-Dist: dqlite-wire<0.3.0,>=0.2.1
+Requires-Dist: dqlite-client<0.3.0,>=0.2.2
+Requires-Dist: dqlite-wire<0.3.0,>=0.2.2
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'

{dqlite_dbapi-0.2.1 → dqlite_dbapi-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dqlite-dbapi"
-version = "0.2.1"
+version = "0.2.2"
 description = "PEP 249 (DB-API 2.0) compliant interface for dqlite"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -26,8 +26,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "dqlite-client>=0.2.1,<0.3.0",
-    "dqlite-wire>=0.2.1,<0.3.0",
+    "dqlite-client>=0.2.2,<0.3.0",
+    "dqlite-wire>=0.2.2,<0.3.0",
 ]
 
 [tool.uv.sources]

{dqlite_dbapi-0.2.1 → dqlite_dbapi-0.2.2}/src/dqlitedbapi/__init__.py

@@ -71,6 +71,7 @@ from dqlitedbapi.connection import (
 )
 from dqlitedbapi.cursor import Cursor
 from dqlitedbapi.exceptions import (
+    AdapterLookupError,
     AmbiguousCommitError,
     DatabaseError,
     DataError,
@@ -83,12 +84,14 @@ from dqlitedbapi.exceptions import (
     ProgrammingError,
     Warning,
 )
+from dqlitedbapi.row import Row
 from dqlitedbapi.types import (
     BINARY,
     DATETIME,
     NUMBER,
     ROWID,
     STRING,
+    UNKNOWN,
     Binary,
     Date,
     DateFromTicks,
@@ -171,7 +174,7 @@ LEGACY_TRANSACTION_CONTROL: _Final[int] = -1
 PARSE_DECLTYPES: _Final[int] = 1
 PARSE_COLNAMES: _Final[int] = 2
 
-__version__: _Final[str] = "0.2.1"
+__version__: _Final[str] = "0.2.2"
 
 __all__ = [  # grouped by PEP 249 section, not alphabetical
     # Module attributes
@@ -214,6 +217,7 @@ __all__ = [  # grouped by PEP 249 section, not alphabetical
     "InternalError",
     "ProgrammingError",
     "NotSupportedError",
+    "AdapterLookupError",
     # Type constructors
     "Date",
     "Time",
@@ -228,6 +232,9 @@ __all__ = [  # grouped by PEP 249 section, not alphabetical
     "NUMBER",
     "DATETIME",
     "ROWID",
+    "UNKNOWN",
+    # Row factory (sqlite3.Row equivalent)
+    "Row",
     # Type aliases
     "DescriptionTuple",
 ]
@@ -248,6 +255,7 @@ def connect(
     dial_func: DialFunc | None = None,
     busy_timeout: float = 5.0,
     check_same_thread: bool = True,
+    session_mode: str | None = None,
     **unknown_kwargs: object,
 ) -> Connection:
     """Connect to a dqlite database.
@@ -406,6 +414,7 @@ def connect(
         dial_func=dial_func,
         busy_timeout=busy_timeout,
         check_same_thread=check_same_thread,
+        session_mode=session_mode,
     )
     # Apply the validated ``isolation_level`` / ``autocommit`` kwargs
     # via the setters on the freshly-constructed connection. Stdlib

dqlite_dbapi-0.2.2/src/dqlitedbapi/_pragma_intercept.py

@@ -0,0 +1,264 @@
+"""Pre-wire SQL interception at the dbapi cursor layer.
+
+This module hosts two interceptions that rewrite or short-circuit
+caller SQL before it reaches the dqlite wire:
+
+1. ``PRAGMA busy_timeout`` — see ``try_intercept_busy_timeout`` below
+   for the rationale (authorizer rejection of the canonical SQLite
+   knob).
+
+2. Bare ``BEGIN`` (and ``BEGIN TRANSACTION``) — rewritten to
+   ``BEGIN IMMEDIATE`` when the connection's ``session_mode`` is
+   ``"immediate"`` (the default). The writer-lock is acquired at
+   BEGIN time so the SELECT-then-INSERT pattern cannot be overtaken
+   by a concurrent committer (the ``SQLITE_BUSY_SNAPSHOT`` race).
+   dqlite-server's own VFS recommends ``BEGIN IMMEDIATE`` for
+   write-bearing transactions. Pass-through for ``BEGIN DEFERRED``
+   / ``BEGIN IMMEDIATE`` / ``BEGIN EXCLUSIVE`` (caller intent
+   already correct).
+
+   Other session modes (``"deferred"`` / ``"exclusive"`` /
+   ``"read_only"``) leave bare ``BEGIN`` untouched — the SQLite
+   engine treats it as DEFERRED, which is the right semantic for
+   read-only sessions and for callers who explicitly want the
+   legacy DEFERRED behaviour. The ``"exclusive"`` mode is reached
+   via the SA dialect's ``do_begin`` emitting the explicit
+   ``BEGIN EXCLUSIVE`` literal, which doesn't match the rewrite
+   regex anyway.
+
+   Configuration: ``Connection(session_mode="…")`` kwarg, URL
+   ``?session_mode=…``, or ``DQLITE_SESSION_MODE`` env var.
+
+The PRAGMA interception writes cursor result state directly:
+
+  - Setter (``PRAGMA busy_timeout = N`` or ``PRAGMA busy_timeout(N)``)
+    updates ``connection._busy_timeout`` in seconds (N is ms per
+    SQLite convention; we divide by 1000) and emits the new value as
+    a single-row result, matching stdlib's PRAGMA result-set shape.
+  - Getter (``PRAGMA busy_timeout``) emits the current value as a
+    single-row result.
+
+Case-insensitive and whitespace-tolerant per SQLite parser
+conventions. Multi-statement strings ARE rejected (only a SINGLE
+``PRAGMA busy_timeout`` statement is intercepted; multi-statement
+inputs surface to the wire where the existing multi-statement
+classifier rejects them with ``ProgrammingError`` — that path is
+unchanged).
+
+The interception writes the cursor's result state directly:
+
+  - ``_description = (("busy_timeout", None, None, None, None, None, None),)``
+  - ``_rows = [(N_ms_clamped,)]``
+  - ``_rowcount = -1`` (PRAGMA does not have a meaningful row count)
+  - ``_row_index = 0``
+
+Then returns True so the caller short-circuits before the wire
+round-trip.
+
+The BEGIN rewrite, by contrast, returns the rewritten SQL string
+(or ``None`` to leave the caller's SQL unchanged) — there is no
+cursor state to populate; the caller substitutes the SQL and lets
+the rewritten ``BEGIN IMMEDIATE`` flow through the regular wire
+round-trip.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from dqlitedbapi.cursor import Cursor
+
+# Match ``PRAGMA busy_timeout`` with optional setter forms:
+#
+#   PRAGMA busy_timeout
+#   PRAGMA busy_timeout = 5000
+#   PRAGMA busy_timeout=5000
+#   pragma BUSY_TIMEOUT  = 5000
+#   PRAGMA busy_timeout(5000)
+#
+# The trailing ``;?`` accommodates the canonical single-statement
+# terminator. A semicolon followed by additional content (multi-
+# statement) does NOT match — those route to the wire where the
+# existing multi-statement classifier rejects them.
+_PRAGMA_BUSY_TIMEOUT_RE = re.compile(
+    r"^\s*PRAGMA\s+busy_timeout\s*"
+    r"(?:=\s*(?P<setter_eq>-?\d+)|\(\s*(?P<setter_paren>-?\d+)\s*\))?"
+    r"\s*;?\s*$",
+    re.IGNORECASE,
+)
+
+
+def try_intercept_busy_timeout(
+    cursor: Cursor,
+    statement: str,
+    parameters: object,
+) -> bool:
+    """Return True if the statement is ``PRAGMA busy_timeout`` (any
+    form) and the cursor's result state has been populated.
+
+    When True, the caller MUST short-circuit BEFORE the wire round-
+    trip (the server would reject the PRAGMA via the VFS authorizer
+    if it reached the wire, defeating the interception's purpose).
+
+    ``parameters`` is accepted for caller-signature parity but
+    PRAGMA does not take parameters. If parameters are non-empty
+    we still match the PRAGMA and ignore them — the engine would
+    do the same. (A future refinement could raise a friendlier
+    error here, but stdlib silently accepts the same shape.)
+    """
+    if not isinstance(statement, str):
+        return False
+    match = _PRAGMA_BUSY_TIMEOUT_RE.match(statement)
+    if match is None:
+        return False
+    setter_eq = match.group("setter_eq")
+    setter_paren = match.group("setter_paren")
+    setter_value = setter_eq if setter_eq is not None else setter_paren
+    connection = cursor._connection
+    if setter_value is not None:
+        # Setter form: update connection._busy_timeout.
+        # SQLite clamps negative values to 0 (no wait) — stdlib parity.
+        new_ms = max(0, int(setter_value))
+        connection._busy_timeout = new_ms / 1000.0
+    # Both setter AND getter forms emit the (possibly updated) value
+    # as a single-row result. Matches SQLite's PRAGMA convention:
+    # ``PRAGMA busy_timeout = 5000`` returns ``(5000,)``,
+    # ``PRAGMA busy_timeout`` (getter) also returns ``(5000,)``.
+    current_ms = int(connection._busy_timeout * 1000)
+    cursor._description = (("busy_timeout", None, None, None, None, None, None),)
+    cursor._rows = [(current_ms,)]
+    cursor._rowcount = -1
+    cursor._row_index = 0
+    # Match stdlib: PRAGMA does not set lastrowid.
+    return True
+
+
+# Match the BEGIN forms that should be upgraded to BEGIN IMMEDIATE:
+#
+#   BEGIN
+#   BEGIN;
+#   BEGIN TRANSACTION
+#   BEGIN TRANSACTION;
+#
+# Explicit ``BEGIN DEFERRED`` / ``BEGIN IMMEDIATE`` / ``BEGIN
+# EXCLUSIVE`` MUST NOT match — the caller (or the SA dialect's
+# per-session ``dqlite_session_mode`` opt-out) has stated explicit
+# intent. The bare ``BEGIN`` form is what SA emits by default
+# and what most callers reach for; it is the only ambiguous
+# shape that benefits from the writer-safe upgrade.
+_BEGIN_REWRITE_RE = re.compile(
+    r"^\s*BEGIN(?:\s+TRANSACTION)?\s*;?\s*$",
+    re.IGNORECASE,
+)
+
+# Recognised session-mode values. The dbapi layer accepts these as
+# the ``session_mode`` kwarg / URL form / env-var value, the SA
+# dialect accepts the same set as ``dqlite_session_mode``
+# execution-option values, and the cursor's BEGIN-rewrite intercept
+# reads ``conn._dqlite_session_mode`` against this set.
+#
+# - ``"immediate"`` (default): bare ``BEGIN`` is rewritten to
+#   ``BEGIN IMMEDIATE`` — writer-safe, no SQLITE_BUSY_SNAPSHOT race.
+# - ``"deferred"``: legacy SQLite DEFERRED — bare ``BEGIN`` passes
+#   through unchanged. Read-only sessions that want to avoid the
+#   writer-lock serialisation tax can opt in.
+# - ``"exclusive"``: dialect emits the explicit ``BEGIN EXCLUSIVE``
+#   literal for stronger lock semantics.
+# - ``"read_only"``: bare ``BEGIN`` passes through (DEFERRED form)
+#   AND ``PRAGMA query_only = 1`` is set on the connection so the
+#   engine rejects every write at PREPARE with SQLITE_READONLY.
+_SESSION_MODE_VALUES: Final[frozenset[str]] = frozenset(
+    {"immediate", "deferred", "exclusive", "read_only"}
+)
+
+# Env-var default for the session mode. Read at module-import time;
+# explicit ``connect(..., session_mode=...)`` always wins. Missing or
+# empty → ``"immediate"`` (the writer-safe default). Any value
+# outside ``_SESSION_MODE_VALUES`` raises at validation; here we just
+# normalise and return the raw string.
+_DQLITE_SESSION_MODE_ENV: Final[str] = os.environ.get("DQLITE_SESSION_MODE", "").strip().lower()
+
+
+def session_mode_default_from_env() -> str:
+    """Return the env-var-derived default for the connection's
+    session mode.
+
+    Used by ``Connection.__init__`` when the caller does not pass an
+    explicit ``session_mode`` kwarg. Re-read at each call so test
+    fixtures that ``monkeypatch.setenv`` see the live value (the
+    module-level cache is only used as the fallback when the env var
+    was set at import time).
+
+    Missing / empty env var → ``"immediate"`` (writer-safe default).
+    Invalid value raises ``ValueError`` so misconfiguration surfaces
+    at construct time, not at first ``do_begin``.
+    """
+    raw = os.environ.get("DQLITE_SESSION_MODE")
+    value = (raw if raw is not None else _DQLITE_SESSION_MODE_ENV).strip().lower()
+    if not value:
+        return "immediate"
+    if value not in _SESSION_MODE_VALUES:
+        raise ValueError(
+            f"DQLITE_SESSION_MODE={raw!r} is not one of {sorted(_SESSION_MODE_VALUES)}"
+        )
+    return value
+
+
+def validate_session_mode(value: object) -> str:
+    """Coerce + validate a ``session_mode`` value.
+
+    Returns the canonical lowercase form. Raises ``ValueError`` for
+    anything outside ``_SESSION_MODE_VALUES`` so misconfiguration
+    surfaces at the boundary (constructor or
+    ``execution_options(...)`` call), not at the first ``do_begin``.
+
+    Accepts ``None`` as "use the env-var default" (caller is
+    responsible for substituting via ``session_mode_default_from_env``
+    when they want that semantics).
+    """
+    if not isinstance(value, str):
+        raise ValueError(f"session_mode must be a str, got {type(value).__name__}")
+    normalised = value.lower()
+    if normalised not in _SESSION_MODE_VALUES:
+        raise ValueError(
+            f"Invalid session_mode {value!r}; valid values are {sorted(_SESSION_MODE_VALUES)}"
+        )
+    return normalised
+
+
+def try_rewrite_begin_to_immediate(
+    statement: str,
+    *,
+    session_mode: str,
+) -> str | None:
+    """Return ``"BEGIN IMMEDIATE"`` if ``statement`` is a plain BEGIN
+    form AND the connection's session mode is ``"immediate"``, else
+    ``None`` (caller leaves the SQL unchanged).
+
+    The rewrite fires only when ``session_mode == "immediate"`` — the
+    writer-safe default. Other modes (``"deferred"``, ``"exclusive"``,
+    ``"read_only"``) leave bare ``BEGIN`` untouched:
+
+    - ``"deferred"`` / ``"read_only"``: the SQLite engine interprets
+      bare ``BEGIN`` as DEFERRED, which is what these modes want.
+      Rewriting to IMMEDIATE would take a useless writer-lock.
+    - ``"exclusive"``: the SA dialect's ``do_begin`` emits the
+      explicit ``BEGIN EXCLUSIVE`` literal, which doesn't match the
+      bare-BEGIN regex anyway. The exclusive case never reaches this
+      function with a bare BEGIN under normal SA usage.
+
+    A ``None`` return also covers the case where ``statement`` is not
+    a recognised plain-BEGIN form (e.g. explicit ``BEGIN IMMEDIATE``
+    / ``BEGIN DEFERRED`` / ``BEGIN EXCLUSIVE`` / non-BEGIN statement).
+    Caller passes the original SQL through unchanged.
+    """
+    if session_mode != "immediate":
+        return None
+    if not isinstance(statement, str):
+        return None
+    if _BEGIN_REWRITE_RE.match(statement) is None:
+        return None
+    return "BEGIN IMMEDIATE"

{dqlite_dbapi-0.2.1 → dqlite_dbapi-0.2.2}/src/dqlitedbapi/aio/__init__.py

@@ -43,6 +43,8 @@ from dqlitedbapi import (  # module-level re-export
     CLUSTER_POLICY_REJECTION_PREFIX,
     FAILED_TO_CONNECT_PREFIX,
     MAX_CONTINUATION_FRAMES_UPPER_BOUND,
+    UNKNOWN,
+    Row,
     complete_statement,
     enable_callback_tracebacks,
     register_converter,
@@ -60,6 +62,7 @@ from dqlitedbapi._constants import (
 from dqlitedbapi.aio.connection import AsyncConnection
 from dqlitedbapi.aio.cursor import AsyncCursor
 from dqlitedbapi.exceptions import (
+    AdapterLookupError,
     AmbiguousCommitError,
     DatabaseError,
     DataError,
@@ -174,6 +177,7 @@ __all__ = [  # grouped by PEP 249 section, not alphabetical
     "InternalError",
     "ProgrammingError",
     "NotSupportedError",
+    "AdapterLookupError",
     # dqlite-specific OperationalError subclass marking an in-doubt
     # commit (leader flip mid-COMMIT). Exposed alongside the PEP 249
     # standard set for cross-driver introspection symmetry.
@@ -192,6 +196,9 @@ __all__ = [  # grouped by PEP 249 section, not alphabetical
     "NUMBER",
     "DATETIME",
     "ROWID",
+    "UNKNOWN",
+    # Row factory (sqlite3.Row equivalent)
+    "Row",
     # Type aliases
     "DescriptionTuple",
     # Type-adapter registry (shared module-global with the sync
@@ -233,6 +240,7 @@ def connect(
     attempt_timeout: float | None = None,
     dial_func: DialFunc | None = None,
     busy_timeout: float = 5.0,
+    session_mode: str | None = None,
     **unknown_kwargs: object,
 ) -> AsyncConnection:
     """Create a dqlite connection (connects lazily on first use).
@@ -361,6 +369,7 @@ def connect(
         attempt_timeout=attempt_timeout,
         dial_func=dial_func,
         busy_timeout=busy_timeout,
+        session_mode=session_mode,
     )
     # Apply the validated ``isolation_level`` / ``autocommit`` kwargs
     # via the setters on the freshly-constructed connection — sync
@@ -386,6 +395,7 @@ async def aconnect(
     attempt_timeout: float | None = None,
     dial_func: DialFunc | None = None,
     busy_timeout: float = 5.0,
+    session_mode: str | None = None,
     **unknown_kwargs: object,
 ) -> AsyncConnection:
     """Connect to a dqlite database asynchronously.
@@ -506,6 +516,7 @@ async def aconnect(
         attempt_timeout=attempt_timeout,
         dial_func=dial_func,
         busy_timeout=busy_timeout,
+        session_mode=session_mode,
     )
     try:
         await conn.connect()
@@ -560,6 +571,21 @@ async def aconnect(
                 "aconnect: exception during cleanup-close after failed connect",
                 exc_info=True,
             )
+        # Defensive null-out: mirrors AsyncConnection.__aenter__'s
+        # cleanup arm. ``close()`` may have short-circuited at its
+        # TOP-of-method ``if self._closed: return`` guard because a
+        # concurrent close (foreign-thread ``force_close_transport``)
+        # flipped ``_closed=True`` first. The short-circuit then
+        # skips the never-connected branch that nulls these slots,
+        # leaving the lazy loop-bound primitives stale. A subsequent
+        # reuse on a different loop would hit a misleading
+        # cross-loop diagnostic in ``_ensure_locks`` instead of the
+        # documented fresh-connect path. Tolerate the attributes
+        # being absent on fixture-built objects.
+        with contextlib.suppress(AttributeError):
+            conn._connect_lock = None
+            conn._op_lock = None
+            conn._loop_ref = None
         raise
     # Apply the validated ``isolation_level`` / ``autocommit`` kwargs
     # via the setters on the freshly-connected AsyncConnection. Stdlib