{"id":2850,"library":"ydb-dbapi","title":"YDB DBAPI","description":"ydb-dbapi is a Python DBAPI 2.0 compliant driver for YDB, a distributed SQL database. It provides both synchronous and asynchronous interfaces for interacting with YDB. The library is actively developed, with frequent minor releases, typically on a monthly cadence, reflecting ongoing enhancements and bug fixes.","status":"active","version":"0.1.20","language":"en","source_language":"en","source_url":"https://github.com/ydb-platform/ydb-python-dbapi/","tags":["database","sql","dbapi","ydb","distributed-database"],"install":[{"cmd":"pip install ydb-dbapi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core YDB Python SDK which ydb-dbapi wraps to provide DBAPI 2.0 compliance.","package":"ydb"}],"imports":[{"symbol":"connect","correct":"import ydb_dbapi\nconnection = ydb_dbapi.connect(...)"},{"symbol":"async_connect","correct":"import ydb_dbapi\nasync_connection = await ydb_dbapi.async_connect(...)"}],"quickstart":{"code":"import os\nimport ydb_dbapi\n\n# Configuration for YDB connection\n# Replace with your YDB endpoint and database path or set as environment variables\nYDB_ENDPOINT = os.environ.get(\"YDB_ENDPOINT\", \"grpc://localhost:2136\")\nYDB_DATABASE = os.environ.get(\"YDB_DATABASE\", \"/local\")\n\nconnection = None\ncursor = None\ntry:\n    # Establish a synchronous connection to YDB\n    connection = ydb_dbapi.connect(\n        host=YDB_ENDPOINT,\n        database=YDB_DATABASE\n    )\n    print(\"Successfully connected to YDB.\")\n\n    # Create a cursor object\n    cursor = connection.cursor()\n\n    # Execute a simple DDL query (create table if not exists)\n    cursor.execute(\"\"\"\n        CREATE TABLE IF NOT EXISTS my_table (\n            id Int64,\n            value Utf8,\n            PRIMARY KEY (id)\n        );\n    \"\"\")\n    print(\"Table 'my_table' ensured to exist.\")\n    connection.commit() # DDL statements usually imply a commit, but explicit is good practice.\n\n    # Execute an UPSERT statement to insert/update data\n    cursor.execute(\"UPSERT INTO my_table (id, value) VALUES (1, 'Hello');\")\n    cursor.execute(\"UPSERT INTO my_table (id, value) VALUES (2, 'YDB DBAPI');\")\n    connection.commit() # Commit the transaction\n    print(\"Inserted data into 'my_table'.\")\n\n    # Execute a SELECT statement\n    cursor.execute(\"SELECT id, value FROM my_table ORDER BY id;\")\n    \n    # Fetch all results\n    rows = cursor.fetchall()\n    print(\"Fetched data:\")\n    for row in rows:\n        print(f\"  ID: {row[0]}, Value: {row[1]}\")\n\nexcept ydb_dbapi.Error as e:\n    print(f\"An YDB DBAPI error occurred: {e}\")\n    if connection:\n        connection.rollback() # Rollback on error\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if cursor:\n        cursor.close()\n    if connection:\n        connection.close()\n    print(\"Connection closed.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always explicitly call `connection.commit()` after operations that modify the database, or manage transactions using `BEGIN`, `COMMIT`, and `ROLLBACK` statements through the cursor.","message":"Failing 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review 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.","message":"YDB 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `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.","message":"PEP 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor 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.","message":"As `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.","severity":"breaking","affected_versions":"0.1.0 and higher (while in 0.x.x series)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}