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

{confluent_sql-0.4.2 → confluent_sql-0.5.1}/.semaphore/semaphore.yml

@@ -31,7 +31,7 @@ blocks:
       jobs:
         - name: "Lint, Type Check, and Test"
           commands:
-            - uv run --frozen ruff check && uv run --frozen pyright && uv run --frozen pytest -m unit --junitxml=test-results.xml
+            - uv run --frozen ruff format --check && uv run --frozen ruff check && uv run --frozen pyright && uv run --frozen pytest -m unit --junitxml=test-results.xml
       epilogue:
         always:
           commands:

confluent_sql-0.5.1/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Change Log
+
+All notable changes to this dbapi driver will be documented in this file.
+
+## Unreleased
+
+## 0.5.1, 2026-08-25
+
+### Fixed
+
+- Streaming changelog compressor fixes for nontrivial changelog streams written to Kafka topics with multiple partitions:
+  - The changelog compressor for streaming non-append-only queries **without** upsert columns (`cursor.changelog_compressor()` on a keyless result, e.g. a global aggregation) no longer raises `InterfaceError` on legitimately out-of-order changelog events. When such a changelog is sinked to a multi-partition keyless topic, partitions are assigned by whole-row hash, so an updated row's `+U`/`-D` spelling can land on a different partition than its original `+I`/`-U` spelling; since Kafka only guarantees ordering within a partition, the events can be observed in a surprising order across spellings (a `+U` before its logical `-U`, or a `-D` before a later `+I`). The compressor previously assumed each `UPDATE_BEFORE` was immediately followed by its `UPDATE_AFTER` and failed on those sequences. It now treats the two additive ops (`+I`, `+U`) as inserts and the two retracting ops (`-U`, `-D`) as deletions, makes no ordering assumptions across different rows' spellings, and converges to the correct result set (intermediate snapshots may transiently show an extra row). Adds `Op.treat_as_insert` / `Op.treat_as_delete` helper properties. (#184)
+  - The changelog compressor for streaming non-append-only queries **with** upsert columns (`cursor.changelog_compressor()` on a keyed result, e.g. a `GROUP BY`) no longer raises `InterfaceError` when an unrelated key's changelog event arrives between one key's `UPDATE_BEFORE` and its own `UPDATE_AFTER`. A consumer reading a keyed upsert topic drains multiple partitions per poll; same-key events stay ordered (a key always hashes to the same partition), but a single fetch batch can still interleave *different* keys' events. The compressor previously modeled `UPDATE_BEFORE`/`UPDATE_AFTER` as a single-slot pending pair that had to be adjacent, and failed on that interleaving even though nothing was actually wrong. `UPDATE_BEFORE` is now treated as an unconditional no-op (it carries no information the matching insert/update doesn't already supply under key-based upsert semantics), and `UPDATE_AFTER` is handled exactly like `INSERT` (last write for the key wins); `DELETE` is unaffected and still validates that the key exists. As part of the same cleanup, the now-unused pending-update tracking hooks are removed from the shared compressor base class. (#185)
+
+## 0.5.0, 2026-08-07
+
+### Added
+
+- `connect()`/`Connection()` accept a `local_time_zone` keyword argument that seeds a read/write `Connection.local_time_zone` property: a connection-level default for the `sql.local-time-zone` statement property, applied to every statement created by the connection unless that statement's own `properties=`/`StatementProperties` sets `local_time_zone`, which takes precedence.
+- `StatementProperties` -- a frozen, keyword-only dataclass giving a typed, autocomplete-friendly way to set the curated statement options instead of hand-building a `sql.*` dict. Fields (all optional): `snapshot_write_mode`, `state_ttl` (a `timedelta`, rendered to a Flink duration such as `"3600 s"`), `scan_startup_mode`, `local_time_zone`, plus an `extra` dict escape hatch for options not yet modeled. Only set fields are emitted, so an instance never pins a default nor collides with the driver-owned overlay. The enum-typed fields also accept a bare `str` so a Flink value newer than this driver can still be passed; a wrong-property enum value, a field of the wrong Python type, or an `extra` key that duplicates a modeled field, raises at construction. `extra` is copied into a read-only mapping, so the frozen guarantee holds after construction too. Pass one anywhere a `properties=` dict is accepted (`Cursor.execute`, `execute_snapshot_ddl`, `execute_streaming_ddl`, ...); it is downgraded to a dict and validated identically. Adds the `ScanStartupMode` value enum (`earliest-offset`/`latest-offset`/`timestamp`/`specific-offsets`). (#163)
+- New module `confluent_sql.statement_properties` gives statement `SET` options a discoverable, type-checkable face alongside the existing open-ended `PropertiesDict`. `Property` is a `str` enum of the `sql.*` option keys from the [SET-options reference](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html) (e.g. `Property.SNAPSHOT_WRITE_MODE`); `SnapshotWriteMode` (`default`/`fast-write`) and `SnapshotMode` (`now`/`off`) enumerate the fixed value sets, sharing the `PropertyValue` base. Members are `str` instances that compare, hash, JSON-serialize, and stringify as their wire string, so they drop straight into a `properties=` dict with no `.value` unwrapping. `PropertiesDict` now advertises `Property` keys and `PropertyValue` values. (#162)
+- class `Connection` now has methods to enable / inspect / disable [Tableflow](https://www.confluent.io/product/tableflow/) materialization of the Kafka topic backing a Flink table (#117). Tableflow-enabled topics/tables can be snapshot queried in an optimized fashion.
+  - `Connection.enable_tableflow(table_name, *, tableflow_formats, storage, config=None, wait_for_running=True, timeout=300)` adds an Iceberg/Delta sink. `tableflow_formats` takes a single `TableFormat` (e.g. `TableFormat.ICEBERG`) or a collection for several; `storage` is one of `ManagedStorage()` (zero-config), `ByobAwsStorage`, or `AzureAdlsStorage`; `config` is an optional `TableflowTopicConfig`. By default it blocks until the topic reaches `RUNNING`; pass `wait_for_running=False` to return as soon as the create is accepted (topic in `PENDING`). Raises `TableflowTopicAlreadyExistsError` if Tableflow is already enabled.
+  - `Connection.get_tableflow(table_name)` returns the current `TableflowTopic` (phase, spec, status), raising `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic.
+  - `Connection.disable_tableflow(table_name, *, wait_for_removal=True, timeout=300)` tears the sink down (all-or-nothing in v1, no per-format disable). By default it blocks until the topic is confirmed gone; pass `wait_for_removal=False` to return as soon as the delete is accepted.
+- `organization_id` is now optional in `connect()`/`Connection()` when a global API key is supplied: if omitted, it's inferred via `GET /org/v2/organizations` -- lazily, on first use of the connection (not at `connect()` time) -- and used when exactly one organization is visible to the key. Raises `OperationalError` on first use if zero or multiple organizations are visible. Unchanged (still required, validated eagerly by `connect()`) for a Flink-region-only key or a dedicated Tableflow/Connect key, neither of which has `/org/v2` reach. (#132)
+- BYOIDC bearer-token authentication for the Flink data plane: `connect()`/`Connection()` now accept an `external_access_token` / `identity_pool_id` pair, letting you authenticate with a bearer token minted by your own OAuth/OIDC identity provider (an "external" token) instead of a Confluent API key + secret. The `external_access_token` name mirrors the Confluent Flink Table API plugin's `client.oauth.external-access-token` option. When supplied, every Flink request carries `Authorization: Bearer <external_access_token>` and `Confluent-Identity-Pool-Id: <identity_pool_id>`. The two are mutually exclusive with every API-key parameter and must be provided together. Scope is the Flink data plane only -- Confluent's authorization model accepts no external token on the control-plane routes this driver calls, so Tableflow, Connectors, and the CMK cluster-id lookup fail closed under BYOIDC (they require an API-key connection), and `organization_id` stays mandatory (there is no control-plane reach to infer it). The token is used verbatim with no refresh; an expired token starts failing requests (surfaced as `OperationalError`) and the connection must be re-opened with a fresh token. (#100)
+
+### Fixed
+
+- Every network-level transport failure from the Flink gateway (`httpx.ConnectError`, `httpx.ReadError`, `httpx.RemoteProtocolError`, timeouts, etc.) is now translated to `OperationalError` instead of leaking the raw `httpx` exception -- this applies uniformly to idempotent GETs (once #137's retry budget is exhausted) and to non-idempotent POST/PATCH/DELETE calls (statement submission, `stop_statement()`, `delete_statement()`), matching the DB-API v2 contract that every exception the driver raises is one of `confluent_sql`'s own `Error` subclasses. The original exception remains available via `__cause__`. (#138)
+
+## 0.4.2, 2026-07-17
+
+### Changed
+
+- Snapshot queries on Confluent Cloud Flink SQL are now Generally Available. Removed the Early Access warning previously emitted on first creation of a snapshot-mode cursor, along with the Early Access advisories throughout the documentation (`README.md`, `ARCHITECTURE.md`, `DBAPI_EXTENSIONS.md`, `STREAMING.md`). (#119, #160)
+
+## 0.4.1, 2026-07-07
+
+### Fixed
+
+- Idempotent GET requests (`list_statements()`'s page-fetch loop, `get_statement()`, and result-page fetching) now retry transient transport errors -- connection resets (`httpx.NetworkError`) and servers that close pooled connections without responding (`httpx.RemoteProtocolError`) -- up to 3 times with a short exponential backoff, instead of failing on the first blip. POST/PATCH/DELETE requests (statement submission, `stop_statement()`, `delete_statement()`) are deliberately left unretried, since re-issuing them after a connection reset could double-submit or double-mutate state. (#137)
+- The same idempotent GET requests now also retry transient HTTP response statuses (429, 500, 502, 503, 504), not just transport-level exceptions -- a request that reaches Confluent Cloud but gets a momentarily-overloaded gateway response was previously failing on the first such response instead of being retried like a dropped connection. (#140)
+- Increased the default HTTP timeout from 5 to 10s for safety. `connect()` and `Connection.__init__()` no longer accept explicit `None` for `http_timeout_secs`.
+
+## 0.4.0, 2026-06-15
+
+### Added
+
+- Support for "Global" Confluent Cloud API keys: `confluent_sql.connect()` (and `Connection`) now accept `global_api_key` / `global_api_secret`. A Global key works against every route this driver touches, so it is preferred over a Flink Region key when both are supplied. `flink_api_key` / `flink_api_secret` remain supported and are now optional; at least one fully-specified pair must be provided. If both pairs are supplied, the Global pair is used (and the Flink pair ignored, with a warning); a half-specified pair (key without secret, or vice versa) is rejected. (#112)
+- Support for "poolless Flink": `confluent_sql.connect()` now treats `compute_pool_id` as optional. Statements submitted w/o their own overriding `compute_pool_id` via a connection w/o a default compute pool id will make use of the default compute pool in the environment+cloud region (provisioning one if necessary). See [the Confluent documentation](https://docs.confluent.io/cloud/current/flink/concepts/compute-pools.html#default-compute-pools) for more details.
+- New `Connection.stop_statement(statement, *, wait_for_stopped=True, timeout=300)` method to stop a running statement without deleting it, leaving the statement resource around for inspection (unlike `delete_statement()`, which also destroys it). Accepts a statement name or a `Statement` object. By default it blocks until the statement reaches `STOPPED`; pass `wait_for_stopped=False` to return as soon as the stop is accepted. A matching `Cursor.stop_statement()` stops the cursor's current statement. New `Statement.is_stopped`, `Statement.is_stopping`, and `Statement.stop_requested` properties expose the relevant state. (#61)
+
+### Changed
+
+- `Connection.list_statements()`:
+  - New optional parameter `compute_pool_id` to list statements only in a single compute pool (otherwise environment-wide).
+  - New optional parameter `name_contains: str` to filter statements server-side to those whose name contains the given substring (case-sensitive).
+  - Existing parameter `label` is now optional.
+  - The end result is that callers can now provide between zero and all of the possible kwargs to vary between 'no filtering at all, return all current statements in the environment' and 'apply all the possible filters as if ANDed together.'
+
+## 0.3.1, 2026-05-21
+
+### Added
+
+- New `http_timeout_secs` parameter for `connect()` to let the caller control how long to wait in HTTP requests.
+
+## 0.3.0, 2026-04-09
+
+### Changed - Breaking
+
+- `connect()` / `Connection.__init__()`: Renamed `environment` parameter to `environment_id` to clarify that an environment ID (_not_ name) is expected. The internal attribute `Connection.environment` has also been renamed to `Connection.environment_id`. Update all calls from `connect(environment="env-123")` to `connect(environment_id="env-123")`. (#92)
+- `Cursor.execute()` and peers: Respelled and re-typed the `statement_label: str | None` parameter to be `statement_labels: list[str] | None` to allow multiple labels to be applied to a statement, including `HIDDEN_LABEL`.
+
+### Added
+
+- New `Connection.get_statement(statement)` method to retrieve statement metadata by name or refresh a Statement object with the latest server state. Accepts either a statement name (string) or a Statement object. Returns a Statement object with current phase, schema, and execution traits. (#86)
+- New `StatementNotFoundError` exception, a subclass of `OperationalError`, raised by `Connection.get_statement(statement)` when attempting to retrieve a statement that does not exist. Provides programmatic access to the statement name via the `statement_name` attribute.
+- New constant `confluent_sql.HIDDEN_LABEL` used for driving `Cursor.execute()` to indicate that the statement should be hidden in default listings in Confluent Cloud UIs. This feature is intended to be used for minor queries, such as when investigating `INFORMATION_SCHEMA`.
+- Added documentation regarding use of `connect(endpoint=)` parameter to make use of private networking endpoints (README.md, docstrings).
+
+## 0.2.0, 2026-03-26
+
+### 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`.
+- Clarified and improved documentation around Flink region API key use.
+
+### 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 Region API key params `flink_api_key` and `flink_api_secret` remain.
+
+## 0.1.x
+
+Early access release of the driver.

{confluent_sql-0.4.2 → confluent_sql-0.5.1}/CLAUDE.md

@@ -1,4 +1,7 @@
-# Project-specific instructions for confluent-sql
+# Repository conventions for Claude
+
+Guidance for any Claude working in this repository. Keep it short and concrete; add a convention
+here only once the codebase actually follows it in more than one place.
 
 ## HTTP request routing: idempotent GETs vs mutating requests
 
@@ -27,3 +30,31 @@ those are equally idempotent GETs even though they weren't the reported failure.
 the same call sites to also retry on retryable HTTP status codes, not just transport exceptions.
 The reasoning, and the case for a plain function over a decorator, is captured in `retry.py`'s
 module docstring and `_request_get`'s docstring.
+
+## Blocking vs. non-blocking lifecycle methods
+
+Methods that drive a server-side resource toward a steady state (start a statement, stop it,
+enable/disable a Tableflow sink, etc.) follow a uniform shape:
+
+- **Block by default; return the settled state.** The common call should leave the resource in its
+  intended terminal/ready state, not hand back a transient one the caller must then poll itself.
+- **Expose a `wait_for_<settled-state>: bool = True` keyword-only argument.** The suffix names the
+  exact condition awaited — *not* a generic `wait`/`block`. Existing names: `wait_for_stopped`
+  (statement reaches STOPPED), `wait_for_running` (Tableflow topic reaches RUNNING),
+  `wait_for_removal` (Tableflow topic is gone). A new method picks the suffix that is literally
+  true of what it waits for.
+- **Pair it with a uniform `timeout` keyword arg** (seconds; the standardized knob across all such
+  methods).
+- **`=False` is the opt-out**: return as soon as the request is accepted (resource typically in a
+  PENDING/just-requested state).
+- **While waiting, raise on terminal failure and on timeout** — surface the failure detail
+  (`OperationalError`, e.g. a statement/topic that went FAILED), don't silently return a broken
+  resource.
+- **Implement the wait by polling with `sleep_with_backoff`** from `polling.py`; don't hand-roll a
+  sleep loop.
+
+Exemplars: `Connection.stop_statement` / `Cursor.stop_statement` (`wait_for_stopped=True`),
+`Connection.enable_tableflow` (`wait_for_running=True`), `Connection.disable_tableflow`
+(`wait_for_removal=True`). The DDL convenience methods (`execute_snapshot_ddl`,
+`execute_streaming_ddl`) block unconditionally and offer no opt-out — that's also acceptable when a
+non-blocking variant would be meaningless.

{confluent_sql-0.4.2 → confluent_sql-0.5.1}/DBAPI_EXTENSIONS.md

@@ -34,6 +34,7 @@ For comprehensive details on streaming queries, polling patterns, and changelog
 - [Result Format Extensions](#result-format-extensions) - Dictionary rows, custom types
 - [Streaming Query Support](#streaming-query-support) - Comprehensive streaming guide
 - [Statement Lifecycle Management](#statement-lifecycle-management) - DDL, naming, stopping, deletion
+- [Tableflow Lifecycle](#tableflow-lifecycle) - Enable, read, and disable Iceberg/Delta sinks
 - [Introspection and Metadata](#introspection-and-metadata) - Properties for query state
 - [Performance Monitoring](#performance-monitoring) - Fetch metrics
 - [Type System Extensions](#type-system-extensions) - Flink type support
@@ -565,6 +566,147 @@ cursor.delete_statement()
 
 ---
 
+## Tableflow Lifecycle
+
+[Tableflow](https://www.confluent.io/product/tableflow/) materializes the Kafka topic backing a
+Flink table into an Iceberg or Delta table. Three `Connection` methods manage that sink. Enabling
+it also unlocks
+[efficiency gains for snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html#snapshot-queries-and-tableflow)
+against the table.
+
+In Confluent Flink a table is backed by a like-named Kafka topic, so the `table_name` you pass is
+both the Flink table and the topic — no escaping or casing translation.
+
+A runnable example covering the full enable/get/disable lifecycle is in
+[examples/tableflow_lifecycle_example.py](examples/tableflow_lifecycle_example.py).
+
+> **Not available under BYOIDC.** Tableflow is a control-plane surface, and Confluent's
+> authorization model accepts no BYOIDC bearer token there. A connection authenticated with
+> `external_access_token` / `identity_pool_id` (see the README's [BYOIDC bearer-token
+> authentication](README.md#byoidc-bearer-token-authentication)) fails closed on these methods —
+> use an API-key connection for Tableflow.
+
+### Selecting formats: `TableFormat`
+
+There is a single format vocabulary, `TableFormat` (`ICEBERG` / `DELTA`), on both the request and
+response sides. A topic can carry **both** formats at once (there is no per-format config), so
+`enable_tableflow`'s `tableflow_formats` argument accepts either a single `TableFormat` for the
+common case or a collection for both:
+
+```python
+connection.enable_tableflow("orders", tableflow_formats=TableFormat.ICEBERG, storage=...)
+connection.enable_tableflow(
+    "orders", tableflow_formats={TableFormat.ICEBERG, TableFormat.DELTA}, storage=...
+)
+```
+
+Responses name the same `TableFormat`s (`topic.spec.table_formats`,
+`topic.status.failing_table_formats`), so checking what you got against what you asked for is a
+plain set comparison:
+
+```python
+topic = connection.enable_tableflow(
+    "orders", tableflow_formats={TableFormat.ICEBERG, TableFormat.DELTA},
+    storage=ManagedStorage(), wait_for_running=True,
+)
+assert set(topic.spec.table_formats) == {TableFormat.ICEBERG, TableFormat.DELTA}
+```
+
+### Storage variants
+
+`enable_tableflow` requires an explicit, frozen storage spec — no silent default:
+
+- `ManagedStorage()` — Confluent-managed bucket, zero config.
+- `ByobAwsStorage(bucket_name=..., provider_integration_id=...)` — bring-your-own AWS S3 bucket.
+- `AzureAdlsStorage(storage_account_name=..., container_name=..., provider_integration_id=...)` —
+  customer-owned Azure Data Lake Storage Gen2.
+
+### Cluster-id resolution
+
+The Tableflow API addresses the cluster by its `lkc-…` id, which the connection must know. Either:
+
+- Pass `database_kafka_cluster_id` to `connect()` (works with only a `tableflow_api_key` pair), or
+- Let it resolve lazily from `database` (the cluster name) via CMK on first use — this path
+  requires a **global** API key, and the resolved id is cached for the connection's life. A name
+  that matches more than one cluster raises, listing the candidate ids so you can disambiguate with
+  `database_kafka_cluster_id`.
+
+### `enable_tableflow()` — add an Iceberg/Delta sink
+
+```python
+from confluent_sql import ManagedStorage, TableFormat, TableflowPhase
+
+topic = connection.enable_tableflow(
+    "orders",
+    tableflow_formats=TableFormat.ICEBERG,
+    storage=ManagedStorage(),
+)
+assert topic.phase is TableflowPhase.RUNNING   # blocked to RUNNING by default
+```
+
+**Behavior notes:**
+
+- `tableflow_formats` and `storage` are required (no defaults); `tableflow_formats` must name at
+  least one format. `config` is an optional `TableflowTopicConfig` (retention, error-handling)
+  shared across all enabled formats.
+- Blocks until `RUNNING` by default (`wait_for_running=True`), raising `OperationalError` on
+  `FAILED` (surfacing `status.error_message` and `failing_table_formats`) — consistent with
+  `stop_statement`'s wait-by-default. Pass `wait_for_running=False` to return as soon as the create
+  is accepted (topic in `PENDING`).
+- Raises `TableflowTopicAlreadyExistsError` if Tableflow is already enabled (HTTP 409), or
+  `ProgrammingError` if no management credential is available or the cluster id can't be resolved.
+
+### `get_tableflow()` — read current state
+
+```python
+topic = connection.get_tableflow("orders")
+print(topic.phase)                       # TableflowPhase.PENDING / RUNNING / FAILED
+print(topic.spec.table_formats)          # [TableFormat.ICEBERG, ...]
+```
+
+Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404). There is
+no separate health check — health is read off `get_tableflow(...).phase`.
+
+### `disable_tableflow()` — tear down the sink
+
+```python
+connection.disable_tableflow("orders")   # blocks until confirmed gone by default
+```
+
+**Behavior notes:**
+
+- All-or-nothing in v1: removes the entire Tableflow topic. (Removing just one of two enabled
+  formats needs a future API and is not yet supported.)
+- Deletion is asynchronous. Blocks until removal is confirmed by default (`wait_for_removal=True`),
+  polling `get_tableflow` until it `404`s. This is why a following `DROP TABLE` is safe by default —
+  dropping the Flink table drops its backing topic, so Tableflow must be confirmed gone first to
+  avoid racing an active materialization. Pass `wait_for_removal=False` to return as soon as the
+  `DELETE` is accepted.
+- Raises `TableflowTopicNotFoundError` if Tableflow was not enabled (HTTP 404).
+
+### Reusing format and config across many tables
+
+Every input is a reusable value — the selection is an enum member, and `storage`/`config` are
+frozen — so hoist them out of the loop. The cluster-id lookup resolves once and is cached, so the
+loop hits CMK at most once:
+
+```python
+from confluent_sql import ManagedStorage, TableFormat, TableflowTopicConfig
+
+storage = ManagedStorage()
+config = TableflowTopicConfig(retention_ms="604800000")
+
+for table in ("orders", "shipments", "returns"):
+    connection.enable_tableflow(
+        table,
+        tableflow_formats=TableFormat.ICEBERG,
+        storage=storage,
+        config=config,
+    )
+```
+
+---
+
 ## Introspection and Metadata
 
 ### Connection Properties
@@ -894,7 +1036,8 @@ cursor.execute(
     timeout: int = 3000,
     statement_name: str | None = None,
     statement_labels: list[str] | None = None,
-    properties: dict[str, str | int | bool] | None = None,
+    properties: dict[str, str | int | bool] | StatementProperties | None = None,
+    compute_pool_id: str | None = None,
 ) -> None
 ```
 
@@ -907,20 +1050,73 @@ cursor.execute(
 | `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_labels` | `list[str] \| None`               | None       | List of labels for grouping related statements                     |
-| `properties`       | `dict[str, str \| int \| bool] \| None` | None | [Statement properties](#statement-properties) to set for execution |
+| `properties`       | `dict[str, str \| int \| bool] \| StatementProperties \| None` | None | [Statement properties](#statement-properties) to set for execution |
+| `compute_pool_id`  | `str \| None`                     | None       | Compute pool to run this statement on, overriding the connection's default |
 
 ### 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.
+The `properties` parameter sets [Flink SQL statement properties](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html#table-options) at query execution time — the same properties Flink SQL `SET` statements control. There are two ways to provide them:
+
+- **`StatementProperties`** (recommended) — a frozen, keyword-only dataclass covering the curated
+  options below, discoverable via autocomplete and validated at construction time instead of at
+  the server. A wrong-property enum value (e.g. a `SnapshotMode` passed to `scan_startup_mode`), a
+  field of the wrong Python type, or an `extra` key that duplicates a modeled field all raise
+  immediately:
+
+  ```python
+  from confluent_sql import Property, ScanStartupMode, SnapshotWriteMode, StatementProperties
+  from datetime import timedelta
+
+  cursor.execute(
+      "SELECT * FROM orders WHERE status = %s",
+      ("pending",),
+      properties=StatementProperties(
+          state_ttl=timedelta(hours=1),                  # -> "3600 s"
+          snapshot_write_mode=SnapshotWriteMode.FAST_WRITE,
+          scan_startup_mode=ScanStartupMode.EARLIEST_OFFSET,
+          # `extra` escape hatch for a property not yet a typed field; Keys can
+          # either be Property enums or strings.
+          extra={Property.SCAN_IDLE_TIMEOUT: "30 s"},
+      ),
+  )
+  ```
+
+  The set of modeled fields grows over time -- see the `StatementProperties` docstring/source for
+  the current list -- but the shape is uniform: only fields you actually set are emitted, so an
+  unset field never pins a server default or collides with the driver's own overlay, and each
+  enum-typed field also accepts a bare `str`, so a Flink value newer than this driver's enum can
+  still be passed through without waiting for a driver release.
+
+- **A raw `dict[str, str | int | bool]`** — the original, open-ended form. Any `sql.*` key is
+  accepted, keyed by the string from the [SET-options
+  reference](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html), which is
+  useful for options `StatementProperties` doesn't model yet (equivalent to `extra` above, without
+  needing to go via the dataclass):
+
+  ```python
+  cursor.execute(query, properties={"sql.state-ttl": "3600 s"})
+  ```
+
+  `confluent_sql.Property` enumerates the known `sql.*` keys (e.g. `Property.STATE_TTL`) if you
+  want autocomplete on the keys without adopting the full dataclass; members are plain `str`
+  instances, so they drop straight into the dict with no `.value` unwrapping.
+
+Both forms are validated identically — a `StatementProperties` is downgraded to a dict internally
+before the same checks run, so a reserved key smuggled through `extra` is rejected the same way a
+raw dict would be.
 
 **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
-
+- System properties are always applied and cannot be overridden by the caller: the connection's
+  catalog/database and the cursor's execution mode (e.g. `sql.snapshot.mode` for snapshot queries).
+- The connection-level `local_time_zone` default (see [`Connection.local_time_zone`](#connection-level-local_time_zone-default) below) fills in `sql.local-time-zone` only when the
+  call's own `properties` didn't already set it.
+- User-provided properties in the `properties` parameter can set anything not covered by the two
+  rules above, but attempting to set a system property (e.g. `sql.current-catalog`) raises
+  `InterfaceError` rather than being silently overridden.
 
 **Accessing Properties After Execution:**
-The properties are stored in the Statement object and can be accessed via `statement.properties`:
+The properties are stored in the cursor-captured Statement object and can be accessed via
+`statement.properties`, a `dict[str, str | int | bool]`:
 
 ```python
 cursor.execute(query, properties={"sql.state-ttl": "100 ms"})
@@ -928,7 +1124,31 @@ props = cursor.statement.properties
 assert props["sql.state-ttl"] == "100 ms"
 ```
 
-**Examples:**
+### Connection-level `local_time_zone` default
+
+`Connection.local_time_zone` (also settable via `connect(local_time_zone=...)`) is a read/write
+property that seeds `sql.local-time-zone` for every statement the connection executes, so you don't
+have to repeat it on each `execute()` call:
+
+```python
+connection.local_time_zone = "America/Chicago"
+cursor.execute("SELECT CURRENT_TIMESTAMP")  # runs with sql.local-time-zone = America/Chicago
+
+# A statement can still override it for itself:
+cursor.execute(
+    "SELECT CURRENT_TIMESTAMP",
+    properties=StatementProperties(local_time_zone="America/Los_Angeles"),
+)
+```
+
+The connection-level value only fills in where a statement's own `properties`
+(dict or `StatementProperties`) didn't already set `sql.local-time-zone` — it never overrides an
+explicit per-call value. Set it to `None` to stop emitting a default.
+
+A runnable example covering both property forms and the connection-level default is in
+[examples/statement_properties_example.py](examples/statement_properties_example.py).
+
+**General Usage Examples:**
 
 ```python
 # Basic execution
@@ -940,7 +1160,7 @@ cursor.execute("SELECT * FROM users WHERE age > %s", (18,))
 # With custom timeout
 cursor.execute(
     "SELECT * FROM users",
-    timeout=5000  # Wait up to 5000 seconds
+    timeout=100  # Wait up to 100 seconds
 )
 
 # With statement naming
@@ -950,7 +1170,7 @@ cursor.execute(
     statement_name="completed-orders-daily"
 )
 
-# With statement labeling (for batch operations)
+# With statement labeling
 cursor.execute(
     "CREATE TABLE orders_backup AS SELECT * FROM orders",
     statement_labels=["daily-backups", "batch-job"]
@@ -965,13 +1185,21 @@ cursor.execute(
     statement_labels=["analytics", "hourly"]
 )
 
-# With statement properties
+# With statement properties (raw dict)
 cursor.execute(
     "SELECT * FROM orders WHERE status = %s",
     ("pending",),
     statement_name="pending-orders-query",
     properties={"sql.state-ttl": "100 ms"}
 )
+
+# With statement properties (StatementProperties)
+cursor.execute(
+    "SELECT * FROM orders WHERE status = %s",
+    ("pending",),
+    statement_name="pending-orders-query",
+    properties=StatementProperties(state_ttl=timedelta(milliseconds=100)),
+)
 ```
 
 ---

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: confluent-sql
-Version: 0.4.2
+Version: 0.5.1
 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
@@ -253,9 +253,11 @@ The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/f
 - **Existing Flink Database** (Confluent Cloud Kafka cluster)
 - **API credentials**, one of:
   - a **"Global" Confluent Cloud API key** and secret, passed as `global_api_key` / `global_api_secret`, or
-  - a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`.
+  - a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`, or
+  - a **BYOIDC bearer token** minted by your own OAuth/OIDC identity provider, passed as `external_access_token` / `identity_pool_id` (see [BYOIDC bearer-token authentication](#byoidc-bearer-token-authentication) below).
 
   A Global key works against every route this driver touches, so it is the more future-proof choice; a Flink Region key works against the Flink SQL routes that are the driver's focus today. Provide at least one pair. If you supply both, the Global pair is used and the Flink pair is ignored. A half-supplied pair (a key without its secret, or vice versa) is rejected.
+- **Organization ID** — required, *unless* you're using a Global API key and it can see exactly one organization, in which case you can omit `organization_id` and it's inferred automatically on first use of the connection. A Flink Region key has no way to discover it, so it always requires `organization_id` explicitly.
 
 ### How to Obtain a Flink Region API Key
 
@@ -276,6 +278,35 @@ To create or find a Flink Region API key:
 
 API keys may also be generated using the Confluent CLI or by API access, outside the scope of this document.
 
+### BYOIDC bearer-token authentication
+
+If your Confluent Cloud organization is configured with your own registered OAuth/OIDC identity provider, you can authenticate to the **Flink data plane** with a bearer token you mint yourself (an "external" token in Confluent's authorization vocabulary) rather than a Confluent API key. Pass the token and the identity-pool id that scopes it:
+
+```python
+import os
+import confluent_sql
+
+connection = confluent_sql.connect(
+    external_access_token=os.environ["MY_IDP_BEARER_TOKEN"],
+    identity_pool_id="pool-abc123",
+    environment_id="env-...",
+    organization_id="org-...",   # required under BYOIDC (see below)
+    cloud_provider="aws",
+    cloud_region="us-east-2",
+    database="your-database-name",   # optional, and works under BYOIDC: it only sets the default
+                                     # database, which needs no CMK cluster-id lookup
+)
+```
+
+The driver stamps `Authorization: Bearer <external_access_token>` and `Confluent-Identity-Pool-Id: <identity_pool_id>` on every Flink request. The parameter name mirrors the Confluent Flink Table API plugin's `client.oauth.external-access-token` option. A runnable example is in [examples/byoidc_bearer_token_example.py](examples/byoidc_bearer_token_example.py).
+
+Things to know:
+
+- **`external_access_token` and `identity_pool_id` are a pair** and are **mutually exclusive** with every API-key parameter (`global_*`, `flink_*`, `tableflow_*`, `connect_*`). Supplying a bearer token alongside any API key is rejected.
+- **Flink data plane only.** Confluent's authorization model does not accept a raw external token on any control-plane route this driver calls. So under BYOIDC the control-plane surfaces — Tableflow (`enable_tableflow` / `get_tableflow` / `disable_tableflow`), Connectors, and the CMK cluster-id lookup that resolves a `database` name to its `lkc-…` id — fail closed with a clear error. Use an API-key connection for those, and pass `database_kafka_cluster_id` to `connect()` if you need the driver to know the cluster id without the CMK lookup.
+- **`organization_id` is required** under BYOIDC. Inferring it needs a control-plane call an external token can't make, so it must be supplied explicitly.
+- **No token refresh.** The token is used verbatim on every request. When it expires, requests begin failing (surfaced as `OperationalError`) and the connection is effectively dead — open a fresh connection with a fresh token.
+
 ## Installation
 
 ```bash
@@ -295,7 +326,7 @@ import confluent_sql
 
 # Connect to Confluent Cloud Flink SQL
 connection = confluent_sql.connect(
-    organization_id="your-org-uuid",
+    organization_id="your-org-uuid",  # optional if using a Global key -- see Prerequisites
     environment_id="env-123456",
     cloud_provider="aws",
     cloud_region="us-east-2",
@@ -379,6 +410,7 @@ This driver extends the standard DB-API v2 interface with additional features:
 - **Streaming cursors** - Non-blocking result consumption from continuous queries
 - **Changelog compression** - Automatic state management for aggregations and joins
 - **Statement lifecycle management** - Named statements, labels, and resource management
+- **Statement properties** - Execution controls not expressible inline within the SQL statement
 - **Type system** - Full support for all Flink SQL types including streaming-specific types
 - **Performance monitoring** - Built-in fetch metrics and introspection
 
@@ -437,14 +469,15 @@ Set required environment variables for integration tests.
 If any of the variables is not set, integration tests will be skipped.
 
 ```bash
-export CONFLUENT_ORG_ID="org-123456"
+export CONFLUENT_ORG_ID="org-123456" # Optional if using a Global key that can see exactly one org.
 export CONFLUENT_ENV_ID="env-123456"
 export CONFLUENT_CLOUD_PROVIDER="aws"
 export CONFLUENT_CLOUD_REGION="us-east-2"
 export CONFLUENT_FLINK_API_KEY="your-key" # Flink Region API key for the above cloud/region ...
 export CONFLUENT_FLINK_API_SECRET="your-secret" # and associated secret.
 # Alternatively, a "Global" Confluent Cloud API key (used in preference to the Flink pair if both
-# are set): export CONFLUENT_GLOBAL_API_KEY / CONFLUENT_GLOBAL_API_SECRET instead.
+# are set): export CONFLUENT_GLOBAL_API_KEY / CONFLUENT_GLOBAL_API_SECRET instead. With a Global
+# key, CONFLUENT_ORG_ID may be omitted -- the integration suite infers it, same as connect() does.
 export CONFLUENT_TEST_DBNAME="test-db" # A database/kafka cluster name within the above cloud/region.
 export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012" # Optional. If set, the integration suite runs against this pool; if unset, the suite runs against the environment's default pool. The driver treats it as optional at connect() either way.
 ```