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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dqlite-dbapi
-Version: 0.2.0
+Version: 0.2.1
 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.0
-Requires-Dist: dqlite-wire<0.3.0,>=0.2.0
+Requires-Dist: dqlite-client<0.3.0,>=0.2.1
+Requires-Dist: dqlite-wire<0.3.0,>=0.2.1
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -73,7 +73,9 @@ asyncio.run(main())
 ## PEP 249 Compliance
 
 - `apilevel = "2.0"`
-- `threadsafety = 1`
+- `threadsafety = 2` (capability ceiling; default `check_same_thread=True`
+  enforces strict per-thread — matches stdlib sqlite3's "advertise
+  ceiling, default to floor" pattern)
 - `paramstyle = "qmark"`
 
 ## Transactions
@@ -240,10 +242,16 @@ borrowed from one.
   stdlib silently accepts empty / whitespace-only / comment-only SQL
   as a no-op; the driver pre-flight rejects per PEP 249 §7 to surface
   caller bugs at the call site.
-- **`threadsafety = 1`** (stdlib reports `3`). Each Connection is
-  thread-affine: methods called from a foreign thread raise
-  `ProgrammingError`. Use one Connection per thread or use the async
-  surface for a single-thread-per-loop model.
+- **`threadsafety = 2`** (stdlib reports `3` — we don't claim Tier 3
+  because cursors aren't shareable per the documented "share
+  connections, not cursors" contract). Tier 2 = "threads may share
+  the module AND connections"; matches the dbapi's
+  ``check_same_thread=False`` opt-in behaviour. Default
+  ``check_same_thread=True`` enforces strict per-thread; methods
+  called from a foreign thread on a default-mode Connection raise
+  ``ProgrammingError``. Tier 3 (cursor sharing) is tracked as
+  future work in
+  ``issues/dbapi-threadsafety-tier-3-cursor-sharing-stdlib-parity.md``.
 - **No `executescript` / `create_function` / `create_aggregate` /
   `create_window_function` / `iterdump` / `backup` / `set_authorizer`
   / `serialize` / `blobopen`.** stdlib-specific APIs that have no

{dqlite_dbapi-0.2.0 → dqlite_dbapi-0.2.1}/README.md

@@ -39,7 +39,9 @@ asyncio.run(main())
 ## PEP 249 Compliance
 
 - `apilevel = "2.0"`
-- `threadsafety = 1`
+- `threadsafety = 2` (capability ceiling; default `check_same_thread=True`
+  enforces strict per-thread — matches stdlib sqlite3's "advertise
+  ceiling, default to floor" pattern)
 - `paramstyle = "qmark"`
 
 ## Transactions
@@ -206,10 +208,16 @@ borrowed from one.
   stdlib silently accepts empty / whitespace-only / comment-only SQL
   as a no-op; the driver pre-flight rejects per PEP 249 §7 to surface
   caller bugs at the call site.
-- **`threadsafety = 1`** (stdlib reports `3`). Each Connection is
-  thread-affine: methods called from a foreign thread raise
-  `ProgrammingError`. Use one Connection per thread or use the async
-  surface for a single-thread-per-loop model.
+- **`threadsafety = 2`** (stdlib reports `3` — we don't claim Tier 3
+  because cursors aren't shareable per the documented "share
+  connections, not cursors" contract). Tier 2 = "threads may share
+  the module AND connections"; matches the dbapi's
+  ``check_same_thread=False`` opt-in behaviour. Default
+  ``check_same_thread=True`` enforces strict per-thread; methods
+  called from a foreign thread on a default-mode Connection raise
+  ``ProgrammingError``. Tier 3 (cursor sharing) is tracked as
+  future work in
+  ``issues/dbapi-threadsafety-tier-3-cursor-sharing-stdlib-parity.md``.
 - **No `executescript` / `create_function` / `create_aggregate` /
   `create_window_function` / `iterdump` / `backup` / `set_authorizer`
   / `serialize` / `blobopen`.** stdlib-specific APIs that have no

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dqlite-dbapi"
-version = "0.2.0"
+version = "0.2.1"
 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.0,<0.3.0",
-    "dqlite-wire>=0.2.0,<0.3.0",
+    "dqlite-client>=0.2.1,<0.3.0",
+    "dqlite-wire>=0.2.1,<0.3.0",
 ]
 
 [tool.uv.sources]

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

@@ -107,14 +107,38 @@ from dqlitewire import (
 
 # PEP 249 module-level attributes
 apilevel: _Final[_Literal["2.0"]] = "2.0"
-# PEP 249 value 1: threads may share the module.
+# PEP 249 value 2: threads may share the module and connections.
 #
-# This driver is stricter than the PEP minimum: each Connection is
-# bound to the thread that created it. Any method call from a
-# different thread raises ProgrammingError. Use one Connection per
-# thread, or use the async API (dqlitedbapi.aio.aconnect) for a
-# single-thread-per-loop model.
-threadsafety: _Final[_Literal[1]] = 1
+# This declares the driver's CAPABILITY ceiling: connections are
+# safe to share across threads once the user opts in via
+# ``check_same_thread=False`` at ``connect()`` (matches stdlib
+# sqlite3's convention — stdlib advertises ``threadsafety = 3``
+# while defaulting ``check_same_thread=True`` to enforce strict
+# per-thread at the Python layer). Cursors are explicitly NOT
+# shareable across threads — the documented contract is "share
+# connections, not cursors" (see ``Connection`` docstring); the
+# ceiling stays at PEP 249 tier 2 for that reason. Tier 3 (cursors
+# shareable too) is tracked as future work in
+# ``issues/dbapi-threadsafety-tier-3-cursor-sharing-stdlib-parity.md``.
+#
+# DEFAULT enforcement is still per-thread: ``check_same_thread``
+# defaults to ``True`` and ``Connection._check_thread()`` raises
+# ``ProgrammingError`` on cross-thread method calls. Pass
+# ``check_same_thread=False`` to use the connection sharing
+# advertised here. The wire is always serialised by ``_op_lock``;
+# the Phase 2 hardening (``_state_lock`` for transaction owner
+# read-check-reserve, ``_cursors`` WeakSet add/discard) closes
+# the cross-thread correctness gaps for the connection-shared
+# path.
+#
+# This declaration uses the "advertise ceiling, default to floor"
+# pattern stdlib sqlite3 established since CPython 3.11
+# (bpo-45613 / gh-31464 made ``sqlite3.threadsafety`` dynamic via
+# ``SQLITE_THREADSAFE`` mode; serialized = tier 3). The pattern
+# describes capability rather than default enforcement;
+# capability-detection libraries reading this value learn the
+# safe-with-opt-in ceiling.
+threadsafety: _Final[_Literal[2]] = 2
 paramstyle: _Final[_Literal["qmark"]] = "qmark"  # Question mark style: WHERE name=?
 
 # SQLite compatibility attributes (for SQLAlchemy).
@@ -147,7 +171,7 @@ LEGACY_TRANSACTION_CONTROL: _Final[int] = -1
 PARSE_DECLTYPES: _Final[int] = 1
 PARSE_COLNAMES: _Final[int] = 2
 
-__version__: _Final[str] = "0.2.0"
+__version__: _Final[str] = "0.2.1"
 
 __all__ = [  # grouped by PEP 249 section, not alphabetical
     # Module attributes
@@ -222,6 +246,8 @@ def connect(
     dial_timeout: float | None = None,
     attempt_timeout: float | None = None,
     dial_func: DialFunc | None = None,
+    busy_timeout: float = 5.0,
+    check_same_thread: bool = True,
     **unknown_kwargs: object,
 ) -> Connection:
     """Connect to a dqlite database.
@@ -269,6 +295,33 @@ def connect(
             ``asyncio.open_connection`` path. Forwarded to the
             underlying :class:`Connection`. See
             :data:`dqliteclient.DialFunc` for the protocol.
+        busy_timeout: Maximum cumulative seconds to spend retrying
+            BUSY responses before raising. Default ``5.0`` matches
+            stdlib ``sqlite3.connect(timeout=5.0)``. Retries follow
+            SQLite's deterministic ``sqliteDefaultBusyCallback``
+            curve (1, 2, 5, 10, 15, 20, 25, 25, 25, 50, 50, 100 ms
+            then flat 100 ms). ``0`` disables retry (first BUSY
+            raises immediately — stdlib parity). dqlite's VFS
+            authorizer rejects the canonical ``PRAGMA busy_timeout``
+            on the server side; this driver intercepts the PRAGMA at
+            the Cursor layer so ``cur.execute("PRAGMA busy_timeout
+            = 30000")`` works transparently and updates the same
+            backing field as the kwarg.
+        check_same_thread: When ``True`` (default), every method
+            call on the returned Connection must come from the
+            thread that called ``connect()``; cross-thread calls
+            raise ``ProgrammingError``. When ``False``, the cross-
+            thread check is gated off and the Connection can be
+            shared across threads — the wire is already serialised
+            by the per-Connection op-lock regardless of caller
+            thread. Per-cursor result state is NOT thread-safe; the
+            documented pattern is "share connections, not cursors."
+            Matches stdlib ``sqlite3.connect(check_same_thread=
+            False)``. The fork check is NEVER relaxed; cross-process
+            Connection use raises ``InterfaceError`` in both modes.
+            See ``dqlitedbapi.Connection`` docstring for the
+            cursor / messages / close() contracts under the
+            relaxation.
 
     Returns:
         A Connection object
@@ -323,11 +376,10 @@ def connect(
             f"(stdlib LEGACY_TRANSACTION_CONTROL) only; got {autoc!r}"
         )
 
-    # Reject stdlib ``sqlite3.connect`` kwargs that this driver
-    # cannot honour (``detect_types``, ``check_same_thread``,
-    # ``factory``, ``cached_statements``, ``uri``) with
-    # ``NotSupportedError`` rather than letting Python's call-
-    # protocol leak ``TypeError`` (which escapes ``except
+    # Reject other stdlib ``sqlite3.connect`` kwargs that this driver
+    # cannot honour (``detect_types``, ``factory``, ``cached_statements``,
+    # ``uri``) with ``NotSupportedError`` rather than letting Python's
+    # call-protocol leak ``TypeError`` (which escapes ``except
     # dbapi.Error:``). Cross-driver code that passes stdlib kwargs
     # through should be able to catch the rejection inside the
     # dbapi error hierarchy.
@@ -352,6 +404,8 @@ def connect(
         dial_timeout=dial_timeout,
         attempt_timeout=attempt_timeout,
         dial_func=dial_func,
+        busy_timeout=busy_timeout,
+        check_same_thread=check_same_thread,
     )
     # Apply the validated ``isolation_level`` / ``autocommit`` kwargs
     # via the setters on the freshly-constructed connection. Stdlib

dqlite_dbapi-0.2.1/src/dqlitedbapi/_busy_retry.py

@@ -0,0 +1,297 @@
+"""Server-BUSY retry mechanism — stdlib ``sqlite3`` parity.
+
+Stdlib ``sqlite3.connect(timeout=N)`` defaults to a 5-second
+``busy_timeout`` at the SQLite C library level. When a write hits
+contention the C library transparently sleeps and retries via a
+deterministic curve (``main.c::sqliteDefaultBusyCallback``). dqlite's
+server-side VFS authorizer denies ``PRAGMA busy_timeout`` (see
+``done/dbapi-pragma-deny-list-no-regression-pin.md``), so callers
+cannot tune the retry behaviour through the canonical SQLite escape
+hatch. Without an in-driver retry, application code that worked
+against stdlib ``sqlite3`` silently regresses on dqlite — two
+concurrent writers contending for the dqlite write lock produce
+``OperationalError: database is locked to <addr>`` surfacing as HTTP
+500s.
+
+This module hosts the SQLite-equivalent retry curve and the
+``OperationalError`` ↔ BUSY classifier so the sync and async surfaces
+can share both. The actual retry-loop helpers live on the
+``Connection`` / ``AsyncConnection`` classes (they need access to the
+per-connection ``busy_timeout`` and the run-sync / run-async
+bridges).
+
+Design notes:
+
+- The curve is SQLite's own (``delays`` / ``totals`` arrays from
+  ``main.c``). Battle-tested. No jitter — BUSY is local contention,
+  not distributed-systems flapping; jitter would only smear the
+  retry burst across siblings without changing the convergence shape.
+
+- The classifier gates on ``code == SQLITE_BUSY`` not on a substring
+  scan. The user-supplied brief referenced
+  ``dqliteclient/connection.py:_RAFT_BUSY_MESSAGE_FRAGMENTS`` but
+  that tuple is narrow (``("checkpoint in progress",)``) and is the
+  classifier for the SEPARATE "checkpoint-BUSY rewrap as
+  ``DqliteConnectionError``" path — NOT the RAFT-BUSY-"is locked"
+  family this retry targets. Code-based gating catches both engine-
+  BUSY and RAFT-BUSY shapes per the existing comment at
+  ``dqliteclient/connection.py:2683-2698``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Awaitable, Callable, Coroutine
+from typing import Any, Final
+
+from dqlitedbapi.exceptions import OperationalError as _OperationalError
+from dqlitewire import SQLITE_BUSY as _SQLITE_BUSY
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_busy_timeout_seconds(connection: object) -> float:
+    """Read ``connection._busy_timeout`` with a MagicMock-safe
+    fallback. Test fixtures construct ``Cursor`` instances with
+    ``MagicMock`` connections whose attributes auto-spawn — without
+    this guard the retry curve's ``int(busy_timeout * 1000)`` would
+    crash on a non-numeric MagicMock. ``isinstance`` check on the
+    return value falls through to ``0.0`` (no retry — preserves the
+    pre-feature test semantics)."""
+    value = getattr(connection, "_busy_timeout", 0.0)
+    # ``bool`` is ``int`` to ``isinstance`` but must be rejected
+    # explicitly; production code rejects bool at validation. A
+    # MagicMock attribute is not a real number — fall through.
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return 0.0
+    return float(value)
+
+
+# SQLite's busy-callback curve (``main.c::sqliteDefaultBusyCallback``).
+# ``delays[i]`` is the milliseconds to sleep before retry attempt
+# ``i+1``; ``totals[i]`` is the cumulative sleep BEFORE attempt
+# ``i`` (so ``totals[i+1] == totals[i] + delays[i]``). After
+# ``len(delays)`` attempts the curve flattens at the last
+# ``delays`` value (100 ms) — see ``next_busy_delay_ms`` below.
+#
+# Pinned to the canonical SQLite values (verified internally
+# consistent via the totals[i+1] = totals[i] + delays[i] check
+# in ``tests/test_busy_retry_curve.py``). The constant 25 appears
+# three times in a row at positions 6, 7, 8 — this is intentional
+# in the upstream curve, not an editing mistake.
+_BUSY_DELAYS_MS: Final[tuple[int, ...]] = (1, 2, 5, 10, 15, 20, 25, 25, 25, 50, 50, 100)
+_BUSY_TOTALS_MS: Final[tuple[int, ...]] = (0, 1, 3, 8, 18, 33, 53, 78, 103, 128, 178, 228)
+
+
+def next_busy_delay_ms(count: int, busy_timeout_ms: int) -> int | None:
+    """Return the sleep duration (ms) before retry attempt ``count+1``,
+    or ``None`` when the cumulative budget is exhausted.
+
+    Mirrors SQLite's ``sqliteDefaultBusyCallback`` exactly:
+
+    - For ``count < len(_BUSY_DELAYS_MS)``, return the next entry from
+      the curve.
+    - For ``count >= len(_BUSY_DELAYS_MS)``, return the flat tail
+      value (100 ms).
+    - If the resulting ``prior + delay`` would overrun
+      ``busy_timeout_ms``, clamp ``delay`` to fit; if the clamp would
+      produce ``delay <= 0``, return ``None`` (caller raises the
+      original BUSY).
+
+    ``busy_timeout_ms <= 0`` short-circuits ``None`` regardless of
+    ``count`` — stdlib parity for ``timeout=0`` meaning "no wait."
+    """
+    if busy_timeout_ms <= 0:
+        return None
+    n_curve = len(_BUSY_DELAYS_MS)
+    if count < n_curve:
+        delay = _BUSY_DELAYS_MS[count]
+        prior = _BUSY_TOTALS_MS[count]
+    else:
+        delay = _BUSY_DELAYS_MS[-1]
+        prior = _BUSY_TOTALS_MS[-1] + delay * (count - (n_curve - 1))
+    if prior + delay > busy_timeout_ms:
+        delay = busy_timeout_ms - prior
+        if delay <= 0:
+            return None
+    return delay
+
+
+def is_busy_exception(exc: BaseException) -> bool:
+    """Classify an exception as a retryable BUSY.
+
+    The retry mechanism gates on ``OperationalError`` whose ``code`` is
+    ``SQLITE_BUSY (5)``. This covers both engine-BUSY (the SQLite-side
+    BUSY where the user can retry the failing statement and continue
+    the same tx) AND RAFT-BUSY translated by the server's gateway
+    (the in-flight write was not accepted; the server-side tx state
+    is the same as engine-BUSY from the client's perspective).
+
+    The two shapes are indistinguishable at the Python layer per the
+    existing comment at ``dqliteclient/connection.py:2683-2698``
+    ("users must retry explicitly"). This retry IS that explicit
+    retry, applied uniformly across both BUSY origins.
+
+    Specifically NOT retried:
+
+    - ``DqliteConnectionError`` (the checkpoint-BUSY rewrap at
+      ``dqliteclient/connection.py:2717``) — bypasses this classifier
+      because it's not an ``OperationalError`` subclass. The
+      checkpoint-BUSY case already triggers SA pool invalidation by
+      design (the connection's tx state was reset; retry on the same
+      connection is wrong).
+    - Other ``OperationalError`` codes (LEADER_ERROR_CODES,
+      INTERFACE_ERROR_CODES, etc.) — leader-flip and transport
+      faults have their own retry semantics elsewhere; this gate
+      narrows to BUSY only.
+    """
+    if not isinstance(exc, _OperationalError):
+        return False
+    return getattr(exc, "code", None) == _SQLITE_BUSY
+
+
+def retry_sync_on_busy[T](
+    busy_timeout: float,
+    run_sync: Callable[[Coroutine[Any, Any, T]], T],
+    coro_factory: Callable[[], Coroutine[Any, Any, T]],
+) -> T:
+    """Module-level sync retry loop.
+
+    Caller provides ``run_sync`` (the function that drives the
+    coroutine on the connection's daemon loop — typically
+    ``connection._run_sync``) and ``coro_factory`` (a callable that
+    returns a fresh coroutine each time the retry needs to re-submit).
+    Coroutines are single-use so the factory shape is mandatory.
+
+    Same retry shape as the inline-on-connection variants: SQLite-curve
+    sleeps, BUSY-only classification (``OperationalError(code=
+    SQLITE_BUSY)``), propagate non-BUSY exceptions unchanged.
+    ``KeyboardInterrupt`` / ``SystemExit`` during ``time.sleep``
+    propagate (those are ``BaseException``, not caught by ``except
+    OperationalError``).
+
+    ``busy_timeout <= 0`` short-circuits to a single ``run_sync``
+    call with no retry (stdlib parity for ``timeout=0``).
+
+    **Cross-thread caveat under** ``check_same_thread=False``:
+
+    The retry loop releases the connection's ``_op_lock`` between
+    attempts. ``run_sync`` acquires the lock at the START of each
+    attempt and releases it before returning; the ``time.sleep``
+    that follows runs OUTSIDE the lock so the sleep doesn't starve
+    sibling threads. By design — holding ``_op_lock`` across a
+    100ms sleep would defeat cross-thread sharing.
+
+    On a Connection shared across threads via
+    ``check_same_thread=False``, a BUSY-retried statement may
+    observe interleaved writes from sibling threads between retry
+    attempts. Example:
+
+        Thread A: cur.execute("UPDATE t SET v=v+1 WHERE k=?") -> BUSY
+        Thread A: sleeps for SQLite-curve delay (op_lock released)
+        Thread B: cur.execute("UPDATE t SET v=v+1 WHERE k=?") -> succeeds
+        Thread A: retries -> sees B's update; may succeed against
+                  a different row state than the original attempt.
+
+    This is the correct semantic for retry-on-contention (each
+    retry sees current state, the same as it would on a fresh
+    connection). Callers who need to retry against an atomic
+    snapshot must wrap in an explicit transaction:
+
+        with conn.transaction():
+            cur.execute("UPDATE t SET v=v+1 WHERE k=?", (k,))
+
+    The transaction holds the wire lock across the entire body, so
+    sibling threads cannot interleave statements between the retry
+    attempts inside that body.
+    """
+    busy_timeout_ms = int(busy_timeout * 1000)
+    if busy_timeout_ms <= 0:
+        return run_sync(coro_factory())
+    count = 0
+    while True:
+        try:
+            return run_sync(coro_factory())
+        except _OperationalError as exc:
+            if not is_busy_exception(exc):
+                raise
+            delay_ms = next_busy_delay_ms(count, busy_timeout_ms)
+            if delay_ms is None:
+                logger.warning(
+                    "busy_timeout budget %.3fs exhausted after %d retries; raising original BUSY",
+                    busy_timeout,
+                    count,
+                )
+                raise
+            logger.debug(
+                "BUSY retry attempt %d: sleeping %dms (budget %.3fs)",
+                count,
+                delay_ms,
+                busy_timeout,
+            )
+            time.sleep(delay_ms / 1000.0)
+            count += 1
+
+
+async def retry_async_on_busy[T](
+    busy_timeout: float,
+    coro_factory: Callable[[], Awaitable[T]],
+) -> T:
+    """Module-level async retry loop. Used by the per-iteration
+    executemany path that cannot route through
+    ``Connection._await_with_busy_retry`` because test fixtures
+    construct ``Cursor`` instances with a ``MagicMock`` connection
+    that does not have that method.
+
+    Same retry shape as the connection-method variants: SQLite-curve
+    sleeps, BUSY-only classification, propagate non-BUSY unchanged.
+    ``CancelledError`` propagates through ``await asyncio.sleep``
+    because the ``except OperationalError`` arm does not catch
+    ``BaseException``.
+
+    ``busy_timeout <= 0`` short-circuits to a single awaitable call
+    with no retry (stdlib parity).
+
+    **Cross-task caveat**:
+
+    Mirrors the sync sibling's cross-thread caveat: the retry loop
+    releases any wire-level lock (the inner ``DqliteConnection``'s
+    op_lock or the AsyncConnection's op_lock) between attempts.
+    ``await asyncio.sleep`` runs OUTSIDE the lock so siblings can
+    make progress; by design.
+
+    On an AsyncConnection shared across asyncio tasks on the same
+    loop, a BUSY-retried statement may observe interleaved writes
+    from sibling tasks between retry attempts. Same shape as the
+    sync sibling: each retry sees current state. Callers who need
+    to retry against an atomic snapshot must wrap in an explicit
+    ``async with conn.transaction():`` block.
+    """
+    busy_timeout_ms = int(busy_timeout * 1000)
+    if busy_timeout_ms <= 0:
+        return await coro_factory()
+    count = 0
+    while True:
+        try:
+            return await coro_factory()
+        except _OperationalError as exc:
+            if not is_busy_exception(exc):
+                raise
+            delay_ms = next_busy_delay_ms(count, busy_timeout_ms)
+            if delay_ms is None:
+                logger.warning(
+                    "busy_timeout budget %.3fs exhausted after %d retries; raising original BUSY",
+                    busy_timeout,
+                    count,
+                )
+                raise
+            logger.debug(
+                "BUSY retry attempt %d: sleeping %dms (budget %.3fs)",
+                count,
+                delay_ms,
+                busy_timeout,
+            )
+            await asyncio.sleep(delay_ms / 1000.0)
+            count += 1

dqlite_dbapi-0.2.1/src/dqlitedbapi/_pragma_intercept.py

@@ -0,0 +1,106 @@
+"""``PRAGMA busy_timeout`` interception at the dbapi cursor layer.
+
+dqlite's C VFS authorizer rejects ``PRAGMA busy_timeout`` (see prior
+issue ``done/dbapi-pragma-deny-list-no-regression-pin.md``), so the
+canonical SQLite escape hatch — ``PRAGMA busy_timeout = N`` — would
+otherwise raise ``DatabaseError("not authorized")`` on the dqlite
+server. To preserve stdlib parity (and to give callers a single
+canonical knob), this module intercepts the PRAGMA at the dbapi
+cursor layer BEFORE the wire round-trip:
+
+  - 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.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+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