Robust schema mapping and technical reference guide (v1.1.0)

Author: tom-dyar

AGENTS.md

@@ -36,4 +36,36 @@ Python 3.11+: Follow standard conventions
 
 
 <!-- MANUAL ADDITIONS START -->
+
+## IRIS Technical Reference (Critical for DBAPI & Embedded)
+
+### 1. DBAPI Connection Pattern (intersystems-irispython)
+Always use this robust import pattern to obtain the DBAPI module. This handles different package versions and environment quirks.
+```python
+try:
+    import iris.dbapi as iris_dbapi # Modern/Standard
+except ImportError:
+    try:
+        import intersystems_iris.dbapi._DBAPI as iris_dbapi # Deep Fallback
+    except ImportError:
+        # Last resort: check if iris module itself has connect (older versions)
+        import iris as iris_dbapi
+```
+
+### 2. Embedded SQL Execution (iris.sql.exec)
+When running code inside IRIS (Embedded Python), parameters **MUST** be passed using the splat operator `*params` to be treated as positional arguments.
+```python
+# CORRECT
+iris.sql.exec(sql, *params)
+
+# INCORRECT (passes list as a single argument)
+iris.sql.exec(sql, params) 
+```
+
+### 3. Case Sensitivity & Identifiers
+- **Schema Name**: Always use `SQLUser` (exact casing). IRIS package/schema names are case-sensitive.
+- **Quoted Identifiers**: Identifiers in double quotes (e.g., `"workflow"`) are case-sensitive in IRIS.
+- **Unquoted Identifiers**: Automatically mapped to UPPERCASE by IRIS.
+- **Normalization**: To ensure consistency, the normalizer should preserve the casing of quoted identifiers and map unquoted ones to uppercase, but it **MUST NOT** change the case of the `SQLUser` schema prefix.
+
 <!-- MANUAL ADDITIONS END -->

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-01-17
+
+### Added
+- **IRIS Technical Reference**: Added definitive guide to `AGENTS.md` covering DBAPI connection patterns, embedded SQL parameter passing, and case-sensitivity rules.
+
+### Fixed
+- **Robust Schema Mapping**: Rewrote `translate_input_schema` to correctly preserve table name quoting and casing (e.g., `public."workflow"` -> `SQLUser."workflow"`). This resolves "Class not found" errors in IRIS when ORMs use quoted identifiers.
+- **Embedded Parameter Passing**: Ensured `iris.sql.exec` receives parameters as positional arguments using the splat operator (`*params`) in all execution paths.
+- **Redundant Translation Cleanup**: Removed conflicting schema translation regexes in `iris_executor.py` that were previously stripping quotes from identifiers.
+
 ## [1.0.9] - 2026-01-17
 
 ### Fixed

list_iris_tables.py

@@ -0,0 +1,25 @@
+import iris
+
+
+def list_sqluser_tables():
+    print("Listing classes in SQLUser package:")
+    # Query %Dictionary.ClassDefinition for classes in SQLUser package
+    result = iris.sql.exec(
+        "SELECT Name FROM %Dictionary.ClassDefinition WHERE Name %STARTSWITH 'SQLUser.'"
+    )
+    for row in result:
+        print(f"Class: {row[0]}")
+
+    print("\nListing tables in SQLUser schema:")
+    result = iris.sql.exec(
+        "SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = 'SQLUser'"
+    )
+    for row in result:
+        print(f"Table: {row[0]}")
+
+
+if __name__ == "__main__":
+    try:
+        list_sqluser_tables()
+    except Exception as e:
+        print(f"Error: {e}")

src/iris_pgwire/__init__.py

@@ -6,7 +6,7 @@
 caretdev/sqlalchemy-iris.
 """
 
-__version__ = "1.0.9"
+__version__ = "1.1.0"
 __author__ = "IRIS PGWire Team"
 
 # Don't import server/protocol in __init__ to avoid sys.modules conflicts

src/iris_pgwire/iris_executor.py

@@ -3045,8 +3045,8 @@ def _sync_execute():
                 # Log the actual SQL being sent to IRIS for debugging
                 logger.info(
                     "About to execute iris.sql.exec",
+                    sql=optimized_sql[:1000],  # Log first 1000 chars
                     sql_ends_with_semicolon=optimized_sql.rstrip().endswith(";"),
-                    sql_last_20=optimized_sql.rstrip()[-20:],
                     has_params=optimized_params is not None and len(optimized_params) > 0,
                     session_id=session_id,
                 )

src/iris_pgwire/schema_mapper.py

@@ -68,34 +68,19 @@ def translate_input_schema(sql: str) -> str:
         flags=re.IGNORECASE,
     )
 
-    # Pattern 2: Schema-qualified table names (e.g., public.tablename or public."tablename")
-    # Match public. followed by identifier (word chars) or quoted identifier
-    result = re.sub(
-        r'\bpublic\s*\.\s*"(\w+)"',
-        rf'{IRIS_SCHEMA}."\1"',
-        result,
-        flags=re.IGNORECASE,
-    )
-    result = re.sub(
-        r"\bpublic\s*\.\s*(\w+)",
-        rf"{IRIS_SCHEMA}.\1",
-        result,
-        flags=re.IGNORECASE,
-    )
-
-    # Pattern 3: Double-quoted schema (e.g., "public".tablename or "public"."tablename")
-    result = re.sub(
-        r'"public"\s*\.\s*"(\w+)"',
-        rf'{IRIS_SCHEMA}."\1"',
-        result,
-        flags=re.IGNORECASE,
-    )
-    result = re.sub(
-        r'"public"\s*\.\s*(\w+)',
-        rf"{IRIS_SCHEMA}.\1",
-        result,
-        flags=re.IGNORECASE,
-    )
+    # Combined robust pattern for public.table, "public".table, public."table", "public"."table"
+    # Matches: (optional quotes)public(optional quotes) . (optional quotes)tablename(optional quotes)
+    # Group 1: opening quote for table, Group 2: table name, Group 3: closing quote for table
+    pattern = r'(?i)\b"?public"?\s*\.\s*(")?(\w+)(")?'
+
+    def replace_schema(match):
+        quoted_table = match.group(1) or ""
+        table_name = match.group(2)
+        closing_quote = match.group(3) or ""
+        # Always use SQLUser (exact case) and preserve table quoting/casing
+        return f"{IRIS_SCHEMA}.{quoted_table}{table_name}{closing_quote}"
+
+    result = re.sub(pattern, replace_schema, result)
 
     return result