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

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

@@ -2,7 +2,12 @@
 
 All notable changes to this dbapi driver will be documented in this file.
 
-## Unreleased
+## 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: confluent-sql
-Version: 0.5.1
+Version: 0.5.2
 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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "confluent-sql"
-version = "0.5.1"
+version = "0.5.2"
 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.2}/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 ...
@@ -336,9 +354,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
 

{confluent_sql-0.5.1 → confluent_sql-0.5.2}/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.2}/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),
@@ -980,32 +984,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)

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

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