Install & Compatibility
Where this runs
tested against v0.1.23 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.142s · 66.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.5s · import 0.918s · 66MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from ydb_dbapi import Connection
✗ import ydb_dbapi
AsyncConnection
✓ from ydb_dbapi import AsyncConnection
✗ import ydb_dbapi
Cursor
✓ from ydb_dbapi import Cursor
✗ import ydb_dbapi
This quickstart demonstrates how to establish a synchronous connection to YDB, create a table, insert data using UPSERT, and query it back. It includes basic error handling and ensures proper resource cleanup by closing the connection and cursor. Environment variables `YDB_ENDPOINT` and `YDB_DATABASE` are used for configuration, falling back to local defaults if not set.
import os
import ydb_dbapi
# Configuration for YDB connection
# Replace with your YDB endpoint and database path or set as environment variables
YDB_ENDPOINT = os.environ.get("YDB_ENDPOINT", "grpc://localhost:2136")
YDB_DATABASE = os.environ.get("YDB_DATABASE", "/local")
connection = None
cursor = None
try:
# Establish a synchronous connection to YDB
connection = ydb_dbapi.connect(
host=YDB_ENDPOINT,
database=YDB_DATABASE
)
print("Successfully connected to YDB.")
# Create a cursor object
cursor = connection.cursor()
# Execute a simple DDL query (create table if not exists)
cursor.execute("""
CREATE TABLE IF NOT EXISTS my_table (
id Int64,
value Utf8,
PRIMARY KEY (id)
);
""")
print("Table 'my_table' ensured to exist.")
connection.commit() # DDL statements usually imply a commit, but explicit is good practice.
# Execute an UPSERT statement to insert/update data
cursor.execute("UPSERT INTO my_table (id, value) VALUES (1, 'Hello');")
cursor.execute("UPSERT INTO my_table (id, value) VALUES (2, 'YDB DBAPI');")
connection.commit() # Commit the transaction
print("Inserted data into 'my_table'.")
# Execute a SELECT statement
cursor.execute("SELECT id, value FROM my_table ORDER BY id;")
# Fetch all results
rows = cursor.fetchall()
print("Fetched data:")
for row in rows:
print(f" ID: {row[0]}, Value: {row[1]}")
except ydb_dbapi.Error as e:
print(f"An YDB DBAPI error occurred: {e}")
if connection:
connection.rollback() # Rollback on error
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
if cursor:
cursor.close()
if connection:
connection.close()
print("Connection closed.")
Debug
Known issues
gotchaFailing to explicitly call `connection.commit()` after DML (INSERT, UPDATE, DELETE) or DDL (CREATE, ALTER) statements will result in an implicit `ROLLBACK` when the connection is closed. This is mandated by PEP 249 and can lead to lost data if not handled carefully.fixAlways explicitly call `connection.commit()` after operations that modify the database, or manage transactions using `BEGIN`, `COMMIT`, and `ROLLBACK` statements through the cursor.
affects: All versions
gotchaYDB is a distributed database and its underlying SDK handles retryable errors. Improper error handling, especially not retrying transient failures, can lead to production incidents and brittle applications. The `ydb` SDK (used by `ydb-dbapi`) has built-in retry mechanisms; understand and configure them or implement appropriate retry logic at the application level.fixReview YDB's official documentation on 'Error Handling and Retries' to understand which errors are retryable and how to implement robust retry policies in your application.
affects: All versions
gotchaPEP 249 deprecates passing a list of tuples to `cursor.execute()` for inserting multiple rows. For improved efficiency and clarity when performing multiple inserts, `cursor.executemany()` should be used instead.fixUse `cursor.executemany(sql, list_of_parameters)` when inserting or updating multiple rows, where `list_of_parameters` is a list of tuples or dictionaries representing each row's values.
affects: All versions
breakingAs `ydb-dbapi` is currently in a 0.x.x version series, breaking changes may be introduced in minor releases (e.g., 0.1.x to 0.2.x) without adhering to strict semantic versioning. Users should review release notes carefully when upgrading between minor versions.fixMonitor GitHub releases and changelogs for any breaking changes when upgrading. Pin your dependency to a specific minor version (e.g., `ydb-dbapi~=0.1.0`) if stability is critical.
affects: 0.1.0 and higher (while in 0.x.x series)
Upgrade
Version history
0.1.23latest on PyPI · released Aug 27, 2026
Audit
Dependencies
ydbrequiredCore YDB Python SDK which ydb-dbapi wraps to provide DBAPI 2.0 compliance.