Graphify-Labs/graphify · error · ImportError

psycopg is required for --postgres. Install with: pip instal

Error message

psycopg is required for --postgres. Install with: pip install 'graphifyy[postgres]'

What it means

ImportError raised when --postgres extraction is requested but the optional psycopg (v3) driver is missing (pg_introspect.py:12-17). The message points at the graphifyy[postgres] extra. Note it catches ModuleNotFoundError specifically, so a broken psycopg install also surfaces here.

Source

Thrown at graphify/pg_introspect.py:16

from __future__ import annotations
from pathlib import Path, PurePosixPath
from graphify.extract import extract_sql


def _quote_ident(name: str) -> str:
    """Double-quote a PostgreSQL identifier, escaping embedded double-quotes."""
    return '"' + name.replace('"', '""') + '"'


def introspect_postgres(dsn: str | None = None) -> dict:
    """Connect to PostgreSQL, reconstruct DDL, and extract via extract_sql()."""
    try:
        import psycopg
    except ModuleNotFoundError:
        raise ImportError(
            "psycopg is required for --postgres. "
            "Install with: pip install 'graphifyy[postgres]'"
        )

    try:
        conn = psycopg.connect(dsn or "")  # empty string = PG* env vars
    except psycopg.OperationalError as exc:
        # Sanitize: strip the DSN/credentials that psycopg may embed in the
        # OperationalError message (e.g. "connection to server … failed: …\nDETAIL: …")
        msg = str(exc).split("\n")[0]
        raise ConnectionError(f"could not connect to PostgreSQL: {msg}") from None

    try:
        conn.execute("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE READ ONLY DEFERRABLE")

        # 1. Query tables
        with conn.cursor() as cur:
            cur.execute("""

View on GitHub (pinned to 7fe58b0b0f)

Solutions

Install the extra: `pip install 'graphifyy[postgres]'` (or plain `pip install psycopg` - note: psycopg, not psycopg2).
If psycopg2 is what is installed, either add psycopg 3 or adapt tooling; graphify requires the v3 package.
Verify in the same interpreter: `python -c "import psycopg"`.

Example fix

# before
$ graphify extract --postgres   # ImportError: psycopg required

# after
$ pip install 'graphifyy[postgres]'
$ graphify extract --postgres --dsn "postgresql://user:pass@host/db"

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("psycopg") is None:
    raise SystemExit("--postgres needs psycopg (v3): pip install 'graphifyy[postgres]'")

Try / catch

try:
    schema = introspect_postgres(dsn)
except ImportError as exc:
    if "psycopg" in str(exc):
        raise SystemExit(f"Missing optional dep: {exc}") from exc
    raise

Prevention

Do not assume psycopg2 covers it - this code imports psycopg 3.
Add DB extras to the same install command as graphify in deploy scripts.
Keep DSNs in PG* env vars so the same command works across environments.

When it happens

Trigger: Running graphify with --postgres (introspect_postgres) when `import psycopg` raises ModuleNotFoundError. The DSN comes from the argument or PG* env vars; the import happens before any connection attempt.

Common situations: Using --postgres on a base install without extras; environments where psycopg2 (v2) is installed and the user assumes coverage - psycopg 3 is a separate package; CI images trimmed of optional deps.

Related errors

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/2b81e4c5b4cf72ea. Report an issue: GitHub.