confluent-sql 0.5.1__tar.gz → 0.5.3__tar.gz

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 All notable changes to this dbapi driver will be documented in this file.
 
-## Unreleased
+## 0.5.3, 2026-08-27
+
+### Fixed
+
+- `Statement.from_response()` no longer raises `OperationalError` for a `PENDING` statement with no `status.traits`, which can possibly happen. (#194)
+
+## 0.5.2, 2026-08-26
+
+### Fixed
+
+- `Statement.is_pure_ddl` / `_PURE_DDL_KINDS` now include `CREATE_MATERIALIZED_TABLE`, `CREATE_OR_ALTER_MATERIALIZED_TABLE`, `ALTER_MATERIALIZED_TABLE` (the bare, query-evolving form), and `DROP_MATERIALIZED_TABLE`.
+  - Previously these kinds weren't classified as pure or impure DDL, so in **streaming** execution mode, `Statement.can_fetch_results` fell through to the "ready when RUNNING" branch used for CTAS -- meaning a streaming-mode `Cursor.execute()` (and therefore `Connection.execute_streaming_ddl()`) on one of these statements could in principle return control as soon as the statement was RUNNING rather than waiting for it to reach a terminal phase, the same way `execute_streaming_ddl()` correctly waits out a genuinely perpetual CTAS job's RUNNING phase. Snapshot execution mode (the default, and what `execute_snapshot_ddl()` always uses) was unaffected -- it already waits for a terminal phase regardless of `is_pure_ddl`.
 
 ## 0.5.1, 2026-08-25
 

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: confluent-sql
-Version: 0.5.1
+Version: 0.5.3
 Summary: DB-API v2 compliant driver for Confluent Cloud Flink SQL
 Project-URL: Repository, https://github.com/confluentinc/confluent-sql
 Project-URL: Documentation, https://github.com/confluentinc/confluent-sql?tab=readme-ov-file#confluent-sql

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "confluent-sql"
-version = "0.5.1"
+version = "0.5.3"
 description = "DB-API v2 compliant driver for Confluent Cloud Flink SQL"
 readme = "README.md"
 requires-python = ">=3.10"

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/src/confluent_sql/cursor.py

@@ -259,8 +259,9 @@ class Cursor:
 
         if self._statement.is_failed:
             raise OperationalError(
-                f"Statement submission failed: {self._statement.status.get('detail', '')}"
-            )  # pragma: no cover
+                f"Statement '{self._statement.name}' submission failed:"
+                f" {self._statement.status.get('detail', '')}"
+            )
 
         # ... and wait for it to be "ready" (either in a terminal state or running) based on
         # execution mode and statement type.

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/src/confluent_sql/statement.py

@@ -170,12 +170,30 @@ class Statement:
     """Represents a Confluent SQL statement, including its metadata, spec, status,
     and parsed traits such as schema, sql kind, etc."""
 
-    # SQL kinds that represent pure DDL statements (create/modify schema objects)
+    # SQL kinds that represent pure DDL statements (create/modify schema objects) which should
+    # be waiting for a terminal state before the created/modified objects are usable.
     _PURE_DDL_KINDS = frozenset(
-        {"CREATE_TABLE", "DROP_TABLE", "CREATE_VIEW", "DROP_VIEW", "ALTER_TABLE"}
+        {
+            "CREATE_TABLE",
+            "DROP_TABLE",
+            "CREATE_VIEW",
+            "DROP_VIEW",
+            "ALTER_TABLE",
+            # The four MATERIALIZED_TABLE kinds stretch "pure" a little: unlike the other
+            # members, CREATE_MATERIALIZED_TABLE, CREATE_OR_ALTER_MATERIALIZED_TABLE, and
+            # ALTER_MATERIALIZED_TABLE (a query-evolving ALTER, not just a metadata-only one)
+            # also kick off (or redeploy) a persistent background refresh job that keeps running
+            # long after this statement settles. But they still will reliably reach terminal
+            # COMPLETED (or FAILED) phase independent of the background job, which is the one
+            # thing this property actually gates.
+            "CREATE_MATERIALIZED_TABLE",
+            "CREATE_OR_ALTER_MATERIALIZED_TABLE",
+            "ALTER_MATERIALIZED_TABLE",
+            "DROP_MATERIALIZED_TABLE",
+        }
     )
 
-    # SQL kinds that represent impure DDL (produce no result set but may stream)
+    # SQL kinds that represent impure DDL (produce no result set but will remain in RUNNING phase)
     _IMPURE_DDL_KINDS = frozenset({"CREATE_TABLE_AS"})
 
     # From the cursor that created this statement ...
@@ -225,6 +243,12 @@ class Statement:
         if self.phase.is_terminal:
             return True
 
+        # Traits aren't sent on the initial PENDING response (see #194) -- without them, the
+        # trait-dependent checks below (is_pure_ddl, is_bounded, is_append_only) can't run yet,
+        # and a non-terminal statement with no traits can't be ready to fetch results anyway.
+        if self.traits is None:
+            return False
+
         if execution_mode.is_streaming:
             # In streaming mode, readiness depends on statement type.
             if self.is_pure_ddl:
@@ -336,9 +360,22 @@ class Statement:
         Pure DDL statements need to complete fully before the created/modified objects
         are ready for use, unlike streaming queries or CTAS which are ready when RUNNING.
 
+        "Pure" is stretched a little to also cover CREATE_MATERIALIZED_TABLE,
+        CREATE_OR_ALTER_MATERIALIZED_TABLE, and ALTER_MATERIALIZED_TABLE (the query-evolving
+        form -- see CREATE_OR_ALTER_MATERIALIZED_TABLE): their completion additionally kicks off
+        (or redeploys) a persistent background refresh job that keeps running long after the
+        statement settles, which isn't true of the other members. They earn the label anyway
+        because they satisfy the one thing this property actually gates: the statement's own
+        phase reliably reaches a terminal phase before the created/altered object is usable,
+        rather than lingering in RUNNING the way CTAS does (see _PURE_DDL_KINDS for the
+        confirming detail). DROP_MATERIALIZED_TABLE needs no such stretch -- like the other
+        DROP_* kinds, it's a one-shot action with no background job of its own.
+
         Returns:
             True if the statement is one of: CREATE_TABLE, DROP_TABLE, CREATE_VIEW,
-            DROP_VIEW, ALTER_TABLE. False otherwise.
+            DROP_VIEW, ALTER_TABLE, CREATE_MATERIALIZED_TABLE,
+            CREATE_OR_ALTER_MATERIALIZED_TABLE, ALTER_MATERIALIZED_TABLE,
+            DROP_MATERIALIZED_TABLE. False otherwise.
         """
         return self.sql_kind in self._PURE_DDL_KINDS
 
@@ -482,8 +519,9 @@ class Statement:
                 else None
             )
 
-            # Defensive check: non-failed statements should have traits
-            if traits is None and phase != Phase.FAILED:
+            # Defensive check: non-failed, non-pending statements should have traits. FAILED
+            # statements never get traits, and PENDING may or may not have traits. (see #194).
+            if traits is None and phase not in (Phase.FAILED, Phase.PENDING):
                 raise OperationalError(
                     f"Received statement '{name}' in phase {phase} without traits. "
                     "This is unexpected and likely indicates a server API change or bug."

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/tests/integration/test_fetch.py

@@ -9,7 +9,7 @@ from typing import NamedTuple
 
 import pytest
 
-from confluent_sql import Connection, SqlNone, YearMonthInterval
+from confluent_sql import Connection, OperationalError, SqlNone, YearMonthInterval
 from confluent_sql.execution_mode import ExecutionMode
 
 
@@ -678,6 +678,133 @@ class TestExecuteDDL:
         assert statement.schema is None, "CTAS schema should be None"
         assert statement.is_deleted, "Snapshot DDL statement should be auto-deleted"
 
+    def test_execute_streaming_ddl_create_materialized_table_completes(
+        self, connection: Connection, auto_dropped_table_name: str
+    ):
+        """Prove that CREATE MATERIALIZED TABLE, submitted via execute_streaming_ddl(), waits
+        for the statement to reach COMPLETED rather than returning as soon as it's RUNNING --
+        unlike CTAS, whose backing job runs forever, a materialized table's own CREATE statement
+        settles once its background refresh job is started (see statement.py's is_pure_ddl)."""
+        try:
+            statement_text = f"""
+                CREATE MATERIALIZED TABLE `{auto_dropped_table_name}`
+                AS SELECT * FROM `sample_data_stock_trades` WHERE quantity > 100
+            """
+
+            statement = connection.execute_streaming_ddl(statement_text)
+
+            # execute_streaming_ddl's closing_cursor auto-deletes a terminal statement on exit,
+            # which flips Statement.phase to DELETED (it overrides the underlying phase once
+            # deleted -- see Statement.phase) -- so we can't read back "COMPLETED" directly here.
+            # is_deleted only follows from a *deletable* terminal phase (COMPLETED/FAILED/
+            # STOPPED); FAILED would have raised OperationalError out of execute_streaming_ddl
+            # instead of returning, and nothing here ever requested a STOPPED, so reaching this
+            # line with is_deleted true and no exception raised is exactly the proof that the
+            # statement settled to COMPLETED.
+            assert not statement.is_running
+            assert statement.is_deleted
+
+            # The table should be immediately queryable.
+            with connection.closing_cursor(as_dict=True) as cursor:
+                cursor.execute(f"SELECT COUNT(*) AS row_count FROM `{auto_dropped_table_name}`")
+                results = cursor.fetchone()
+                assert results is not None
+        finally:
+            with suppress(Exception):
+                connection.execute_snapshot_ddl(
+                    f"DROP MATERIALIZED TABLE IF EXISTS `{auto_dropped_table_name}`"
+                )
+
+    def test_execute_streaming_ddl_create_or_alter_materialized_table_completes(
+        self, connection: Connection, auto_dropped_table_name: str
+    ):
+        """Prove that CREATE OR ALTER MATERIALIZED TABLE, and a bare (query-evolving) ALTER
+        MATERIALIZED TABLE, both also wait for COMPLETED, same as a first-time CREATE
+        MATERIALIZED TABLE. Each step respells the filter predicate (>100, then >=100, then >50)
+        to exercise a genuine redefinition of an already-existing materialized table."""
+
+        def show_create_ddl_text(table_name: str) -> str:
+            # SHOW CREATE MATERIALIZED TABLE is a plain bounded single-row query, so a default
+            # (snapshot mode) cursor is all it needs.
+            with connection.closing_cursor(as_dict=True) as cursor:
+                cursor.execute(f"SHOW CREATE MATERIALIZED TABLE `{table_name}`")
+                row = cursor.fetchone()
+                assert row is not None
+                return row["SHOW CREATE MATERIALIZED TABLE"]  # type: ignore[index]
+
+        try:
+            create_statement_text = f"""
+                CREATE MATERIALIZED TABLE `{auto_dropped_table_name}`
+                AS SELECT * FROM `sample_data_stock_trades` WHERE quantity > 100
+            """
+            created = connection.execute_streaming_ddl(create_statement_text)
+            assert not created.is_running
+            assert created.is_deleted  # see the sibling CREATE test for why this implies COMPLETED
+
+            create_or_alter_statement_text = f"""
+                CREATE OR ALTER MATERIALIZED TABLE `{auto_dropped_table_name}`
+                AS SELECT * FROM `sample_data_stock_trades` WHERE quantity >= 100
+            """
+            create_or_altered = connection.execute_streaming_ddl(create_or_alter_statement_text)
+
+            assert not create_or_altered.is_running
+            assert create_or_altered.is_deleted
+
+            # Prove the redefinition actually took effect.
+            assert ">= 100" in show_create_ddl_text(auto_dropped_table_name)
+
+            # A bare ALTER (no CREATE OR prefix) with a new AS SELECT is query evolution too --
+            # same completion semantics, since ALTER_MATERIALIZED_TABLE is also pure DDL.
+            bare_alter_statement_text = f"""
+                ALTER MATERIALIZED TABLE `{auto_dropped_table_name}`
+                AS SELECT * FROM `sample_data_stock_trades` WHERE quantity > 50
+            """
+            bare_altered = connection.execute_streaming_ddl(bare_alter_statement_text)
+
+            assert not bare_altered.is_running
+            assert bare_altered.is_deleted
+
+            assert "> 50" in show_create_ddl_text(auto_dropped_table_name)
+        finally:
+            with suppress(Exception):
+                connection.execute_snapshot_ddl(
+                    f"DROP MATERIALIZED TABLE IF EXISTS `{auto_dropped_table_name}`"
+                )
+
+    def test_execute_snapshot_ddl_drop_materialized_table_completes(
+        self, connection: Connection, auto_dropped_table_name: str
+    ):
+        """Prove that DROP MATERIALIZED TABLE, submitted via execute_snapshot_ddl(), completes
+        (it's pure DDL, like the other DROP_* kinds -- see statement.py's _PURE_DDL_KINDS)."""
+        try:
+            create_statement_text = f"""
+                CREATE MATERIALIZED TABLE `{auto_dropped_table_name}`
+                AS SELECT * FROM `sample_data_stock_trades` WHERE quantity > 100
+            """
+            connection.execute_streaming_ddl(create_statement_text)
+
+            drop_statement = connection.execute_snapshot_ddl(
+                f"DROP MATERIALIZED TABLE `{auto_dropped_table_name}`"
+            )
+
+            # is_deleted implies COMPLETED here, not just some other deletable terminal phase --
+            # see the CREATE test above for why.
+            assert not drop_statement.is_running
+            assert drop_statement.is_deleted
+
+            # The table should be gone: selecting from it should now fail with the backend's
+            # missing-object diagnostic, not just some unrelated failure.
+            with (
+                pytest.raises(OperationalError, match="does not exist"),
+                connection.closing_cursor() as cursor,
+            ):
+                cursor.execute(f"SELECT * FROM `{auto_dropped_table_name}`")
+        finally:
+            with suppress(Exception):
+                connection.execute_snapshot_ddl(
+                    f"DROP MATERIALIZED TABLE IF EXISTS `{auto_dropped_table_name}`"
+                )
+
 
 @pytest.mark.integration
 class TestArrayStatements:

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/tests/unit/test_cursor_unit.py

@@ -13,7 +13,7 @@ from confluent_sql.exceptions import (
 )
 from confluent_sql.execution_mode import ExecutionMode
 from confluent_sql.result_readers import ChangelogEventReader, ChangeloggedRow, FetchMetrics
-from confluent_sql.statement import ChangelogRow, Op, Statement
+from confluent_sql.statement import ChangelogRow, Op, Phase, Statement
 from tests.unit.conftest import (
     CursorWithStatementFactory,
     MockConnectionFactory,
@@ -94,6 +94,33 @@ class TestExecute:
         # non-append-only statements.
         assert isinstance(mock_connection_cursor._result_reader, ChangelogEventReader)
 
+    def test_execute_raises_with_actual_statement_name_on_immediate_submission_failure(
+        self,
+        mock_connection_cursor: Cursor,
+        statement_response_factory: StatementResponseFactory,
+    ):
+        """Prove that when the *submission* response (not a later poll) already reports FAILED,
+        the raised OperationalError names the statement per the parsed response -- not the
+        caller's statement_name argument, which is None on the common path where the caller lets
+        the server generate a name. Regression test for the bug Copilot's review of #195 caught:
+        interpolating the (usually None) statement_name parameter instead of
+        self._statement.name."""
+        failed_submission = statement_response_factory(
+            phase="FAILED",
+            status_detail="Invalid SQL syntax",
+            name="dbapi-server-generated-name",
+        )
+        mock_connection_cursor._connection._execute_statement.return_value = (  # type: ignore
+            failed_submission
+        )
+
+        with pytest.raises(
+            OperationalError,
+            match=r"Statement 'dbapi-server-generated-name' submission failed: Invalid SQL syntax",
+        ):
+            # statement_name intentionally omitted, as most callers do -- the server assigns one.
+            mock_connection_cursor.execute("SELECT 1 AS col")
+
     def test_execute_calls_raise_if_statement_is_broken_for_failed_statement(
         self,
         mock_connection_cursor: Cursor,
@@ -253,6 +280,53 @@ class TestExecute:
 
         backoff.assert_called_once_with(30, started_at=0.0)
 
+    def test_becomes_ready_after_pending_without_traits_then_running_with_traits(
+        self,
+        mock_connection_cursor: Cursor,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        """End-to-end lifecycle for #194: a statement is submitted PENDING with no traits (the
+        documented shape of Confluent Cloud's initial response), stays PENDING with no traits for
+        two more polls, then transitions to RUNNING with traits -- at which point execute() must
+        return instead of raising or timing out."""
+        pending_no_traits = statement_response_factory(phase="PENDING")
+        pending_no_traits["status"]["traits"] = None
+
+        running_with_traits = statement_response_factory(
+            sql_statement="SELECT * FROM source_table",
+            sql_kind="SELECT",
+            phase="RUNNING",
+            is_bounded=True,
+            is_append_only=True,
+        )
+
+        mock_connection_cursor._execution_mode = ExecutionMode.STREAMING_QUERY
+
+        # The initial submission (POST) response.
+        mock_connection_cursor._connection._execute_statement.return_value = (  # type: ignore
+            pending_no_traits
+        )
+        # Subsequent polls (GET): two more PENDING-without-traits observations, then RUNNING
+        # with traits on the third.
+        mock_connection_cursor._connection._get_statement.side_effect = (  # type: ignore
+            [pending_no_traits, pending_no_traits, running_with_traits]
+        )
+
+        mocker.patch("time.sleep", return_value=None)
+        start_time = 1000000.0
+        time_mock = mocker.patch(
+            "time.monotonic", side_effect=lambda: start_time + time_mock.call_count
+        )
+
+        mock_connection_cursor.execute("SELECT * FROM source_table")
+
+        assert mock_connection_cursor._connection._get_statement.call_count == 3  # type: ignore
+        assert mock_connection_cursor._statement is not None
+        assert mock_connection_cursor._statement.phase is Phase.RUNNING
+        assert mock_connection_cursor._statement.traits is not None
+        assert mock_connection_cursor._statement.can_fetch_results(ExecutionMode.STREAMING_QUERY)
+
     @pytest.mark.parametrize(
         "streaming_mode",
         [ExecutionMode.STREAMING_QUERY, ExecutionMode.STREAMING_DDL],

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/tests/unit/test_statement_unit.py

@@ -440,6 +440,10 @@ class TestStatementProperties:
             ("CREATE_VIEW", True),
             ("DROP_VIEW", True),
             ("ALTER_TABLE", True),
+            ("CREATE_MATERIALIZED_TABLE", True),
+            ("CREATE_OR_ALTER_MATERIALIZED_TABLE", True),
+            ("ALTER_MATERIALIZED_TABLE", True),
+            ("DROP_MATERIALIZED_TABLE", True),
             ("SELECT", False),
             ("INSERT", False),
             ("UPDATE", False),
@@ -613,6 +617,22 @@ class TestStatementFromResponse:
         ):
             Statement.from_response(mock_connection, response)
 
+    def test_allows_pending_statement_without_traits(
+        self, mock_connection: Connection, statement_response_factory: StatementResponseFactory
+    ):
+        """Test that from_response accepts a PENDING statement without traits.
+
+        Confluent Cloud's documented initial response to a statement submission is a PENDING
+        phase with no status.traits at all -- see #194. Traits only become available once the
+        statement has been polled at least once.
+        """
+        response = statement_response_factory(phase="PENDING")
+        response["status"]["traits"] = None
+
+        statement = Statement.from_response(mock_connection, response)
+        assert statement.traits is None
+        assert statement.phase == Phase.PENDING
+
     def test_parses_row_result_schema(
         self, mock_connection: Connection, statement_response_factory: StatementResponseFactory
     ):
@@ -980,32 +1000,63 @@ class TestStatementCanFetchResults:
         statement = Statement.from_response(mock_connection, statement_json)
         assert statement.can_fetch_results(ExecutionMode.STREAMING_QUERY)
 
+    @pytest.mark.parametrize(
+        "sql_kind",
+        [
+            "CREATE_TABLE",
+            "CREATE_MATERIALIZED_TABLE",
+            "CREATE_OR_ALTER_MATERIALIZED_TABLE",
+            "ALTER_MATERIALIZED_TABLE",
+            "DROP_MATERIALIZED_TABLE",
+        ],
+    )
     @pytest.mark.parametrize("phase", ["PENDING", "RUNNING"])
     def test_streaming_ddl_pure_ddl_not_ready(
         self,
         mock_connection: Connection,
         statement_response_factory: StatementResponseFactory,
         phase: str,
+        sql_kind: str,
     ):
-        """In streaming DDL mode, pure DDL must wait for terminal state."""
+        """In streaming DDL mode, pure DDL must wait for terminal state.
+
+        The three MATERIALIZED_TABLE kinds are included alongside CREATE_TABLE here: even though
+        CREATE_MATERIALIZED_TABLE, CREATE_OR_ALTER_MATERIALIZED_TABLE, and
+        ALTER_MATERIALIZED_TABLE all kick off (or redeploy) a persistent background refresh job
+        on completion, each statement's own phase reliably reaches a terminal phase once that job
+        is started (confirmed against a real environment -- unlike CTAS, which the Flink API
+        traits currently mis-report as perpetually RUNNING, see is_bounded's Jan 2026 bug note),
+        so they belong in the same "must wait for terminal" bucket as the other pure DDL kinds.
+        """
         statement_json = statement_response_factory(
             phase=phase,
-            sql_kind="CREATE_TABLE",
+            sql_kind=sql_kind,
         )
         statement = Statement.from_response(mock_connection, statement_json)
         assert not statement.can_fetch_results(ExecutionMode.STREAMING_DDL)
 
+    @pytest.mark.parametrize(
+        "sql_kind",
+        [
+            "CREATE_TABLE",
+            "CREATE_MATERIALIZED_TABLE",
+            "CREATE_OR_ALTER_MATERIALIZED_TABLE",
+            "ALTER_MATERIALIZED_TABLE",
+            "DROP_MATERIALIZED_TABLE",
+        ],
+    )
     @pytest.mark.parametrize("phase", ["COMPLETED", "STOPPED", "FAILED"])
     def test_streaming_ddl_pure_ddl_ready(
         self,
         mock_connection: Connection,
         statement_response_factory: StatementResponseFactory,
         phase: str,
+        sql_kind: str,
     ):
         """In streaming DDL mode, pure DDL is ready in terminal states."""
         statement_json = statement_response_factory(
             phase=phase,
-            sql_kind="CREATE_TABLE",
+            sql_kind=sql_kind,
         )
         statement = Statement.from_response(mock_connection, statement_json)
         assert statement.can_fetch_results(ExecutionMode.STREAMING_DDL)
@@ -1075,3 +1126,22 @@ class TestStatementCanFetchResults:
         )
         statement = Statement.from_response(mock_connection, statement_json)
         assert statement.can_fetch_results(ExecutionMode.STREAMING_DDL)
+
+    @pytest.mark.parametrize(
+        "execution_mode",
+        [ExecutionMode.SNAPSHOT, ExecutionMode.STREAMING_QUERY, ExecutionMode.STREAMING_DDL],
+    )
+    def test_pending_without_traits_not_ready(
+        self,
+        mock_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        execution_mode: ExecutionMode,
+    ):
+        """A freshly-submitted PENDING statement has no traits yet (see #194) -- it must be
+        reported as not-yet-ready rather than raising while probing trait-dependent properties
+        like is_pure_ddl."""
+        response = statement_response_factory(phase="PENDING")
+        response["status"]["traits"] = None
+
+        statement = Statement.from_response(mock_connection, response)
+        assert not statement.can_fetch_results(execution_mode)

{confluent_sql-0.5.1 → confluent_sql-0.5.3}/uv.lock

@@ -36,7 +36,7 @@ wheels = [
 
 [[package]]
 name = "confluent-sql"
-version = "0.5.1"
+version = "0.5.3"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },