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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dqlite-dbapi
-Version: 0.2.0
+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.0
-Requires-Dist: dqlite-wire<0.3.0,>=0.2.0
+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'
@@ -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.2}/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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dqlite-dbapi"
-version = "0.2.0"
+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.0,<0.3.0",
-    "dqlite-wire>=0.2.0,<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.0 → 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,
@@ -107,14 +110,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 +174,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.2"
 
 __all__ = [  # grouped by PEP 249 section, not alphabetical
     # Module attributes
@@ -190,6 +217,7 @@ __all__ = [  # grouped by PEP 249 section, not alphabetical
     "InternalError",
     "ProgrammingError",
     "NotSupportedError",
+    "AdapterLookupError",
     # Type constructors
     "Date",
     "Time",
@@ -204,6 +232,9 @@ __all__ = [  # grouped by PEP 249 section, not alphabetical
     "NUMBER",
     "DATETIME",
     "ROWID",
+    "UNKNOWN",
+    # Row factory (sqlite3.Row equivalent)
+    "Row",
     # Type aliases
     "DescriptionTuple",
 ]
@@ -222,6 +253,9 @@ 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,
+    session_mode: str | None = None,
     **unknown_kwargs: object,
 ) -> Connection:
     """Connect to a dqlite database.
@@ -269,6 +303,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 +384,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 +412,9 @@ def connect(
         dial_timeout=dial_timeout,
         attempt_timeout=attempt_timeout,
         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/_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