YDB Python SDK

Warnings

• breaking Starting with version 3.26.0, the YDB Python SDK dropped compatibility with Python 3.7. Users on Python 3.7 or older must upgrade to Python 3.8 or higher.
  Fix: Upgrade your Python environment to 3.8 or a newer supported version (e.g., `python3.8 -m pip install ydb`).
• gotcha Authentication is critical and has several methods. Older YDB Python SDK v2 documentation might refer to environment variables like `USE_METADATA_CREDENTIALS` or `SA_KEY_FILE` which are peculiar to deprecated versions. Always refer to the latest documentation for current authentication practices, which involve `ydb.credentials` classes.
  Fix: Use explicit credential providers from `ydb.credentials`, such as `AuthTokenCredentials`, `ServiceAccountCredentials.from_file`, `StaticCredentials`, or `AnonymousCredentials`. Modern environment variables like `YDB_TOKEN`, `YDB_USER`, and `YDB_PASSWORD` can also be used, depending on the credential provider.
• gotcha Errors like "Sent message larger than max" are now non-retryable starting from version 3.26.8. This change prevents indefinite retries on errors that cannot be resolved by retrying. [cite: Changelog]
  Fix: Review your application logic to ensure messages adhere to YDB's size limits. Such errors indicate a fundamental data size issue rather than a transient network problem.
• gotcha When using `ydb.dbapi` for DB-API 2.0 compliance, ensure you are importing `ydb.dbapi` from the main `ydb` SDK. While there's a separate `ydb-dbapi` package, the recommended approach for modern applications is to use the `ydb.dbapi` module directly provided by the `ydb` SDK.
  Fix: Prefer `import ydb.dbapi` and use its `connect` function. Avoid installing `ydb-dbapi` as a standalone package unless specifically required for an older system.

Install

• pip install ydb Install YDB Python SDK

Imports

• ydb

  import ydb

  Primary import for the YDB SDK.
• Driver

  import ydb
  from ydb.driver import Driver

  Driver is typically imported from `ydb.driver` or accessed via `ydb.Driver` after `import ydb` for type hints.
• SessionPool

  from ydb.table import SessionPool

  SessionPool is part of the table service, commonly imported from `ydb.table`.
• dbapi

  import ydb.dbapi

  The `ydb.dbapi` module provides a DB-API 2.0 compliant interface and is included with the `ydb` SDK. There is also a separate, older `ydb-dbapi` package which is not the primary way to use DB-API 2.0 with the main YDB SDK.
• iam

  import ydb.iam

  Module for various Identity and Access Management (IAM) credentials.

Quickstart

This quickstart demonstrates how to initialize the YDB driver and session pool, connecting to a YDB instance. It prioritizes authentication via an environment variable `YDB_TOKEN` for `AuthTokenCredentials`, falling back to `AnonymousCredentials` if not provided, suitable for local setups. Replace `YDB_ENDPOINT` and `YDB_DATABASE` with your YDB instance details.

import os
import ydb

# Configure connection details from environment variables for flexibility
ENDPOINT = os.environ.get('YDB_ENDPOINT', 'grpcs://localhost:2135') # e.g., 'grpcs://ydb.example.com:2135'
DATABASE = os.environ.get('YDB_DATABASE', '/local/database') # e.g., '/path/to/my/db'
AUTH_TOKEN = os.environ.get('YDB_TOKEN')

def main():
    driver_config = ydb.DriverConfig(ENDPOINT, DATABASE)

    # Use token authentication if YDB_TOKEN is set, otherwise anonymous
    if AUTH_TOKEN:
        driver_config.credentials = ydb.credentials.AuthTokenCredentials(AUTH_TOKEN)
    else:
        # For local YDB or scenarios requiring no explicit auth (e.g., metadata service)
        driver_config.credentials = ydb.credentials.AnonymousCredentials()

    with ydb.Driver(driver_config) as driver:
        driver.wait(timeout=5, fail_fast=True)
        print("YDB driver initialized successfully.")

        # Create a session pool
        with ydb.SessionPool(driver) as session_pool:
            def execute_query(session):
                try:
                    session.execute('SELECT 1 as my_column;')
                    print("Query executed successfully.")
                except Exception as e:
                    print(f"Error executing query: {e}")

            session_pool.retry_operation_sync(execute_query)

if __name__ == '__main__':
    main()