ydb-dbapi

ydb-dbapi is the Python DBAPI layer for YDB, the distributed SQL database. It complies with PEP 249, exposing the familiar connection-and-cursor model on top of the underlying ydb driver, so applications interact with YDB the same way they would any other Python database.

Uniquely, it ships both synchronous and asynchronous variants: connect() returns a standard blocking connection, while async_connect() returns an awaitable connection whose cursors support async execute and fetch. This makes it a natural fit for both traditional scripts and asyncio services, and it integrates with SQLAlchemy for higher-level ORM and query-builder use.

What You Get

• PEP 249-compliant connect() and async_connect() entry points
• Cursors with execute plus fetchone, fetchmany, and fetchall
• Fully asynchronous connection and cursor variants for asyncio code
• Parameterized query support with type conversion to YDB
• SQLAlchemy compatibility for ORM and query-builder workflows

Common Use Cases

• Querying a YDB database from Python scripts using standard DBAPI patterns
• Running non-blocking YDB queries inside an asyncio service
• Using YDB as a SQLAlchemy backend for ORM-based applications
• Migrating code written against other DBAPI drivers to YDB

Under The Hood

Architecture — The ydb_dbapi package is a thin DBAPI adapter over the official ydb driver. connections.py defines the sync and async connection factories (connect / async_connect) and manages the underlying ydb session and transaction; cursors.py implements the cursor with execute and the fetch family in both blocking and awaitable forms; utils.py handles parameter conversion into YDB’s type system, with errors.py and constants.py supplying the PEP 249 exception hierarchy and module-level constants.

Tech Stack — Python 3.8+ managed with Poetry, depending on the ydb package for the actual protocol client. The dev toolchain is modern — ruff, mypy, pytest with pytest-asyncio, poethepoet task runner, and pre-commit — and SQLAlchemy/greenlet appear as dev dependencies for integration testing.

Code Quality — Tests cover connections, cursors, and parameter conversion (test_connections, test_cursors, test_convert_parameters) with async support, and the repo maintains a CHANGELOG plus CI version-increment scripting. Strict typing (mypy, types-protobuf) and ruff enforcement keep the small codebase tidy.

API Design — The API mirrors PEP 249 exactly, so connect(), cursor(), execute(), and fetchone/fetchmany/fetchall behave as expected, and the async variant simply swaps in async_connect plus await. The README demonstrates both sync and async usage side by side in a few lines, and SQLAlchemy compatibility offers a higher-level path when the raw DBAPI is too low-level.