fix: thread original_sql through execute pipeline so RETURNING emulation fires

Two root causes for INSERT...RETURNING still returning [] after v1.5.5:

1. Execute handler fast-batch bypass checked has_returning on translated_query
   (RETURNING stripped) → INSERT...RETURNING was batched, emulation skipped.
   Fix: use original_query (pre-translation) for has_returning check.

2. _prepare_sql built ReturningPlan from optimized_sql (RETURNING stripped by
   normalization pipeline) → plan.has_returning always False, emulation block
   never entered. Fix: add original_sql param to _prepare_sql, thread it from
   _execute_external_async, _execute_embedded_async, and execute_query.

Both paths (embedded + external) fixed. Bumps version to 1.5.6.

Author: tom-dyar

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.6] - 2026-03-09
+
+### Fixed
+- **`INSERT ... RETURNING` returns empty array with Extended Query Protocol (Drizzle / Better Auth) — complete fix**: v1.5.5 fixed the Describe phase (NoData → RowDescription), but the Execute phase still returned zero rows. Two additional root causes:
+
+  1. **Fast-batch bypass used translated SQL for `has_returning` check** (`protocol.py` Execute handler): The batch fast-path (`is_dml and not has_returning`) inspected `translated_query` (RETURNING stripped) instead of `original_query`. This caused `has_returning=False`, so INSERT...RETURNING was incorrectly fast-batched — the INSERT executed and sent a synthetic `CommandComplete` immediately, but `_emulate_returning` was never reached and zero DataRows were returned.
+
+  2. **`_prepare_sql` used translated SQL for `ReturningPlan`** (`iris_executor.py`): Even when the fast-batch was bypassed, `_prepare_sql` built `ReturningPlan` from `optimized_sql` (which has RETURNING stripped by the normalization pipeline). `plan.has_returning` was therefore always `False`, so the RETURNING emulation block was never entered. Fixed by adding an `original_sql` parameter to `_prepare_sql`, `_execute_external_async`, `_execute_embedded_async`, and `execute_query`, threading the pre-translation SQL all the way through so `ReturningPlan` can detect RETURNING correctly.
+
+- **Impact**: Affects both embedded and external IRIS connection modes. Better Auth "Failed to create session", Drizzle `.returning()` always `[]`, SQLAlchemy `.returning()` with psycopg3.
+
 ## [1.5.5] - 2026-03-09
 
 ### Fixed

src/iris_pgwire/__init__.py

@@ -6,7 +6,7 @@
 caretdev/sqlalchemy-iris.
 """
 
-__version__ = "1.5.5"
+__version__ = "1.5.6"
 __author__ = "Thomas Dyar <thomas.dyar@intersystems.com>"
 
 # Don't import server/protocol in __init__ to avoid sys.modules conflicts

src/iris_pgwire/iris_executor.py

@@ -627,6 +627,7 @@ def _prepare_sql(
         params: list | None,
         execution_path: str,
         session_id: str | None = None,
+        original_sql: str | None = None,
     ) -> tuple[str, list | None, "ReturningPlan", float]:
         """
         Shared pre-execution pipeline (steps 1–7) used by both embedded and external paths.
@@ -678,8 +679,12 @@ def _prepare_sql(
         t_opt_elapsed = (time.perf_counter() - t_opt_start) * 1000
 
         # 5. RETURNING / ON CONFLICT parsing
+        # Use original_sql (pre-translation) for RETURNING detection when available.
+        # translated sql (optimized_sql) has the RETURNING clause stripped because IRIS
+        # doesn't support it natively — so ReturningPlan must inspect the original.
+        _sql_for_plan = original_sql if original_sql else optimized_sql
         plan = ReturningPlan.from_sql(
-            optimized_sql,
+            _sql_for_plan,
             metadata_cache=self.metadata_cache,
             executor=self,
         )
@@ -998,10 +1003,14 @@ async def execute_query(
                 )
                 if self.embedded_mode:
                     logger.warning("🔍 DEBUG: Taking EMBEDDED path → _execute_embedded_async()")
-                    result = await self._execute_embedded_async(sql, params, session_id)
+                    result = await self._execute_embedded_async(
+                        sql, params, session_id, original_sql=kwargs.get("original_sql")
+                    )
                 else:
                     logger.warning("🔍 DEBUG: Taking EXTERNAL path → _execute_external_async()")
-                    result = await self._execute_external_async(sql, params, session_id)
+                    result = await self._execute_external_async(
+                        sql, params, session_id, original_sql=kwargs.get("original_sql")
+                    )
 
                 # Feature 026: Handle DDL idempotency (IF NOT EXISTS)
                 # Check both for raised exceptions and for success=False results
@@ -2292,7 +2301,11 @@ def _materialize_embedded_result(
         return rows, columns
 
     async def _execute_embedded_async(
-        self, sql: str, params: list | None = None, session_id: str | None = None
+        self,
+        sql: str,
+        params: list | None = None,
+        session_id: str | None = None,
+        original_sql: str | None = None,
     ) -> dict[str, Any]:
         """Execute query in IRIS embedded Python environment (async wrapper)"""
 
@@ -2354,7 +2367,11 @@ def _sync_execute(captured_sql, captured_params, captured_session_id):
 
                 # Steps 1-7: Shared pre-execution pipeline
                 optimized_sql, optimized_params, plan, t_opt_elapsed = self._prepare_sql(
-                    sql, params, execution_path="direct", session_id=session_id
+                    sql,
+                    params,
+                    execution_path="direct",
+                    session_id=session_id,
+                    original_sql=original_sql,
                 )
                 optimized_sql_upper = optimized_sql.upper()
                 returning_operation = plan.operation
@@ -2883,7 +2900,11 @@ def _materialize_external_result(
         return rows, columns
 
     async def _execute_external_async(
-        self, sql: str, params: list | None = None, session_id: str | None = None
+        self,
+        sql: str,
+        params: list | None = None,
+        session_id: str | None = None,
+        original_sql: str | None = None,
     ) -> dict[str, Any]:
         """
         Execute SQL using external IRIS connection with proper async threading
@@ -2910,7 +2931,11 @@ def _sync_external_execute(captured_sql, captured_params, captured_session_id):
 
                 # Steps 1-7: Shared pre-execution pipeline
                 optimized_sql, optimized_params, plan, t_opt_elapsed = self._prepare_sql(
-                    sql, params, execution_path="external", session_id=session_id
+                    sql,
+                    params,
+                    execution_path="external",
+                    session_id=session_id,
+                    original_sql=original_sql,
                 )
                 optimized_sql_upper = optimized_sql.upper()
 

src/iris_pgwire/protocol.py

@@ -3312,6 +3312,9 @@ async def handle_execute_message(self, body: bytes):
 
             # Use translated query for execution
             query = stmt.get("translated_query", stmt.get("query", stmt.get("original_query", "")))
+            # Use original_query for RETURNING detection: translated_query has RETURNING stripped.
+            # has_returning check below decides whether to fast-batch (DML without RETURNING).
+            original_query = stmt.get("original_query", query)
 
             # Log execution of prepared statement with translation metadata
             translation_metadata = stmt.get("translation_metadata", {})
@@ -3394,7 +3397,11 @@ async def handle_execute_message(self, body: bytes):
             # Standard PostgreSQL clients (psycopg3) send Sync every 5 rows, which is slow.
             # We buffer parameters and send synthetic CommandComplete to keep client pipe full.
             is_dml = self.iris_executor.sql_parser.is_dml_statement(query)
-            has_returning = self.iris_executor.sql_parser.has_returning_clause(query)
+            # Use original_query for RETURNING detection: translated_query has RETURNING stripped.
+            # If we used query (translated) here, INSERT...RETURNING would be fast-batched
+            # (because has_returning=False on translated_query), INSERT would execute but
+            # zero DataRows would be returned to the client.
+            has_returning = self.iris_executor.sql_parser.has_returning_clause(original_query)
 
             if is_dml and not has_returning:
                 # Store SQL if first row in batch
@@ -3432,6 +3439,7 @@ async def handle_execute_message(self, body: bytes):
                 session_id=self.connection_id,
                 in_transaction=in_txn,
                 autocommit=autocommit,
+                original_sql=original_query,
             )
 
             if result["success"]: