sqlalchemy-dqlite 0.1.2__tar.gz → 0.2.0__tar.gz

sqlalchemy_dqlite-0.2.0/DEVELOPMENT.md

@@ -0,0 +1,199 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
+- Docker (for integration tests)
+
+## Setup
+
+Clone [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire), [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client), and [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi) alongside this checkout; `[tool.uv.sources]` in `pyproject.toml` points the sibling packages at their `../python-dqlite-*` directories, so `uv sync` picks up in-tree changes automatically.
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv sync --extra dev
+```
+
+## Development Tools
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| **pytest** | Testing framework | `pytest` |
+| **ruff** | Linter (replaces flake8, isort, etc.) | `ruff check` |
+| **ruff format** | Code formatter (replaces black) | `ruff format` |
+| **mypy** | Static type checker | `mypy src` |
+
+## Running Tests
+
+```bash
+# 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
+.venv/bin/pytest tests/
+```
+
+The default pytest run **skips** `tests/compliance/` (the SQLAlchemy
+dialect compliance suite). See "SQLAlchemy compliance suite" below
+for the why and how to run it.
+
+## SQLAlchemy compliance suite
+
+The SQLAlchemy project ships an in-tree, dialect-agnostic test suite
+at `sqlalchemy.testing.suite`. Third-party dialects engage it by
+providing a `Requirements` class (declares which features are
+supported), a `provision.py` module (handles per-test database
+lifecycle), and a `tests/test_suite.py` that imports the suite. SA's
+pytest plugin then runs every suite test against the dialect, gated
+by `Requirements.<feature>.enabled`.
+
+This package wires the suite under `tests/compliance/`. Running it:
+
+```bash
+# Start the cluster (any reachable dqlite cluster works; the suite
+# defaults to localhost:9001 via setup.cfg's [db] section).
+.venv/bin/pytest tests/compliance/
+```
+
+### Why the default pytest run skips it
+
+`tests/compliance/conftest.py` loads `sqlalchemy.testing.plugin.pytestplugin`,
+which **replaces pytest's default test-collection model** — it filters
+discovery to `sqlalchemy.testing.fixtures.TestBase` subclasses only.
+If we let it load globally for `pytest tests/`, the project's existing
+unit and integration tests under `tests/test_*.py` would silently
+disappear from the run.
+
+The plugin also requires CLI options (`--dburi`, etc.) the project's
+runners do not pass; without them it errors at session start.
+
+To keep the two test corpora cleanly separated, `pyproject.toml`'s
+pytest config has `addopts=["--ignore=tests/compliance"]`. Run the
+suite explicitly with `pytest tests/compliance/`.
+
+### Why ~700 suite tests are skipped (and that's correct)
+
+Each compliance run reports a large `skipped` count (currently
+~689). Every skip is gated by a `Requirements.<feature>` declaration
+in `src/sqlalchemydqlite/requirements.py` that says "dqlite doesn't
+support this." The skipped tests are testing capabilities the
+underlying database genuinely lacks — running them would fail with
+`syntax error` / `unknown database` / `no such function`, not with
+real bugs.
+
+Examples of features dqlite doesn't have (each declared
+`exclusions.closed()`):
+
+- ATTACH-DATABASE schemas (`schemas`)
+- Two-phase commit (`two_phase_transactions`)
+- `CREATE SEQUENCE` (`sequences` — SQLite has no native sequences;
+  this one is gated by the dialect-level `supports_sequences = False`
+  flag inherited from the SQLite dialect rather than an explicit
+  `closed()` in `requirements.py`)
+- Parenthesised SELECTs in UNION (`parens_in_union_*`)
+- Cross-schema FK reflection (`cross_schema_fk_reflection`)
+
+A future dqlite version that adds the feature flips the requirement
+to `exclusions.open()`, and the suite tests for that feature start
+running.
+
+### Adjusting Requirements
+
+When the suite surfaces a real bug, fix the dialect. When the suite
+runs a test for a capability dqlite genuinely doesn't have, add or
+adjust a `Requirements.<name>` property in `requirements.py` with a
+docstring explaining why. The matching property in SA's
+`SuiteRequirements` has a docstring describing what the feature is
+— mirror that in the override.
+
+### Per-session unique database names
+
+dqlite has no `DROP DATABASE` primitive. The cluster persists every
+database name ever opened, across pytest sessions and across the
+project's other integration tests. To prevent cross-run schema
+bleed in reflection tests that enumerate "all tables in the schema",
+`src/sqlalchemydqlite/provision.py` generates a per-session token
+(`sa_<pid>_<monotonic-ns>`) and suffixes every test database name
+with it. Each pytest run gets a fresh, empty database namespace on
+the cluster.
+
+## Linting & Formatting
+
+```bash
+# Lint
+.venv/bin/ruff check src tests
+
+# Auto-fix lint issues
+.venv/bin/ruff check --fix src tests
+
+# Format
+.venv/bin/ruff format src tests
+```
+
+## Type Checking
+
+```bash
+.venv/bin/mypy src
+```
+
+## Pre-commit Workflow
+
+```bash
+.venv/bin/ruff format src tests
+.venv/bin/ruff check --fix src tests
+.venv/bin/mypy src
+.venv/bin/pytest tests/ --ignore=tests/integration
+```
+
+## Commit message hygiene
+
+Commit messages must not contain workflow vocabulary
+("Round N" / "Cycle N" / "Phase N" / "Bundle X" / "ultrathink"),
+`ISSUE-<token>` identifiers, or `done/*.md` filename references.
+The durable referent for cross-commit citations is the commit hash;
+the workflow token is ornamental and leaks the development process
+into the published history.
+
+`scripts/check-commit-msg.sh` enforces the rule. Install it as a
+local `commit-msg` hook:
+
+```bash
+ln -s ../../scripts/check-commit-msg.sh .git/hooks/commit-msg
+```
+
+Or lint a range manually:
+
+```bash
+scripts/check-commit-msg.sh --range origin/main..HEAD
+```
+
+The same script ships in `python-dqlite-wire/scripts/` so the
+workspace shares a single rule across packages. Published commits
+that already contain the pattern (e.g. `33d1d96`'s "Round 7"
+opener) are left intact — amending would rewrite SHAs sibling
+packages reference; the script is forward-looking only.
+
+## SQLAlchemy URL Format
+
+```
+# Sync
+dqlite://host:port/database
+
+# Async
+dqlite+aio://host:port/database
+```
+
+## Dialect Registration
+
+The dialects are registered via entry points in `pyproject.toml`:
+
+```toml
+[project.entry-points."sqlalchemy.dialects"]
+dqlite = "sqlalchemydqlite:DqliteDialect"
+"dqlite.aio" = "sqlalchemydqlite.aio:DqliteDialect_aio"
+```

sqlalchemy_dqlite-0.2.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-dqlite
+Version: 0.2.0
+Summary: SQLAlchemy 2.0 dialect for dqlite distributed SQLite
+Project-URL: Homepage, https://github.com/letsdiscodev/sqlalchemy-dqlite
+Project-URL: Repository, https://github.com/letsdiscodev/sqlalchemy-dqlite
+Project-URL: Issues, https://github.com/letsdiscodev/sqlalchemy-dqlite/issues
+Author-email: Antoine Leclair <antoineleclair@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: database,distributed,dqlite,orm,sqlalchemy,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.3.0,>=0.2.0
+Requires-Dist: dqlite-dbapi<0.3.0,>=0.2.0
+Requires-Dist: dqlite-wire<0.3.0,>=0.2.0
+Requires-Dist: sqlalchemy<3.0,>=2.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
+
+# sqlalchemy-dqlite
+
+SQLAlchemy 2.0 dialect for [dqlite](https://dqlite.io/).
+
+## Installation
+
+```bash
+pip install sqlalchemy-dqlite
+```
+
+## Usage
+
+```python
+from sqlalchemy import create_engine, text
+
+# Sync
+engine = create_engine("dqlite://localhost:9001/mydb")
+with engine.connect() as conn:
+    result = conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+
+# Async
+from sqlalchemy.ext.asyncio import create_async_engine
+
+async_engine = create_async_engine("dqlite+aio://localhost:9001/mydb")
+async with async_engine.connect() as conn:
+    result = await conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+```
+
+## Transactions
+
+SQLAlchemy owns the `BEGIN`/`COMMIT`/`ROLLBACK` for any block opened via
+`engine.begin()`, `connection.begin()`, or `session.begin()`. Do not
+issue raw `BEGIN` yourself.
+
+```python
+from sqlalchemy import create_engine, text
+
+engine = create_engine("dqlite://localhost:9001/mydb")
+
+# OK — SA emits BEGIN / COMMIT for you
+with engine.begin() as conn:
+    conn.execute(text("INSERT INTO t VALUES (1)"))
+
+# WRONG — second BEGIN inside an SA-managed transaction errors with
+#   OperationalError: cannot start a transaction within a transaction
+with engine.begin() as conn:
+    conn.execute(text("BEGIN"))                  # error
+    conn.execute(text("INSERT INTO t VALUES (1)"))
+```
+
+The same rule applies to `engine.connect()`: SA auto-begins a
+transaction on the first execute, so a user-issued `text("BEGIN")`
+collides the same way. This matches every other SA backend (pysqlite,
+postgres, mysql); SA's transaction model is universal.
+
+`isolation_level="AUTOCOMMIT"` is rejected — every dqlite statement
+goes through Raft consensus and there is no per-statement autocommit
+mode. Use `engine.begin()` (or `connection.begin()`) for writes.
+
+See SQLAlchemy's [transaction
+docs](https://docs.sqlalchemy.org/en/20/core/connections.html#using-transactions)
+for the full model.
+
+## Savepoint naming
+
+The dqlite client tracks active SAVEPOINTs to keep the SQLAlchemy
+pool's ROLLBACK-on-checkin path correct. The tracker only handles
+bare-ASCII SQLite identifiers (e.g. `sa_savepoint_1`, `my_sp`) —
+SQLAlchemy's generated savepoint names always match this shape, so
+`engine.begin()` / `Session.begin_nested()` / `connection.begin_nested()`
+are unaffected.
+
+If user-issued raw SQL uses quoted, backticked, square-bracketed,
+unicode, or leading-digit savepoint names (e.g.
+`text('SAVEPOINT "weird name"')`), the client conservatively flags
+the connection as carrying an untracked savepoint. On the next pool
+checkin SQLAlchemy issues a safety `ROLLBACK`, paying one extra
+round-trip per checkout for the remainder of that connection's
+lifetime in the pool. Stick to bare-ASCII SAVEPOINT names in raw
+text SQL to avoid the overhead, or accept the per-checkout cost.
+
+## URL Format
+
+```
+dqlite://host:port/database
+dqlite+aio://host:port/database
+```
+
+When a query parameter is repeated
+(`?max_total_rows=100&max_total_rows=200`), the **last** occurrence
+wins. This matches `urllib.parse.parse_qsl` ordering. Templated
+connection URLs that layer values from multiple sources should be
+aware that duplicated keys silently override earlier values rather
+than raising.
+
+The URL host:port pair is the bootstrap address — the dqlite client
+discovers the rest of the cluster from that one node's leader-info
+response. If the URL host is unreachable, leader-discovery cannot
+start; operators that want bootstrap-from-many-addresses should put
+a load balancer or DNS round-robin in front of the cluster, or rotate
+the URL host across deployments. Multi-address bootstrap is not
+exposed at the dialect URL surface.
+
+## STRICT-table DDL is unavailable through SA's compiler
+
+SA's SQLite dialect gates STRICT-table compilation on
+`server_version_info >= (3, 37)` (`sqlalchemy/dialects/sqlite/base.py`).
+The dqlite dbapi pins `sqlite_version_info = (3, 35, 0)` as the
+documented floor (see
+`python-dqlite-dbapi/src/dqlitedbapi/_constants.py`) to avoid silently
+rejecting connections to older-server clusters that ship SQLite below
+the floor. As a consequence, SA's compiler will NOT emit
+`CREATE TABLE ... STRICT` DDL through this dialect, even when the
+cluster ships SQLite 3.37 or newer.
+
+If your cluster supports STRICT tables and you want STRICT semantics,
+emit the DDL via raw SQL (`engine.execute(text("CREATE TABLE ...
+STRICT"))`) rather than SA's `Table` / `Column` model.
+
+## Cross-version semantic shift: NULL in BOOLEAN/DATETIME columns
+
+Upstream dqlite commit `f30fc99` (`query: preserve SQLITE_NULL type
+for NULL values`, 2026-01-25) changed the wire encoding of NULL cells
+in columns declared `BOOLEAN`, `DATE`, `DATETIME`, or `TIMESTAMP`.
+Before that commit, a NULL in a `BOOLEAN` column was emitted as
+`BOOLEAN(0)` (decodes to `False`) and a NULL in a `DATETIME` column
+was emitted as `ISO8601("")` — indistinguishable on the wire from
+real `FALSE` / empty-string values. After the commit, NULL is emitted
+with the SQLite NULL type and decodes to `None`.
+
+ORM models with `Boolean()` and `DateTime()` columns will start
+returning `None` for previously-`False` / `""` values after a server
+upgrade. SQLAlchemy `nullable=False` constraints will start tripping
+on rows that previously decoded to non-NULL. There is no driver-level
+handshake distinguishing the two server versions — check your dqlite
+cluster version before relying on the post-fix semantics.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup, contribution guidelines,
+and the SQLAlchemy compliance test-suite documentation (how to run it
+locally, why it's not part of the default `pytest` invocation, and
+why ~700 of its tests are correctly skipped).
+
+## License
+
+MIT

sqlalchemy_dqlite-0.2.0/README.md

@@ -0,0 +1,149 @@
+# sqlalchemy-dqlite
+
+SQLAlchemy 2.0 dialect for [dqlite](https://dqlite.io/).
+
+## Installation
+
+```bash
+pip install sqlalchemy-dqlite
+```
+
+## Usage
+
+```python
+from sqlalchemy import create_engine, text
+
+# Sync
+engine = create_engine("dqlite://localhost:9001/mydb")
+with engine.connect() as conn:
+    result = conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+
+# Async
+from sqlalchemy.ext.asyncio import create_async_engine
+
+async_engine = create_async_engine("dqlite+aio://localhost:9001/mydb")
+async with async_engine.connect() as conn:
+    result = await conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+```
+
+## Transactions
+
+SQLAlchemy owns the `BEGIN`/`COMMIT`/`ROLLBACK` for any block opened via
+`engine.begin()`, `connection.begin()`, or `session.begin()`. Do not
+issue raw `BEGIN` yourself.
+
+```python
+from sqlalchemy import create_engine, text
+
+engine = create_engine("dqlite://localhost:9001/mydb")
+
+# OK — SA emits BEGIN / COMMIT for you
+with engine.begin() as conn:
+    conn.execute(text("INSERT INTO t VALUES (1)"))
+
+# WRONG — second BEGIN inside an SA-managed transaction errors with
+#   OperationalError: cannot start a transaction within a transaction
+with engine.begin() as conn:
+    conn.execute(text("BEGIN"))                  # error
+    conn.execute(text("INSERT INTO t VALUES (1)"))
+```
+
+The same rule applies to `engine.connect()`: SA auto-begins a
+transaction on the first execute, so a user-issued `text("BEGIN")`
+collides the same way. This matches every other SA backend (pysqlite,
+postgres, mysql); SA's transaction model is universal.
+
+`isolation_level="AUTOCOMMIT"` is rejected — every dqlite statement
+goes through Raft consensus and there is no per-statement autocommit
+mode. Use `engine.begin()` (or `connection.begin()`) for writes.
+
+See SQLAlchemy's [transaction
+docs](https://docs.sqlalchemy.org/en/20/core/connections.html#using-transactions)
+for the full model.
+
+## Savepoint naming
+
+The dqlite client tracks active SAVEPOINTs to keep the SQLAlchemy
+pool's ROLLBACK-on-checkin path correct. The tracker only handles
+bare-ASCII SQLite identifiers (e.g. `sa_savepoint_1`, `my_sp`) —
+SQLAlchemy's generated savepoint names always match this shape, so
+`engine.begin()` / `Session.begin_nested()` / `connection.begin_nested()`
+are unaffected.
+
+If user-issued raw SQL uses quoted, backticked, square-bracketed,
+unicode, or leading-digit savepoint names (e.g.
+`text('SAVEPOINT "weird name"')`), the client conservatively flags
+the connection as carrying an untracked savepoint. On the next pool
+checkin SQLAlchemy issues a safety `ROLLBACK`, paying one extra
+round-trip per checkout for the remainder of that connection's
+lifetime in the pool. Stick to bare-ASCII SAVEPOINT names in raw
+text SQL to avoid the overhead, or accept the per-checkout cost.
+
+## URL Format
+
+```
+dqlite://host:port/database
+dqlite+aio://host:port/database
+```
+
+When a query parameter is repeated
+(`?max_total_rows=100&max_total_rows=200`), the **last** occurrence
+wins. This matches `urllib.parse.parse_qsl` ordering. Templated
+connection URLs that layer values from multiple sources should be
+aware that duplicated keys silently override earlier values rather
+than raising.
+
+The URL host:port pair is the bootstrap address — the dqlite client
+discovers the rest of the cluster from that one node's leader-info
+response. If the URL host is unreachable, leader-discovery cannot
+start; operators that want bootstrap-from-many-addresses should put
+a load balancer or DNS round-robin in front of the cluster, or rotate
+the URL host across deployments. Multi-address bootstrap is not
+exposed at the dialect URL surface.
+
+## STRICT-table DDL is unavailable through SA's compiler
+
+SA's SQLite dialect gates STRICT-table compilation on
+`server_version_info >= (3, 37)` (`sqlalchemy/dialects/sqlite/base.py`).
+The dqlite dbapi pins `sqlite_version_info = (3, 35, 0)` as the
+documented floor (see
+`python-dqlite-dbapi/src/dqlitedbapi/_constants.py`) to avoid silently
+rejecting connections to older-server clusters that ship SQLite below
+the floor. As a consequence, SA's compiler will NOT emit
+`CREATE TABLE ... STRICT` DDL through this dialect, even when the
+cluster ships SQLite 3.37 or newer.
+
+If your cluster supports STRICT tables and you want STRICT semantics,
+emit the DDL via raw SQL (`engine.execute(text("CREATE TABLE ...
+STRICT"))`) rather than SA's `Table` / `Column` model.
+
+## Cross-version semantic shift: NULL in BOOLEAN/DATETIME columns
+
+Upstream dqlite commit `f30fc99` (`query: preserve SQLITE_NULL type
+for NULL values`, 2026-01-25) changed the wire encoding of NULL cells
+in columns declared `BOOLEAN`, `DATE`, `DATETIME`, or `TIMESTAMP`.
+Before that commit, a NULL in a `BOOLEAN` column was emitted as
+`BOOLEAN(0)` (decodes to `False`) and a NULL in a `DATETIME` column
+was emitted as `ISO8601("")` — indistinguishable on the wire from
+real `FALSE` / empty-string values. After the commit, NULL is emitted
+with the SQLite NULL type and decodes to `None`.
+
+ORM models with `Boolean()` and `DateTime()` columns will start
+returning `None` for previously-`False` / `""` values after a server
+upgrade. SQLAlchemy `nullable=False` constraints will start tripping
+on rows that previously decoded to non-NULL. There is no driver-level
+handshake distinguishing the two server versions — check your dqlite
+cluster version before relying on the post-fix semantics.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup, contribution guidelines,
+and the SQLAlchemy compliance test-suite documentation (how to run it
+locally, why it's not part of the default `pytest` invocation, and
+why ~700 of its tests are correctly skipped).
+
+## License
+
+MIT

sqlalchemy_dqlite-0.2.0/pyproject.toml

@@ -0,0 +1,141 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqlalchemy-dqlite"
+version = "0.2.0"
+description = "SQLAlchemy 2.0 dialect for dqlite distributed SQLite"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [{ name = "Antoine Leclair", email = "antoineleclair@gmail.com" }]
+keywords = ["dqlite", "sqlite", "distributed", "database", "sqlalchemy", "orm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Database :: Front-Ends",
+    "Typing :: Typed",
+]
+dependencies = [
+    "dqlite-dbapi>=0.2.0,<0.3.0",
+    # The SA dialect imports dqliteclient and dqlitewire directly
+    # (base.py / aio.py reach into client exception classes for
+    # is_disconnect, and into dqlitewire for shared helpers). Pin
+    # both transitively so a future major-version bump in either
+    # package surfaces at install time, not at module-import time
+    # in user code.
+    "dqlite-client>=0.2.0,<0.3.0",
+    "dqlite-wire>=0.2.0,<0.3.0",
+    "sqlalchemy>=2.0,<3.0",
+]
+
+[tool.uv.sources]
+dqlite-dbapi = { path = "../python-dqlite-dbapi", editable = true }
+dqlite-client = { path = "../python-dqlite-client", editable = true }
+dqlite-wire = { path = "../python-dqlite-wire", editable = true }
+
+[project.urls]
+Homepage = "https://github.com/letsdiscodev/sqlalchemy-dqlite"
+Repository = "https://github.com/letsdiscodev/sqlalchemy-dqlite"
+Issues = "https://github.com/letsdiscodev/sqlalchemy-dqlite/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=4.0", "pytest-asyncio>=0.23", "mypy>=1.0", "ruff>=0.4"]
+
+[project.entry-points."sqlalchemy.dialects"]
+# Bare ``dqlite`` is the URL-default; ``dqlite.dqlitedbapi`` is the
+# explicit driver-suffix form (URL ``dqlite+dqlitedbapi://``). Both
+# resolve to the same class, mirroring how ``sqlite+pysqlite://`` and
+# bare ``sqlite://`` both reach ``SQLiteDialect_pysqlite`` in SA's
+# built-in dispatch (see ``sqlalchemy/dialects/__init__.py:_auto_fn``).
+# We have to register the explicit form because we are external to SA;
+# its built-ins are auto-routed by name-splitting, ours are not.
+dqlite = "sqlalchemydqlite:DqliteDialect"
+"dqlite.dqlitedbapi" = "sqlalchemydqlite:DqliteDialect"
+"dqlite.aio" = "sqlalchemydqlite.aio:DqliteDialect_aio"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqlalchemydqlite"]
+
+# Hatchling's default file-selection would already ship ``py.typed`` via
+# ``packages``, but declaring it explicitly is the documented PEP 561
+# pattern and makes the intent obvious to anyone auditing the wheel.
+[tool.hatch.build.targets.wheel.force-include]
+"src/sqlalchemydqlite/py.typed" = "sqlalchemydqlite/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+# Exclude the SA compliance suite from the default pytest run.
+# tests/compliance/ loads SA's pytest plugin via its conftest, which
+# replaces pytest's normal collection model and requires CLI options
+# (--dburi etc.) the project-wide test runner does not pass. Run the
+# suite explicitly with ``pytest tests/compliance/``.
+addopts = ["--ignore=tests/compliance"]
+filterwarnings = [
+    # Promote deprecations to errors so the suite catches stdlib
+    # deprecation surface under the CPython version the workspace
+    # already runs CI on (3.13/3.14). Whitelist genuine third-party
+    # noise with explicit ``ignore:<pattern>:DeprecationWarning:<module>``
+    # entries below, with a comment explaining the upstream tracker.
+    "error::DeprecationWarning",
+    "error::PendingDeprecationWarning",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+# Tests live under ``tests/`` with no ``__init__.py``; mypy needs
+# ``explicit_package_bases`` (or namespace packages) to avoid the
+# duplicate-conftest module-name collision when scanning sibling
+# integration/ subdirectories. ``mypy_path`` mirrors the
+# ``pythonpath = ["src"]`` declared for pytest so the source files
+# resolve under the package name (``sqlalchemydqlite``), not the
+# layout path (``src.sqlalchemydqlite``).
+explicit_package_bases = true
+mypy_path = "src"
+
+# Tests use a few patterns that mypy's strict mode flags but are
+# correct at runtime. Disabling these codes only inside ``tests.*``
+# keeps strict typing on production code while letting the test suite
+# use idiomatic patterns without per-line ``# type: ignore`` noise:
+#
+# * ``method-assign`` — monkey-patching bound methods
+#   (``conn.execute = fake_execute``) is the standard way to inject a
+#   fake without subclassing.
+# * ``no-untyped-def`` / ``no-untyped-call`` — pytest fixtures and
+#   small helpers are conventionally written without type annotations.
+# * ``comparison-overlap`` — ``assert SomeIntEnum.FOO == 0`` is the
+#   canonical "this enum matches its int value" pin against a
+#   reference table; mypy's literal-type narrowing incorrectly flags
+#   it as non-overlapping even though IntEnum's ``__eq__`` works.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disable_error_code = ["method-assign", "no-untyped-def", "no-untyped-call", "comparison-overlap"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sqlalchemydqlite", "dqlitedbapi", "dqliteclient", "dqlitewire"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true