cocoindex-io/cocoindex · error · ImportError

asyncpg is required to use the PostgreSQL source connector.

Error message

asyncpg is required to use the PostgreSQL source connector. Please install cocoindex[postgres].

What it means

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.

Source

Thrown at python/cocoindex/connectors/postgres/_source.py:36

    overload,
)

from typing_extensions import TypeVar

import re

from cocoindex._internal.datatype import RecordType, is_record_type
from cocoindex._internal.stable_path import StableKey
from cocoindex.connectorkits.async_adapters import async_to_sync_iter


# Valid SQL identifier pattern: starts with letter or underscore, contains only letters, digits, underscores, or $ (for temp tables)
_VALID_IDENTIFIER_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_$]*$")

try:
    import asyncpg  # type: ignore
except ImportError as e:
    raise ImportError(
        "asyncpg is required to use the PostgreSQL source connector. "
        "Please install cocoindex[postgres]."
    ) from e


RowT = TypeVar("RowT", default=dict[str, Any])


def _validate_identifier(name: str, identifier_type: str) -> None:
    """Validate that a string is a valid SQL identifier."""
    if not name:
        raise ValueError(f"{identifier_type} cannot be empty")
    if not _VALID_IDENTIFIER_RE.match(name):
        raise ValueError(
            f"Invalid {identifier_type}: '{name}'. "
            f"Must start with a letter or underscore and contain only letters, digits, underscores, or $"
        )

View on GitHub (pinned to e84aa99b32)

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.

Example fix

// before
pip install cocoindex
// after
pip install "cocoindex[postgres]"

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("asyncpg") is None:
    raise SystemExit("Install the postgres extra: pip install 'cocoindex[postgres]'")

Try / catch

try:
    from cocoindex.connectors import postgres
except ImportError as e:
    raise SystemExit(f"Postgres connector unavailable: {e}") from e

Prevention

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.

When it happens

Trigger: Importing cocoindex.connectors.postgres._source (or the postgres connector package) in an environment without asyncpg installed.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/af42c3ade6799b02. Report an issue: GitHub.