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

{dqlite_dbapi-0.2.2 → 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/
 ```
 
@@ -57,6 +57,31 @@ cd ../dqlite-test-cluster && docker compose up -d
 .venv/bin/mypy src
 ```
 
+## Comments and docstrings
+
+Keep comments and docstrings to a minimum — the code should be clear
+enough to stand on its own. Prefer renaming a function or variable over
+writing a comment to explain an unclear one.
+
+- Write a comment only when it captures something genuinely non-obvious
+  that the code cannot: a subtle invariant, a security caveat, a
+  workaround for an upstream bug, or a "why" a reader would otherwise
+  get wrong. Delete comments that merely restate what the code does.
+- Most functions need no docstring. Add a one-line docstring only when
+  it tells a reader something the name and signature do not. Avoid
+  multi-paragraph essays, param-by-param prose, and "Notes/Divergence"
+  sections.
+- Do not record rationale, history, or decision logs in comments — that
+  context belongs in the commit message and git history (`git blame`,
+  `git log -p`), where it stays attached to the change instead of aging
+  in the source.
+- Tooling directives (`# type:`, `# noqa`, `# pragma:`) are exempt —
+  keep them.
+
+When in doubt, leave it out: a missing explanation is a `git blame`
+away; a redundant or stale comment is noise every future reader pays
+for.
+
 ## Pre-commit Workflow
 
 ```bash
@@ -71,5 +96,5 @@ cd ../dqlite-test-cluster && docker compose up -d
 This package implements the DB-API 2.0 specification (PEP 249):
 
 - `apilevel = "2.0"`
-- `threadsafety = 1` (threads may share module, not connections)
+- `threadsafety = 2` (threads may share module and connections, not cursors)
 - `paramstyle = "qmark"` (question mark placeholders)

dqlite_dbapi-0.4.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: dqlite-dbapi
+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
+Project-URL: Issues, https://github.com/letsdiscodev/python-dqlite-dbapi/issues
+Author-email: Antoine Leclair <antoineleclair@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: database,dbapi,distributed,dqlite,pep249,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+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'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dqlite-dbapi
+
+A [PEP 249](https://peps.python.org/pep-0249/) (DB-API 2.0) driver for
+[dqlite](https://dqlite.io/), Canonical's distributed SQLite. If you have
+used Python's standard `sqlite3` module, this will feel familiar — same
+`connect()` / `cursor()` / `execute()` / `fetchone()` shape — but it talks
+to a replicated dqlite cluster over the network instead of a local file.
+
+It comes in two flavors from one package: a **synchronous** API
+(`dqlitedbapi`) and an **async** API (`dqlitedbapi.aio`).
+
+## Is this the package you want?
+
+Yes, if you want a drop-in-style database driver for dqlite — directly,
+or under a tool that expects a DB-API 2.0 driver. For SQLAlchemy
+specifically, use [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite)
+(it builds on this package).
+
+## Installation
+
+```bash
+pip install dqlite-dbapi
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+### Sync
+
+```python
+import dqlitedbapi
+
+conn = dqlitedbapi.connect("localhost:9001")
+cur = conn.cursor()
+cur.execute("SELECT 1")
+print(cur.fetchone())
+conn.close()
+```
+
+### Async
+
+```python
+import asyncio
+from dqlitedbapi.aio import aconnect
+
+async def main():
+    conn = await aconnect("localhost:9001")
+    cur = conn.cursor()
+    await cur.execute("SELECT 1")
+    print(await cur.fetchone())
+    await conn.close()
+
+asyncio.run(main())
+```
+
+## Key facts
+
+- `apilevel = "2.0"`, `paramstyle = "qmark"` (`?` placeholders),
+  `threadsafety = 2`.
+- **Autocommit by default.** Unlike stdlib `sqlite3`, the driver does not
+  auto-`BEGIN` before a statement — wrap writes in an explicit transaction
+  when you need atomic multi-statement semantics. See
+  [Transactions](docs/transactions.md).
+- **Isolation is always SERIALIZABLE** — every write goes through Raft
+  consensus, every read is serializable.
+
+## The dqlite Python stack
+
+This is one of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite) | SQLAlchemy 2.0 dialect |
+| **dqlite-dbapi** — this package | PEP 249 (DB-API 2.0) driver — sync & async |
+| [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) | Async wire client — pooling, leader discovery |
+| [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire) | Wire-protocol codec |
+
+Using SQLAlchemy or an ORM? Prefer
+[sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).
+
+## Documentation
+
+- [Transactions](docs/transactions.md) — the autocommit-by-default model and how to group statements.
+- [Differences from `sqlite3`](docs/differences-from-sqlite3.md) — what to
+  expect when porting from the stdlib module (and a server-version NULL
+  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
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

dqlite_dbapi-0.4.0/README.md

@@ -0,0 +1,99 @@
+# dqlite-dbapi
+
+A [PEP 249](https://peps.python.org/pep-0249/) (DB-API 2.0) driver for
+[dqlite](https://dqlite.io/), Canonical's distributed SQLite. If you have
+used Python's standard `sqlite3` module, this will feel familiar — same
+`connect()` / `cursor()` / `execute()` / `fetchone()` shape — but it talks
+to a replicated dqlite cluster over the network instead of a local file.
+
+It comes in two flavors from one package: a **synchronous** API
+(`dqlitedbapi`) and an **async** API (`dqlitedbapi.aio`).
+
+## Is this the package you want?
+
+Yes, if you want a drop-in-style database driver for dqlite — directly,
+or under a tool that expects a DB-API 2.0 driver. For SQLAlchemy
+specifically, use [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite)
+(it builds on this package).
+
+## Installation
+
+```bash
+pip install dqlite-dbapi
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+### Sync
+
+```python
+import dqlitedbapi
+
+conn = dqlitedbapi.connect("localhost:9001")
+cur = conn.cursor()
+cur.execute("SELECT 1")
+print(cur.fetchone())
+conn.close()
+```
+
+### Async
+
+```python
+import asyncio
+from dqlitedbapi.aio import aconnect
+
+async def main():
+    conn = await aconnect("localhost:9001")
+    cur = conn.cursor()
+    await cur.execute("SELECT 1")
+    print(await cur.fetchone())
+    await conn.close()
+
+asyncio.run(main())
+```
+
+## Key facts
+
+- `apilevel = "2.0"`, `paramstyle = "qmark"` (`?` placeholders),
+  `threadsafety = 2`.
+- **Autocommit by default.** Unlike stdlib `sqlite3`, the driver does not
+  auto-`BEGIN` before a statement — wrap writes in an explicit transaction
+  when you need atomic multi-statement semantics. See
+  [Transactions](docs/transactions.md).
+- **Isolation is always SERIALIZABLE** — every write goes through Raft
+  consensus, every read is serializable.
+
+## The dqlite Python stack
+
+This is one of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite) | SQLAlchemy 2.0 dialect |
+| **dqlite-dbapi** — this package | PEP 249 (DB-API 2.0) driver — sync & async |
+| [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) | Async wire client — pooling, leader discovery |
+| [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire) | Wire-protocol codec |
+
+Using SQLAlchemy or an ORM? Prefer
+[sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).
+
+## Documentation
+
+- [Transactions](docs/transactions.md) — the autocommit-by-default model and how to group statements.
+- [Differences from `sqlite3`](docs/differences-from-sqlite3.md) — what to
+  expect when porting from the stdlib module (and a server-version NULL
+  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
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

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.4.0/docs/differences-from-aiosqlite.md

@@ -0,0 +1,42 @@
+# Differences from `aiosqlite`
+
+The async surface lives under `dqlitedbapi.aio` and mirrors the sync
+`dqlitedbapi` surface, plus async-specific `aconnect` / `AsyncConnection` /
+`AsyncCursor`.
+
+For easy porting from [aiosqlite](https://github.com/omnilib/aiosqlite), the
+full PEP 249 module surface is re-exported under `dqlitedbapi.aio` from one
+namespace: the module attributes (`apilevel`, `threadsafety`, `paramstyle`,
+`sqlite_version`, `sqlite_version_info`), the exception hierarchy (`Warning`,
+`Error`, `InterfaceError`, `DatabaseError`, `DataError`, `OperationalError`,
+`IntegrityError`, `InternalError`, `ProgrammingError`, `NotSupportedError`),
+the type constructors (`Date`, `Time`, `Timestamp`, `DateFromTicks`,
+`TimeFromTicks`, `TimestampFromTicks`, `Binary`), the type sentinels
+(`STRING`, `BINARY`, `NUMBER`, `DATETIME`, `ROWID`, `UNKNOWN`), the `Row`
+factory and `DescriptionTuple`, `register_adapter` / `unregister_adapter`, and
+the `NotSupportedError` stubs for stdlib-only APIs.
+
+## The one difference to watch
+
+**`AsyncConnection.__aexit__` does not close the connection.** It commits or
+rolls back per the block outcome and leaves the connection reusable — matching
+stdlib `sqlite3.Connection.__exit__` and PEP 249 §7. `aiosqlite`'s
+`__aexit__` *does* close (it tears down its proxy thread and sqlite3
+connection).
+
+So when porting from aiosqlite, add an explicit `await conn.close()` (or use a
+pool) where you relied on close-on-exit:
+
+```python
+# aiosqlite — closes on aexit:
+async with aiosqlite.connect(":memory:") as conn:
+    ...
+
+# dqlitedbapi.aio — does NOT close on aexit (matches stdlib sqlite3):
+async with await dqlitedbapi.aio.aconnect(...) as conn:
+    ...
+    await conn.close()   # explicit
+```
+
+Everything else under [Differences from `sqlite3`](differences-from-sqlite3.md)
+applies to the async surface too.

dqlite_dbapi-0.4.0/docs/differences-from-sqlite3.md

@@ -0,0 +1,108 @@
+# Differences from `sqlite3`
+
+`dqlite-dbapi` is shaped like the stdlib `sqlite3` module, but it talks to a
+replicated cluster over the network rather than a local file. This page
+covers the differences you are most likely to notice when porting code.
+
+## Things you'll likely notice
+
+- **Autocommit by default.** No implicit `BEGIN` before DML — the opposite
+  of stdlib's implicit-transaction model. See
+  [Transactions](transactions.md).
+- **One statement per `execute()`.** `cursor.execute("SELECT 1; SELECT 2;")`
+  raises `ProgrammingError` (client-side, before any network round-trip).
+  Split into separate calls. There is no `executescript()` — it raises
+  `NotSupportedError`.
+- **`qmark` parameters only.** Use `?` placeholders. Stdlib also accepts
+  `:name`; this driver advertises only `qmark` and rejects mappings with
+  `ProgrammingError`.
+- **Foreign keys are enforced by default.** dqlite defaults every fresh
+  connection to `PRAGMA foreign_keys = ON` — the opposite of stdlib/pysqlite,
+  which default `OFF`. Issue `PRAGMA foreign_keys = OFF` per connection for
+  SQLite's legacy unenforced behavior.
+- **SERIALIZABLE isolation only.** Every statement is ordered by Raft;
+  weaker isolation levels are not exposed.
+- **`connect()` timeouts differ from stdlib.** stdlib's `timeout` is the
+  busy (lock-wait) budget; here `timeout` is a per-RPC-phase deadline and
+  the busy budget is the separate `busy_timeout` argument. `connect()` also
+  exposes safety caps — `max_message_size`, `max_continuation_frames`,
+  `max_total_rows` — and `trust_server_heartbeat`.
+- **Result sets are fully materialized at `execute()` time.** Stdlib streams
+  rows lazily from the C engine; dqlite drains every continuation frame into
+  the cursor's in-memory buffer before `execute()` returns, and `fetchone()`
+  / `fetchmany()` / `fetchall()` iterate that buffer. For large queries, cap
+  memory with `max_total_rows` (forwarded from `connect()`) or shape queries
+  with an explicit `LIMIT`.
+- **No SQLite extension APIs.** `create_function`, `create_aggregate`,
+  `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
+  or write — matching stdlib), and for a never-executed cursor.
+
+## NULL in BOOLEAN/DATETIME columns depends on the server version
+
+A 2026 dqlite server change (upstream commit `f30fc99`) changed how a NULL
+cell is encoded in columns declared `BOOLEAN`, `DATE`, `DATETIME`, or
+`TIMESTAMP`:
+
+- **Before**: a NULL came back as `False` (for `BOOLEAN`) or `""` (for
+  datetime types) — indistinguishable from a real value.
+- **After**: a NULL comes back as `None`.
+
+There is no handshake that distinguishes the two server versions, and the
+driver decodes faithfully whatever the server sends. Code like
+`if row[0] is None:` will silently miss rows on an old cluster and start
+matching after an upgrade. Check your dqlite cluster version before relying
+on `is None` for these columns.
+
+## Minor / edge-case differences
+
+You can usually ignore these, but they are here so nothing surprises you:
+
+- **`lastrowid` is `None` (not `0`) before the first INSERT.** After the
+  first INSERT both drivers agree and keep the value sticky across
+  UPDATE/DELETE/DDL.
+- **`fetchmany(0)` returns `[]`** (PEP 249 read literally). Pass `None` or
+  omit the argument to default to `arraysize`. `fetchmany(negative)` raises
+  `ProgrammingError`.
+- **`execute("")` raises `ProgrammingError`** (empty/whitespace/comment-only
+  SQL). Stdlib treats it as a no-op.
+- **Empty result sets report the `UNKNOWN` type code** in
+  `description[i][1]` (importable from `dqlitedbapi`). Test it with
+  `type_code == UNKNOWN`; for column types on an empty result, query
+  `PRAGMA table_info(...)`.
+- **CTE-prefixed DML** (`WITH ... INSERT/UPDATE/DELETE`) sets `lastrowid` and
+  reports `rowcount` as the affected-row count. That `rowcount` is a dqlite
+  extra: stdlib sqlite3 returns `-1` for CTE-prefixed DML (it counts only
+  non-CTE DML). `WITH ... SELECT` and `WITH ... RETURNING` return rows as usual.
+
+### Type-code sentinels: compare with `==`, not `in {}`
+
+The PEP 249 type sentinels (`STRING`, `BINARY`, `NUMBER`, `DATETIME`,
+`ROWID`) match a `description` type code through `__eq__`, and each wraps
+several wire types (`NUMBER` covers INTEGER+FLOAT+BOOLEAN; `DATETIME` covers
+DATE+TIMESTAMP+ISO8601). A bare wire-int type code does not *hash* equal to a
+sentinel, so set/dict membership silently returns `False`:
+
+```python
+type_code = cur.description[i][1]
+if type_code == STRING or type_code == NUMBER:   # correct
+    ...
+if type_code in {STRING, NUMBER}:                # WRONG: silently False
+    ...
+```
+
+Stdlib `sqlite3` doesn't export these sentinels at all, so the
+chained-equality form is also the cross-driver-portable idiom.