Async Python client for dqlite, Canonical's distributed SQLite. It connects to a dqlite cluster, finds the current Raft leader, runs SQL, and pools connections.
The API is inspired by asyncpg's
ergonomics — explicit connect() / create_pool(), fetch / fetchall
/ fetchval, and context-manager transactions — with a deliberately
simple data model: fetch returns list[dict], fetchall returns
list[list], fetchval returns a scalar. There is no Record type.
Use dqlite-client directly when you want a lightweight async client
with no ORM or DB-API layer, or when you need fine-grained control over
cluster bootstrapping and the wire protocol.
If you want a standard PEP 249 driver, SQLAlchemy, Alembic, or most ORMs, reach for a higher layer instead — see The dqlite Python stack below.
pip install dqlite-clientRequires Python 3.13+.
importasynciofromdqliteclientimportconnectasyncdefmain():
conn=awaitconnect("localhost:9001")
asyncwithconn.transaction():
awaitconn.execute("CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, name TEXT)")
awaitconn.execute("INSERT INTO t (name) VALUES (?)", ["hello"])
rows=awaitconn.fetch("SELECT * FROM t") # list[dict]forrowinrows:
print(row)
awaitconn.close()
asyncio.run(main())fromdqliteclientimportcreate_poolpool=awaitcreate_pool(["localhost:9001", "localhost:9002", "localhost:9003"])
asyncwithpool.acquire() asconn:
rows=awaitconn.fetch("SELECT 1")This is one of four layered packages. Each builds on the one below:
| Package | Role |
|---|---|
| sqlalchemy-dqlite | SQLAlchemy 2.0 dialect |
| dqlite-dbapi | PEP 249 (DB-API 2.0) driver — sync & async |
| dqlite-client — this package | Async wire client — pooling, leader discovery |
| dqlite-wire | Wire-protocol codec |
For SQLAlchemy/ORM use, prefer sqlalchemy-dqlite or dqlite-dbapi.
- Connection pooling — sizing, startup, and leader behavior.
- Deployment: forking & multiprocessing — read this
if you use gunicorn, Celery, or
multiprocessing. - Data types & NULL handling — the row model and a server-version gotcha for NULLs in typed columns.
See DEVELOPMENT.md for setup and contribution guidelines.
MIT