{"record":{"id":"af42c3ade6799b02","repo":"cocoindex-io/cocoindex","slug":"asyncpg-is-required-to-use-the-postgresql-source-c","errorCode":null,"errorMessage":"asyncpg is required to use the PostgreSQL source connector. Please install cocoindex[postgres].","messagePattern":"asyncpg is required to use the PostgreSQL source connector\\. Please install cocoindex\\[postgres\\]\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/postgres/_source.py","lineNumber":36,"sourceCode":"    overload,\n)\n\nfrom typing_extensions import TypeVar\n\nimport re\n\nfrom cocoindex._internal.datatype import RecordType, is_record_type\nfrom cocoindex._internal.stable_path import StableKey\nfrom cocoindex.connectorkits.async_adapters import async_to_sync_iter\n\n\n# Valid SQL identifier pattern: starts with letter or underscore, contains only letters, digits, underscores, or $ (for temp tables)\n_VALID_IDENTIFIER_RE = re.compile(r\"^[a-zA-Z_][a-zA-Z0-9_$]*$\")\n\ntry:\n    import asyncpg  # type: ignore\nexcept ImportError as e:\n    raise ImportError(\n        \"asyncpg is required to use the PostgreSQL source connector. \"\n        \"Please install cocoindex[postgres].\"\n    ) from e\n\n\nRowT = TypeVar(\"RowT\", default=dict[str, Any])\n\n\ndef _validate_identifier(name: str, identifier_type: str) -> None:\n    \"\"\"Validate that a string is a valid SQL identifier.\"\"\"\n    if not name:\n        raise ValueError(f\"{identifier_type} cannot be empty\")\n    if not _VALID_IDENTIFIER_RE.match(name):\n        raise ValueError(\n            f\"Invalid {identifier_type}: '{name}'. \"\n            f\"Must start with a letter or underscore and contain only letters, digits, underscores, or $\"\n        )\n","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/postgres/_source.py#L18-L54","documentation":"The PostgreSQL source connector requires the asyncpg driver. The module imports asyncpg in a try/except and raises ImportError at import time with instructions to install cocoindex[postgres] if it is absent.","triggerScenarios":"Importing cocoindex.connectors.postgres._source (or the postgres connector package) in an environment without asyncpg installed.","commonSituations":"Base cocoindex install without the postgres extra; fresh CI/dev container missing optional deps; switching from the target-only postgres connector (different dep) to the source connector.","solutions":["Install the extra: pip install \"cocoindex[postgres]\" (or uv add \"cocoindex[postgres]\").","Install asyncpg directly: pip install asyncpg.","Remove the postgres source connector usage if PostgreSQL is not needed."],"exampleFix":"// before\npip install cocoindex\n// after\npip install \"cocoindex[postgres]\"","handlingStrategy":"fallback","validationCode":"import importlib.util\nif importlib.util.find_spec(\"asyncpg\") is None:\n    raise SystemExit(\"Install the postgres extra: pip install 'cocoindex[postgres]'\")","typeGuard":null,"tryCatchPattern":"try:\n    from cocoindex.connectors import postgres\nexcept ImportError as e:\n    raise SystemExit(f\"Postgres connector unavailable: {e}\") from e","preventionTips":["Add \"cocoindex[postgres]\" to your dependency manifest wherever the pipeline uses Postgres.","Verify installed deps in the Docker image / CI before running pipelines.","Document required extras next to each connector usage in your codebase."],"tags":["python","import-error","optional-dependency","postgres"],"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"}