nl2data-postgres 0.1.0__py3-none-any.whl

nl2data_postgres/__init__.py

@@ -0,0 +1,26 @@
+"""PostgreSQL metadata discovery and governed SQL execution for nl2data-core.
+
+The package implements the core ``MetadataDiscoverer`` and ``QueryAdapter``
+ports using ``psycopg``.  The driver is never imported at package import
+time; it is loaded lazily when a discoverer or adapter is first used.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .config import PostgresAdapterConfig
+
+__all__ = ["PostgresAdapterConfig"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "PostgresMetadataDiscoverer":
+        from .discovery import PostgresMetadataDiscoverer
+
+        return PostgresMetadataDiscoverer
+    if name == "PostgresQueryAdapter":
+        from .adapter import PostgresQueryAdapter
+
+        return PostgresQueryAdapter
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nl2data_postgres/adapter.py

@@ -0,0 +1,215 @@
+"""PostgreSQL ``QueryAdapter`` port implementation."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from typing import Any
+
+from nl2data_core.adapters.models import (
+    AdapterCapabilities,
+    AdapterLimits,
+    AsyncMode,
+    CostEstimate,
+    ExecutionResult,
+    GeneratedArtifact,
+    ParsedArtifact,
+    ValidatedArtifact,
+    ValidationContext,
+)
+from nl2data_core.adapters.sql.guard import SQLGuardPolicy, assert_guarded
+from nl2data_core.adapters.sql.parsing import parse_sql
+from nl2data_core.metadata.protocol import MetadataDiscoveryCapability
+from sqlglot import exp
+
+from .config import PostgresAdapterConfig
+from .errors import PostgresAdapterError
+from .execution import PostgresExecutor
+
+
+class PostgresQueryAdapter:
+    """Read-only, single-statement PostgreSQL adapter over the core contract."""
+
+    def __init__(
+        self,
+        config: PostgresAdapterConfig,
+        *,
+        allowed_objects: frozenset[str] = frozenset(),
+        allowed_columns: frozenset[str] | None = None,
+        require_limit: bool = True,
+        snapshot_fingerprint: str | None = None,
+    ) -> None:
+        self._config = config
+        self._policy = SQLGuardPolicy(
+            allowed_objects=allowed_objects,
+            allowed_columns=allowed_columns,
+            max_rows=config.max_rows,
+            require_limit=require_limit,
+        )
+        self._snapshot_fingerprint = snapshot_fingerprint
+        self._executor = PostgresExecutor(config)
+        self._parsed_by_id: dict[str, Any] = {}
+        self._sql_by_id: dict[str, str] = {}
+
+    def capabilities(self) -> AdapterCapabilities:
+        return AdapterCapabilities(
+            adapter_type="sql",
+            query_language="sql",
+            async_mode=AsyncMode.THREAD_OFFLOAD,
+            features=frozenset(
+                {
+                    "read_only",
+                    "single_statement",
+                    "bounded_results",
+                    "ast_validation",
+                    "aggregation",
+                    "ordering",
+                    "list_ops",
+                    "contains",
+                    "metadata_discovery",
+                    "join",
+                    "multi_entity",
+                    "cte",
+                    "grouping",
+                    "union",
+                    "computed_expressions",
+                    "prior_period",
+                }
+            ),
+            limits=AdapterLimits(
+                max_query_length=self._config.max_query_length,
+                max_result_rows=self._policy.max_rows,
+            ),
+        )
+
+    def metadata_discovery_capability(self) -> MetadataDiscoveryCapability:
+        return MetadataDiscoveryCapability(
+            backend="sql:postgresql",
+            supported=True,
+            max_objects=1_024,
+            max_fields_per_object=16_384,
+            supports_statistics=True,
+            supports_sampling=False,
+            description="bounded postgresql catalog introspection",
+        )
+
+    def parse(self, query: str, context: ValidationContext) -> ParsedArtifact:
+        parsed = parse_sql(
+            query,
+            dialect="postgres",
+            artifact_id=f"pg-{len(self._parsed_by_id) + 1}",
+            max_query_length=self._config.max_query_length,
+        )
+        self._parsed_by_id[parsed.artifact_id] = parsed
+        return ParsedArtifact(
+            artifact_id=parsed.artifact_id,
+            fingerprint=parsed.fingerprint,
+            parse_metadata={
+                "statement_type": parsed.statement_type,
+                "tables": ",".join(parsed.tables),
+                "dialect": parsed.dialect,
+            },
+        )
+
+    def _obligation_policy(self, context: ValidationContext) -> SQLGuardPolicy:
+        if not context.required_obligation_fingerprints:
+            return self._policy
+        return replace(
+            self._policy,
+            required_obligation_fingerprints=(
+                self._policy.required_obligation_fingerprints
+                | context.required_obligation_fingerprints
+            ),
+        )
+
+    def validate(self, artifact: ParsedArtifact, context: ValidationContext) -> ValidatedArtifact:
+        parsed = self._parsed_by_id.get(artifact.artifact_id)
+        if parsed is None:
+            raise PostgresAdapterError(
+                "cannot validate an artifact that was not parsed by this adapter",
+                details={"artifact_id": artifact.artifact_id},
+            )
+        if (
+            self._snapshot_fingerprint is not None
+            and context.snapshot_fingerprint is not None
+            and context.snapshot_fingerprint != self._snapshot_fingerprint
+        ):
+            raise PostgresAdapterError(
+                "the metadata snapshot does not match the adapter's bound snapshot",
+                details={"artifact_id": artifact.artifact_id},
+            )
+        guard = assert_guarded(
+            parsed,
+            self._obligation_policy(context),
+            statement=exp.maybe_parse(parsed.sql_text, dialect="postgres"),
+            field_bindings=context.field_bindings,
+        )
+        self._sql_by_id[artifact.artifact_id] = parsed.sql_text
+        return ValidatedArtifact(
+            artifact_id=artifact.artifact_id,
+            fingerprint=guard.fingerprint,
+            snapshot_fingerprint=context.snapshot_fingerprint,
+            validation_metadata={
+                "tables": ",".join(parsed.tables),
+                "limit": str(parsed.limit_value or 0),
+                "columns": ",".join(parsed.columns),
+            },
+            obligations_verified=guard.obligations_verified,
+            bounded_rows=parsed.limit_value,
+        )
+
+    async def generate(self, query: str, context: ValidationContext) -> GeneratedArtifact:
+        parsed = parse_sql(
+            query,
+            dialect="postgres",
+            artifact_id=f"pg-{len(self._parsed_by_id) + 1}",
+            max_query_length=self._config.max_query_length,
+        )
+        guard = assert_guarded(
+            parsed,
+            self._obligation_policy(context),
+            statement=exp.maybe_parse(parsed.sql_text, dialect="postgres"),
+            field_bindings=context.field_bindings,
+        )
+        self._parsed_by_id[parsed.artifact_id] = parsed
+        self._sql_by_id[parsed.artifact_id] = parsed.sql_text
+        return GeneratedArtifact(
+            artifact_id=parsed.artifact_id,
+            fingerprint=guard.fingerprint,
+            content_type="text/sql",
+            size_bytes=len(parsed.sql_text.encode("utf-8")),
+            metadata={"dialect": parsed.dialect},
+        )
+
+    async def estimate_cost(
+        self, artifact: ValidatedArtifact, context: ValidationContext
+    ) -> CostEstimate:
+        parsed = self._parsed_by_id.get(artifact.artifact_id)
+        if parsed is None:
+            raise PostgresAdapterError(
+                "cannot estimate an artifact that was not parsed by this adapter",
+                details={"artifact_id": artifact.artifact_id},
+            )
+        return CostEstimate(estimated_units=parsed.limit_value or self._policy.max_rows)
+
+    async def execute(
+        self, artifact: ValidatedArtifact, context: ValidationContext
+    ) -> ExecutionResult:
+        sql_text = self._sql_by_id.get(artifact.artifact_id)
+        if sql_text is None:
+            raise PostgresAdapterError(
+                "cannot execute an artifact that was not validated by this adapter",
+                details={"artifact_id": artifact.artifact_id},
+            )
+        return await asyncio.to_thread(
+            self._executor.execute,
+            sql_text,
+            max_rows=context.limits.max_result_rows if context.limits else self._policy.max_rows,
+            max_result_bytes=context.max_result_bytes,
+            timeout_seconds=context.execution_timeout_seconds,
+        )
+
+    async def close(self) -> None:
+        self._parsed_by_id.clear()
+        self._sql_by_id.clear()
+        self._executor.close()

nl2data_postgres/client.py

@@ -0,0 +1,121 @@
+"""Lazy psycopg client loading and bounded read-only connection helpers."""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+from collections.abc import Iterator
+from importlib import import_module
+from importlib.util import find_spec
+from typing import Any
+
+from nl2data.errors import NL2DataError
+from nl2data_core.metadata.protocol import (
+    MetadataDiscoveryError,
+    MetadataUnauthorizedError,
+    MetadataUnavailableError,
+)
+
+from .config import PostgresAdapterConfig
+
+_AUTH_SQLSTATES = frozenset({"28P01", "42501", "42502"})
+
+
+def _pool_module() -> Any:
+    """Return the psycopg_pool module, raising a safe error if absent."""
+    if find_spec("psycopg_pool") is None:
+        raise MetadataUnavailableError(
+            "the psycopg pool driver is not installed; install the 'postgres' extra",
+            details={"cause_type": "ImportError"},
+        )
+    return import_module("psycopg_pool")
+
+
+def _raise_normalized_discovery_error(error: BaseException, message: str) -> None:
+    """Normalize a psycopg failure into the safe discovery error family."""
+    cause_type = error.__class__.__name__
+    sqlstate = getattr(error, "sqlstate", None)
+    if sqlstate in _AUTH_SQLSTATES or cause_type in {
+        "InsufficientPrivilege",
+        "InvalidPassword",
+        "PasswordMismatch",
+    }:
+        raise MetadataUnauthorizedError(message, details={"cause_type": cause_type}) from error
+    if cause_type in {
+        "OperationalError",
+        "InterfaceError",
+        "ConnectionError",
+        "PoolTimeout",
+    }:
+        raise MetadataUnavailableError(message, details={"cause_type": cause_type}) from error
+    raise MetadataDiscoveryError(message, details={"cause_type": cause_type}) from error
+
+
+class PostgresPool:
+    """A lazily-created bounded psycopg connection pool.
+
+    The pool is created only on first use and is closed idempotently.
+    DSN resolution and driver loading happen lazily, so importing this
+    module does not require ``psycopg``.
+    """
+
+    def __init__(self, config: PostgresAdapterConfig) -> None:
+        self._config = config
+        self._pool: Any | None = None
+        self._lock = threading.Lock()
+
+    def _connect_timeout(self) -> float:
+        return min(self._config.timeout_seconds, 5.0)
+
+    def _ensure_pool(self) -> Any:
+        if self._pool is not None:
+            return self._pool
+        with self._lock:
+            if self._pool is not None:
+                return self._pool
+            pool_module = _pool_module()
+            try:
+                dsn = self._config.resolve_dsn()
+            except ValueError as error:
+                raise MetadataUnavailableError(
+                    "postgresql dsn reference could not be resolved",
+                    details={"cause_type": type(error).__name__},
+                ) from error
+            try:
+                self._pool = pool_module.ConnectionPool(
+                    dsn,
+                    min_size=self._config.pool_min_size,
+                    max_size=self._config.pool_max_size,
+                    open=True,
+                    kwargs={"connect_timeout": self._connect_timeout()},
+                )
+                self._pool.wait(timeout=self._connect_timeout())
+            except Exception as error:
+                self._pool = None
+                _raise_normalized_discovery_error(error, "could not connect to postgresql")
+            return self._pool
+
+    @contextlib.contextmanager
+    def connection(self) -> Iterator[Any]:
+        """Yield a read-only or standard connection from the pool."""
+        pool = self._ensure_pool()
+        connection: Any | None = None
+        try:
+            with pool.connection() as connection:
+                if self._config.read_only:
+                    connection.execute("SET TRANSACTION READ ONLY")
+                yield connection
+        except NL2DataError:
+            raise
+        except Exception as error:
+            if connection is None:
+                _raise_normalized_discovery_error(error, "could not obtain a postgresql connection")
+            _raise_normalized_discovery_error(error, "postgresql operation failed")
+
+    def close(self) -> None:
+        """Release the pool idempotently."""
+        with self._lock:
+            if self._pool is not None:
+                with contextlib.suppress(Exception):
+                    self._pool.close()
+                self._pool = None

nl2data_postgres/config.py

@@ -0,0 +1,109 @@
+"""Bounded, credential-free PostgreSQL adapter configuration.
+
+DSNs are host-injected references (for example ``env:VAR_NAME``) rather
+than raw connection strings, so configuration stays fingerprintable and
+safe to serialize.  The package resolves the reference at runtime.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from nl2data_core.canonical import strict_sha256_fingerprint
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+_MAX_QUERY_LENGTH = 10_000
+_MAX_RESULT_ROWS = 100_000
+_MAX_RESULT_BYTES = 10_485_760
+_MAX_TIMEOUT_SECONDS = 3600.0
+_MAX_OBJECTS = 1_024
+_MAX_FIELDS_PER_OBJECT = 16_384
+_MAX_STATISTICS = 8_192
+
+
+class PostgresAdapterConfig(BaseModel):
+    """Bounded PostgreSQL discovery and execution configuration.
+
+    ``dsn_reference`` is a host-injected DSN reference such as
+    ``env:NL2DATA_POSTGRES_DSN``.  The reference is resolved lazily at
+    runtime; the configuration object never carries a raw password or
+    connection string.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    dsn_reference: str = Field(min_length=1, max_length=512)
+    schema_name: str | None = Field(default=None, min_length=1, max_length=128)
+    allowed_objects: frozenset[str] = Field(default_factory=frozenset, max_length=_MAX_OBJECTS)
+    allowed_fields: frozenset[str] = Field(
+        default_factory=frozenset, max_length=_MAX_FIELDS_PER_OBJECT
+    )
+    max_objects: int = Field(default=256, ge=1, le=_MAX_OBJECTS)
+    max_fields_per_object: int = Field(default=1_024, ge=1, le=_MAX_FIELDS_PER_OBJECT)
+    max_statistics: int = Field(default=1_024, ge=0, le=_MAX_STATISTICS)
+    include_statistics: bool = True
+    timeout_seconds: float = Field(default=30.0, gt=0.0, le=_MAX_TIMEOUT_SECONDS)
+    max_query_length: int = Field(default=_MAX_QUERY_LENGTH, ge=1, le=1_000_000)
+    max_rows: int = Field(default=_MAX_RESULT_ROWS, ge=1, le=1_000_000_000)
+    max_result_bytes: int = Field(default=_MAX_RESULT_BYTES, ge=1, le=1_073_741_824)
+    pool_min_size: int = Field(default=1, ge=0, le=64)
+    pool_max_size: int = Field(default=4, ge=1, le=128)
+    read_only: bool = True
+    source_id: str | None = Field(default=None, min_length=1, max_length=128)
+
+    @field_validator("allowed_objects", "allowed_fields")
+    @classmethod
+    def _bounded_identifiers(cls, value: frozenset[str]) -> frozenset[str]:
+        import re
+
+        pattern = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-\.]{0,127}$")
+        for identifier in value:
+            if pattern.fullmatch(identifier) is None:
+                raise ValueError("allowlist entries must be bounded identifiers")
+        return value
+
+    @field_validator("pool_max_size")
+    @classmethod
+    def _pool_size_consistent(cls, value: int, info: Any) -> int:
+        if (info.data.get("pool_min_size") or 0) > value:
+            raise ValueError("pool_min_size cannot exceed pool_max_size")
+        return value
+
+    def resolve_dsn(self) -> str:
+        """Resolve the host-injected DSN reference to a connection string."""
+        reference = self.dsn_reference.strip()
+        if reference.startswith("env:"):
+            env_name = reference[4:]
+            env_value = os.environ.get(env_name)
+            if env_value is None:
+                raise ValueError(f"DSN environment variable '{env_name}' is not set")
+            return env_value
+        if reference.startswith("dsn:"):
+            return reference[4:]
+        return reference
+
+    def safe_payload(self) -> dict[str, Any]:
+        """Safe, credential-free serialization of bounded settings."""
+        return {
+            "dsn_reference": self.dsn_reference,
+            "schema_name": self.schema_name,
+            "allowed_objects": sorted(self.allowed_objects),
+            "allowed_fields": sorted(self.allowed_fields),
+            "max_objects": self.max_objects,
+            "max_fields_per_object": self.max_fields_per_object,
+            "max_statistics": self.max_statistics,
+            "include_statistics": self.include_statistics,
+            "timeout_seconds": self.timeout_seconds,
+            "max_query_length": self.max_query_length,
+            "max_rows": self.max_rows,
+            "max_result_bytes": self.max_result_bytes,
+            "pool_min_size": self.pool_min_size,
+            "pool_max_size": self.pool_max_size,
+            "read_only": self.read_only,
+            "source_id": self.source_id,
+        }
+
+    def fingerprint(self) -> str:
+        """Stable fingerprint of this configuration; no secrets included."""
+        return strict_sha256_fingerprint(self.safe_payload())

nl2data_postgres/discovery.py

@@ -0,0 +1,351 @@
+"""PostgreSQL metadata discovery behind the provider-neutral core contract."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from typing import Any
+
+from nl2data_core.canonical import strict_sha256_fingerprint
+from nl2data_core.metadata.models import (
+    MetadataConstraint,
+    MetadataConstraintKind,
+    MetadataEvidence,
+    MetadataField,
+    MetadataFreshness,
+    MetadataObject,
+    MetadataObjectKind,
+    MetadataProvenance,
+    MetadataRelationship,
+    MetadataRelationshipKind,
+    MetadataSnapshot,
+    MetadataSourceReference,
+    MetadataStatistic,
+    MetadataStatisticKind,
+    MetadataTrustLevel,
+)
+from nl2data_core.metadata.protocol import (
+    MetadataDiscoveryCapability,
+    MetadataDiscoveryConfig,
+    MetadataDiscoveryError,
+    MetadataUnauthorizedError,
+)
+
+from .client import PostgresPool
+from .config import PostgresAdapterConfig
+
+_IDENTIFIER_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-\.]{0,127}$")
+
+
+def _quote_ident(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _sql_type(declared: str) -> str:
+    """Normalize a declared SQL type into a bounded canonical name."""
+    base = declared.split("(", 1)[0].strip().upper()
+    aliases = {
+        "CHARACTER VARYING": "VARCHAR",
+        "CHAR VARYING": "VARCHAR",
+        "CHARACTER": "CHAR",
+        "DOUBLE PRECISION": "DOUBLE",
+        "TIMESTAMP WITHOUT TIME ZONE": "TIMESTAMP",
+        "TIMESTAMP WITH TIME ZONE": "TIMESTAMPTZ",
+    }
+    base = aliases.get(base, base)
+    return base[:64] or "UNKNOWN"
+
+
+class PostgresMetadataDiscoverer:
+    """Read-only PostgreSQL metadata discovery over the core contract."""
+
+    def __init__(
+        self,
+        config: PostgresAdapterConfig,
+        *,
+        allowed_objects: frozenset[str] = frozenset(),
+        allowed_fields: frozenset[str] = frozenset(),
+    ) -> None:
+        self._config = config
+        self._allowed_objects = allowed_objects
+        self._allowed_fields = allowed_fields
+        self._pool = PostgresPool(config)
+
+    def capability(self) -> MetadataDiscoveryCapability:
+        """Declare the discovery bounds this backend supports."""
+        return MetadataDiscoveryCapability(
+            backend="sql:postgresql",
+            supported=True,
+            max_objects=1_024,
+            max_fields_per_object=16_384,
+            supports_statistics=True,
+            supports_sampling=False,
+            description="bounded postgresql catalog introspection",
+        )
+
+    async def discover(self, config: MetadataDiscoveryConfig) -> MetadataSnapshot:
+        """Discover a bounded canonical snapshot of the configured source."""
+        effective_objects = (
+            self._allowed_objects & config.allowed_objects
+            if config.allowed_objects
+            else self._allowed_objects
+        )
+        if not effective_objects:
+            raise MetadataUnauthorizedError(
+                "no objects are authorized for metadata discovery",
+                details={"authorized_objects": str(len(self._allowed_objects))},
+            )
+        return await asyncio.to_thread(
+            self._discover_sync, config, effective_objects, self._allowed_fields
+        )
+
+    async def close(self) -> None:
+        """Release the underlying connection pool."""
+        self._pool.close()
+
+
+    def _discover_sync(
+        self,
+        config: MetadataDiscoveryConfig,
+        allowed_objects: frozenset[str],
+        allowed_fields: frozenset[str],
+    ) -> MetadataSnapshot:
+        """Synchronous PostgreSQL discovery using the discoverer's bounded pool."""
+        with self._pool.connection() as connection:
+            return _introspect(connection, self._config, config, allowed_objects, allowed_fields)
+
+
+def _introspect(
+    connection: Any,
+    pg_config: PostgresAdapterConfig,
+    config: MetadataDiscoveryConfig,
+    allowed_objects: frozenset[str],
+    allowed_fields: frozenset[str],
+) -> MetadataSnapshot:
+    schema = pg_config.schema_name or "public"
+    objects: list[MetadataObject] = []
+    relationships: list[MetadataRelationship] = []
+    evidence: list[MetadataEvidence] = []
+    bounded_objects = False
+    bounded_fields = False
+    bounded_samples = False
+    statistic_count = 0
+    deadline = time.monotonic() + config.timeout_seconds
+
+    timeout_ms = max(1, int(config.timeout_seconds * 1000))
+    connection.execute(f"SET statement_timeout = {timeout_ms}")
+
+    rows = connection.execute(
+        "SELECT table_name, table_type FROM information_schema.tables "
+        "WHERE table_schema = %s AND table_type IN ('BASE TABLE', 'VIEW') "
+        "ORDER BY table_name",
+        (schema,),
+    ).fetchall()
+    catalog_objects = [
+        (str(name), str(kind))
+        for name, kind in rows
+        if _IDENTIFIER_PATTERN.fullmatch(str(name)) is not None
+    ]
+    selected = [(name, kind) for name, kind in catalog_objects if name in allowed_objects]
+    if len(selected) > config.max_objects:
+        selected = selected[: config.max_objects]
+        bounded_objects = True
+
+    for name, kind in selected:
+        if time.monotonic() >= deadline:
+            raise MetadataDiscoveryError(
+                "metadata discovery exceeded the authorized timeout",
+                details={"timeout_seconds": str(config.timeout_seconds)},
+            )
+        object_kind = MetadataObjectKind.VIEW if kind == "VIEW" else MetadataObjectKind.TABLE
+        columns = connection.execute(
+            "SELECT column_name, data_type, is_nullable "
+            "FROM information_schema.columns "
+            "WHERE table_schema = %s AND table_name = %s "
+            "ORDER BY ordinal_position",
+            (schema, name),
+        ).fetchall()
+        if len(columns) > config.max_fields_per_object:
+            columns = columns[: config.max_fields_per_object]
+            bounded_fields = True
+
+        fields: list[MetadataField] = []
+        for column in columns:
+            column_name = str(column[0])
+            if _IDENTIFIER_PATTERN.fullmatch(column_name) is None:
+                bounded_fields = True
+                continue
+            if config.allowed_fields and column_name not in config.allowed_fields:
+                continue
+            if allowed_fields and column_name not in allowed_fields:
+                continue
+            fields.append(
+                MetadataField(
+                    field_id=column_name,
+                    object_id=name,
+                    path=column_name,
+                    data_type=_sql_type(str(column[1] or "UNKNOWN")),
+                    nullable=str(column[2]).lower() != "no",
+                    trust_level=MetadataTrustLevel.DECLARED,
+                )
+            )
+        field_evidence = MetadataEvidence(
+            evidence_id=f"pg-obj-{name}",
+            kind="object",
+            reference=strict_sha256_fingerprint(
+                {"object": name, "fields": sorted(field.field_id for field in fields)}
+            ),
+            description="postgresql catalog object observation",
+        )
+        evidence.append(field_evidence)
+
+        constraints: list[MetadataConstraint] = []
+        pk_rows = connection.execute(
+            "SELECT kcu.column_name "
+            "FROM information_schema.table_constraints tc "
+            "JOIN information_schema.key_column_usage kcu "
+            "  ON kcu.constraint_name = tc.constraint_name "
+            " AND kcu.table_schema = tc.table_schema "
+            "WHERE tc.table_schema = %s AND tc.table_name = %s "
+            "  AND tc.constraint_type = 'PRIMARY KEY' "
+            "ORDER BY kcu.ordinal_position",
+            (schema, name),
+        ).fetchall()
+        primary_fields = [str(row[0]) for row in pk_rows if row[0] is not None]
+        if primary_fields:
+            constraints.append(
+                MetadataConstraint(
+                    constraint_id=f"{name}_pk",
+                    kind=MetadataConstraintKind.PRIMARY_KEY,
+                    fields=frozenset(primary_fields),
+                    trust_level=MetadataTrustLevel.DECLARED,
+                )
+            )
+        unique_by_name: dict[str, list[str]] = {}
+        for constraint_name, column_name in connection.execute(
+            "SELECT tc.constraint_name, kcu.column_name "
+            "FROM information_schema.table_constraints tc "
+            "JOIN information_schema.key_column_usage kcu "
+            "  ON kcu.constraint_name = tc.constraint_name "
+            " AND kcu.table_schema = tc.table_schema "
+            "WHERE tc.table_schema = %s AND tc.table_name = %s "
+            "  AND tc.constraint_type = 'UNIQUE' "
+            "ORDER BY tc.constraint_name, kcu.ordinal_position",
+            (schema, name),
+        ).fetchall():
+            unique_by_name.setdefault(str(constraint_name), []).append(str(column_name))
+        field_ids = {field.field_id for field in fields}
+        for constraint_name, unique_columns in unique_by_name.items():
+            bounded_columns = [column for column in unique_columns if column in field_ids]
+            if bounded_columns:
+                constraints.append(
+                    MetadataConstraint(
+                        constraint_id=f"{name}_{constraint_name}",
+                        kind=MetadataConstraintKind.UNIQUE,
+                        fields=frozenset(bounded_columns),
+                        trust_level=MetadataTrustLevel.DECLARED,
+                    )
+                )
+
+        statistics: list[MetadataStatistic] = []
+        if config.include_statistics and statistic_count < config.max_statistics:
+            count_row = connection.execute(
+                f"SELECT COUNT(*) FROM {_quote_ident(schema)}.{_quote_ident(name)}"
+            ).fetchone()
+            if count_row is not None:
+                statistics.append(
+                    MetadataStatistic(
+                        statistic_id=f"{name}_row_count",
+                        kind=MetadataStatisticKind.ROW_COUNT,
+                        scope_object_id=name,
+                        value=float(count_row[0]),
+                        trust_level=MetadataTrustLevel.DECLARED,
+                    )
+                )
+                statistic_count += 1
+
+        objects.append(
+            MetadataObject(
+                object_id=name,
+                kind=object_kind,
+                name=name,
+                fields=tuple(fields),
+                constraints=tuple(constraints),
+                statistics=tuple(statistics),
+                trust_level=MetadataTrustLevel.DECLARED,
+                observed_incomplete=False,
+            )
+        )
+
+        for _constraint_name, from_column, to_column, target_table in (
+            connection.execute(
+                "SELECT c.conname, a.attname AS from_column, "
+                "  fa.attname AS to_column, f.relname AS target_table "
+                "FROM pg_constraint c "
+                "JOIN pg_class t ON t.oid = c.conrelid "
+                "JOIN pg_namespace n ON n.oid = t.relnamespace "
+                "CROSS JOIN LATERAL unnest(c.conkey, c.confkey) "
+                "  WITH ORDINALITY AS u(fk_attnum, ref_attnum, ord) "
+                "JOIN pg_attribute a "
+                "  ON a.attrelid = c.conrelid AND a.attnum = u.fk_attnum "
+                "JOIN pg_attribute fa "
+                "  ON fa.attrelid = c.confrelid AND fa.attnum = u.ref_attnum "
+                "JOIN pg_class f ON f.oid = c.confrelid "
+                "WHERE c.contype = 'f' AND n.nspname = %s AND t.relname = %s "
+                "ORDER BY c.conname, u.ord",
+                (schema, name),
+            ).fetchall()
+        ):
+            if str(target_table) not in allowed_objects or str(from_column) not in field_ids:
+                continue
+            relationship_id = f"{name}_{str(target_table)}_via_{str(from_column)}"
+            relationships.append(
+                MetadataRelationship(
+                    relationship_id=relationship_id,
+                    kind=MetadataRelationshipKind.FOREIGN_KEY,
+                    source_object_id=name,
+                    target_object_id=str(target_table),
+                    source_fields=frozenset({str(from_column)}),
+                    target_fields=frozenset({str(to_column)}),
+                    trust_level=MetadataTrustLevel.DECLARED,
+                )
+            )
+            constraints.append(
+                MetadataConstraint(
+                    constraint_id=f"{relationship_id}_fk",
+                    kind=MetadataConstraintKind.FOREIGN_KEY,
+                    fields=frozenset({str(from_column)}),
+                    trust_level=MetadataTrustLevel.DECLARED,
+                )
+            )
+
+    source_digest = strict_sha256_fingerprint(
+        {
+            "objects": sorted(obj.object_id for obj in objects),
+            "fingerprints": sorted(evidence_item.reference for evidence_item in evidence),
+        }
+    )
+    return MetadataSnapshot(
+        snapshot_id=f"pg-{source_digest[-16:]}",
+        source=MetadataSourceReference(
+            source_id=pg_config.source_id or "postgresql",
+            catalog_fingerprint=source_digest,
+            description="read-only postgresql catalog",
+        ),
+        objects=tuple(objects),
+        relationships=tuple(relationships),
+        freshness=MetadataFreshness(
+            bounded_objects=bounded_objects,
+            bounded_fields=bounded_fields,
+            bounded_samples=bounded_samples,
+            sample_limit=config.max_samples,
+        ),
+        provenance=MetadataProvenance(
+            discovered_by_fingerprint=strict_sha256_fingerprint(
+                {"backend": "sql:postgresql", "schema": schema}
+            ),
+            method="postgresql_introspection",
+            evidence=tuple(evidence),
+        ),
+    )

nl2data_postgres/errors.py

@@ -0,0 +1,33 @@
+"""Safe normalized errors for the PostgreSQL adapter boundary."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nl2data.errors import ErrorCategory, ErrorCode, NL2DataError
+
+
+class PostgresAdapterError(NL2DataError):
+    """Raised for PostgreSQL adapter misuse outside the guarded lifecycle."""
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(
+            ErrorCategory.ADAPTER,
+            ErrorCode.SQL_REJECTED,
+            message,
+            retryable=False,
+            details=details,
+        )
+
+
+class PostgresExecutionError(NL2DataError):
+    """Raised when PostgreSQL execution fails or produces unsupported values."""
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(
+            ErrorCategory.ADAPTER,
+            ErrorCode.SQL_EXECUTION_FAILED,
+            message,
+            retryable=False,
+            details=details,
+        )

nl2data_postgres/execution.py

@@ -0,0 +1,148 @@
+"""Read-only PostgreSQL SQL execution with bounded protected results."""
+
+from __future__ import annotations
+
+import math
+import time
+from decimal import Decimal
+from typing import Any
+
+from nl2data_core.adapters.models import ExecutionResult
+from nl2data_core.canonical import strict_sha256_fingerprint
+from nl2data_core.compilation.expansion import ZeroDivisionPolicyError
+
+from .client import PostgresPool
+from .config import PostgresAdapterConfig
+from .errors import PostgresExecutionError
+
+#: The protected public scalar set; everything else is unsupported.
+_SCALAR_TYPES: tuple[type, ...] = (str, int, float, bool, type(None))
+
+
+def _normalize_cell(value: Any, *, row_index: int, column_index: int) -> Any:
+    if isinstance(value, _SCALAR_TYPES):
+        return value
+    if isinstance(value, Decimal):
+        #: NUMERIC columns arrive as Decimal; normalize into the protected
+        #: float scalar so the same computed math (e.g. ROUND(100.0 * a / b))
+        #: yields SQLite-equivalent float64 values.  Non-finite numerics
+        #: (NaN/Infinity) stay fail-closed: a poisoned float would break the
+        #: canonical JSON payload downstream.
+        converted = float(value)
+        if math.isfinite(converted):
+            return converted
+    raise PostgresExecutionError(
+        "database returned a value outside the protected scalar set",
+        details={
+            "row_index": str(row_index),
+            "column_index": str(column_index),
+            "value_type": type(value).__name__,
+        },
+    )
+
+
+class PostgresExecutor:
+    """Bounded read-only executor for a single PostgreSQL adapter."""
+
+    def __init__(self, config: PostgresAdapterConfig) -> None:
+        self._config = config
+        self._pool = PostgresPool(config)
+
+    def close(self) -> None:
+        self._pool.close()
+
+    def execute(
+        self,
+        sql: str,
+        *,
+        max_rows: int | None = None,
+        max_columns: int | None = None,
+        max_result_bytes: int | None = None,
+        timeout_seconds: float | None = None,
+    ) -> ExecutionResult:
+        """Execute one validated read-only statement and map to protected scalars."""
+        effective_max_rows = max_rows if max_rows is not None else self._config.max_rows
+        effective_max_columns = max_columns if max_columns is not None else 1_000
+        effective_max_bytes = (
+            max_result_bytes if max_result_bytes is not None else self._config.max_result_bytes
+        )
+        effective_timeout = timeout_seconds or self._config.timeout_seconds
+        started = time.monotonic()
+        deadline = started + effective_timeout
+
+        with self._pool.connection() as connection:
+            timeout_ms = max(1, int(effective_timeout * 1000))
+            connection.execute(f"SET statement_timeout = {timeout_ms}")
+            try:
+                cursor = connection.execute(sql)
+            except Exception as error:
+                if getattr(error, "sqlstate", None) == "22012":
+                    raise ZeroDivisionPolicyError(
+                        "calculated-field division by zero",
+                        details={"sqlstate": "22012"},
+                    ) from error
+                raise PostgresExecutionError(
+                    "postgresql execution failed",
+                    details={"cause_type": type(error).__name__},
+                ) from error
+
+            columns = tuple(description[0] for description in cursor.description or ())
+            if len(columns) > effective_max_columns:
+                raise PostgresExecutionError(
+                    "result column count exceeds the bounded maximum",
+                    details={"max_columns": str(effective_max_columns)},
+                )
+
+            rows: list[tuple[Any, ...]] = []
+            for row_index, row in enumerate(cursor.fetchmany(effective_max_rows + 1)):
+                if row_index >= effective_max_rows:
+                    raise PostgresExecutionError(
+                        "result row count exceeds the bounded maximum",
+                        details={"max_rows": str(effective_max_rows)},
+                    )
+                rows.append(
+                    tuple(
+                        _normalize_cell(cell, row_index=row_index, column_index=col_index)
+                        for col_index, cell in enumerate(row)
+                    )
+                )
+                if effective_max_bytes is not None:
+                    text_bytes = sum(
+                        len(str(cell).encode("utf-8"))
+                        for current_row in rows
+                        for cell in current_row
+                    )
+                    result_bytes = sum(len(str(column).encode("utf-8")) for column in columns)
+                    result_bytes += text_bytes
+                    if result_bytes > effective_max_bytes:
+                        raise PostgresExecutionError(
+                            "result bytes exceed the authorized maximum",
+                            details={
+                                "max_result_bytes": str(effective_max_bytes),
+                                "actual": str(result_bytes),
+                            },
+                        )
+            if time.monotonic() >= deadline:
+                raise PostgresExecutionError(
+                    "SQL execution exceeded the authorized timeout",
+                    details={"timeout_seconds": str(effective_timeout)},
+                )
+
+        # Rows are model-native tuples; the fingerprint payload carries them
+        # as JSON arrays so strict canonicalization stays fail-closed.
+        fingerprint = strict_sha256_fingerprint(
+            {
+                "columns": list(columns),
+                "rows": [list(row) for row in rows],
+            }
+        )
+        duration_ms = int((time.monotonic() - started) * 1000)
+        return ExecutionResult(
+            result_id=f"result-{fingerprint[-16:]}",
+            fingerprint=fingerprint,
+            row_count=len(rows),
+            columns=columns,
+            rows=tuple(rows),
+            duration_ms=duration_ms,
+            metadata={"dialect": "postgres"},
+        )

nl2data_postgres-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: nl2data-postgres
+Version: 0.1.0
+Summary: PostgreSQL metadata discovery and governed SQL execution adapter for nl2data-core.
+Author: NL2Data Contributors
+License: Apache-2.0
+Keywords: nl2data,postgresql,metadata,sql,adapter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: nl2data-core>=0.1.0
+Requires-Dist: psycopg[binary,pool]<4,>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# nl2data-postgres
+
+An optional PostgreSQL backend integration for
+[nl2data-core](https://github.com/emmansun/nl2data-core). It combines
+metadata discovery and governed read-only SQL execution behind the core
+provider-neutral contracts.
+
+`psycopg` is an optional dependency and is loaded lazily at first use. The
+core import boundary never loads the PostgreSQL driver.
+
+## Install
+
+```bash
+pip install nl2data-postgres
+```
+
+Requires Python 3.11+, `nl2data-core>=0.1.0`, and
+`psycopg[binary,pool]>=3.1,<4`.
+
+From a source checkout:
+
+```bash
+pip install -e packages/nl2data-postgres
+```
+
+## Public surface
+
+```python
+from nl2data_postgres import (
+    PostgresAdapterConfig,
+    PostgresMetadataDiscoverer,
+    PostgresQueryAdapter,
+)
+```
+
+- `PostgresAdapterConfig` — bounded discovery/execution configuration with
+  host-injected DSN references, object/field allowlists, and result bounds.
+- `PostgresMetadataDiscoverer` — the core `MetadataDiscoverer` port
+  implementation for PostgreSQL.
+- `PostgresQueryAdapter` — the core `QueryAdapter` port implementation
+  for read-only PostgreSQL SQL.
+
+## Configuration
+
+Configuration is credential-free; hosts inject DSNs through a resolver
+or environment at runtime. `PostgresAdapterConfig` carries only
+bounded, fingerprintable settings.
+
+```python
+from nl2data_postgres import PostgresAdapterConfig
+
+config = PostgresAdapterConfig(
+    dsn_reference="env:NL2DATA_POSTGRES_DSN",
+    allowed_objects={"users", "orders"},
+    max_objects=256,
+    max_rows=10_000,
+)
+```
+
+## Discovery
+
+```python
+from nl2data_postgres import PostgresAdapterConfig, PostgresMetadataDiscoverer
+from nl2data_core.metadata.protocol import MetadataDiscoveryConfig
+
+discoverer = PostgresMetadataDiscoverer(
+    config=PostgresAdapterConfig(dsn_reference="env:NL2DATA_POSTGRES_DSN"),
+    allowed_objects={"users", "orders"},
+)
+snapshot = await discoverer.discover(MetadataDiscoveryConfig())
+```
+
+Discovery returns a core `MetadataSnapshot` with normalized tables,
+columns, types, primary/foreign keys, and bounded protected statistics.
+
+## Query execution
+
+```python
+from nl2data_postgres import PostgresAdapterConfig, PostgresQueryAdapter
+from nl2data_core.adapters.models import ValidationContext
+
+adapter = PostgresQueryAdapter(
+    config=PostgresAdapterConfig(dsn_reference="env:NL2DATA_POSTGRES_DSN"),
+    allowed_objects={"users"},
+)
+artifact = adapter.parse("SELECT id, name FROM users LIMIT 10", ValidationContext())
+validated = adapter.validate(artifact, ValidationContext())
+result = await adapter.execute(validated, ValidationContext())
+```
+
+Execution uses a read-only connection pool, enforces statement timeout,
+limits rows/columns/bytes, and maps every result value to the protected
+scalar set.
+
+## Failure classification
+
+| Condition | Normalized result |
+| --- | --- |
+| Missing driver / unreachable service | Retryable `MetadataUnavailableError` |
+| Authorization or permission denial | `MetadataUnauthorizedError` |
+| Lifecycle misuse (unparsed/unvalidated artifacts) | `PostgresAdapterError` |
+| Guard rejection (scope/obligation/limit) | `SQLGuardError` |
+| Statement/result bounds exceeded | `PostgresExecutionError` |
+| Malformed SQL | `SQLParseError` |
+
+DSNs, raw SQL, native exceptions, and credentials never cross the
+boundary.
+
+## Compatibility
+
+The in-core `nl2data_core.adapters.sql.SqlMetadataDiscoverer` still
+accepts `dialect="postgresql"` as a temporary compatibility path, but it
+always uses the legacy in-core implementation and emits a deprecation
+warning; it does not delegate to this package. New code should import
+from `nl2data_postgres` directly.
+
+## More documentation
+
+- [Documentation index](../../docs/README.md)
+- [Adding an adapter or provider](../../docs/development/adding-adapter-or-provider.md)
+- [Secrets and live testing](../../docs/operations/secrets.md)
+- [Capabilities and support](../../docs/reference/capabilities.md)

nl2data_postgres-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+nl2data_postgres/__init__.py,sha256=aRHG-IuP1pFfbYGCNA4-HWdRFa-CLF7Rp4x3KfcuqOk,852
+nl2data_postgres/adapter.py,sha256=_X6IN-cNz7OiizES3xbcP-P2HRx0VccTOExozxxx7bE,8240
+nl2data_postgres/client.py,sha256=VfRPRLzmJLuPc5RRHYflwVZANhZYGIJTXPlmrpTHGoc,4549
+nl2data_postgres/config.py,sha256=dS5Np_GldMWBunkkatPkeN32RRUrXjplQM1FDzRRAfA,4607
+nl2data_postgres/discovery.py,sha256=Jpz0LiF4gQrD3URahVRhHuCv8ysyvqycb5JetEjXtik,13768
+nl2data_postgres/errors.py,sha256=PDqmv5GA4_jfpGQBjA7vYn44RFLZeSGcD1Fj3QkA8Dg,1033
+nl2data_postgres/execution.py,sha256=OGoGWRfAn0Pt8PTXf2DOVwgEBZRmg8Mzeh1Zg_2x5-U,6156
+nl2data_postgres/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nl2data_postgres-0.1.0.dist-info/METADATA,sha256=zAj3mH9hh1zFLAF5oxpPclewD611qzMrNilGkKl3tEg,4836
+nl2data_postgres-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nl2data_postgres-0.1.0.dist-info/top_level.txt,sha256=OIQ8dphDbQpNfaAaJ_HPlVuT2IyHdTH0kJH9ZGVXv8Q,17
+nl2data_postgres-0.1.0.dist-info/RECORD,,

nl2data_postgres-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nl2data_postgres-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nl2data_postgres