{"record":{"id":"00a09ccd5fda66fa","repo":"zylon-ai/private-gpt","slug":"postgres-client-dependencies-are-not-installed-in","errorCode":null,"errorMessage":"Postgres client dependencies are not installed. Install with one of: `uv sync --inexact --extra database-postgres` or `uv sync --inexact --extra nodestore-postgres`.","messagePattern":"Postgres client dependencies are not installed\\. Install with one of: `uv sync --inexact --extra database-postgres` or `uv sync --inexact --extra nodestore-postgres`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/postgres/postgres_client.py","lineNumber":8,"sourceCode":"import logging\nimport threading\nfrom importlib.util import find_spec\n\nfrom private_gpt.utils.dependencies import format_missing_dependency_message\n\nif find_spec(\"psycopg2\") is None or find_spec(\"sqlalchemy\") is None:\n    raise ImportError(\n        format_missing_dependency_message(\n            \"Postgres client\",\n            extras=(\"database-postgres\", \"nodestore-postgres\"),\n        )\n    )\n\nfrom sqlalchemy import create_engine\nfrom sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom sqlalchemy.orm import Session, sessionmaker\n\nfrom private_gpt.settings.settings import Settings\n\nlogger = logging.getLogger(__name__)\nlogger.setLevel(logging.DEBUG)\n\n\nclass PostgresClient:\n    def __init__(self, settings: Settings):","sourceCodeStart":1,"sourceCodeEnd":26,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/postgres/postgres_client.py#L1-L26","documentation":"Module-level import guard in postgres_client.py: at import time it uses `find_spec` to check for `psycopg2` and `sqlalchemy`; if either is absent it raises ImportError with an install hint naming the `database-postgres` and `nodestore-postgres` extras. Because it runs at import, merely importing this module (transitively, when postgres is configured) fails in environments missing the optional deps.","triggerScenarios":"Configuring postgres as database provider or node store in an environment installed without the extras; any code path importing `private_gpt.components.postgres.postgres_client` (e.g. persistence component's postgres branch, node store's postgres provider) triggers the check at import.","commonSituations":"Minimal installs (`uv sync` without extras) then flipping settings to postgres; slim Docker images; CI jobs testing non-postgres paths that accidentally import the module.","solutions":["Install the extra: `uv sync --inexact --extra database-postgres` (or `nodestore-postgres` if only node store needs it)","If psycopg2 binary wheels are a problem on your platform, install `psycopg2-binary` or build deps accordingly","Keep the provider setting consistent with installed extras to avoid importing this module unconditionally"],"exampleFix":"# before\nuv sync --inexact\n# settings: database.provider=postgres -> ImportError\n\n# after\nuv sync --inexact --extra database-postgres","handlingStrategy":"validation","validationCode":"from importlib.util import find_spec\n\nif settings.database.provider == \"postgres\" or settings.node_store.index_store == \"postgres\":\n    missing = [m for m in (\"psycopg2\", \"sqlalchemy\") if find_spec(m) is None]\n    if missing:\n        raise SystemExit(f\"missing {missing}; run: uv sync --inexact --extra database-postgres\")","typeGuard":null,"tryCatchPattern":"try:\n    from private_gpt.components.postgres import postgres_client\nexcept ImportError as e:\n    raise SystemExit(str(e)) from e  # surfaces the exact uv sync command","preventionTips":["Install extras in lockstep with settings changes; put both in the same PR","Add CI matrix jobs covering each extras combination you deploy"],"tags":["dependency","optional-extra","postgres","import-guard","packaging"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}