iris-pgwire 1.5.9__tar.gz → 1.7.1__tar.gz

{iris_pgwire-1.5.9 → iris_pgwire-1.7.1}/.gitignore

@@ -94,7 +94,6 @@ merge.cpf
 iris_pgwire.json
 
 # AI tooling files (not for public repo)
-AGENTS.md
 CODEX.md
 TABNINE.md
 
@@ -111,3 +110,8 @@ test_pg_type.py
 test_scope.py
 update_article.py
 verify_demo.sql
+
+# iris-agentic-dev local connection config (per-developer: host, port, container
+# name and credentials vary by machine). Template is committed at
+# specs/043-local-first-sync/spikes/iris-agentic-dev.toml.example
+.iris-agentic-dev.toml

{iris_pgwire-1.5.9 → iris_pgwire-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: iris-pgwire
-Version: 1.5.9
+Version: 1.7.1
 Summary: PostgreSQL Wire Protocol Server for InterSystems IRIS - Connect BI tools, Python frameworks, and PostgreSQL clients to IRIS databases
 Project-URL: Homepage, https://github.com/intersystems-community/iris-pgwire
 Project-URL: Documentation, https://github.com/intersystems-community/iris-pgwire#readme
@@ -57,12 +57,12 @@ Requires-Dist: opentelemetry-instrumentation-asyncio>=0.41b0
 Requires-Dist: opentelemetry-sdk>=1.20.0
 Requires-Dist: prometheus-client>=0.17.0
 Requires-Dist: psycopg2-binary>=2.9.10
-Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic<2.12,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: sqlparse>=0.4.0
 Requires-Dist: structlog>=23.0.0
+Requires-Dist: typing-extensions<5,>=4.12.2
 Provides-Extra: ai
-Requires-Dist: iris-agentic-dev>=1.0; extra == 'ai'
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'

{iris_pgwire-1.5.9 → iris_pgwire-1.7.1}/pyproject.toml

@@ -63,7 +63,9 @@ dependencies = [
     "opentelemetry-sdk>=1.20.0",
     "opentelemetry-instrumentation-asyncio>=0.41b0",
     "opentelemetry-exporter-otlp>=1.20.0",
-    "pydantic>=2.0.0",
+    # pydantic>=2.12 requires typing_extensions>=4.14.1; IRIS irispython ships 4.12.2
+    "pydantic>=2.0.0,<2.12",
+    "typing_extensions>=4.12.2,<5",
     "pyyaml>=6.0.0",
     "prometheus-client>=0.17.0",
 ]
@@ -100,7 +102,13 @@ iris = [
     # "intersystems-iris>=3.6.0",
 ]
 ai = [
-    "iris-agentic-dev>=1.0",
+    # IRIS-aware agent tooling. iris-agentic-dev is a Rust binary and is NOT
+    # published on PyPI, so it cannot be declared as a dependency here — doing
+    # so made `pip install iris-pgwire[ai]` fail outright. Install it directly:
+    #   Linux:  curl -fsSL https://github.com/intersystems-community/iris-agentic-dev/releases/latest/download/iris-agentic-dev-linux-x86_64 \
+    #             -o /usr/local/bin/iris-agentic-dev && chmod +x /usr/local/bin/iris-agentic-dev
+    #   macOS:  brew install https://raw.githubusercontent.com/intersystems-community/iris-agentic-dev/master/Formula/iris-agentic-dev.rb
+    # See docs/iris-pgwire-iad-setup-issues.md and AGENTS.md.
 ]
 kerberos = [
     # Kerberos GSSAPI authentication (optional - not implemented in wire protocol yet)

{iris_pgwire-1.5.9 → iris_pgwire-1.7.1}/src/iris_pgwire/__init__.py

@@ -6,7 +6,7 @@ Based on the specification from docs/iris_pgwire_plan.md and proven patterns fro
 caretdev/sqlalchemy-iris.
 """
 
-__version__ = "1.5.9"
+__version__ = "1.7.1"
 __author__ = "Thomas Dyar <thomas.dyar@intersystems.com>"
 
 # Don't import server/protocol in __init__ to avoid sys.modules conflicts

iris_pgwire-1.7.1/src/iris_pgwire/catalog/_reentrancy.py

@@ -0,0 +1,27 @@
+"""Re-entrancy guard for catalog query handling.
+
+Lives in its own module because two things need it and importing it from
+`catalog_router` creates a cycle: the router imports the view registry, and the
+view installer needs the guard.
+
+Some handlers answer a catalog query by issuing their own SQL through the
+executor — `_build_pg_class_response` asks IRIS for `INFORMATION_SCHEMA.TABLES`.
+That inner query re-enters the router, which would intercept it and return zero
+rows, leaving the handler with nothing to report. The view installer has the
+same problem in a sharper form: its `CREATE VIEW pg_catalog.pg_class AS ...` was
+handed to the pg_class handler, which answered it with a synthetic success — so
+installation reported success while creating nothing.
+
+A ContextVar rather than a flag, so the guard is scoped to the asyncio task and
+one session's internal query cannot suppress interception for a concurrent one.
+"""
+
+from __future__ import annotations
+
+import contextvars
+
+_IN_CATALOG_HANDLER: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "iris_pgwire_in_catalog_handler", default=False
+)
+
+__all__ = ["_IN_CATALOG_HANDLER"]

{iris_pgwire-1.5.9 → iris_pgwire-1.7.1}/src/iris_pgwire/catalog/catalog_router.py

@@ -15,6 +15,7 @@ import structlog
 from iris_pgwire.schema_mapper import IRIS_SCHEMA
 from iris_pgwire.type_mapping import get_type_mapping
 
+from ._reentrancy import _IN_CATALOG_HANDLER
 from .oid_generator import OIDGenerator
 from .pg_attrdef import PgAttrdefEmulator
 from .pg_attribute import PgAttributeEmulator
@@ -23,10 +24,12 @@ from .pg_constraint import PgConstraintEmulator
 from .pg_index import PgIndexEmulator
 from .pg_namespace import PgNamespaceEmulator
 from .pg_type import PgTypeEmulator
+from .views.definitions import CATALOG_SCHEMA, VIEW_BACKED_TABLES
 
 logger = structlog.get_logger(__name__)
 
 
+
 @dataclass
 class CatalogQueryResult:
     """
@@ -138,10 +141,8 @@ class CatalogRouter:
             "pg_namespace": self._handle_pg_namespace,
             "pg_class": self._handle_pg_class,
             "information_schema.columns": self._handle_information_schema_columns,
-            "pg_attribute": self._handle_pg_attribute,
             "pg_constraint": self._handle_pg_constraint,
             "pg_index": self._handle_pg_index,
-            "pg_attrdef": self._handle_pg_attrdef,
         }
 
     def can_handle(self, query: str) -> bool:
@@ -174,12 +175,20 @@ class CatalogRouter:
         Returns:
             Set of catalog table names (lowercase)
         """
-        words = set(re.findall(r"\b(\w+)\b", query.lower()))
+        lowered = query.lower()
+        words = set(re.findall(r"\b(\w+)\b", lowered))
+        # A pg_* name followed by `(` is a function call, not a table. Without
+        # this, `pg_get_constraintdef(constr.oid)` counted as a catalog table, so
+        # the set of targeted tables was never a subset of the view-backed ones
+        # and the decline below never fired — the pg_class handler then answered
+        # Prisma's constraints query with pg_class's own 32 columns, including
+        # relfrozenxid typed `xid`. Measured: that is the whole of the failure.
+        called = set(re.findall(r"\b(pg_\w+)\s*\(", lowered))
         tables: set[str] = set()
 
         # Find pg_* references
         for word in words:
-            if word.startswith("pg_"):
+            if word.startswith("pg_") and word not in called:
                 if word in self.CATALOG_TABLES or len(word) > 3:
                     tables.add(word)
 
@@ -298,6 +307,32 @@ class CatalogRouter:
 
         return self._regclass_pattern.sub(replace_regclass, query)
 
+    # The relation a statement is about: the first catalog table after FROM, or
+    # after a JOIN only if no FROM relation is a catalog table at all. Optional
+    # schema qualifier, optional quotes, optional alias.
+    _FROM_RELATION = re.compile(
+        r"\bFROM\s+(?:(?:\"?\w+\"?)\s*\.\s*)?\"?(\w+)\"?",
+        re.IGNORECASE,
+    )
+
+    def primary_catalog_relation(self, query: str) -> str | None:
+        """The catalog table the query is *about*, or None if it is about none.
+
+        Distinct from :meth:`get_target_catalog`, which returns the highest-
+        priority catalog table mentioned *anywhere*. That is the right question
+        for "which emulator knows most about this statement" and the wrong one
+        for "which table's columns should the answer have": Prisma's pg_views
+        query mentions pg_class in a JOIN, and answering with pg_class's shape
+        made the client fail (T015a).
+        """
+        for match in self._FROM_RELATION.finditer(query):
+            name = match.group(1).lower()
+            if name in self.CATALOG_TABLES or (
+                name.startswith("pg_") and len(name) > 3
+            ):
+                return name
+        return None
+
     def get_target_catalog(self, query: str) -> str | None:
         """
         Get primary catalog table targeted by query.
@@ -330,6 +365,17 @@ class CatalogRouter:
         # Return first found
         return next(iter(tables))
 
+    # Expressions the row emulators cannot evaluate. They can project and
+    # filter columns over emulated rows; they cannot compute EXISTS(...) or
+    # call scalar functions. Queries containing these must fall through to
+    # SQLInterceptor, which has purpose-built handlers for them — notably
+    # Prisma's schema probe:
+    #   SELECT EXISTS(SELECT 1 FROM pg_namespace WHERE nspname = $1),
+    #          version(), current_setting('server_version_num')
+    # Intercepting that returned raw namespace rows, so Prisma read it as
+    # "public does not exist" and issued CREATE SCHEMA "public".
+    UNEVALUABLE_EXPRESSIONS = ("EXISTS(", "EXISTS (", "VERSION()", "CURRENT_SETTING(")
+
     async def handle_catalog_query(
         self,
         sql: str,
@@ -349,20 +395,109 @@ class CatalogRouter:
             session_id=session_id,
         )
 
+        # Tables served by real IRIS views are answered by the database, which
+        # evaluates projections, aliases, joins and CTEs correctly. Declining
+        # here is what makes exactly one path answer a given catalog table
+        # (spec 044 FR-011). Without it the old handler would intercept first
+        # and the view would be unreachable.
+        # extract_catalog_tables() matches anything with a pg_ prefix, so the
+        # schema qualifier in "pg_catalog.pg_class" comes back looking like a
+        # table. Drop it before deciding, or no qualified query would ever be
+        # declined.
+        targeted = {t for t in self.extract_catalog_tables(sql) if t != CATALOG_SCHEMA}
+        if targeted and targeted <= set(VIEW_BACKED_TABLES):
+            logger.debug(
+                "Declining catalog query served by IRIS views",
+                tables=sorted(targeted),
+                session_id=session_id,
+            )
+            return None
+
+        if _IN_CATALOG_HANDLER.get():
+            logger.debug(
+                "Declining nested catalog query issued by a handler",
+                sql_preview=sql[:120],
+                session_id=session_id,
+            )
+            return None
+
+        if any(token in sql_upper for token in self.UNEVALUABLE_EXPRESSIONS):
+            logger.debug(
+                "Declining catalog query with unevaluable expression",
+                sql_preview=sql[:120],
+                session_id=session_id,
+            )
+            return None
+
         tables = self.extract_catalog_tables(sql)
-        for table in self.CATALOG_HANDLER_PRIORITY:
-            if table not in tables:
-                continue
-            handler = self._catalog_handler_map.get(table)
-            if not handler:
-                continue
-            result = await handler(sql, sql_upper, params, session_id, executor)
-            if result is not None:
-                return result
+
+        # A handler may only answer for the relation the query is *about*.
+        #
+        # The loop below walks a priority list and takes the first handler whose
+        # table appears anywhere in the statement — a JOIN partner included. So a
+        # question about pg_views, which names pg_class only in a JOIN, was
+        # answered by the pg_class handler with pg_class's own 32 columns, and
+        # the client failed on `relfrozenxid` typed `xid`. The same happened to
+        # Prisma's constraints query before pg_constraint became a view, and
+        # would happen to the next catalog table with no path of its own.
+        #
+        # Declining is the honest alternative: IRIS then reports the relation it
+        # cannot find, which reaches the client as 42P01 (spec FR-008a). What is
+        # never acceptable is a confidently wrong shape.
+        # Scoped deliberately to the *substitution* case: the primary relation has
+        # no handler, but some other table in the statement does, so falling
+        # through would answer with that other table's columns. A statement whose
+        # only catalog table is unhandled still reaches the "empty fallback"
+        # below — that fabricated empty result is a separate defect (FR-008c),
+        # already located, and removing it is T020's own verification pass rather
+        # than something to smuggle in here.
+        primary = self.primary_catalog_relation(sql)
+        substitutes = primary is not None and primary not in self._catalog_handler_map
+        if substitutes and any(
+            table != primary and table in self._catalog_handler_map for table in tables
+        ):
+            logger.debug(
+                "Declining: would answer with another relation's columns",
+                primary=primary,
+                targeted=sorted(tables),
+                session_id=session_id,
+            )
+            return None
+
+        guard_token = _IN_CATALOG_HANDLER.set(True)
+        try:
+            for table in self.CATALOG_HANDLER_PRIORITY:
+                if table not in tables:
+                    continue
+                # Same rule inside the loop: only the primary relation's handler
+                # may answer, so priority order cannot substitute a JOIN partner.
+                if primary is not None and table != primary:
+                    continue
+                handler = self._catalog_handler_map.get(table)
+                if not handler:
+                    continue
+                result = await handler(sql, sql_upper, params, session_id, executor)
+                if result is not None:
+                    return result
+        finally:
+            _IN_CATALOG_HANDLER.reset(guard_token)
 
         if self.can_handle(sql):
             target = self.get_target_catalog(sql)
-            logger.info(f"Intercepting {target} query (empty fallback)", session_id=session_id)
+            # FR-008c forbids this branch: it fabricates a zero-row, zero-column
+            # answer for any catalog query can_handle() claims but no handler
+            # recognises, so a client cannot tell an empty schema from an
+            # unimplemented one. T020 removes it. Until then the log has to name
+            # the statement, or the only trace of a swallowed query is the target
+            # table it was misattributed to — which is how four of Prisma's
+            # twelve statements went unnoticed.
+            logger.warning(
+                "Fabricating empty catalog result (FR-008c violation, T020)",
+                target=target,
+                primary_relation=self.primary_catalog_relation(sql),
+                sql_preview=" ".join(sql.split())[:220],
+                session_id=session_id,
+            )
             return {
                 "success": True,
                 "rows": [],
@@ -494,7 +629,14 @@ class CatalogRouter:
     ) -> dict[str, Any] | None:
         is_simple_pg_namespace = (
             "PG_NAMESPACE" in sql_upper
-            and re.search(r"\bFROM\s+PG_NAMESPACE\b", sql_upper)
+            # Accept the schema-qualified form too. Real clients emit
+            # "FROM pg_catalog.pg_namespace"; requiring the bare name sent every
+            # qualified query to the empty fallback, which returns zero rows.
+            # Prisma's schema-existence probe is
+            #   SELECT EXISTS(SELECT 1 FROM pg_namespace WHERE nspname = $1)
+            # so an empty result reads as "the public schema does not exist" and
+            # introspection reports the database as empty.
+            and re.search(r"\bFROM\s+(?:PG_CATALOG\.)?PG_NAMESPACE\b", sql_upper)
             and "JOIN" not in sql_upper
             and len(re.findall(r"\bFROM\b", sql_upper)) <= 2
         )
@@ -533,6 +675,7 @@ class CatalogRouter:
             and "PG_ATTRIBUTE" not in sql_upper
             and "ATT.ATTTYPID" not in sql_upper
             and "INFO.COLUMN_NAME" not in sql_upper
+            and not sql_upper.lstrip().startswith("WITH")
         )
 
         if not is_simple_pg_class:

iris_pgwire-1.7.1/src/iris_pgwire/catalog/function_installer.py

@@ -0,0 +1,103 @@
+"""Create the PGWire SQL functions in IRIS, idempotently.
+
+Runs before the view installer, which cannot define a single view without them.
+
+Before this existed the functions had to be loaded by hand with
+`$SYSTEM.OBJ.Load`, and nothing in the codebase did it — so catalog views only
+worked on an instance where someone had already done so, and a fresh one would
+fail at startup. Installing them over SQL removes the manual step and works
+identically on both backends, since `CREATE FUNCTION` needs only a connection
+whereas loading a class file needs the source on the server's own filesystem.
+
+Failures are raised, never swallowed, for the same reason the view installer
+raises: a catalog that half-installs answers introspection with empty results,
+which reads to a client as "this database has nothing in it" (spec FR-009).
+"""
+
+from __future__ import annotations
+
+import structlog
+
+from ..sql_translator.verbatim import verbatim_sql
+from ._reentrancy import _IN_CATALOG_HANDLER
+from .functions import CATALOG_FUNCTIONS, CATALOG_SCHEMA, CatalogFunction
+
+logger = structlog.get_logger(__name__)
+
+
+class CatalogFunctionInstallError(RuntimeError):
+    """Raised when a PGWire SQL function cannot be created."""
+
+
+class CatalogFunctionInstaller:
+    """Install the ObjectScript-bodied SQL functions the catalog depends on."""
+
+    def __init__(self, executor):
+        self._executor = executor
+
+    async def install(self, session_id: str | None = None) -> list[str]:
+        """Create every function, replacing any existing definition.
+
+        Returns the qualified names installed. Idempotent by construction —
+        `CREATE OR REPLACE` converges rather than needing a DROP first.
+
+        Routing is suppressed for the same reason the view installer suppresses
+        it: these statements mention catalog names, and the router would answer
+        them with a synthetic success while nothing was created.
+        """
+        installed: list[str] = []
+        guard = _IN_CATALOG_HANDLER.set(True)
+        try:
+            # Verbatim: the bodies are ObjectScript, and the translation
+            # pipeline uppercases identifiers. It turned $SYSTEM.Encryption into
+            # %SYSTEM.ENCRYPTION (class names are case-sensitive) and cased the
+            # declared parameter differently from its uses in the body. Both
+            # installed cleanly and then failed on every call.
+            with verbatim_sql():
+                for function in CATALOG_FUNCTIONS:
+                    await self._install_one(function, session_id)
+                    installed.append(function.qualified_name)
+        finally:
+            _IN_CATALOG_HANDLER.reset(guard)
+
+        logger.info("Catalog functions installed", schema=CATALOG_SCHEMA, functions=installed)
+        return installed
+
+    async def _install_one(self, function: CatalogFunction, session_id: str | None) -> None:
+        """Execute CREATE OR REPLACE for one function, raising on failure."""
+        try:
+            result = await self._executor.execute_query(
+                function.create_sql(), session_id=session_id
+            )
+        except Exception as exc:  # noqa: BLE001 — re-raised as an install error
+            raise CatalogFunctionInstallError(
+                f"Could not create {function.qualified_name} ({function.purpose}): {exc}"
+            ) from exc
+
+        if not result.get("success", False):
+            raise CatalogFunctionInstallError(
+                f"Could not create {function.qualified_name} ({function.purpose}): "
+                f"{result.get('error')}. The catalog views depend on it, so startup is "
+                "aborted rather than serving a catalog that answers with empty results."
+            )
+
+    async def verify(self, session_id: str | None = None) -> dict[str, bool]:
+        """Report which functions are present and callable."""
+        probes = {
+            "PG_OID": f"SELECT {CATALOG_SCHEMA}.PG_OID('probe')",
+            "PG_PUBLIC_SCHEMA": f"SELECT {CATALOG_SCHEMA}.PG_PUBLIC_SCHEMA()",
+            "PG_ARRAY": f"SELECT {CATALOG_SCHEMA}.PG_ARRAY('0|')",
+        }
+        status: dict[str, bool] = {}
+        guard = _IN_CATALOG_HANDLER.set(True)
+        try:
+            for name, probe in probes.items():
+                qualified = f"{CATALOG_SCHEMA}.{name}"
+                try:
+                    result = await self._executor.execute_query(probe, session_id=session_id)
+                    status[qualified] = bool(result.get("success", False))
+                except Exception:  # noqa: BLE001 — absence is the answer, not an error
+                    status[qualified] = False
+        finally:
+            _IN_CATALOG_HANDLER.reset(guard)
+        return status