zylon-ai/private-gpt · error · ImportError

Database query dependencies are not installed. Install with

Error message

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

What it means

ImportError raised by _load_database_query_dependencies when private_gpt.components.tabular.database_query_generator cannot be imported. The database query tool's heavy dependencies (SQL drivers for postgres/mysql/mssql/db2) are optional extras, and the loader re-raises with a formatted message telling you which uv extra to install.

Source

Thrown at private_gpt/components/tools/builders/database_query_builder.py:60

        QueryResultType,
    )


def _load_database_query_dependencies() -> tuple[
    type["DatabaseQueryGenerator"],
    type["ErrorQueryResult"],
    type["QueryResult"],
    type["QueryResultType"],
]:
    try:
        from private_gpt.components.tabular.database_query_generator import (
            DatabaseQueryGenerator,
            ErrorQueryResult,
            QueryResult,
            QueryResultType,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Database query",
                extras=(
                    "database-postgres",
                    "database-mysql",
                    "database-mssql",
                    "database-db2",
                    "database",
                ),
            )
        ) from e

    return DatabaseQueryGenerator, ErrorQueryResult, QueryResult, QueryResultType


@singleton
class DatabaseQueryToolBuilder:
    """A builder class for creating a database query tool.

View on GitHub (pinned to 4a030776a3)

Solutions

Install the matching extra for your engine: uv sync --inexact --extra database-postgres (or database-mysql / database-mssql / database-db2).
If you need multiple engines or are unsure, install the aggregate extra: uv sync --inexact --extra database.
Verify the import works afterwards: python -c "from private_gpt.components.tabular.database_query_generator import DatabaseQueryGenerator".

Example fix

# before
uv sync --inexact

# after
uv sync --inexact --extra database-postgres

Defensive patterns

Strategy: type-guard

Validate before calling

def database_query_available() -> bool:
    try:
        from private_gpt.components.tabular.database_query_generator import DatabaseQueryGenerator  # noqa: F401
        return True
    except ImportError:
        return False

if not database_query_available():
    # skip registering the database query tool
    pass

Try / catch

try:
    tool = build_database_query_tool(...)
except ImportError as e:
    logger.warning("database query tool unavailable: %s", e)
    # register toolset without database query

Prevention

Install the extra matching your engine at image build time: uv sync --inexact --extra database-postgres.
Gate tool registration on an availability probe so missing deps degrade gracefully.
Document which extras each deployment profile needs.

When it happens

Trigger: Building or invoking the database query tool (database_query_builder) in an environment where none of the database-* optional extras were installed; the inner import of DatabaseQueryGenerator fails and is chained into this ImportError.

Common situations: Fresh install with only the base extras; CI image trimmed of optional deps; switching from a full 'database' extra install to a leaner environment; adding the database query tool to a deployment without updating the sync command.

Related errors

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