{"record":{"id":"9d81f35c929dce85","repo":"cocoindex-io/cocoindex","slug":"asyncpg-is-required-to-use-the-postgresql-connecto","errorCode":null,"errorMessage":"asyncpg is required to use the PostgreSQL connector. Please install cocoindex[postgres].","messagePattern":"asyncpg is required to use the PostgreSQL connector\\. Please install cocoindex\\[postgres\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/postgres/_target.py","lineNumber":36,"sourceCode":"import uuid\nfrom dataclasses import dataclass\nfrom typing import (\n    Any,\n    Callable,\n    Collection,\n    Generic,\n    Literal,\n    NamedTuple,\n    Sequence,\n)\n\n\nfrom typing_extensions import TypeVar\n\ntry:\n    import asyncpg  # type: ignore\nexcept ImportError as e:\n    raise ImportError(\n        \"asyncpg is required to use the PostgreSQL connector. \"\n        \"Please install cocoindex[postgres].\"\n    ) from e\n\nimport numpy as np\n\nimport cocoindex as coco\nfrom cocoindex.connectorkits import statediff, target\nfrom cocoindex.connectorkits.fingerprint import fingerprint_object\nfrom cocoindex._internal.datatype import (\n    AnyType,\n    MappingType,\n    SequenceType,\n    RecordType,\n    TypeChecker,\n    UnionType,\n    analyze_type_info,\n    is_record_type,","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/postgres/_target.py#L18-L54","documentation":"The PostgreSQL target connector depends on the asyncpg package, which is an optional dependency of cocoindex. Importing the connector without asyncpg installed raises ImportError with instructions to install the extra.","triggerScenarios":"Running `import cocoindex.connectors.postgres` (or code importing the _target module) in an environment where cocoindex was installed without the [postgres] extra.","commonSituations":"Fresh virtualenv or CI container with bare `pip install cocoindex`; deploying to a server where the extras group was omitted; switching Python environments.","solutions":["Run `pip install 'cocoindex[postgres]'` (or `uv add 'cocoindex[postgres]'`).","Verify with `python -c \"import asyncpg\"` that the dependency resolves in the active environment.","If deploying, add the postgres extra to your dependency/lock file."],"exampleFix":"// before\npip install cocoindex\n// after\npip install \"cocoindex[postgres]\"","handlingStrategy":"validation","validationCode":"try:\n    import asyncpg\nexcept ImportError:\n    raise SystemExit(\"Install with: pip install 'cocoindex[postgres]'\")","typeGuard":null,"tryCatchPattern":"try:\n    from cocoindex.connectors import postgres\nexcept ImportError as e:\n    if \"asyncpg is required\" in str(e):\n        raise SystemExit(\"Run: pip install 'cocoindex[postgres]'\") from e","preventionTips":["Install extras explicitly: cocoindex[postgres] in pyproject/requirements.","Pin dependencies and use a lockfile so CI matches local envs.","Smoke-test imports at application startup, not deep in a request path."],"tags":["python","dependency","import-error"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}