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

{confluent_sql-0.4.2 → confluent_sql-0.5.0}/.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.4.2 → confluent_sql-0.5.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this dbapi driver will be documented in this file.
 
+## 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

{confluent_sql-0.4.2 → confluent_sql-0.5.0}/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.0}/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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluent-sql
-Version: 0.4.2
+Version: 0.5.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
@@ -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.
 ```

{confluent_sql-0.4.2 → confluent_sql-0.5.0}/README.md

@@ -22,9 +22,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
 
@@ -45,6 +47,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
@@ -64,7 +95,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",
@@ -148,6 +179,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
 
@@ -206,14 +238,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.
 ```

confluent_sql-0.5.0/examples/byoidc_bearer_token_example.py

@@ -0,0 +1,34 @@
+"""Example of BYOIDC authentication: authenticate to the Flink data plane with a bearer token
+minted by your own OAuth/OIDC identity provider, instead of a Confluent API key + secret.
+
+The driver stamps `Authorization: Bearer <external_access_token>` and `Confluent-Identity-Pool-Id`
+on every Flink request. BYOIDC reaches the Flink data plane only -- Tableflow, Connectors, and the
+CMK cluster-id lookup require an API-key connection. organization_id is mandatory (there is no
+control-plane reach to infer it), and the token is used verbatim with no refresh (when it
+expires, open a fresh connection with a fresh token).
+"""
+
+import os
+
+import confluent_sql
+
+# os.environ[...] on the required params so a missing var fails fast naming itself, rather than an
+# empty string slipping through: an empty external_access_token is falsy, so the driver would never
+# enter BYOIDC mode and would instead raise a misleading API-key/org-id error.
+conn = confluent_sql.connect(
+    external_access_token=os.environ["CONFLUENT_EXTERNAL_ACCESS_TOKEN"],
+    identity_pool_id=os.environ["CONFLUENT_IDENTITY_POOL_ID"],
+    environment_id=os.environ["CONFLUENT_ENV_ID"],
+    organization_id=os.environ["CONFLUENT_ORG_ID"],
+    cloud_provider=os.environ["CONFLUENT_CLOUD_PROVIDER"],
+    cloud_region=os.environ["CONFLUENT_CLOUD_REGION"],
+    compute_pool_id=os.getenv("CONFLUENT_COMPUTE_POOL_ID"),  # optional; None -> default pool
+)
+cursor = conn.cursor()
+try:
+    cursor.execute("SELECT 1 as test_value_1, 2 as test_value_2, 3 as test_value_3")
+    for row in cursor:
+        print(f"iterating over cursor results: {row}")
+finally:
+    cursor.close()
+    conn.close()