sqlalchemy-dqlite 0.3.0

SQLAlchemy 2.0 dialect for dqlite distributed SQLite

sqlalchemy-dqlite

A SQLAlchemy 2.0 dialect for dqlite, 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.

Installation

pip install sqlalchemy-dqlite

Requires Python 3.13+ and SQLAlchemy 2.0+.

Usage

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:

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 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	PEP 249 (DB-API 2.0) driver — sync & async
dqlite-client	Async wire client — pooling, leader discovery
dqlite-wire	Wire-protocol codec

Documentation

• Transactions — SQLAlchemy owns BEGIN/COMMIT; no AUTOCOMMIT.
• Connection URL — URL format, the bootstrap address, and query parameters.
• Limitations & notes — STRICT tables, savepoint naming, and a server-version NULL gotcha.

Development

See DEVELOPMENT.md for setup, contribution guidelines, and how to run the SQLAlchemy compliance test suite.

License

MIT