dqlite-dbapi 0.3.0__tar.gz → 0.4.0__tar.gz

{dqlite_dbapi-0.3.0 → dqlite_dbapi-0.4.0}/DEVELOPMENT.md

@@ -33,8 +33,8 @@ uv sync --extra dev
 # Run unit tests only
 .venv/bin/pytest tests/ --ignore=tests/integration
 
-# Run all tests (requires Docker cluster)
-cd ../dqlite-test-cluster && docker compose up -d
+# Run all tests (requires the Docker cluster from the sibling python-dqlite-dev checkout)
+(cd ../python-dqlite-dev/cluster && docker compose up -d)
 .venv/bin/pytest tests/
 ```
 

{dqlite_dbapi-0.3.0 → dqlite_dbapi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dqlite-dbapi
-Version: 0.3.0
+Version: 0.4.0
 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.4.0,>=0.3.0
-Requires-Dist: dqlite-wire<0.4.0,>=0.3.0
+Requires-Dist: dqlite-client<0.5.0,>=0.4.0
+Requires-Dist: dqlite-wire<0.5.0,>=0.4.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -121,6 +121,8 @@ Using SQLAlchemy or an ORM? Prefer
   gotcha).
 - [Differences from `aiosqlite`](docs/differences-from-aiosqlite.md) — for
   the async surface.
+- [Architecture](docs/architecture.md) — how the sync surface wraps the
+  async core, and the threading, lifecycle, and error-mapping policies.
 
 ## Development
 

{dqlite_dbapi-0.3.0 → dqlite_dbapi-0.4.0}/README.md

@@ -87,6 +87,8 @@ Using SQLAlchemy or an ORM? Prefer
   gotcha).
 - [Differences from `aiosqlite`](docs/differences-from-aiosqlite.md) — for
   the async surface.
+- [Architecture](docs/architecture.md) — how the sync surface wraps the
+  async core, and the threading, lifecycle, and error-mapping policies.
 
 ## Development
 

dqlite_dbapi-0.4.0/docs/architecture.md

@@ -0,0 +1,169 @@
+# Architecture
+
+This page records the design decisions behind `dqlite-dbapi`. The user-facing
+behaviour they produce is documented in [Transactions](transactions.md) and
+[Differences from `sqlite3`](differences-from-sqlite3.md).
+
+## Layering
+
+```
+dqlitedbapi          sync PEP 249 surface: Connection, Cursor
+    │  one daemon thread + asyncio loop per Connection
+dqlitedbapi.aio      async surface: AsyncConnection, AsyncCursor  ← all driver logic
+    │
+dqliteclient         DqliteConnection (wire session), ClusterClient (leader discovery)
+```
+
+All driver logic lives in `dqlitedbapi.aio`. The sync package is a thin
+adapter: a sync `Connection` owns one `AsyncConnection` and one background
+thread running an asyncio event loop; every sync method submits the matching
+coroutine to that loop and blocks on the result. Fetch methods never hop to
+the loop: results are fully buffered at execute time, so the sync cursor reads
+the buffer directly.
+
+Modules:
+
+| Module | Responsibility |
+| --- | --- |
+| `aio/connection.py` | `AsyncConnection`: lifecycle, transactions, session mode, operation lock |
+| `aio/cursor.py` | `AsyncCursor`: execute / executemany, result buffering, description |
+| `connection.py`, `cursor.py` | sync adapters over the async classes |
+| `_loop.py` | the background loop thread used by the sync adapter |
+| `_sql.py` | statement classification (row-returning, DML verbs, BEGIN rewrite, PRAGMA intercept) |
+| `_busy.py` | `SQLITE_BUSY` retry curve |
+| `exceptions.py` | PEP 249 hierarchy and the client-error to dbapi-error mapping |
+| `types.py`, `row.py` | type objects, constructors, adapters, datetime codecs, `Row` |
+
+Lexical SQL helpers (comment stripping, top-level statement splitting,
+literal blanking, leading keyword) come from `dqliteclient.sql`, which the
+client also uses for its own transaction tracking. `_sql.py` holds only the
+semantic rules the driver adds on top.
+
+## Connection lifecycle
+
+- Constructing a connection validates its arguments and does no I/O.
+- The first operation (or an explicit `connect()` / `aconnect()`) resolves
+  the cluster leader from the seed address through `ClusterClient`, opens the
+  wire session against the leader, and applies the session mode.
+- **An invalidated connection is a closed connection.** When the underlying
+  wire session is lost (transport error, leader change, cancellation or
+  interrupt during an operation), `closed` becomes `True`, `invalidated`
+  becomes `True`, and every further operation raises `InterfaceError`. The
+  driver never reconnects silently: a reconnect would drop transaction state
+  the caller believes is still open. Pools (SQLAlchemy's included) discard the
+  connection and open a fresh one.
+- `close()` is idempotent and does not roll back (stdlib `sqlite3` parity).
+- `force_close_transport()` is synchronous, thread-safe, never raises, and
+  tears the socket down without waiting for an in-flight operation. It exists
+  for pool `terminate` paths and for shutting down from a thread that is not
+  the connection's owner.
+
+## Threading and concurrency
+
+### Sync surface
+
+- `check_same_thread=True` (default): every method except
+  `force_close_transport()` must be called from the thread that created the
+  connection; other threads get `ProgrammingError`.
+- `check_same_thread=False`: any thread may call the connection. Calls are
+  serialised by a lock. Cursors are still single-thread objects, as in
+  `sqlite3`: share the connection, give each thread its own cursor.
+- **Interrupts close the connection.** A `KeyboardInterrupt` or `SystemExit`
+  delivered while a call is blocked cancels the in-flight operation,
+  force-closes the connection, and propagates. The driver must not be
+  re-entered from a signal handler; that case is out of contract.
+- The sync side imposes no deadline of its own. Every await in the async
+  layer is already bounded by the client's per-RPC timeouts, so a blocked sync
+  call ends when those fire or when `force_close_transport()` is called from
+  another thread.
+
+### Async surface
+
+- An `AsyncConnection` binds to the event loop it first runs on. Using it
+  from another loop raises `InterfaceError`; it cannot be shared across
+  `asyncio.run()` calls or threads.
+- One operation at a time: an `asyncio.Lock` serialises execute, commit and
+  rollback across tasks on the same loop. Waiting tasks queue rather than
+  fail. A cursor is a single-task object.
+- Cancellation during a wire round-trip invalidates the connection (see
+  above), because the server-side effect of the interrupted statement is
+  unknown.
+
+## Statements
+
+- One statement per `execute()`; a second statement after `;` raises
+  `ProgrammingError` before any network round-trip. `CREATE TRIGGER` bodies
+  are understood, so their inner `;` do not count.
+- Empty, comment-only, and NUL-containing SQL raise `ProgrammingError`.
+- A `?` count that does not match the parameter count raises
+  `ProgrammingError` client-side.
+- Row-returning statements (`SELECT`, `VALUES`, `PRAGMA`, `EXPLAIN`, a
+  `WITH` whose final statement is one of those, and any DML with
+  `RETURNING`) go through the query path and populate `description` and the
+  row buffer. Everything else goes through the exec path and populates
+  `rowcount` (INSERT/UPDATE/DELETE/REPLACE only, else -1) and `lastrowid`
+  (INSERT/REPLACE only, sticky across other statements).
+- `PRAGMA busy_timeout` is answered locally: the server rejects it, and the
+  driver owns the busy budget.
+- A bare `BEGIN` / `BEGIN TRANSACTION` is rewritten according to the session
+  mode: `immediate` → `BEGIN IMMEDIATE`, `exclusive` → `BEGIN EXCLUSIVE`,
+  `deferred` and `read_only` → unchanged. An explicit qualifier is never
+  rewritten.
+- `SQLITE_BUSY` is retried on SQLite's default busy-callback curve until the
+  connection's `busy_timeout` budget is spent. Each `executemany` iteration
+  retries independently.
+- `description` carries `(name, type_code, None, None, None, None, None)`;
+  the type code is the wire `ValueType` of the first non-NULL cell in the
+  column, or the `UNKNOWN` sentinel when there is none.
+- `ISO8601` and `UNIXTIME` wire cells decode to `datetime` objects; every
+  other cell is passed through as the wire primitive.
+
+## Transactions
+
+- Autocommit by default: no implicit `BEGIN`.
+- `commit()` / `rollback()` are no-ops before the first connection and when no
+  transaction is open. A server reply of "no transaction is active" is
+  swallowed. Every other failure propagates.
+- A `COMMIT` that fails with a leadership-lost code raises
+  `AmbiguousCommitError` (an `OperationalError`): the write may or may not
+  have been applied.
+- `transaction()` is a context manager issuing `BEGIN` / `COMMIT` /
+  `ROLLBACK`. Calling `commit()` or `rollback()` inside the block raises
+  `InterfaceError`, because the block owns the boundaries.
+- `with conn:` / `async with conn:` commit on success and roll back on
+  exception; neither closes the connection.
+- `session_mode` is read-only; `set_session_mode()` changes it, emitting
+  `PRAGMA query_only` when crossing the `read_only` boundary. It may not be
+  called inside a transaction.
+
+## Errors
+
+Client exceptions are translated at the boundary by `exceptions.translate`:
+
+| Client exception | dbapi exception |
+| --- | --- |
+| `OperationalError` with code | class chosen from the SQLite primary code (constraint → `IntegrityError`, internal/nomem/notfound → `InternalError`, toobig → `DataError`, range/misuse → `InterfaceError`, corrupt/format/notadb → bare `DatabaseError`, dqlite parse/notfound → `ProgrammingError`, else `OperationalError`) |
+| `DqliteConnectionError`, `ClusterError`, `ProtocolError` | `OperationalError` with `code=None` |
+| `ClusterPolicyError` | `InterfaceError` prefixed `Cluster policy rejection` (never retried) |
+| `DataError`, wire `EncodeError` | `DataError` |
+| `InterfaceError` | `InterfaceError` |
+| any other `DqliteError` | `DatabaseError` |
+
+Every raised error keeps `code` and `raw_message` (the untruncated server
+text). Connect-time failures are prefixed `Failed to connect: `. These
+prefixes and the `Connection is closed` / `Cursor is closed` /
+`invalidated (id=` wordings are load-bearing: `sqlalchemy-dqlite` classifies
+disconnects on them.
+
+## Contract with sqlalchemy-dqlite
+
+The dialect relies on exactly this dbapi surface, beyond PEP 249 itself:
+
+- module: `connect`, exception classes, `paramstyle`, `sqlite_version_info`,
+  `FAILED_TO_CONNECT_PREFIX`, `CLUSTER_POLICY_REJECTION_PREFIX`;
+- connection: `cursor()`, `commit()`, `rollback()`, `close()`,
+  `force_close_transport()`, `connect()` (async), `session_mode`,
+  `default_session_mode`, `set_session_mode()`, `in_transaction`;
+- cursor: `execute()`, `executemany()`, `description`, `rowcount`,
+  `lastrowid`, `drain_rows()` (async), `close()`;
+- `types.format_utc_offset()` for the dialect's datetime processors.

{dqlite_dbapi-0.3.0 → dqlite_dbapi-0.4.0}/docs/differences-from-sqlite3.md

@@ -37,6 +37,15 @@ covers the differences you are most likely to notice when porting code.
   `create_window_function`, `iterdump`, `backup`, `set_authorizer`,
   `serialize`, `blobopen`, `executescript`, and `register_converter` have no
   server-side counterpart in dqlite; their stubs raise `NotSupportedError`.
+- **A lost connection stays lost.** When the wire session drops (transport
+  error, leader change, or an interrupted call), `closed` becomes `True`,
+  `invalidated` becomes `True`, and every further call raises
+  `InterfaceError`. The driver never reconnects behind your back, because a
+  silent reconnect would drop transaction state; open a new connection (a
+  pool does this for you).
+- **Bad `connect()` arguments raise `ProgrammingError`**, not `TypeError` /
+  `ValueError`, so configuration mistakes stay inside the `dbapi.Error`
+  hierarchy.
 - **`rowcount` after SELECT is `len(rows)`.** Stdlib returns `-1` for queries.
   dqlite knows the full result at execute time, so it reports the count.
   `rowcount` stays `-1` for non-result paths, for all PRAGMA statements (read

{dqlite_dbapi-0.3.0 → dqlite_dbapi-0.4.0}/docs/transactions.md

@@ -29,23 +29,35 @@ cur.execute("INSERT INTO t VALUES (?)", (2,))
 conn.commit()       # or conn.rollback()
 ```
 
-Under the default session mode (`immediate`) a bare `BEGIN` / `BEGIN
-TRANSACTION` is rewritten to `BEGIN IMMEDIATE`, so the deferred-to-write
-upgrade can't fail later with `SQLITE_BUSY_SNAPSHOT`; an explicit `DEFERRED`
-/ `IMMEDIATE` / `EXCLUSIVE` qualifier is passed through unchanged. dqlite's
-Raft FSM serializes the transaction across the cluster regardless of the
-qualifier, so the qualifier changes only lock-acquisition timing on the
-leader, never isolation.
-
-The session mode is selected with the `session_mode` connect argument (or the
-`DQLITE_SESSION_MODE` environment variable): `immediate` (default; rewrites a
-bare `BEGIN`), `deferred` / `exclusive` (no rewrite), or `read_only` (issues
-`PRAGMA query_only = 1`).
+A bare `BEGIN` / `BEGIN TRANSACTION` is qualified according to the
+connection's session mode; an explicit `DEFERRED` / `IMMEDIATE` /
+`EXCLUSIVE` qualifier is always passed through unchanged. dqlite's Raft FSM
+serializes the transaction across the cluster regardless of the qualifier, so
+the qualifier changes only lock-acquisition timing on the leader, never
+isolation.
+
+| `session_mode` | bare `BEGIN` becomes | notes |
+| --- | --- | --- |
+| `immediate` (default) | `BEGIN IMMEDIATE` | takes the write lock up front, so a read-then-write cannot fail later with `SQLITE_BUSY_SNAPSHOT` |
+| `deferred` | `BEGIN` | SQLite's default deferred transaction |
+| `exclusive` | `BEGIN EXCLUSIVE` | |
+| `read_only` | `BEGIN` | the connection runs with `PRAGMA query_only = 1`; writes raise `OperationalError` |
+
+The mode is selected with the `session_mode` connect argument (or the
+`DQLITE_SESSION_MODE` environment variable), read back through the
+`session_mode` property, and changed at runtime with `set_session_mode()`,
+which may not be called inside a transaction. `default_session_mode` is the
+value given at construction.
 
 The connection also works as a context manager (matching stdlib `sqlite3`):
 the `with conn:` block commits on clean exit and rolls back on exception.
 It does **not** close the connection — the connection stays reusable.
 
+`conn.transaction()` (sync) / `async with conn.transaction():` wraps a block
+in `BEGIN` / `COMMIT` / `ROLLBACK`. Calling `commit()` or `rollback()`
+inside the block raises `InterfaceError`, because the block owns the
+boundaries; use `SAVEPOINT` for nesting.
+
 ## `commit()` / `rollback()` details
 
 - Calling `commit()` / `rollback()` before any query has run is a silent

{dqlite_dbapi-0.3.0 → dqlite_dbapi-0.4.0}/pyproject.toml

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

dqlite_dbapi-0.4.0/src/dqlitedbapi/__init__.py

@@ -0,0 +1,156 @@
+"""PEP 249 (DB-API 2.0) driver for dqlite."""
+
+import logging
+
+from dqliteclient import DEFAULT_CLOSE_TIMEOUT_SECONDS, DEFAULT_TIMEOUT_SECONDS, DialFunc
+from dqlitedbapi._module import (
+    LEGACY_TRANSACTION_CONTROL,
+    PARSE_COLNAMES,
+    PARSE_DECLTYPES,
+    __version__,
+    apilevel,
+    complete_statement,
+    enable_callback_tracebacks,
+    paramstyle,
+    register_converter,
+    sqlite_version,
+    sqlite_version_info,
+    threadsafety,
+)
+from dqlitedbapi.aio.connection import apply_stdlib_connect_kwargs as _apply_stdlib_connect_kwargs
+from dqlitedbapi.connection import Connection
+from dqlitedbapi.cursor import Cursor
+from dqlitedbapi.exceptions import (
+    CLUSTER_POLICY_REJECTION_PREFIX,
+    FAILED_TO_CONNECT_PREFIX,
+    AdapterLookupError,
+    AmbiguousCommitError,
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+from dqlitedbapi.row import Row
+from dqlitedbapi.types import (
+    BINARY,
+    DATETIME,
+    NUMBER,
+    ROWID,
+    STRING,
+    UNKNOWN,
+    Binary,
+    Date,
+    DateFromTicks,
+    DescriptionTuple,
+    PrepareProtocol,
+    Time,
+    TimeFromTicks,
+    Timestamp,
+    TimestampFromTicks,
+    register_adapter,
+    unregister_adapter,
+)
+from dqlitewire import DEFAULT_MAX_CONTINUATION_FRAMES as _DEFAULT_MAX_CONTINUATION_FRAMES
+from dqlitewire import DEFAULT_MAX_TOTAL_ROWS as _DEFAULT_MAX_TOTAL_ROWS
+
+__all__ = [
+    "__version__",
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    "sqlite_version",
+    "sqlite_version_info",
+    "LEGACY_TRANSACTION_CONTROL",
+    "PARSE_DECLTYPES",
+    "PARSE_COLNAMES",
+    "connect",
+    "Connection",
+    "Cursor",
+    "DialFunc",
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "AmbiguousCommitError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+    "AdapterLookupError",
+    "Date",
+    "Time",
+    "Timestamp",
+    "DateFromTicks",
+    "TimeFromTicks",
+    "TimestampFromTicks",
+    "Binary",
+    "STRING",
+    "BINARY",
+    "NUMBER",
+    "DATETIME",
+    "ROWID",
+    "UNKNOWN",
+    "Row",
+    "DescriptionTuple",
+    "PrepareProtocol",
+    "register_adapter",
+    "unregister_adapter",
+    "register_converter",
+    "complete_statement",
+    "enable_callback_tracebacks",
+    "CLUSTER_POLICY_REJECTION_PREFIX",
+    "FAILED_TO_CONNECT_PREFIX",
+]
+
+
+def connect(
+    address: str,
+    *,
+    database: str = "default",
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    max_total_rows: int | None = _DEFAULT_MAX_TOTAL_ROWS,
+    max_continuation_frames: int | None = _DEFAULT_MAX_CONTINUATION_FRAMES,
+    max_message_size: int | None = None,
+    trust_server_heartbeat: bool = False,
+    close_timeout: float = DEFAULT_CLOSE_TIMEOUT_SECONDS,
+    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,
+    **stdlib_kwargs: object,
+) -> Connection:
+    """Create a connection to the cluster reachable through ``address`` (``host:port``).
+
+    The wire session opens on first use; ``timeout`` bounds each RPC phase.
+    """
+    connection = Connection(
+        address,
+        database=database,
+        timeout=timeout,
+        max_total_rows=max_total_rows,
+        max_continuation_frames=max_continuation_frames,
+        max_message_size=max_message_size,
+        trust_server_heartbeat=trust_server_heartbeat,
+        close_timeout=close_timeout,
+        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_stdlib_connect_kwargs(connection._async, stdlib_kwargs)
+    return connection
+
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

dqlite_dbapi-0.4.0/src/dqlitedbapi/_busy.py

@@ -0,0 +1,57 @@
+"""Retry on ``SQLITE_BUSY`` following SQLite's default busy-handler curve.
+
+dqlite rejects ``PRAGMA busy_timeout`` on the wire, so the driver owns the budget.
+"""
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Final
+
+from dqlitedbapi.exceptions import OperationalError
+from dqlitewire import SQLITE_BUSY
+
+logger = logging.getLogger(__name__)
+
+# sqlite3.c ``sqliteDefaultBusyCallback``: sleep before retry i, and cumulative sleep.
+_DELAYS_MS: Final[tuple[int, ...]] = (1, 2, 5, 10, 15, 20, 25, 25, 25, 50, 50, 100)
+_TOTALS_MS: Final[tuple[int, ...]] = (0, 1, 3, 8, 18, 33, 53, 78, 103, 128, 178, 228)
+
+
+def next_delay_ms(attempt: int, budget_ms: int) -> int | None:
+    """Milliseconds to sleep before retry ``attempt + 1``, or ``None`` when the budget is spent."""
+    if budget_ms <= 0:
+        return None
+    if attempt < len(_DELAYS_MS):
+        delay, prior = _DELAYS_MS[attempt], _TOTALS_MS[attempt]
+    else:
+        delay = _DELAYS_MS[-1]
+        prior = _TOTALS_MS[-1] + delay * (attempt - (len(_DELAYS_MS) - 1))
+    if prior + delay > budget_ms:
+        delay = budget_ms - prior
+    return delay if delay > 0 else None
+
+
+def is_busy(exc: BaseException) -> bool:
+    return isinstance(exc, OperationalError) and exc.code == SQLITE_BUSY
+
+
+async def retry_on_busy[T](busy_timeout: float, attempt: Callable[[], Awaitable[T]]) -> T:
+    """Run ``attempt()`` until it succeeds, fails with a non-BUSY error, or the budget is spent."""
+    budget_ms = round(busy_timeout * 1000)
+    count = 0
+    while True:
+        try:
+            return await attempt()
+        except OperationalError as exc:
+            if not is_busy(exc):
+                raise
+            delay = next_delay_ms(count, budget_ms)
+            if delay is None:
+                if budget_ms > 0:
+                    logger.warning(
+                        "busy_timeout budget %.3fs exhausted after %d retries", busy_timeout, count
+                    )
+                raise
+            await asyncio.sleep(delay / 1000)
+            count += 1

dqlite_dbapi-0.4.0/src/dqlitedbapi/_loop.py

@@ -0,0 +1,105 @@
+"""Background event-loop thread used by the sync surface."""
+
+import asyncio
+import concurrent.futures
+import contextlib
+import threading
+from collections.abc import Coroutine
+from typing import Any
+
+from dqlitedbapi.exceptions import InterfaceError
+
+
+class LoopThread:
+    """A daemon thread running an asyncio loop; coroutines are submitted and awaited from
+    other threads. Started on first use, stopped by :meth:`shutdown`."""
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._inflight: set[concurrent.futures.Future[Any]] = set()
+        self._guard = threading.Lock()
+
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop | None:
+        return self._loop
+
+    def run[T](self, coro: Coroutine[Any, Any, T]) -> T:
+        """Run ``coro`` on the loop thread and block for its result.
+
+        A ``KeyboardInterrupt`` or ``SystemExit`` while blocked cancels the coroutine before
+        propagating. A cancellation triggered by :meth:`shutdown` surfaces as
+        ``concurrent.futures.CancelledError``.
+        """
+        try:
+            loop = self._ensure_running()
+        except BaseException:
+            coro.close()
+            raise
+        future = asyncio.run_coroutine_threadsafe(coro, loop)
+        with self._guard:
+            self._inflight.add(future)
+        try:
+            return future.result()
+        except BaseException:
+            future.cancel()
+            raise
+        finally:
+            with self._guard:
+                self._inflight.discard(future)
+
+    def shutdown(self, timeout: float) -> None:
+        """Cancel in-flight work, stop the loop and join the thread. Idempotent, never raises."""
+        with self._guard:
+            loop, thread = self._loop, self._thread
+            self._thread = None
+        if loop is None:
+            return
+        if thread is not None and thread.is_alive():
+            stopper = _cancel_all_and_stop(loop, timeout)
+            try:
+                asyncio.run_coroutine_threadsafe(stopper, loop)
+            except RuntimeError:
+                stopper.close()
+            thread.join(timeout + 1.0)
+        with self._guard:
+            inflight = list(self._inflight)
+        for future in inflight:
+            with contextlib.suppress(concurrent.futures.InvalidStateError):
+                future.set_exception(
+                    InterfaceError("Connection closed while an operation was in flight")
+                )
+        if not loop.is_running():
+            with contextlib.suppress(Exception):
+                loop.close()
+
+    def _ensure_running(self) -> asyncio.AbstractEventLoop:
+        with self._guard:
+            if self._thread is not None and self._thread.is_alive() and self._loop is not None:
+                return self._loop
+            if self._loop is not None and self._loop.is_closed():
+                raise InterfaceError("Connection is closed (event loop thread stopped)")
+            loop = asyncio.new_event_loop()
+            started = threading.Event()
+
+            def main() -> None:
+                asyncio.set_event_loop(loop)
+                loop.call_soon(started.set)
+                loop.run_forever()
+
+            thread = threading.Thread(target=main, name=self._name, daemon=True)
+            thread.start()
+            started.wait()
+            self._loop, self._thread = loop, thread
+            return loop
+
+
+async def _cancel_all_and_stop(loop: asyncio.AbstractEventLoop, timeout: float) -> None:
+    me = asyncio.current_task()
+    tasks = [t for t in asyncio.all_tasks(loop) if t is not me]
+    for task in tasks:
+        task.cancel()
+    if tasks:
+        await asyncio.wait(tasks, timeout=timeout)
+    loop.stop()

dqlite_dbapi-0.4.0/src/dqlitedbapi/_module.py

@@ -0,0 +1,35 @@
+"""Module-level PEP 249 attributes shared by ``dqlitedbapi`` and ``dqlitedbapi.aio``."""
+
+from typing import Final, Literal, NoReturn
+
+from dqlitedbapi.exceptions import NotSupportedError
+
+__version__: Final[str] = "0.4.0"
+
+apilevel: Final[Literal["2.0"]] = "2.0"
+threadsafety: Final[Literal[2]] = 2
+paramstyle: Final[Literal["qmark"]] = "qmark"
+
+# The SQLite feature floor every supported dqlite server provides (RETURNING needs 3.35).
+sqlite_version_info: Final[tuple[int, int, int]] = (3, 35, 0)
+sqlite_version: Final[str] = "3.35.0"
+
+# stdlib sqlite3 parity constants; ``PARSE_*`` are accepted nowhere and enable nothing.
+LEGACY_TRANSACTION_CONTROL: Final[int] = -1
+PARSE_DECLTYPES: Final[int] = 1
+PARSE_COLNAMES: Final[int] = 2
+
+
+def register_converter(*args: object, **kwargs: object) -> NoReturn:
+    raise NotSupportedError(
+        "register_converter is not supported: the wire carries no declared column types; "
+        "use row_factory to post-process rows"
+    )
+
+
+def complete_statement(*args: object, **kwargs: object) -> NoReturn:
+    raise NotSupportedError("complete_statement is not supported")
+
+
+def enable_callback_tracebacks(*args: object, **kwargs: object) -> NoReturn:
+    raise NotSupportedError("enable_callback_tracebacks is not supported: there are no callbacks")