iris-pgwire 1.5.7__tar.gz → 1.5.8__tar.gz

{iris_pgwire-1.5.7 → iris_pgwire-1.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-pgwire
-Version: 1.5.7
+Version: 1.5.8
 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

{iris_pgwire-1.5.7 → iris_pgwire-1.5.8}/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.7"
+__version__ = "1.5.8"
 __author__ = "Thomas Dyar <thomas.dyar@intersystems.com>"
 
 # Don't import server/protocol in __init__ to avoid sys.modules conflicts

iris_pgwire-1.5.8/src/iris_pgwire/auth/AGENTS.md

@@ -0,0 +1,38 @@
+# auth — Agent Knowledge Base
+
+**6 files.** Pluggable authentication: SCRAM-SHA-256, OAuth 2.0, GSSAPI/Kerberos,
+and IRIS Wallet credentials.
+
+## STRUCTURE
+
+```
+auth/
+├── auth_selector.py      # AuthenticationSelector — routes to correct backend
+├── scram.py              # SCRAM-SHA-256 implementation
+├── oauth_bridge.py       # OAuth 2.0 token validation bridge
+├── gssapi_auth.py        # GSSAPI/Kerberos (optional dep: gssapi>=1.8.0)
+└── wallet_credentials.py # IRIS Wallet credential store integration
+```
+
+## WHERE TO LOOK
+
+| Task | File |
+|------|------|
+| Auth method selection logic | `auth_selector.py` |
+| SCRAM handshake failures | `scram.py` |
+| OAuth token/JWT validation | `oauth_bridge.py` |
+| Kerberos realm issues | `gssapi_auth.py` |
+| Wallet credential retrieval | `wallet_credentials.py` |
+
+## CRITICAL INVARIANTS
+
+- GSSAPI is an optional dep — `gssapi_auth.py` has conditional imports (F401 ignored by ruff)
+- SCRAM-SHA-256 is the default and primary auth method
+- OAuth bridge validates tokens against external IdP — never trust without validation
+- Auth selector checks `oauth_enabled` and `kerberos_enabled` flags from config
+
+## ANTI-PATTERNS
+
+- Never hardcode credentials — always source from env vars or IRIS Wallet
+- SSL/TLS is handled via reverse proxy (nginx/HAProxy) — not in-process here
+- `gssapi_auth.py` imports are conditional — don't assume gssapi is installed

iris_pgwire-1.5.8/src/iris_pgwire/catalog/AGENTS.md

@@ -0,0 +1,44 @@
+# catalog — Agent Knowledge Base
+
+**11 files.** Emulates PostgreSQL's `pg_catalog` and `information_schema` so ORMs
+(SQLAlchemy, Prisma, Drizzle) can introspect IRIS schema as if it were PostgreSQL.
+
+## STRUCTURE
+
+```
+catalog/
+├── catalog_router.py    # Entry point — routes pg_catalog queries to emulators
+├── oid_generator.py     # Deterministic OID generation for IRIS objects
+├── pg_attribute.py      # pg_attribute (column info)
+├── pg_attrdef.py        # pg_attrdef (column defaults)
+├── pg_class.py          # pg_class (table/index info)
+├── pg_constraint.py     # pg_constraint (PK/FK/CHECK)
+├── pg_index.py          # pg_index (index metadata)
+├── pg_namespace.py      # pg_namespace (schemas as namespaces)
+├── pg_type.py           # pg_type (type OID registry)
+└── catalog_functions.py # pg_get_indexdef, pg_get_constraintdef, etc.
+```
+
+## WHERE TO LOOK
+
+| Task | File |
+|------|------|
+| ORM can't see tables | `catalog_router.py` → `pg_class.py` |
+| ORM can't see columns | `pg_attribute.py` |
+| ORM can't see constraints | `pg_constraint.py` |
+| Wrong OIDs causing type errors | `oid_generator.py` + `pg_type.py` |
+| `pg_get_indexdef` / `pg_get_constraintdef` failures | `catalog_functions.py` |
+| Schema (namespace) not found | `pg_namespace.py` |
+
+## CRITICAL INVARIANTS
+
+- OIDs must be deterministic (same IRIS object → same OID across connections)
+- `SQLUser` namespace always maps to OID representing the `public` schema
+- Array parameters from PG clients arrive as `{val1,val2}` strings — parse before use
+- `regclass` references must resolve via OID lookup before catalog queries execute
+
+## ANTI-PATTERNS
+
+- Never use random OIDs — breaks ORM caching
+- Never return PG-specific column types that IRIS can't represent
+- Don't assume `pg_catalog.` prefix is present — queries may omit schema

iris_pgwire-1.5.8/src/iris_pgwire/conversions/AGENTS.md

@@ -0,0 +1,31 @@
+# conversions — Agent Knowledge Base
+
+**7 files.** Data format conversions between PostgreSQL wire format and IRIS internals.
+
+## STRUCTURE
+
+```
+conversions/
+├── date_horolog.py      # PG DATE/TIMESTAMP ↔ IRIS $HOROLOG format
+├── ddl_idempotency.py   # Make DDL idempotent (IF NOT EXISTS, etc.)
+├── ddl_splitter.py      # Split multi-statement DDL into individual statements
+├── bulk_insert.py       # Bulk INSERT optimization helpers
+├── json_path.py         # JSON path expression builder
+└── vector_syntax.py     # pgvector syntax ↔ IRIS VECTOR syntax
+```
+
+## WHERE TO LOOK
+
+| Task | File |
+|------|------|
+| Date/timestamp wrong values | `date_horolog.py` |
+| DDL fails on re-run | `ddl_idempotency.py` |
+| Multi-statement DDL errors | `ddl_splitter.py` |
+| JSON/JSONB path issues | `json_path.py` |
+| Vector operator translation | `vector_syntax.py` |
+
+## CRITICAL INVARIANTS
+
+- IRIS uses `$HOROLOG` (days since 12/31/1840) for dates — conversion must be exact
+- `<=>` (cosine) and `<#>` (dot product) supported; `<->` (L2) → NOT IMPLEMENTED error
+- DDL splitter must handle semicolons inside string literals correctly

{iris_pgwire-1.5.7 → iris_pgwire-1.5.8}/src/iris_pgwire/protocol.py

@@ -32,6 +32,7 @@ from .sql_translator import PerformanceStats, get_translator
 from .sql_translator.copy_parser import CopyCommandParser, CopyDirection
 from .sql_translator.performance_monitor import MetricType, PerformanceTracker, get_monitor
 from .sql_translator.returning_plan import ReturningPlan
+from .vector_optimizer import VectorQueryOptimizer
 
 logger = structlog.get_logger()
 
@@ -1378,12 +1379,32 @@ class PGWireProtocol:
             if result["success"]:
                 await self.send_query_result(result, send_ready=send_ready)
             else:
-                await self.send_error_response(
-                    "ERROR", "42000", "syntax_error", result.get("error", "Query execution failed")
-                )
-                # CRITICAL: Send ReadyForQuery after error (only if last statement)
-                if send_ready:
-                    await self.send_ready_for_query()
+                error_msg = result.get("error", "Query execution failed")
+                if (
+                    VectorQueryOptimizer.sql_has_if_not_exists(final_sql)
+                    and VectorQueryOptimizer.is_duplicate_object_error(error_msg)
+                ):
+                    logger.info(
+                        "IF NOT EXISTS: suppressing duplicate-object error",
+                        connection_id=self.connection_id,
+                        sql_preview=final_sql[:100],
+                        error=error_msg,
+                    )
+                    fake_result = {
+                        "success": True,
+                        "rows": [],
+                        "columns": [],
+                        "row_count": 0,
+                        "command_tag": "CREATE TABLE",
+                    }
+                    await self.send_query_result(fake_result, send_ready=send_ready)
+                else:
+                    await self.send_error_response(
+                        "ERROR", "42000", "syntax_error", error_msg
+                    )
+                    # CRITICAL: Send ReadyForQuery after error (only if last statement)
+                    if send_ready:
+                        await self.send_ready_for_query()
 
         except Exception as e:
             logger.error(

iris_pgwire-1.5.8/src/iris_pgwire/quality/AGENTS.md

@@ -0,0 +1,32 @@
+# quality — Agent Knowledge Base
+
+**7 files.** Package and code quality validation — mirrors CI checks. Run locally
+with `./scripts/validate_package.sh` or `python -m iris_pgwire.quality`.
+
+## STRUCTURE
+
+```
+quality/
+├── __main__.py                  # CLI entry: python -m iris_pgwire.quality
+├── validator.py                 # Orchestrator — runs all validators
+├── package_metadata_validator.py  # pyroma score, MANIFEST.in, classifiers
+├── code_quality_validator.py    # black/ruff compliance checks
+├── documentation_validator.py  # interrogate docstring coverage (fail-under=80)
+└── security_validator.py       # bandit security scan + pip-audit
+```
+
+## WHERE TO LOOK
+
+| Task | File |
+|------|------|
+| CI quality gate failing | `validator.py` — run locally first |
+| Docstring coverage below 80% | `documentation_validator.py` |
+| Security audit failures | `security_validator.py` |
+| Package metadata issues | `package_metadata_validator.py` |
+
+## CRITICAL INVARIANTS
+
+- interrogate fail-under=80 — excludes `tests/` but includes all `src/`
+- bandit ignores `tests/` (`.bandit` config at repo root)
+- CI runs on Python 3.11 and 3.12 (matrix in `package-quality.yml`)
+- `check-manifest` is disabled — MANIFEST.in deliberately excludes non-essential files

iris_pgwire-1.5.8/src/iris_pgwire/sql_translator/AGENTS.md

@@ -0,0 +1,96 @@
+# sql_translator — Agent Knowledge Base
+
+**37 files.** Core translation pipeline converting PostgreSQL SQL to IRIS-compatible SQL.
+
+## OVERVIEW
+
+Multi-stage pipeline: schema mapping → statement filtering → parameter translation →
+normalization → refinement → optimization. Entry: `pipeline.py` → `normalizer.py`.
+
+## STRUCTURE
+
+```
+sql_translator/
+├── pipeline.py            # SQLPipeline — orchestrates all stages
+├── normalizer.py          # SQLTranslator — main orchestrator (stage coordinator)
+├── translator.py          # Low-level translation primitives
+├── identifier_normalizer.py  # Quoted/unquoted identifier casing
+├── ddl_translator.py      # Strip PG-specific DDL (fillfactor, GENERATED, USING btree)
+├── date_translator.py     # DATE/TIMESTAMP → IRIS horolog
+├── boolean_translator.py  # true/false → 1/0
+├── enum_translator.py     # ENUM type handling
+├── enum_registry.py       # Tracks CREATE TYPE enums
+├── statement_filter.py    # Skip unsupported statements (RLS, etc.)
+├── transaction_translator.py  # BEGIN/COMMIT/SAVEPOINT handling
+├── type_translator.py     # PG type names → IRIS equivalents
+├── constraint_translator.py   # CHECK/FOREIGN KEY translation
+├── returning_plan.py      # RETURNING clause emulation plan
+├── refiner.py             # ORDER BY alias fixes, post-normalize cleanup
+├── cache.py               # Translation result cache
+├── metadata_cache.py      # IRIS schema metadata cache
+├── confidence_analyzer.py # Translation confidence scoring
+├── error_handler.py       # Translation error handling/recovery
+├── interceptor.py         # Pre/post translation hooks
+├── copy_parser.py         # COPY statement parsing
+├── api.py                 # Public translation API
+├── parser.py              # SQL parsing utilities
+├── debug.py               # Debug output helpers
+├── models.py              # TranslationResult, PerformanceStats
+├── reserved_words.py      # IRIS reserved word list
+├── skipped_table_set.py   # Tables whose DDL should be skipped
+├── index_validator.py     # Index statement validation
+├── default_values.py      # DEFAULT clause metadata resolution
+├── alias_extractor.py     # SELECT alias extraction
+├── mappings/              # Static translation tables
+│   ├── datatypes.py       # PG → IRIS type mapping
+│   ├── functions.py       # PG → IRIS function mapping
+│   ├── constructs.py      # SQL construct mapping
+│   └── document_filters.py  # JSON path filter mapping
+```
+
+## WHERE TO LOOK
+
+| Task | File |
+|------|------|
+| Fix a translation bug (end-to-end) | `pipeline.py` → `normalizer.py` |
+| Identifier casing (`"MyTable"` vs `MYTABLE`) | `identifier_normalizer.py` |
+| DDL stripping (fillfactor, GENERATED, etc.) | `ddl_translator.py` |
+| Date/timestamp handling | `date_translator.py` |
+| ENUM support | `enum_translator.py` + `enum_registry.py` |
+| Add new PG function mapping | `mappings/functions.py` |
+| Add new PG type mapping | `mappings/datatypes.py` |
+| Skip/filter unsupported SQL | `statement_filter.py` |
+| RETURNING clause issues | `returning_plan.py` |
+| Performance / overhead | `cache.py`, `metrics.py` |
+| Transaction handling | `transaction_translator.py` |
+
+## CRITICAL INVARIANTS
+
+- `SQLUser` casing MUST NEVER be changed — IRIS is case-sensitive on schema names
+- Translation overhead MUST be <5ms per query
+- Quoted identifiers preserve case; unquoted → UPPERCASE
+- `$1`, `$2` PG params → `?` IRIS params
+- `public.` schema prefix → `SQLUser.` (configurable via `IRIS_SCHEMA` env var)
+
+## ANTI-PATTERNS
+
+- Never hardcode `SQLUser` — always use `IRIS_SCHEMA` from `schema_mapper`
+- Never return partial results on translation error — use `error_handler.py`
+- Never skip the cache for hot paths — check `cache.py` first
+- Don't add L2 (`<->`) translation — must raise NOT IMPLEMENTED
+
+## PIPELINE FLOW
+
+```
+input SQL
+  → StatementFilter (skip RLS, unsupported DDL)
+  → SQLTranslator.normalize_sql_with_result()
+      → schema mapping (public→SQLUser)
+      → identifier normalization
+      → date translation
+      → boolean translation
+      → enum translation
+      → construct/function mapping
+  → SQLRefiner (ORDER BY alias, post-normalize fixes)
+  → output SQL + TranslationResult
+```

{iris_pgwire-1.5.7 → iris_pgwire-1.5.8}/src/iris_pgwire/vector_optimizer.py

@@ -102,6 +102,9 @@ class VectorQueryOptimizer:
         # Rewrite pgvector operators to IRIS vector functions
         sql = self._rewrite_pgvector_operators(sql)
 
+        if "->" in sql:
+            sql = self._translate_nested_json_operators(sql)
+
         sql_upper = sql.upper()
 
         # Handle INSERT/UPDATE with vector patterns
@@ -266,6 +269,9 @@ class VectorQueryOptimizer:
     def _rewrite_pgvector_operators(self, sql: str) -> str:
         """Rewrite pgvector operators (<=> / <#>) to IRIS vector functions.
 
+        For DDL containing HNSW index syntax, translates to IRIS-native form instead
+        of rewriting operators.
+
         Raises:
             NotImplementedError: If L2 distance operator (<->) is found.
         """
@@ -274,7 +280,11 @@ class VectorQueryOptimizer:
 
         sql_upper = sql.upper()
         if any(kw in sql_upper for kw in _DDL_KEYWORDS):
-            return sql
+            # Translate pgvector HNSW DDL (CREATE INDEX … USING hnsw) to IRIS syntax
+            translated = self._translate_hnsw_index_ddl(sql)
+            if translated != sql:
+                logger.info("HNSW DDL translated", translated=translated[:200])
+            return translated
 
         return self._rewrite_operators_in_text(sql)
 
@@ -604,6 +614,113 @@ class VectorQueryOptimizer:
         }
 
 
+    # ------------------------------------------------------------------
+    # HNSW index DDL translation (pgvector → IRIS)
+    # ------------------------------------------------------------------
+
+    _HNSW_DDL_RE = re.compile(
+        r"""
+        CREATE\s+INDEX\s+                    # CREATE INDEX
+        (?:IF\s+NOT\s+EXISTS\s+)?            # optional IF NOT EXISTS
+        (\w+)\s+                             # index name (group 1)
+        ON\s+(\w+(?:\.\w+)?)\s+             # ON table (group 2; schema.table ok)
+        USING\s+hnsw\s*                      # USING hnsw
+        \(\s*(\w+)(?:\s+(\w+))?\s*\)        # (column [inline_op_class]) groups 3,4
+        (?:\s+WITH\s*\(([^)]*)\))?           # optional WITH (options) group 5
+        """,
+        re.IGNORECASE | re.VERBOSE,
+    )
+
+    _DISTANCE_MAP = {
+        "vector_cosine_ops": "Cosine",
+        "vector_ip_ops": "DotProduct",
+        "vector_l2_ops": None,
+    }
+
+    def _translate_hnsw_index_ddl(self, sql: str) -> str:
+        """Translate pgvector HNSW index DDL to IRIS-native HNSW syntax."""
+
+        def _replace(m: re.Match) -> str:
+            idx_name = m.group(1)
+            table = m.group(2)
+            col = m.group(3)
+            inline_ops = m.group(4) or ""
+            with_clause = m.group(5) or ""
+            distance = "Cosine"
+            ops_source = inline_ops or ""
+            ops_match = re.search(r"op_class\s*=\s*(\w+)", with_clause, re.IGNORECASE)
+            if ops_match:
+                ops_source = ops_match.group(1)
+            if ops_source:
+                mapped = self._DISTANCE_MAP.get(ops_source.lower())
+                if mapped is None:
+                    raise NotImplementedError(
+                        "IRIS does not support L2 distance (vector_l2_ops) in HNSW indexes. "
+                        "Use Cosine or DotProduct."
+                    )
+                distance = mapped
+            iris_ddl = f"CREATE INDEX {idx_name} ON {table} ({col}) AS HNSW(Distance={distance}"
+            m_opts = re.search(r"\bm\s*=\s*(\d+)", with_clause, re.IGNORECASE)
+            ef_opts = re.search(r"ef_construction\s*=\s*(\d+)", with_clause, re.IGNORECASE)
+            if m_opts:
+                iris_ddl += f", M={m_opts.group(1)}"
+            if ef_opts:
+                iris_ddl += f", efConstruction={ef_opts.group(1)}"
+            iris_ddl += ")"
+            return iris_ddl
+
+        return self._HNSW_DDL_RE.sub(_replace, sql)
+
+    # ------------------------------------------------------------------
+    # PostgreSQL JSON operators → IRIS JSON_VALUE / JSON_QUERY
+    # ------------------------------------------------------------------
+
+    _JSON_CHAIN_RE = re.compile(
+        r"(\w+(?:\.\w+)?)"
+        r"((?:\s*->>\s*'[^']+'"
+        r"|\s*->\s*'[^']+')+)",
+        re.IGNORECASE,
+    )
+
+    def _translate_nested_json_operators(self, sql: str) -> str:
+        """Translate PostgreSQL -> / ->> chains to IRIS JSON_VALUE / JSON_QUERY."""
+
+        def _replace(m: re.Match) -> str:
+            col = m.group(1)
+            chain = m.group(2)
+            text_extract = "->>" in chain
+            keys = re.findall(r"->>?\s*'([^']+)'", chain)
+            path = "." + ".".join(keys)
+            if text_extract:
+                return f"JSON_VALUE({col}, '${path}')"
+            return f"JSON_QUERY({col}, '${path}')"
+
+        return self._JSON_CHAIN_RE.sub(_replace, sql)
+
+    # ------------------------------------------------------------------
+    # IF NOT EXISTS error classification (Feature 026)
+    # ------------------------------------------------------------------
+
+    _IRIS_DUPLICATE_CODES = frozenset({
+        "5016",
+        "5019",
+        "5002",
+        "SQLCODE: <-5016>",
+        "SQLCODE: <-5019>",
+        "SQLCODE: <-5002>",
+    })
+
+    @staticmethod
+    def is_duplicate_object_error(error_msg: str) -> bool:
+        """Return True if error_msg indicates an object-already-exists SQLCODE."""
+        return any(code in error_msg for code in VectorQueryOptimizer._IRIS_DUPLICATE_CODES)
+
+    @staticmethod
+    def sql_has_if_not_exists(sql: str) -> bool:
+        """Return True if sql contains an IF NOT EXISTS clause."""
+        return bool(re.search(r"\bIF\s+NOT\s+EXISTS\b", sql, re.IGNORECASE))
+
+
 # ---------------------------------------------------------------------------
 # Module-level API
 # ---------------------------------------------------------------------------