Metadata-Version: 2.4
Name: dqlite-dbapi
Version: 0.3.0
Summary: PEP 249 (DB-API 2.0) compliant interface for dqlite
Project-URL: Homepage, https://github.com/letsdiscodev/python-dqlite-dbapi
Project-URL: Repository, https://github.com/letsdiscodev/python-dqlite-dbapi
Project-URL: Issues, https://github.com/letsdiscodev/python-dqlite-dbapi/issues
Author-email: Antoine Leclair <antoineleclair@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Keywords: database,dbapi,distributed,dqlite,pep249,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-wire<0.4.0,>=0.3.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

# dqlite-dbapi

A [PEP 249](https://peps.python.org/pep-0249/) (DB-API 2.0) driver for
[dqlite](https://dqlite.io/), Canonical's distributed SQLite. If you have
used Python's standard `sqlite3` module, this will feel familiar — same
`connect()` / `cursor()` / `execute()` / `fetchone()` shape — but it talks
to a replicated dqlite cluster over the network instead of a local file.

It comes in two flavors from one package: a **synchronous** API
(`dqlitedbapi`) and an **async** API (`dqlitedbapi.aio`).

## Is this the package you want?

Yes, if you want a drop-in-style database driver for dqlite — directly,
or under a tool that expects a DB-API 2.0 driver. For SQLAlchemy
specifically, use [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite)
(it builds on this package).

## Installation

```bash
pip install dqlite-dbapi
```

Requires Python 3.13+.

## Usage

### Sync

```python
import dqlitedbapi

conn = dqlitedbapi.connect("localhost:9001")
cur = conn.cursor()
cur.execute("SELECT 1")
print(cur.fetchone())
conn.close()
```

### Async

```python
import asyncio
from dqlitedbapi.aio import aconnect

async def main():
    conn = await aconnect("localhost:9001")
    cur = conn.cursor()
    await cur.execute("SELECT 1")
    print(await cur.fetchone())
    await conn.close()

asyncio.run(main())
```

## Key facts

- `apilevel = "2.0"`, `paramstyle = "qmark"` (`?` placeholders),
  `threadsafety = 2`.
- **Autocommit by default.** Unlike stdlib `sqlite3`, the driver does not
  auto-`BEGIN` before a statement — wrap writes in an explicit transaction
  when you need atomic multi-statement semantics. See
  [Transactions](docs/transactions.md).
- **Isolation is always SERIALIZABLE** — every write goes through Raft
  consensus, every read is serializable.

## The dqlite Python stack

This is one of four layered packages. Each builds on the one below:

| Package | Role |
| --- | --- |
| [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite) | SQLAlchemy 2.0 dialect |
| **dqlite-dbapi** — this package | 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 |

Using SQLAlchemy or an ORM? Prefer
[sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).

## Documentation

- [Transactions](docs/transactions.md) — the autocommit-by-default model and how to group statements.
- [Differences from `sqlite3`](docs/differences-from-sqlite3.md) — what to
  expect when porting from the stdlib module (and a server-version NULL
  gotcha).
- [Differences from `aiosqlite`](docs/differences-from-aiosqlite.md) — for
  the async surface.

## Development

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

## License

MIT
