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

Raised by the cached helper _load_ibm_db() when the ibm_db driver cannot be imported. Only the DB2 code path needs it, so the top-level sqlglot extra is not enough — the DB2-specific extra (database-db2 or database) must be installed. The helper is functools.cache'd, so after a failed attempt in the same process the ImportError is re-raised from cache; after installing the package you must restart the process.

Source

Thrown at private_gpt/components/tabular/database_query_generator.py:87

        format_missing_dependency_message(
            "Database query",
            extras=(
                "database-postgres",
                "database-mysql",
                "database-mssql",
                "database-db2",
                "database",
            ),
        )
    ) from e


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

    return ibm_db


class ErrorType(enum.StrEnum):
    UNKNOWN = "UNKNOWN"
    NOT_SUPPORTED_TYPE_MSSQL = "HY106"  # Error code for MSSQL unsupported type
    RETURNED_SQL_CURSOR = (
        "RETURNED_SQL_CURSOR"  # Postgres procedure returned a SQL cursor
    )
    INVALID_PARAM_MODE_DB2 = (
        "42886"  # DB2 procedure invalid parameter mode (e.g., OUT param used as IN)
    )

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Run: uv sync --inexact --extra database-db2 (or --extra database)
  2. Confirm the active interpreter matches the venv where ibm_db is installed: python -c "import ibm_db"
  3. Restart the application after installing (module-level and cached imports do not pick up new packages mid-process)

Example fix

# terminal — before: ValueError/ImportError on DB2 query
uv sync --inexact --extra database-db2
# after: restart app, DB2 queries proceed past driver load
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("ibm_db") is None:
    raise SystemExit(
        "DB2 support requires ibm_db: uv sync --inexact --extra database-db2"
    )

Type guard

def db2_driver_available() -> bool:
    import importlib.util
    return importlib.util.find_spec("ibm_db") is not None

Try / catch

try:
    sql = generator.generate(...)
except ImportError as e:
    if "database-db2" not in str(e):
        raise
    raise SystemExit("install extra: uv sync --inexact --extra database-db2") from e

Prevention

When it happens

Trigger: Configuring a DB2 connection (TSQL-adjacent DB2 dialect path) and executing a query, which triggers _load_ibm_db() without the ibm_db package installed.

Common situations: Installing --extra database-postgres for sqlglot but then pointing the connector at a DB2 URL; ibm_db installed in a different venv than the running app; platform wheels for ibm_db missing on the host.

Related errors

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