confluent-sql 0.1.3__tar.gz → 0.2.0__tar.gz

confluent_sql-0.2.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Change Log
+
+All notable changes to this dbapi driver will be documented in this file.
+
+## Unreleased
+
+## 0.2.0
+
+### Changed
+  * Respelled the `connect()` parameter `dbname` to `database`. The old spelling `dbname` is deprecated and will be removed in after one release cycle.
+  * Class `SqlNone` now gracefully strips trailing `NOT NULL` constraints from type names (case-insensitively), so that `str(SqlNone("DATE NOT NULL"))` returns valid FlinkSQL `"cast (null as DATE)"`.
+  * `connect()` is now keyword-only callable.
+  * The `host` parameter for `Connection.__init__()` has been renamed to `endpoint`.
+
+### Added
+  * New optional keyword parameter `properties: PropertiesDict | None` on `Cursor.execute()` and related methods to allow callers to provide [statement execution properties](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html#table-options). Note: connection or cursor-level properties for default catalog, database, and execution mode cannot be overridden by this parameter.
+  * New optional `endpoint` parameter on `connect()` and `Connection.__init__` to allow users to specify a custom Confluent Cloud API base endpoint (e.g., for private networking, staging, etc.). Mutually exclusive with (`cloud_provider`, `cloud_region`) -- either `endpoint` or (`cloud_provider`, `cloud_region`) must be provided. This replaces the `host` parameter in `Connection.__init__()`. (#66)
+
+### Removed
+  * The unused control-plane `api_key` and `api_secret` `connect()` parameters have been removed. The Flink regional API key params `flink_api_key` and `flink_api_secret` remain.
+
+## 0.1.x
+
+Early access release of the driver.

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/DBAPI_EXTENSIONS.md

@@ -808,18 +808,39 @@ cursor.execute(
     timeout: int = 3000,
     statement_name: str | None = None,
     statement_label: str | None = None,
+    properties: dict[str, str | int | bool] | None = None,
 ) -> None
 ```
 
 ### Parameter Reference
 
-| Parameter         | Type                    | Default    | Description                                                        |
-| ----------------- | ----------------------- | ---------- | ------------------------------------------------------------------ |
-| `statement_text`  | `str`                   | (required) | SQL statement to execute                                           |
-| `parameters`      | `tuple \| list \| None` | None       | Parameter values for parameterized statements                      |
-| `timeout`         | `int`                   | 3000       | Max seconds to wait for statement to reach RUNNING/COMPLETED phase |
-| `statement_name`  | `str \| None`           | None       | Custom statement identifier (defaults to UUID)                     |
-| `statement_label` | `str \| None`           | None       | Label for grouping related statements                              |
+| Parameter         | Type                              | Default    | Description                                                        |
+| ----------------- | --------------------------------- | ---------- | ------------------------------------------------------------------ |
+| `statement_text`  | `str`                             | (required) | SQL statement to execute                                           |
+| `parameters`      | `tuple \| list \| None`           | None       | Parameter values for parameterized statements                      |
+| `timeout`         | `int`                             | 3000       | Max seconds to wait for statement to reach RUNNING/COMPLETED phase |
+| `statement_name`  | `str \| None`                     | None       | Custom statement identifier (defaults to UUID)                     |
+| `statement_label` | `str \| None`                     | None       | Label for grouping related statements                              |
+| `properties`      | `dict[str, str \| int \| bool] \| None` | None | [Statement properties](#statement-properties) to set for execution |
+
+### Statement Properties
+
+The `properties` parameter allows you to set [Flink SQL statement properties](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html#table-options) at query execution time. These are the same properties that can be set with Flink SQL `SET` statements.
+
+**Important Precedence Rules:**
+- Connection-level defaults (catalog, database) are always applied
+- Cursor execution mode settings (e.g., `sql.snapshot.mode` for snapshot queries) are always applied
+- User-provided properties in the `properties` parameter can extend these settings but cannot override system properties
+
+
+**Accessing Properties After Execution:**
+The properties are stored in the Statement object and can be accessed via `statement.properties`:
+
+```python
+cursor.execute(query, properties={"sql.state-ttl": "100 ms"})
+props = cursor.statement.properties
+assert props["sql.state-ttl"] == "100 ms"
+```
 
 **Examples:**
 
@@ -857,6 +878,14 @@ cursor.execute(
     statement_name="product-sales-hourly",
     statement_label="analytics"
 )
+
+# With statement properties
+cursor.execute(
+    "SELECT * FROM orders WHERE status = %s",
+    ("pending",),
+    statement_name="pending-orders-query",
+    properties={"sql.state-ttl": "100 ms"}
+)
 ```
 
 ---

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluent-sql
-Version: 0.1.3
+Version: 0.2.0
 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
@@ -245,7 +245,7 @@ This is pre-production code mainly developed as the lower level portion of a `db
 
 The behavior of snapshot-mode cursors, complying with dbapi semantics, are well stable. The streaming query extensions are more of a work in progress at this time. Feedback and suggestions are welcome!
 
-> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. The driver defaults to snapshot mode for all queries unless streaming mode is explicitly requested.
+> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. You will need to request access to snapshot queries for your organization from Confluent. The driver defaults to snapshot mode for all queries unless streaming mode is explicitly requested.
 
 ## Prerequisites
 
@@ -279,7 +279,7 @@ connection = confluent_sql.connect(
     compute_pool_id="lfcp-789012",
     cloud_provider="aws",
     cloud_region="us-east-2",
-    dbname="your-database-name"
+    database="your-database-name"
 )
 ```
 

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/README.md

@@ -14,7 +14,7 @@ This is pre-production code mainly developed as the lower level portion of a `db
 
 The behavior of snapshot-mode cursors, complying with dbapi semantics, are well stable. The streaming query extensions are more of a work in progress at this time. Feedback and suggestions are welcome!
 
-> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. The driver defaults to snapshot mode for all queries unless streaming mode is explicitly requested.
+> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. You will need to request access to snapshot queries for your organization from Confluent. The driver defaults to snapshot mode for all queries unless streaming mode is explicitly requested.
 
 ## Prerequisites
 
@@ -48,7 +48,7 @@ connection = confluent_sql.connect(
     compute_pool_id="lfcp-789012",
     cloud_provider="aws",
     cloud_region="us-east-2",
-    dbname="your-database-name"
+    database="your-database-name"
 )
 ```
 

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/examples/simple_append_only_streaming_query_example.py

@@ -13,7 +13,7 @@ conn = confluent_sql.connect(
     compute_pool_id=os.getenv("CONFLUENT_COMPUTE_POOL_ID", ""),
     cloud_provider=os.getenv("CONFLUENT_CLOUD_PROVIDER", ""),
     cloud_region=os.getenv("CONFLUENT_CLOUD_REGION", ""),
-    dbname=os.getenv("CONFLUENT_TEST_DBNAME", "default"),
+    database=os.getenv("CONFLUENT_TEST_DBNAME", "default"),
 )
 
 

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/pyproject.toml

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

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/src/confluent_sql/__init__.py

@@ -27,7 +27,7 @@ from .exceptions import (
 from .execution_mode import ExecutionMode
 from .result_readers import ChangeloggedRow
 from .statement import Op
-from .types import SqlNone, YearMonthInterval
+from .types import PropertiesDict, SqlNone, YearMonthInterval
 
 # DB-API v2 module globals
 apilevel = "2.0"
@@ -59,6 +59,7 @@ __all__ = [
     "apilevel",
     "threadsafety",
     "paramstyle",
+    "PropertiesDict",
     "SqlNone",
     "YearMonthInterval",
 ]

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/src/confluent_sql/connection.py

@@ -24,22 +24,23 @@ from .exceptions import InterfaceError, OperationalError, StatementDeletedError
 from .execution_mode import ExecutionMode
 from .statement import LABEL_PREFIX as STATEMENT_LABEL_PREFIX
 from .statement import ChangelogRow, Statement
-from .types import RowPythonTypes
+from .types import PropertiesDict, RowPythonTypes
 
 logger = logging.getLogger(__name__)
 
 
 def connect(  # noqa: PLR0913
+    *,
     flink_api_key: str,
     flink_api_secret: str,
     environment: str,
     compute_pool_id: str,
     organization_id: str,
-    cloud_provider: str,
-    cloud_region: str,
-    api_key: str | None = None,
-    api_secret: str | None = None,
-    dbname: str | None = None,
+    cloud_provider: str | None = None,
+    cloud_region: str | None = None,
+    database: str | None = None,
+    endpoint: str | None = None,
+    dbname: str | None = None,  # deprecated, use database parameter
     result_page_fetch_pause_millis: int = 100,
     http_user_agent: str | None = None,
 ) -> Connection:
@@ -47,16 +48,23 @@ def connect(  # noqa: PLR0913
     Create a connection to a Confluent SQL service.
 
     Args:
-        flink_api_key: Flink API key
-        flink_api_secret: Flink API secret
+        flink_api_key: Flink Region API key
+        flink_api_secret: Flink Region API secret
         environment: Environment ID
         compute_pool_id: Compute pool ID for SQL execution
         organization_id: Organization ID
-        cloud_provider: Cloud provider (e.g., "aws", "gcp", "azure")
-        cloud_region: Cloud region (e.g., "us-east-2", "us-west-2")
-        api_key: Confluent Cloud API key (optional, for general Confluent Cloud resources)
-        api_secret: Confluent Cloud API secret (optional)
-        dbname: The name of the database to use (optional)
+        cloud_provider: Cloud provider (e.g., "aws", "gcp", "azure"). Required if endpoint is not
+            provided; must not be provided if endpoint is specified.
+        cloud_region: Cloud region (e.g., "us-east-2", "us-west-2"). Required if endpoint is not
+            provided; must not be provided if endpoint is specified.
+        database: The default Flink database (Kafka cluster) to use when resolving
+            table/view/udf names (optional)
+        endpoint: The base URL for Confluent Cloud API (optional). If not provided, the endpoint
+            will be constructed based on the cloud_provider and cloud_region parameters in the
+            format "https://flink.{cloud_region}.{cloud_provider}.confluent.cloud". A trailing
+            slash is optional and will be stripped if provided (e.g., both
+            "https://custom.example.com" and "https://custom.example.com/" are accepted).
+        dbname: Deprecated alias for database parameter (optional)
         result_page_fetch_pause_millis: Maximum milliseconds to wait between fetching pages of
             statement results (per statement). Defaults to 100ms. Prevents tight loops of requests
             to the statement results API when consuming results for a statement, especially when
@@ -88,15 +96,33 @@ def connect(  # noqa: PLR0913
     if not organization_id:
         raise InterfaceError("Organization ID is required")
 
-    if not cloud_provider:
-        raise InterfaceError("Cloud provider is required")
+    if endpoint:
+        if cloud_provider or cloud_region:
+            raise InterfaceError(
+                "cloud_provider and cloud_region should not be provided when endpoint is specified"
+            )
+    else:
+        if not cloud_provider:
+            raise InterfaceError("Cloud provider is required when endpoint is not provided")
 
-    if not cloud_region:
-        raise InterfaceError("Cloud region is required")
+        if not cloud_region:
+            raise InterfaceError("Cloud region is required when endpoint is not provided")
 
     if not flink_api_key or not flink_api_secret:
         raise InterfaceError("Flink API key and secret are required")
 
+    if dbname is not None:
+        warnings.warn(
+            "The 'dbname' parameter is deprecated and will be removed in a future release. "
+            "Please use the 'database' parameter instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if database is not None:
+            raise InterfaceError(
+                "Cannot specify both 'database' and deprecated 'dbname' parameters"
+            )
+
     return Connection(
         flink_api_key,
         flink_api_secret,
@@ -105,9 +131,8 @@ def connect(  # noqa: PLR0913
         organization_id,
         cloud_provider,
         cloud_region,
-        api_key=api_key,
-        api_secret=api_secret,
-        dbname=dbname,
+        endpoint,
+        database=database or dbname,  # dbname is deprecated.
         statement_results_page_fetch_pause_millis=result_page_fetch_pause_millis,
         http_user_agent=http_user_agent,
     )
@@ -128,9 +153,6 @@ class Connection:
     environment: str
     organization_id: str
     compute_pool_id: str
-    api_key: str | None
-    api_secret: str | None
-    host: str | None
     statement_results_page_fetch_pause_secs: float
     """Maximum seconds to wait between fetching pages of statement
         results (per statement). Prevents tight loops of requests to the
@@ -147,7 +169,7 @@ class Connection:
     """
 
     _closed: bool
-    _dbname: str | None
+    _database: str | None
     _client: httpx.Client
     _http_user_agent: str
 
@@ -165,12 +187,10 @@ class Connection:
         environment: str,
         compute_pool_id: str,
         organization_id: str,
-        cloud_provider: str,
-        cloud_region: str,
-        api_key: str | None = None,
-        api_secret: str | None = None,
-        host: str | None = None,
-        dbname: str | None = None,
+        cloud_provider: str | None,
+        cloud_region: str | None,
+        endpoint: str | None,
+        database: str | None = None,
         statement_results_page_fetch_pause_millis: int = 100,
         http_user_agent: str | None = None,
     ):
@@ -183,16 +203,18 @@ class Connection:
             environment: Environment ID
             compute_pool_id: Compute pool ID for SQL execution
             organization_id: Organization ID
-            cloud_provider: Cloud provider
-            cloud_region: Cloud region (e.g., "us-east-2", "us-west-2")
+            cloud_provider: Cloud provider (required if endpoint is not provided)
+            cloud_region: Cloud region (e.g., "us-east-2", "us-west-2"). Required if endpoint is
+                not provided.
+            endpoint: The base URL for Confluent Cloud API (optional). If not provided, the
+                endpoint will be constructed based on the cloud_provider and cloud_region
+                parameters in the format "https://flink.{cloud_region}.{cloud_provider}.confluent.cloud".
+                A trailing slash is optional and will be stripped if provided.
+            database: The name of the database to use (optional)
             result_page_fetch_pause_millis: Milliseconds to possibly wait between fetching pages of
                 statement results. Defaults to 100ms. If most recent fetch of results for a
                 statement was more than this long ago, then no delay will happen when fetching
                 the next page of results for the statement.
-            api_key: Confluent Cloud API key for general Confluent Cloud resources (optional)
-            api_secret: Confluent Cloud API secret for general Confluent Cloud resources (optional)
-            host: The base URL for Confluent Cloud API (optional)
-            dbname: The name of the database to use (optional)
             http_user_agent: User-Agent header for HTTP requests. String, 1-100 chars.
                            Defaults to the value of DEFAULT_USER_AGENT, which includes the
                            driver name/version, documentation URL, and support email.
@@ -200,9 +222,6 @@ class Connection:
         self.environment = environment
         self.compute_pool_id = compute_pool_id
         self.organization_id = organization_id
-        self.api_key = api_key
-        self.api_secret = api_secret
-        self.host = host
 
         if statement_results_page_fetch_pause_millis < 0:
             raise InterfaceError("result_page_fetch_pause_millis must be non-negative")
@@ -215,17 +234,27 @@ class Connection:
 
         # Internal state
         self._closed = False
-        self._dbname = dbname
+        self._database = database
 
         # Set user agent (validation happens in setter, default if None)
         self.http_user_agent = (
             http_user_agent if http_user_agent is not None else self.DEFAULT_USER_AGENT
         )
 
+        if not endpoint and not (cloud_provider and cloud_region):
+            raise InterfaceError(
+                "cloud_provider and cloud_region are required when endpoint is not provided"
+            )
+
         # Create httpx client for making API calls
-        if self.host is None:
-            self.host = f"https://flink.{cloud_region}.{cloud_provider}.confluent.cloud"
-        base_url = f"{self.host}/sql/v1/organizations/{organization_id}/environments/{environment}"
+        if not endpoint:
+            # Construct the endpoint URL based on cloud provider and region.
+            endpoint = f"https://flink.{cloud_region}.{cloud_provider}.confluent.cloud"
+        else:
+            # Strip trailing slash if user provided one, to ensure clean URL construction
+            endpoint = endpoint.rstrip("/")
+
+        base_url = f"{endpoint}/sql/v1/organizations/{organization_id}/environments/{environment}"
 
         # Create httpx client for making API calls
         basic_auth = httpx.BasicAuth(username=flink_api_key, password=flink_api_secret)
@@ -477,6 +506,7 @@ class Connection:
         timeout: int = 3000,
         statement_name: str | None = None,
         statement_label: str | None = None,
+        properties: PropertiesDict | None = None,
     ) -> Statement:
         """Execute bounded DDL that completes after consuming snapshot data.
 
@@ -499,6 +529,8 @@ class Connection:
                             group and manage related statements. The label will be
                             prefixed with "user.confluent.io/" when stored but you only
                             need to provide the label value itself (e.g., "my-ddl-batch")
+            properties: Optional dictionary of statement properties to set for this execution.
+                       Keys must be strings, values must be str, int, or bool.
 
         Returns:
             Statement for managing the statement lifecycle
@@ -514,6 +546,7 @@ class Connection:
                 timeout=timeout,
                 statement_name=statement_name,
                 statement_label=statement_label,
+                properties=properties,
             )
 
         # Return the last version of the statement
@@ -526,6 +559,7 @@ class Connection:
         timeout: int = 3000,
         statement_name: str | None = None,
         statement_label: str | None = None,
+        properties: PropertiesDict | None = None,
     ) -> Statement:
         """Execute unbounded DDL that starts a streaming job.
 
@@ -544,6 +578,8 @@ class Connection:
                             group and manage related statements. The label will be
                             prefixed with "user.confluent.io/" when stored but you only
                             need to provide the label value itself (e.g., "streaming-jobs")
+            properties: Optional dictionary of statement properties to set for this execution.
+                       Keys must be strings, values must be str, int, or bool.
         Returns:
             Statement for any further management of the statement lifecycle
         """
@@ -555,6 +591,7 @@ class Connection:
                 timeout=timeout,
                 statement_name=statement_name,
                 statement_label=statement_label,
+                properties=properties,
             )
 
         return cur.statement
@@ -739,12 +776,79 @@ class Connection:
 
         self._row_type_registry.register_row_type(class_for_flink_row)
 
+    _NEVER_USER_PROVIDED_PROPERTIES = {
+        "sql.current-catalog",
+        "sql.current-database",
+        "sql.snapshot.mode",
+    }
+
+    def _resolve_properties(
+        self, properties: PropertiesDict | None, execution_mode: ExecutionMode
+    ) -> PropertiesDict:
+        """
+        Validate and merge user properties with system properties.
+
+        Validates the properties parameter and merges it with system-level properties
+        (catalog, database, snapshot mode). System properties always have precedence
+        and cannot be overridden by user input.
+
+        Args:
+            properties: Optional dictionary of user-provided statement properties.
+                       Keys must be strings, values must be str, int, or bool.
+            execution_mode: The execution mode (determines if snapshot.mode is set).
+
+        Returns:
+            Merged properties dictionary with system properties overlaid.
+
+        Raises:
+            InterfaceError: If properties parameter is invalid (not a dict, invalid keys/values).
+        """
+        # Validate properties parameter if provided
+        if properties is not None:
+            if not isinstance(properties, dict):
+                raise InterfaceError(f"properties must be a dict, got {type(properties).__name__}")
+
+            for key, value in properties.items():
+                if not isinstance(key, str):
+                    raise InterfaceError(
+                        f"properties keys must be strings, got {type(key).__name__} for key {key!r}"
+                    )
+                if not isinstance(value, (str, int, bool)):
+                    raise InterfaceError(
+                        f"properties values must be str, int, or bool, "
+                        f"got {type(value).__name__} for key {key!r}"
+                    )
+                if key in self._NEVER_USER_PROVIDED_PROPERTIES:
+                    raise InterfaceError(f"'{key}' is a reserved system property.")
+
+        # Start with user properties (if provided), then overlay system properties
+        # This ensures system properties always win and cannot be overridden
+        merged_properties: PropertiesDict = {}
+
+        if properties is not None:
+            # User properties applied first
+            merged_properties.update(properties)
+
+        # Connection-level properties overlay (always set, cannot be overridden by user)
+        merged_properties["sql.current-catalog"] = self.environment
+
+        if self._database is not None:
+            merged_properties["sql.current-database"] = self._database
+
+        # Cursor-level execution mode properties overlay (always set when applicable)
+        if execution_mode.is_snapshot:
+            # Ask for snapshot mode behavior -- point-in-time results.
+            merged_properties["sql.snapshot.mode"] = "now"
+
+        return merged_properties
+
     def _execute_statement(
         self,
         statement: str,
         execution_mode: ExecutionMode,
         statement_name: str | None = None,
         statement_label: str | None = None,
+        properties: PropertiesDict | None = None,
     ) -> dict[str, Any]:
         """
         Execute a SQL statement and return the response.
@@ -755,28 +859,25 @@ class Connection:
             statement_name: Optional name for the statement (defaults to 'dbapi-{uuid}')
             statement_label: Optional label for the statement for easier identification in
                             server logs and UIs (defaults to None).
+            properties: Optional dictionary of statement properties to set for this execution.
+                       Keys must be strings, values must be str, int, or bool. System
+                       properties (sql.current-catalog, sql.current-database, sql.snapshot.mode)
+                       are always set by the driver and cannot be overridden.
 
         Returns:
             Dictionary containing the API response
 
         Raises:
             OperationalError: If statement execution fails
+            InterfaceError: If properties parameter is invalid
         """
 
         # Create the statement payload as per Flink SQL API documentation
         if statement_name is None:
             statement_name = f"dbapi-{str(uuid.uuid4())}"
 
-        # Each connection uses a single environment, also
-        # called catalog, so we set the property here
-        properties = {"sql.current-catalog": self.environment}
-
-        if self._dbname is not None:
-            properties["sql.current-database"] = self._dbname
-
-        if execution_mode.is_snapshot:
-            # Ask for snapshot mode behavior -- point-in-time results.
-            properties["sql.snapshot.mode"] = "now"
+        # Resolve and merge user properties with system properties
+        merged_properties = self._resolve_properties(properties, execution_mode)
 
         payload = {
             "name": statement_name,
@@ -784,7 +885,7 @@ class Connection:
             "environment_id": self.environment,
             "spec": {
                 "statement": statement,
-                "properties": properties,
+                "properties": merged_properties,
                 "compute_pool_id": self.compute_pool_id,
                 "stopped": False,
             },

{confluent_sql-0.1.3 → confluent_sql-0.2.0}/src/confluent_sql/cursor.py

@@ -31,7 +31,7 @@ from .result_readers import (
     ResultTupleOrDict,
 )
 from .statement import Statement
-from .types import convert_statement_parameters
+from .types import PropertiesDict, convert_statement_parameters
 
 if TYPE_CHECKING:
     from .connection import Connection
@@ -118,9 +118,7 @@ class Cursor:
 
         # Statement execution state
         self._statement: Statement | None = None
-        self._result_reader: AppendOnlyResultReader | ChangelogEventReader | None = (
-            None
-        )
+        self._result_reader: AppendOnlyResultReader | ChangelogEventReader | None = None
 
     @property
     def description(self) -> list[tuple] | None:
@@ -158,9 +156,7 @@ class Cursor:
                 f"arraysize must be a positive integer, got {type(value).__name__}"
             )
         if value <= 0:
-            raise InterfaceError(
-                f"arraysize must be a positive integer, got {value}"
-            )
+            raise InterfaceError(f"arraysize must be a positive integer, got {value}")
         self._arraysize = value
 
     @property
@@ -186,6 +182,7 @@ class Cursor:
         timeout: int = 3000,
         statement_name: str | None = None,
         statement_label: str | None = None,
+        properties: PropertiesDict | None = None,
     ) -> None:
         """
         Execute a SQL statement.
@@ -203,9 +200,13 @@ class Cursor:
                             need to provide the label value itself (e.g., "my-batch-job").
                             Use Connection.list_statements(label=...) to retrieve statements
                             by label.
+            properties: Optional dictionary of statement properties to set for this execution.
+                       Keys must be strings, values must be str, int, or bool. System
+                       properties (sql.current-catalog, sql.current-database, sql.snapshot.mode)
+                       are always set by the driver and cannot be overridden.
 
         Raises:
-            InterfaceError: If the cursor is closed
+            InterfaceError: If the cursor is closed, or if invalid properties are provided.
             ProgrammingError: If the SQL statement is invalid
             OperationalError: If the statement cannot be executed
         """
@@ -235,7 +236,7 @@ class Cursor:
 
         # Now submit the statement ...
         self._statement = self._submit_statement(
-            statement_text, parameters, statement_name, statement_label
+            statement_text, parameters, statement_name, statement_label, properties
         )
 
         if self._statement.is_failed:
@@ -354,9 +355,7 @@ class Cursor:
         self._raise_if_closed()
         self._raise_if_ddl_mode()
 
-        return self._get_result_reader().fetchmany(
-            size if size is not None else self.arraysize
-        )
+        return self._get_result_reader().fetchmany(size if size is not None else self.arraysize)
 
     def fetchall(self) -> list[ResultRow]:
         """
@@ -743,6 +742,7 @@ class Cursor:
         parameters: tuple | list | None = None,
         statement_name: str | None = None,
         statement_label: str | None = None,
+        properties: PropertiesDict | None = None,
     ) -> Statement:
         """
         Submit a SQL statement for execution.
@@ -754,6 +754,7 @@ class Cursor:
                             not provided)
             statement_label: Optional label for the statement for easier identification in
                             server logs and UIs (defaults to None)
+            properties: Optional dictionary of statement properties (optional)
 
         Returns:
             The submitted Statement object
@@ -761,6 +762,7 @@ class Cursor:
         Raises:
             OperationalError: If statement submission fails
             ProgrammingError: If template parameter interpolation fails
+            InterfaceError: If the provided properties are invalid
         """
         logger.info(f"Submitting statement {statement_text}")
 
@@ -773,6 +775,7 @@ class Cursor:
             self._execution_mode,
             statement_name,
             statement_label,
+            properties,
         )
         return Statement.from_response(self._connection, response)