Skip to content

Commit 90c8f2f

Browse files
README: add Layering section pointing to higher-level wrappers
ISSUE-29 — explain when to use dqlite-client directly vs dqlite-dbapi or sqlalchemy-dqlite, so newcomers don't mistake the wire client for the ergonomic interface. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent bdf75e3 commit 90c8f2f

1 file changed

Lines changed: 14 additions & 0 deletions

File tree

README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,20 @@ async with pool.acquire() as conn:
3737
rows = await conn.fetch("SELECT 1")
3838
```
3939

40+
## Layering
41+
42+
`dqlite-client` is the low-level async wire client. Most applications
43+
should reach for one of the higher-level packages instead:
44+
45+
- **`dqlite-dbapi`** — PEP 249–compliant wrapper (sync *or* async).
46+
Plug-and-play with SQLAlchemy, Alembic, most ORMs.
47+
- **`sqlalchemy-dqlite`** — SQLAlchemy 2.0 dialect, built on top of
48+
`dqlite-dbapi`.
49+
50+
Use `dqlite-client` directly when you need fine-grained control over
51+
the wire protocol: custom cluster bootstrapping, explicit message
52+
decoding, or building a new high-level driver.
53+
4054
## Development
4155

4256
See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.

0 commit comments

Comments
 (0)