sqlalchemy-dqlite 0.2.2__tar.gz → 0.3.0__tar.gz

{sqlalchemy_dqlite-0.2.2 → sqlalchemy_dqlite-0.3.0}/DEVELOPMENT.md

@@ -79,13 +79,22 @@ 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
+~639). Most skips are 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.
 
+A few schema-using parametrize variants are skipped at the
+compliance-conftest level instead (`_SCHEMA_USING_PARAMETRIZE_SKIPS`
+in `tests/compliance/conftest.py`): SQLAlchemy parametrises some
+reflection tests with `use_schema=True/False` without gating the
+`True` branch on `requires.schemas`, so the `True` variants try to
+create tables in `test_schema` (which dqlite lacks, having no ATTACH)
+and are skipped explicitly while the `False` variants run for real
+coverage.
+
 Examples of features dqlite doesn't have (each declared
 `exclusions.closed()`):
 
@@ -141,6 +150,31 @@ the cluster.
 .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

sqlalchemy_dqlite-0.3.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-dqlite
+Version: 0.3.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.4.0,>=0.3.0
+Requires-Dist: dqlite-dbapi<0.4.0,>=0.3.0
+Requires-Dist: dqlite-wire<0.4.0,>=0.3.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
+
+A [SQLAlchemy 2.0](https://www.sqlalchemy.org/) dialect for
+[dqlite](https://dqlite.io/), Canonical's distributed SQLite. Point
+SQLAlchemy (and Alembic, and most ORMs built on it) at a dqlite cluster
+with a `dqlite://` URL and use it like any other backend.
+
+It supports both the synchronous and the async SQLAlchemy engines, and
+builds on dqlite's SQLite roots, so SQLAlchemy treats it as a SQLite-family
+dialect.
+
+## Is this the package you want?
+
+Yes, if you use SQLAlchemy or an ORM/migration tool on top of it (Alembic,
+Flask-SQLAlchemy, etc.) and want it backed by dqlite. If you want a plain
+database driver without SQLAlchemy, use
+[dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi).
+
+## Installation
+
+```bash
+pip install sqlalchemy-dqlite
+```
+
+Requires Python 3.13+ and SQLAlchemy 2.0+.
+
+## Usage
+
+```python
+from sqlalchemy import create_engine, text
+
+engine = create_engine("dqlite://localhost:9001/mydb")
+with engine.connect() as conn:
+    print(conn.execute(text("SELECT 1")).fetchone())
+```
+
+Async:
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+engine = create_async_engine("dqlite+aio://localhost:9001/mydb")
+async with engine.connect() as conn:
+    result = await conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+```
+
+URL format: `dqlite://host:port/database` (or `dqlite+aio://…` for async).
+The host:port is the bootstrap node — the cluster is discovered from there.
+See [Connection URL](docs/connection-url.md) for details.
+
+## The dqlite Python stack
+
+This is the top of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| **sqlalchemy-dqlite** — this package | SQLAlchemy 2.0 dialect |
+| [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi) | 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 |
+
+## Documentation
+
+- [Transactions](docs/transactions.md) — SQLAlchemy owns `BEGIN`/`COMMIT`; no `AUTOCOMMIT`.
+- [Connection URL](docs/connection-url.md) — URL format, the bootstrap address, and query parameters.
+- [Limitations & notes](docs/limitations.md) — STRICT tables, savepoint
+  naming, and a server-version NULL gotcha.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup, contribution guidelines, and
+how to run the SQLAlchemy compliance test suite.
+
+## License
+
+MIT

sqlalchemy_dqlite-0.3.0/README.md

@@ -0,0 +1,77 @@
+# sqlalchemy-dqlite
+
+A [SQLAlchemy 2.0](https://www.sqlalchemy.org/) dialect for
+[dqlite](https://dqlite.io/), Canonical's distributed SQLite. Point
+SQLAlchemy (and Alembic, and most ORMs built on it) at a dqlite cluster
+with a `dqlite://` URL and use it like any other backend.
+
+It supports both the synchronous and the async SQLAlchemy engines, and
+builds on dqlite's SQLite roots, so SQLAlchemy treats it as a SQLite-family
+dialect.
+
+## Is this the package you want?
+
+Yes, if you use SQLAlchemy or an ORM/migration tool on top of it (Alembic,
+Flask-SQLAlchemy, etc.) and want it backed by dqlite. If you want a plain
+database driver without SQLAlchemy, use
+[dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi).
+
+## Installation
+
+```bash
+pip install sqlalchemy-dqlite
+```
+
+Requires Python 3.13+ and SQLAlchemy 2.0+.
+
+## Usage
+
+```python
+from sqlalchemy import create_engine, text
+
+engine = create_engine("dqlite://localhost:9001/mydb")
+with engine.connect() as conn:
+    print(conn.execute(text("SELECT 1")).fetchone())
+```
+
+Async:
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+
+engine = create_async_engine("dqlite+aio://localhost:9001/mydb")
+async with engine.connect() as conn:
+    result = await conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+```
+
+URL format: `dqlite://host:port/database` (or `dqlite+aio://…` for async).
+The host:port is the bootstrap node — the cluster is discovered from there.
+See [Connection URL](docs/connection-url.md) for details.
+
+## The dqlite Python stack
+
+This is the top of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| **sqlalchemy-dqlite** — this package | SQLAlchemy 2.0 dialect |
+| [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi) | 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 |
+
+## Documentation
+
+- [Transactions](docs/transactions.md) — SQLAlchemy owns `BEGIN`/`COMMIT`; no `AUTOCOMMIT`.
+- [Connection URL](docs/connection-url.md) — URL format, the bootstrap address, and query parameters.
+- [Limitations & notes](docs/limitations.md) — STRICT tables, savepoint
+  naming, and a server-version NULL gotcha.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup, contribution guidelines, and
+how to run the SQLAlchemy compliance test suite.
+
+## License
+
+MIT

sqlalchemy_dqlite-0.3.0/docs/connection-url.md

@@ -0,0 +1,31 @@
+# Connection URL
+
+```
+dqlite://host:port/database
+dqlite+aio://host:port/database     # async engine
+```
+
+```python
+from sqlalchemy import create_engine
+engine = create_engine("dqlite://localhost:9001/mydb")
+```
+
+## The host:port is a bootstrap address
+
+The host:port pair is just the *bootstrap* node. The dqlite client connects
+there, reads that node's leader-info response, and discovers the rest of the
+cluster from it. You point at one reachable node, not the whole cluster.
+
+If that host is unreachable, leader discovery cannot start. Multi-address
+bootstrap is not exposed at the dialect URL surface — if you want
+bootstrap-from-many, put a load balancer or DNS round-robin in front of the
+cluster, or rotate the URL host across deployments.
+
+## Query parameters
+
+Connection options can be passed as URL query parameters (e.g.
+`max_total_rows`). When a parameter is repeated
+(`?max_total_rows=100&max_total_rows=200`), the **last** occurrence wins —
+matching `urllib.parse.parse_qsl` ordering. Templated URLs that layer values
+from multiple sources should be aware that a duplicated key silently
+overrides the earlier value rather than raising.

sqlalchemy_dqlite-0.3.0/docs/limitations.md

@@ -0,0 +1,31 @@
+# Limitations & notes
+
+## STRICT tables are not emitted by the compiler
+
+SQLAlchemy's SQLite dialect gates `CREATE TABLE ... STRICT` compilation on
+`server_version_info >= (3, 37)`. This dialect pins
+`sqlite_version_info = (3, 35, 0)` as a documented floor so it doesn't reject
+connections to older-server clusters. As a result, SQLAlchemy's compiler will
+**not** emit STRICT DDL through this dialect, even when your cluster ships
+SQLite 3.37+.
+
+If your cluster supports STRICT tables and you want them, emit the DDL as raw
+SQL (`engine.execute(text("CREATE TABLE ... STRICT"))`) rather than through
+SQLAlchemy's `Table` / `Column` model.
+
+## 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` (Boolean) or `""` (datetime
+  types) — indistinguishable from a real value.
+- **After**: a NULL comes back as `None`.
+
+For ORM models this means a `Boolean()` / `DateTime()` column that used to
+return `False` / `""` will start returning `None` after a server upgrade, and
+`nullable=False` constraints may start tripping on rows that previously
+decoded to non-NULL. There is no handshake distinguishing the two server
+versions — check your dqlite cluster version before relying on the post-change
+semantics.

sqlalchemy_dqlite-0.3.0/docs/transactions.md

@@ -0,0 +1,50 @@
+# Transactions
+
+SQLAlchemy owns `BEGIN` / `COMMIT` / `ROLLBACK` for any block opened via
+`engine.begin()`, `connection.begin()`, or `session.begin()`. **Do not issue
+a raw `BEGIN` yourself** — this is the standard SQLAlchemy model, and it is
+the same on every backend (pysqlite, PostgreSQL, MySQL).
+
+```python
+from sqlalchemy import create_engine, text
+
+engine = create_engine("dqlite://localhost:9001/mydb")
+
+# OK — SQLAlchemy emits BEGIN / COMMIT for you:
+with engine.begin() as conn:
+    conn.execute(text("INSERT INTO t VALUES (1)"))
+
+# WRONG — a manual BEGIN inside an SA-managed transaction errors with
+#   "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 applies to `engine.connect()`: SQLAlchemy auto-begins on the first
+execute, so a user-issued `text("BEGIN")` collides the same way.
+
+## No `AUTOCOMMIT`
+
+`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. Isolation is always
+SERIALIZABLE.
+
+See SQLAlchemy's
+[transaction docs](https://docs.sqlalchemy.org/en/20/core/connections.html#using-transactions)
+for the full model.
+
+## Savepoints
+
+SQLAlchemy's `Session.begin_nested()` / `connection.begin_nested()` use
+generated savepoint names (e.g. `sa_savepoint_1`), which the dialect tracks
+correctly — no action needed.
+
+Only **raw** SQL with an unusual savepoint name (quoted, backticked,
+bracketed, unicode, or leading-digit, e.g. `text('SAVEPOINT "weird name"')`)
+falls outside the tracker. When that happens the connection is conservatively
+flagged as carrying an untracked savepoint, and SQLAlchemy issues a safety
+`ROLLBACK` on the next pool checkin — one extra round-trip per checkout for
+the rest of that connection's life in the pool. Stick to bare-ASCII savepoint
+names in raw SQL to avoid it.

{sqlalchemy_dqlite-0.2.2 → sqlalchemy_dqlite-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlalchemy-dqlite"
-version = "0.2.2"
+version = "0.3.0"
 description = "SQLAlchemy 2.0 dialect for dqlite distributed SQLite"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -26,15 +26,15 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "dqlite-dbapi>=0.2.2,<0.3.0",
+    "dqlite-dbapi>=0.3.0,<0.4.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.2,<0.3.0",
-    "dqlite-wire>=0.2.2,<0.3.0",
+    "dqlite-client>=0.3.0,<0.4.0",
+    "dqlite-wire>=0.3.0,<0.4.0",
     "sqlalchemy>=2.0,<3.0",
 ]
 

{sqlalchemy_dqlite-0.2.2 → sqlalchemy_dqlite-0.3.0}/src/sqlalchemydqlite/__init__.py

@@ -27,19 +27,14 @@ from sqlalchemy.dialects.sqlite import (
 from sqlalchemydqlite.aio import DqliteDialect_aio
 from sqlalchemydqlite.base import DqliteCompiler, DqliteDialect
 
-__version__: _Final[str] = "0.2.2"
+__version__: _Final[str] = "0.3.0"
 
-# SA convention (every shipped dialect package — sqlite, mysql, mssql,
-# oracle, postgresql): expose ``<package>.dialect`` pointing at the
-# default sync class. Pysqlite at ``.venv/.../sqlite/__init__.py:34``
-# does ``base.dialect = dialect = pysqlite.dialect``; we follow the same
-# pattern so ``from sqlalchemydqlite import dialect`` resolves
-# canonically.
+# SA convention: every shipped dialect package exposes ``<package>.dialect``
+# pointing at the default sync class.
 dialect: _Final[type[DqliteDialect]] = DqliteDialect
 dialect_aio: _Final[type[DqliteDialect_aio]] = DqliteDialect_aio
 
-__all__ = [  # grouped: dialect entry points, then SA-shared SQLite types
-    # Dialect entry points
+__all__ = [
     "DqliteCompiler",
     "DqliteDialect",
     "DqliteDialect_aio",
@@ -48,7 +43,6 @@ __all__ = [  # grouped: dialect entry points, then SA-shared SQLite types
     "dialect",
     "dialect_aio",
     "insert",
-    # SA-shared SQLite type re-exports (alphabetical within group)
     "BLOB",
     "BOOLEAN",
     "CHAR",
@@ -67,9 +61,5 @@ __all__ = [  # grouped: dialect entry points, then SA-shared SQLite types
     "VARCHAR",
 ]
 
-# Convention from the Python logging HOWTO: attach a ``NullHandler``
-# to the library's top-level logger so applications that have not
-# configured logging don't see the ``lastResort`` stderr emission,
-# and downstream code can silence the library cleanly via
-# ``getLogger("sqlalchemydqlite").propagate = False``.
+# NullHandler keeps the library quiet until the application configures logging.
 logging.getLogger(__name__).addHandler(logging.NullHandler())