zylon-ai/private-gpt · error · ImportError

DB2 database query dependencies are not installed. Install w

Error message

DB2 database query dependencies are not installed. Install with one of: `uv sync --inexact --extra database-db2` or `uv sync --inexact --extra database`.

What it means

ImportError raised by the cached loader _load_ibm_db_dbi when the ibm_db_dbi driver is missing. It is raised lazily on first DB2 connection attempt and chained from the original ImportError, with a message telling you exactly which uv extras provide the driver: database-db2 (DB2 only) or database (all database drivers). functools.cache means the failure is remembered, so fixing the environment requires no code change, only a re-run.

Source

Thrown at private_gpt/components/database/connection_factory.py:49

    "mysql": DatabaseDialect.MYSQL,
    "mssql": DatabaseDialect.MSSQL,
    "microsoft": DatabaseDialect.MSSQL,
    "db2": DatabaseDialect.DB2,
    "ibm_db_sa": DatabaseDialect.DB2,
}

_URL_PASSWORD_RE = re.compile(r"(://[^:/?#@]+:)([^@/?#]+)(@)")
_DB2_BRACED_PWD_RE = re.compile(r"(PWD=)\{((?:[^}]|}})*)\}(;)", re.IGNORECASE)
_DB2_PLAIN_PWD_RE = re.compile(r"(PWD=)(?!\{)([^;]*)(;)", re.IGNORECASE)
_DB2_VALUE_NEEDS_ESCAPING_RE = re.compile(r"[;{}]|^\s|\s$")


@functools.cache
def _load_ibm_db_dbi() -> Any:
    try:
        import ibm_db_dbi  # type: ignore[import-not-found,import-untyped]
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "DB2 database query",
                extras=("database-db2", "database"),
            )
        ) from e

    return ibm_db_dbi


def classify_dialect(dialect_name: str | None) -> DatabaseDialect:
    """Classify a dialect/scheme identifier into a DatabaseDialect."""
    return _DIALECT_NAME_MAP.get((dialect_name or "").lower(), DatabaseDialect.UNKNOWN)


def is_db2_connection_string(connection_string: str) -> bool:
    """Whether a SQLAlchemy-style connection string targets DB2."""
    scheme = connection_string.split("://", 1)[0].split("+", 1)[0]
    return classify_dialect(scheme) is DatabaseDialect.DB2

View on GitHub (pinned to 4a030776a3)

Solutions

Run: uv sync --inexact --extra database-db2 (or --extra database for all drivers)
Verify with: python -c "import ibm_db_dbi" in the same environment the app runs in
If the import still fails after install, check the underlying chained ImportError for missing OS-level DB2 client libraries and install those
Ensure you are not running in a different virtualenv/conda env than the one you synced

Example fix

# before: raises ImportError on first DB2 query
# after
# uv sync --inexact --extra database-db2
conn = connection_factory.create(db2_url)

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec('ibm_db_dbi') is None:
    raise SystemExit('DB2 driver missing; run: uv sync --inexact --extra database-db2')

Try / catch

try:
    conn = connection_factory.create(db2_url)
except ImportError as e:
    if 'database-db2' in str(e):
        raise SystemExit('DB2 driver missing; run: uv sync --inexact --extra database-db2') from e
    raise

Prevention

Declare the database-db2 (or database) extra in deployment images, not just locally
Smoke-test required drivers at container start with importlib.util.find_spec
Keep app and sync in the same virtualenv; verify with python -c 'import ibm_db_dbi'

When it happens

Trigger: Creating a DB2 connection through connection_factory with a db2://... URL (or a dialect classified as DB2) when the ibm_db_dbi package is not importable in the current virtualenv.

Common situations: Running with a minimal dependency set (no database extra); a fresh environment after switching from pip/poetry to uv; CI cache restored without the db2 extra; system-level ibm_db driver libs missing so the Python package fails to import.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/2a727d98a98442c8. Report an issue: GitHub.