confluent-sql 0.7.0__tar.gz → 0.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/CHANGELOG.md +51 -0
- confluent_sql-0.9.0/CLAUDE.md +115 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/DBAPI_EXTENSIONS.md +24 -20
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/PKG-INFO +86 -6
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/README.md +85 -5
- confluent_sql-0.9.0/examples/interactive_oauth_login.py +43 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/tableflow_gcs_example.py +8 -6
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/tableflow_lifecycle_example.py +6 -4
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/pyproject.toml +11 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/service.yml +4 -3
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/__init__.py +28 -1
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/__version__.py +1 -1
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/artifacts.py +111 -76
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/auth.py +4 -1
- confluent_sql-0.9.0/src/confluent_sql/connect_options.py +111 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/connection.py +939 -1003
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/connectors.py +124 -157
- confluent_sql-0.9.0/src/confluent_sql/context.py +51 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/cursor.py +65 -18
- confluent_sql-0.9.0/src/confluent_sql/exceptions.py +569 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/__init__.py +24 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/callback_server.py +533 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/config.py +63 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/holder.py +428 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/http_json.py +108 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/pkce.py +38 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/provider.py +1015 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/token_chain.py +360 -0
- confluent_sql-0.9.0/src/confluent_sql/oauth/token_set.py +56 -0
- confluent_sql-0.9.0/src/confluent_sql/polling.py +122 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/result_readers.py +52 -18
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/retry.py +26 -5
- confluent_sql-0.9.0/src/confluent_sql/service_client.py +302 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/statement.py +3 -6
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/tableflow.py +345 -13
- confluent_sql-0.9.0/src/confluent_sql/utils.py +97 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/conftest.py +3 -4
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/conftest.py +128 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/test_connection.py +50 -3
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/test_connector.py +12 -8
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/test_cursor.py +95 -31
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/test_fetch.py +9 -1
- confluent_sql-0.9.0/tests/integration/test_global_key_organization.py +97 -0
- confluent_sql-0.9.0/tests/integration/test_infer_cloud.py +198 -0
- confluent_sql-0.9.0/tests/integration/test_oauth.py +115 -0
- confluent_sql-0.9.0/tests/integration/test_oauth_ambiguous_org.py +73 -0
- confluent_sql-0.9.0/tests/integration/test_oauth_rejected_org.py +50 -0
- confluent_sql-0.9.0/tests/integration/test_oauth_user_identity.py +80 -0
- confluent_sql-0.9.0/tests/integration/test_oauth_user_mismatch.py +97 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/test_tableflow.py +5 -4
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/conftest.py +18 -1
- confluent_sql-0.9.0/tests/unit/oauth/test_callback_server_unit.py +762 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_config_unit.py +75 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_holder_unit.py +870 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_http_json_unit.py +133 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_pkce_unit.py +42 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_provider_unit.py +1728 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_token_chain_unit.py +610 -0
- confluent_sql-0.9.0/tests/unit/oauth/test_token_set_unit.py +108 -0
- confluent_sql-0.9.0/tests/unit/test_artifacts_connection_unit.py +143 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_artifacts_unit.py +190 -58
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_changelog_unit.py +21 -20
- confluent_sql-0.9.0/tests/unit/test_connect_options_unit.py +119 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connection_byoidc_unit.py +9 -13
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connection_close_unit.py +14 -42
- confluent_sql-0.9.0/tests/unit/test_connection_connector_unit.py +94 -0
- confluent_sql-0.9.0/tests/unit/test_connection_controlplane_surfaces_unit.py +257 -0
- confluent_sql-0.9.0/tests/unit/test_connection_infer_cloud_unit.py +378 -0
- confluent_sql-0.9.0/tests/unit/test_connection_oauth_unit.py +837 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connection_unit.py +376 -466
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connection_unit_properties.py +1 -1
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connectors_connection_unit.py +268 -101
- confluent_sql-0.9.0/tests/unit/test_context_unit.py +73 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_cursor_unit.py +85 -5
- confluent_sql-0.9.0/tests/unit/test_package_unit.py +33 -0
- confluent_sql-0.9.0/tests/unit/test_poll_until_forwards_ctx_unit.py +135 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_polling_unit.py +149 -1
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_result_readers_unit.py +240 -1
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_retry_unit.py +84 -0
- confluent_sql-0.9.0/tests/unit/test_service_client_unit.py +671 -0
- confluent_sql-0.9.0/tests/unit/test_tableflow_api_unit.py +678 -0
- confluent_sql-0.9.0/tests/unit/test_tableflow_connection_unit.py +222 -0
- confluent_sql-0.9.0/tests/unit/test_utils_unit.py +83 -0
- confluent_sql-0.7.0/CLAUDE.md +0 -60
- confluent_sql-0.7.0/src/confluent_sql/exceptions.py +0 -345
- confluent_sql-0.7.0/src/confluent_sql/polling.py +0 -57
- confluent_sql-0.7.0/src/confluent_sql/service_api.py +0 -33
- confluent_sql-0.7.0/src/confluent_sql/utils.py +0 -62
- confluent_sql-0.7.0/tests/unit/test_artifacts_connection_unit.py +0 -231
- confluent_sql-0.7.0/tests/unit/test_connection_connector_unit.py +0 -164
- confluent_sql-0.7.0/tests/unit/test_package_unit.py +0 -10
- confluent_sql-0.7.0/tests/unit/test_tableflow_connection_unit.py +0 -698
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/.claude/rules/software-engineering.md +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/.github/CODEOWNERS +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/.gitignore +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/.semaphore/publish_to_pypi.yml +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/.semaphore/semaphore.yml +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/ARCHITECTURE.md +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/LICENSE.txt +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/Makefile +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/STREAMING.md +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/TYPES.md +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/artifact_udf/pyproject.toml +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/artifact_udf/src/example_udf/__init__.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/artifact_udf/src/example_udf/py.typed +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/artifact_udf/src/example_udf/tshirt_sizing.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/artifact_upload_example.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/byoidc_bearer_token_example.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/errors.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/simple_append_only_streaming_query_example.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/snapshot_mode_tuple_cursor_simple_example.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/examples/statement_properties_example.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/changelog_compressor.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/execution_mode.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/statement_properties.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/types.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/src/confluent_sql/variant.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/__init__.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/integration/test_artifact.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_auth_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_changelog_compressor_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connection_credentials_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_connectors_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_execution_mode_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_statement_properties_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_statement_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_tableflow_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/tests/unit/test_types_unit.py +0 -0
- {confluent_sql-0.7.0 → confluent_sql-0.9.0}/uv.lock +0 -0
|
@@ -2,6 +2,57 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this dbapi driver will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.9.0, 2026-11-16
|
|
6
|
+
|
|
7
|
+
### Changed - Breaking
|
|
8
|
+
|
|
9
|
+
- The Tableflow methods moved off `Connection` into a new `TableflowApi` client (`confluent_sql.TableflowApi`), obtained from the new `Connection.get_tableflow_api()` like `get_artifacts_api()` and `get_connector_api()`. `Connection.enable_tableflow()`, `get_tableflow()`, `update_tableflow()` and `disable_tableflow()` are removed, with no deprecation shims: call `.enable()`, `.get()`, `.update()` and `.disable()` on the client instead, e.g. `connection.get_tableflow_api().enable("orders", table_formats=..., storage=...)`. Signatures, blocking behavior and exceptions are unchanged. (#289)
|
|
10
|
+
- Removed the `Connection` methods `connect_controlplane_request()`, `artifact_controlplane_request()`, `resolve_kafka_cluster_id()` and `artifact_scope()`. They were never documented as public: they only existed as hooks for the connector and artifact service APIs, which now receive a request callable, the environment id and (for connectors) a cluster-id resolver or (for artifacts) the cloud, region and endpoint at construction instead (`ConnectorApi`/`ArtifactsApi` are still obtained through `Connection`).
|
|
11
|
+
- Removed the undocumented `Connection.create_connector()`, `get_connector()`, `delete_connector()`, `pause_connector()` and `resume_connector()` passthroughs. Use `Connection.get_connector_api()`, the counterpart of `get_artifacts_api()`, and call `.create()`, `.get()`, `.delete()`, `.pause()` and `.resume()` on it. (#235) The `confluent_sql.service_api` module and the `ControlPlaneContext` and `ArtifactsContext` protocols are removed with them. (#235)
|
|
12
|
+
- `connect()` and `Connection.__init__()` no longer accept `http_timeout_secs`. The setting moved into the new frozen `Timeouts` dataclass (`confluent_sql.Timeouts`, defined in the new `confluent_sql.connect_options` module): replace `http_timeout_secs=5` with `timeouts=Timeouts(httpx_request_timeout_secs=5)`. `connect()` defaults `timeouts` to `DEFAULT_TIMEOUTS`; `Connection.__init__()` has no default and requires a `timeouts` keyword argument. Invalid values still raise `InterfaceError`, now naming the field (`Timeouts.httpx_request_timeout_secs must be positive, got 0`). `Connection.http_timeout_secs` remains as a read-only shorthand for `connection.timeouts.httpx_request_timeout_secs`. (#236)
|
|
13
|
+
- `confluent_sql.oauth.__all__` shrinks to the supported public surface: `OAuthMetrics` and `discard_login`, the function behind the documented `confluent_sql.oauth_discard_login()`, which is unchanged and remains the way to call it. (#313)
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- `cloud_provider` and `cloud_region` may now be omitted from `connect()` when the connection has control-plane reach (a global API key or `auth="oauth"`) and `database` (or `database_kafka_cluster_id`) is given. The lookup runs during `connect()`, so no match, several matches (`AmbiguousClusterError`, below) or a lookup failure surface there. Supplying only one of `cloud_provider` / `cloud_region` no longer raises when inference is possible: the other half is filled in from the cluster and the one supplied is checked against it (`ClusterMismatchError`, below), as is a `database` supplied beside a `database_kafka_cluster_id`; a complete provider+region pair is still trusted with no lookup. Private networking is not derivable, so private-link users keep passing `endpoint` (a cluster that looks private-only, attached to a network with no public access point, draws a warning to do so); BYOIDC and non-global API keys keep today's requirements, with the `InterfaceError` now naming the inference route as well. (#310)
|
|
18
|
+
- `ClusterMismatchError`, a subclass of `OperationalError` importable from `confluent_sql`, raised from `connect()` while cloud and region are being inferred when a supplied `database`, `cloud_provider` or `cloud_region` disagrees with the Kafka cluster the driver resolved. It carries the cluster as `.cluster_id` and every disagreement as `.mismatches` (`(parameter, supplied, actual)` triples; `.parameters` for just the names). Nothing is checked on paths that make no lookup (explicit `endpoint`, or a complete provider+region pair). (#310)
|
|
19
|
+
- `AmbiguousClusterError`, a subclass of `OperationalError` importable from `confluent_sql`, raised when several Kafka clusters in the environment share the connection's `database` name. It carries the candidates as `.clusters` (`(cluster_id, cloud, region)` triples; `.cluster_ids` for just the ids), so callers can catch it by type and pick one to pass as `database_kafka_cluster_id`. (#310)
|
|
20
|
+
- `AmbiguousOrganizationError`, a subclass of `OperationalError` importable from `confluent_sql`, raised when `organization_id` is omitted and the credential can reach more than one organization. It carries the candidates as `.organizations` (`(id, display_name)` pairs; `.organization_ids` for just the ids) and names them in its message, so callers can catch it by type instead of matching message text, and pick one to pass as `organization_id`. (#311)
|
|
21
|
+
- `ConnectorApi` and `TableflowApi` are now importable from `confluent_sql` (as `ArtifactsApi` already was), so callers can annotate what `get_connector_api()` and `get_tableflow_api()` return. (#289)
|
|
22
|
+
- `RequestTimeoutError`, a subclass of `OperationalError` importable from `confluent_sql`, raised when an individual HTTP request times out. Existing `except OperationalError` handlers keep working. (#236)
|
|
23
|
+
|
|
24
|
+
- `Timeouts.statement_results_response_wallclock_secs` (default 30.0), passed as `connect(..., timeouts=Timeouts(statement_results_response_wallclock_secs=...))`: the most wall-clock time a blocking result read spends getting one response to a fetch of statement results, however many timed-out attempts that takes. It is not a cap on a read's total duration. Override a single field with `dataclasses.replace(DEFAULT_TIMEOUTS, statement_results_response_wallclock_secs=60)`. A window no longer than `httpx_request_timeout_secs` leaves no room for a retry, so `Timeouts` emits a `UserWarning` for it. (#236)
|
|
25
|
+
|
|
26
|
+
### Fixed
|
|
27
|
+
|
|
28
|
+
- `confluent_sql.paramstyle` now reads `"format"` (positional `%s` placeholders, which is what the driver has always accepted) instead of the incorrect `"pyformat"`. Code that branches on `paramstyle` (e.g. SQLAlchemy-style dialect detection) now sees the truth. (#223)
|
|
29
|
+
- Under `auth="oauth"`, an omitted `organization_id` is no longer taken silently from the login's default organization, which for a multi-organization user led to a confusing "environment not found" failure much later. The driver now lists the user's organizations (`GET /org/v2/organizations`) as part of the login, during `connect()`, applying the rule it already used for a global API key: exactly one is used, and more than one raises `AmbiguousOrganizationError`. That is a behavior change for multi-organization OAuth users who omitted `organization_id`: they now get the error from `connect()` and must pass `organization_id`. The login is refused along with the connection, so retrying with `organization_id` in the same process works (at the cost of a second browser login). A `connect()` that reuses an established login inherits its organization without listing again. A global key now behaves the same way: where an omitted `organization_id` used to be inferred lazily on first use of the connection, `connect()` now lists the organizations itself and raises `AmbiguousOrganizationError` (instead of a bare `OperationalError` from some later call) when several are reachable, so the failure moves from first use to `connect()` and costs one extra GET per `connect()` (message text changed; no organizations visible still raises `OperationalError`). (#311)
|
|
30
|
+
- Inside a timed wait (`Cursor.execute()`, the `wait_for_*` and `timeout=` calls) and a blocking result read's `statement_results_response_wallclock_secs` window, each HTTP request's timeouts are now capped at the time the wait has left, so a slow request can no longer overrun the wait's `timeout` by up to one `httpx_request_timeout_secs`. The cap applies to each of httpx's connect/read/write/pool timeouts separately, not to the request as a whole (httpx has no total-request deadline), so a server that trickles bytes can still run a little over. A retried GET also stops retrying once that deadline cannot outlast its next backoff, so neither a request nor a backoff sleep runs past it. (#236)
|
|
31
|
+
- A single slow status poll (an `httpx` connect/read/write/pool timeout, e.g. against a cold compute pool) no longer aborts `Cursor.execute()`'s readiness wait, `stop_statement(wait_for_stopped=True)`, the Tableflow `wait_for_running`/`wait_for_removal` waits, or the Connect (create/pause/resume/delete) and Artifacts (delete) waits. Such a poll is treated as "no news yet" and polled again until the call's own `timeout` expires. (#236)
|
|
32
|
+
- A single slow results-page fetch no longer aborts blocking reads of a statement's results (iterating a cursor, `fetchall()`, and snapshot-mode `fetchone()`/`fetchmany()`). The page is requested again, and `RequestTimeoutError` is raised only once timeouts have gone on for the connection's `Timeouts.statement_results_response_wallclock_secs` (default 30 seconds) of wall-clock time. Streaming-mode `fetchone()`/`fetchmany()` still make at most one request and raise `RequestTimeoutError` as before; the failed fetch leaves the cursor untouched, so calling again retries the same page. (#236)
|
|
33
|
+
- Idempotent GETs against the Connect, Tableflow, CMK and organization-lookup control-plane routes are now retried on transient transport errors (connection resets) and transient HTTP statuses (429/500/502/503/504), as Flink-gateway and Artifacts GETs already were. Mutating requests are still sent once. (#235)
|
|
34
|
+
|
|
35
|
+
## 0.8.0, 2026-10-30
|
|
36
|
+
|
|
37
|
+
### Changed - Breaking
|
|
38
|
+
|
|
39
|
+
- `Connection.__init__`'s positional parameters are reordered: `organization_id` now comes after `cloud_provider`/`cloud_region`/`endpoint` (previously it was second, right after `environment_id`).
|
|
40
|
+
|
|
41
|
+
### Added
|
|
42
|
+
|
|
43
|
+
- Interactive browser login: `connect(auth="oauth", ...)` signs in once through your browser instead of requiring API keys, and the login is shared by every connection in the process. `organization_id` is optional. While the login is in progress the driver listens on the fixed loopback port `127.0.0.1:26642`, which must be free (otherwise `OAuthLoginError` with reason `PORT_IN_USE`). See the README and `examples/interactive_oauth_login.py` (#150).
|
|
44
|
+
- `confluent_sql.oauth_discard_login()`: discard the process's shared interactive OAuth login. Closing a `Connection` never does this; the next `connect(auth="oauth", ...)` opens the browser again. (#150)
|
|
45
|
+
- `connect(..., reauth="auto"|"raise")` (with `auth="oauth"` only): what to do once an OAuth session can no longer be refreshed. `"auto"` (default) opens the browser for a fresh login and retries the request; `"raise"` raises `ReauthenticationRequired` instead, for unattended runs. (#150)
|
|
46
|
+
- New exceptions, all subclasses of `OperationalError` and importable from `confluent_sql` (#150):
|
|
47
|
+
- `OAuthLoginError`: the interactive browser login could not complete. Its `reason` is an `OAuthLoginFailure`: `TIMED_OUT`, `PORT_IN_USE`, `AUTHORIZATION_DENIED`, `SERVER_ERROR`, or (on re-authentication) `USER_MISMATCH`.
|
|
48
|
+
- `OAuthTokenEndpointError`: the auth service's token endpoint rejected a request. Carries the OAuth `error_code` (e.g. `"invalid_grant"`) and `http_status_code`.
|
|
49
|
+
- `ReauthenticationRequired`: the session can only be recovered by a fresh login. Its `reason` is a `ReauthenticationReason`: `ABSOLUTE_EXPIRY` (the ~8h session limit) or `REFRESH_REJECTED`.
|
|
50
|
+
|
|
51
|
+
### Changed
|
|
52
|
+
|
|
53
|
+
- `organization_id` is now genuinely optional on both `connect()` and `Connection()` when it can be self-discovered (configured to use either oauth or a global API key).
|
|
54
|
+
- Direct `Connection()` construction's `organization_id` requirement (introduced in 0.6.0, #213) does not apply under `auth="oauth"`, which discovers the organization from the interactive login's session.
|
|
55
|
+
|
|
5
56
|
## 0.7.0, 2026-10-19
|
|
6
57
|
|
|
7
58
|
### Added
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Repository conventions for Claude
|
|
2
|
+
|
|
3
|
+
Guidance for any Claude working in this repository. Keep it short and concrete; add a convention
|
|
4
|
+
here only once the codebase actually follows it in more than one place.
|
|
5
|
+
|
|
6
|
+
## HTTP request routing: `ServiceClient`
|
|
7
|
+
|
|
8
|
+
Every HTTP request this driver makes goes through a `ServiceClient`
|
|
9
|
+
(`src/confluent_sql/service_client.py`), one per plane, held by `Connection`:
|
|
10
|
+
|
|
11
|
+
- `_dataplane` — the Flink gateway (statements and results).
|
|
12
|
+
- `_controlplane` — everything else: Tableflow, the CMK cluster lookup, the `/org/v2` organization
|
|
13
|
+
lookup, Connect, Artifacts. One client and pool, built without credentials. Each request names
|
|
14
|
+
the API it calls as a `ControlPlaneSurface` (`TABLEFLOW`, `CONNECT`, `ARTIFACTS`, `CMK`,
|
|
15
|
+
`ORGANIZATION`) through `Connection._controlplane_request(surface, url, ...)`, which attaches
|
|
16
|
+
that surface's credential (`_auth_for`, from `_surface_auth`) and applies its logging rule
|
|
17
|
+
(Artifacts never logs response bodies: the presign response carries a live upload URL). CMK and
|
|
18
|
+
organization lookups are global-key-only. A new surface is a new enum member, not a new client.
|
|
19
|
+
|
|
20
|
+
`ServiceClient.request(url, method="GET", raise_for_status=True, *, log_body=True, **kwargs)` is the
|
|
21
|
+
only way to send a request, and it decides retry from the method, so callers pick the plane (and,
|
|
22
|
+
on the control plane, the surface) they mean and never a retry policy:
|
|
23
|
+
|
|
24
|
+
- **GET is retried** via `call_with_retries()` (`src/confluent_sql/retry.py`) on transient transport
|
|
25
|
+
errors (`httpx.NetworkError`, `httpx.RemoteProtocolError`; #137) and transient HTTP statuses
|
|
26
|
+
(429/500/502/503/504, via `DEFAULT_RETRYABLE_STATUS_CODES`; #140), with a short exponential
|
|
27
|
+
backoff before giving up. Timeouts are deliberately not retried; wait loops tolerate them via
|
|
28
|
+
`poll_until` (#236), which also hands each attempt a Go-style `Context` (`context.py`) carrying
|
|
29
|
+
the wait's deadline; a blocking result read does the same with its
|
|
30
|
+
`statement_results_response_wallclock_secs` window. Pass it down explicitly as `ctx=` to the
|
|
31
|
+
request, and `ServiceClient.request` caps that request's httpx timeouts at the time left (per
|
|
32
|
+
phase: httpx has no total-request deadline), and a retried GET stops retrying once the deadline
|
|
33
|
+
cannot outlast the next backoff (`call_with_retries(..., ctx=)`). A new wait's attempt should
|
|
34
|
+
always forward its `ctx`. Timeouts are wall-clock budgets, never attempt counts. Status retries ride a private
|
|
35
|
+
`_RetryableStatusError` sentinel, so `call_with_retries` itself stays HTTP-agnostic.
|
|
36
|
+
- **Every other method is sent exactly once**: re-issuing a POST/PATCH/DELETE after a dropped
|
|
37
|
+
connection can double-submit or double-mutate state.
|
|
38
|
+
|
|
39
|
+
A caller that wants a specific status to become a specific exception passes
|
|
40
|
+
`status_exceptions={404: lambda response: SomeNotFoundError(...)}` (status -> factory that *returns*
|
|
41
|
+
the exception; the framework raises it) and an `error_prefix`, rather than `raise_for_status=False`
|
|
42
|
+
plus hand-written checks. Every other error status gets the standard `OperationalError` translation,
|
|
43
|
+
led by `error_prefix`. The mapping is consulted once the request is finished, so a factory mapped to
|
|
44
|
+
a retryable status fires only after a GET's retries are spent. `status_exceptions` / `error_prefix`
|
|
45
|
+
with `raise_for_status=False` is a contradiction and raises `ProgrammingError`; keep
|
|
46
|
+
`raise_for_status=False` only where the status is data (e.g. `delete_statement` treats 404 as
|
|
47
|
+
success) or the condition is not a plain status. Test fakes standing in for a `Requester` call
|
|
48
|
+
`apply_status_policy` so they exercise the real mapping.
|
|
49
|
+
|
|
50
|
+
Never reach for the raw `httpx.Client` (`ServiceClient.httpx_client`) to send a request; that
|
|
51
|
+
bypasses retries, error translation (every `httpx.RequestError` becomes `OperationalError`, #138;
|
|
52
|
+
timeouts become `RequestTimeoutError`) and the reauth policy. Don't add a family of request
|
|
53
|
+
methods on `Connection`: the plane's `ServiceClient` (or `_controlplane_request`) is the entry point.
|
|
54
|
+
|
|
55
|
+
The retry design was introduced in #137 (see `CHANGELOG.md` 0.4.1) after a reported `ECONNRESET`
|
|
56
|
+
while polling a single statement; #140 added status retries and #235 extended them from the Flink
|
|
57
|
+
gateway to every control-plane GET. The reasoning, and the case for a plain function over a
|
|
58
|
+
decorator, is captured in `retry.py`'s module docstring.
|
|
59
|
+
|
|
60
|
+
## Blocking vs. non-blocking lifecycle methods
|
|
61
|
+
|
|
62
|
+
Methods that drive a server-side resource toward a steady state (start a statement, stop it,
|
|
63
|
+
enable/disable a Tableflow sink, etc.) follow a uniform shape:
|
|
64
|
+
|
|
65
|
+
- **Block by default; return the settled state.** The common call should leave the resource in its
|
|
66
|
+
intended terminal/ready state, not hand back a transient one the caller must then poll itself.
|
|
67
|
+
- **Expose a `wait_for_<settled-state>: bool = True` keyword-only argument.** The suffix names the
|
|
68
|
+
exact condition awaited — *not* a generic `wait`/`block`. Existing names: `wait_for_stopped`
|
|
69
|
+
(statement reaches STOPPED), `wait_for_running` (Tableflow topic reaches RUNNING),
|
|
70
|
+
`wait_for_removal` (Tableflow topic is gone). A new method picks the suffix that is literally
|
|
71
|
+
true of what it waits for.
|
|
72
|
+
- **Pair it with a uniform `timeout` keyword arg** (seconds; the standardized knob across all such
|
|
73
|
+
methods).
|
|
74
|
+
- **`=False` is the opt-out**: return as soon as the request is accepted (resource typically in a
|
|
75
|
+
PENDING/just-requested state).
|
|
76
|
+
- **While waiting, raise on terminal failure and on timeout** — surface the failure detail
|
|
77
|
+
(`OperationalError`, e.g. a statement/topic that went FAILED), don't silently return a broken
|
|
78
|
+
resource.
|
|
79
|
+
- **Implement the wait with `poll_until`** from `polling.py`: it owns the backoff, the deadline and
|
|
80
|
+
the `timeout` error, and treats one request timeout (`RequestTimeoutError`) as "no news yet"
|
|
81
|
+
rather than a failure (#236). Don't hand-roll a sleep loop, and don't call `sleep_with_backoff`
|
|
82
|
+
directly.
|
|
83
|
+
|
|
84
|
+
Exemplars: `Connection.stop_statement` / `Cursor.stop_statement` (`wait_for_stopped=True`),
|
|
85
|
+
`TableflowApi.enable` (`wait_for_running=True`), `TableflowApi.disable`
|
|
86
|
+
(`wait_for_removal=True`). The DDL convenience methods (`execute_snapshot_ddl`,
|
|
87
|
+
`execute_streaming_ddl`) block unconditionally and offer no opt-out — that's also acceptable when a
|
|
88
|
+
non-blocking variant would be meaningless.
|
|
89
|
+
|
|
90
|
+
## The `oauth` test marker
|
|
91
|
+
|
|
92
|
+
Test modules exercising the interactive OAuth login -- everything under `tests/unit/oauth/`,
|
|
93
|
+
`test_connection_oauth_unit.py`, and the `tests/integration/test_oauth*.py` modules -- carry
|
|
94
|
+
`pytest.mark.oauth` via module-level `pytestmark`, alongside their `unit`/`integration` marker. A
|
|
95
|
+
new OAuth-only test module should prefer the same. A module that mixes OAuth and non-OAuth tests
|
|
96
|
+
(e.g. `tests/integration/test_infer_cloud.py`) may instead mark just its OAuth tests with
|
|
97
|
+
`@pytest.mark.oauth`, so the others aren't swept into `-m oauth` runs. It is a topic axis
|
|
98
|
+
orthogonal to unit/integration:
|
|
99
|
+
|
|
100
|
+
- `uv run pytest -m oauth` -- every OAuth test (integration ones skip without `RUN_OAUTH_TESTS`).
|
|
101
|
+
- `uv run pytest -m "oauth and unit"` -- the fast, browser-free subset.
|
|
102
|
+
- `RUN_OAUTH_TESTS=1 uv run pytest -n0 -m "oauth and integration"` -- the human-in-the-loop browser
|
|
103
|
+
run. `-n0` is mandatory: the loopback callback port is fixed, so parallel workers collide.
|
|
104
|
+
|
|
105
|
+
## The `integration_with_mocks` test marker
|
|
106
|
+
|
|
107
|
+
Some integration tests are semi-real: they run against the live service, but wrap a real route or
|
|
108
|
+
client call to inject a fault (a dropped connection, a request timeout) or to augment the real
|
|
109
|
+
answer (a bogus extra organization or same-named cluster, so an ambiguity can be exercised on an
|
|
110
|
+
account that doesn't genuinely have one). Such a test carries just `pytest.mark.integration_with_mocks`;
|
|
111
|
+
the integration `conftest.py` adds `integration` automatically, so `-m integration` still selects it. The pattern:
|
|
112
|
+
capture the real function, call it for real, and only then tamper with what it returns (or fail
|
|
113
|
+
before delegating), so the real route and parsing still run and the test can't pass vacuously.
|
|
114
|
+
This pytest marker isn't so much for actually selecting and running this subset, but rather
|
|
115
|
+
to assist in finding similar technique tests (when being asked to write more)
|
|
@@ -600,7 +600,7 @@ cursor.delete_statement()
|
|
|
600
600
|
## Tableflow Lifecycle
|
|
601
601
|
|
|
602
602
|
[Tableflow](https://www.confluent.io/product/tableflow/) materializes the Kafka topic backing a
|
|
603
|
-
Flink table into an Iceberg or Delta table. Four `
|
|
603
|
+
Flink table into an Iceberg or Delta table. Four `TableflowApi` methods manage that sink; get the client with `Connection.get_tableflow_api()` (peer to `get_artifacts_api()` and `get_connector_api()`). Enabling
|
|
604
604
|
it also unlocks
|
|
605
605
|
[efficiency gains for snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html#snapshot-queries-and-tableflow)
|
|
606
606
|
against the table.
|
|
@@ -617,16 +617,20 @@ A runnable example covering the full enable/get/disable lifecycle is in
|
|
|
617
617
|
> authentication](README.md#byoidc-bearer-token-authentication)) fails closed on these methods —
|
|
618
618
|
> use an API-key connection for Tableflow.
|
|
619
619
|
|
|
620
|
+
```python
|
|
621
|
+
tableflow = connection.get_tableflow_api() # used by every example below
|
|
622
|
+
```
|
|
623
|
+
|
|
620
624
|
### Selecting formats: `TableFormat`
|
|
621
625
|
|
|
622
626
|
There is a single format vocabulary, `TableFormat` (`ICEBERG` / `DELTA`), on both the request and
|
|
623
627
|
response sides. A topic can carry **both** formats at once (there is no per-format config), so
|
|
624
|
-
`
|
|
628
|
+
`TableflowApi.enable`'s `table_formats` argument accepts either a single `TableFormat` for the
|
|
625
629
|
common case or a collection for both:
|
|
626
630
|
|
|
627
631
|
```python
|
|
628
|
-
|
|
629
|
-
|
|
632
|
+
tableflow.enable("orders", table_formats=TableFormat.ICEBERG, storage=...)
|
|
633
|
+
tableflow.enable(
|
|
630
634
|
"orders", table_formats={TableFormat.ICEBERG, TableFormat.DELTA}, storage=...
|
|
631
635
|
)
|
|
632
636
|
```
|
|
@@ -636,7 +640,7 @@ Responses name the same `TableFormat`s (`topic.spec.table_formats`,
|
|
|
636
640
|
plain set comparison:
|
|
637
641
|
|
|
638
642
|
```python
|
|
639
|
-
topic =
|
|
643
|
+
topic = tableflow.enable(
|
|
640
644
|
"orders", table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
|
|
641
645
|
storage=ManagedStorage(), wait_for_running=True,
|
|
642
646
|
)
|
|
@@ -645,7 +649,7 @@ assert set(topic.spec.table_formats) == {TableFormat.ICEBERG, TableFormat.DELTA}
|
|
|
645
649
|
|
|
646
650
|
### Storage variants
|
|
647
651
|
|
|
648
|
-
`
|
|
652
|
+
`TableflowApi.enable` requires an explicit, frozen storage spec — no silent default:
|
|
649
653
|
|
|
650
654
|
- `ManagedStorage()` — Confluent-managed bucket, zero config.
|
|
651
655
|
- `ByobAwsStorage(bucket_name=..., provider_integration_id=...)` — bring-your-own AWS S3 bucket.
|
|
@@ -664,12 +668,12 @@ The Tableflow API addresses the cluster by its `lkc-…` id, which the connectio
|
|
|
664
668
|
that matches more than one cluster raises, listing the candidate ids so you can disambiguate with
|
|
665
669
|
`database_kafka_cluster_id`.
|
|
666
670
|
|
|
667
|
-
### `
|
|
671
|
+
### `enable()` — add an Iceberg/Delta sink
|
|
668
672
|
|
|
669
673
|
```python
|
|
670
674
|
from confluent_sql import ManagedStorage, TableFormat, TableflowPhase
|
|
671
675
|
|
|
672
|
-
topic =
|
|
676
|
+
topic = tableflow.enable(
|
|
673
677
|
"orders",
|
|
674
678
|
table_formats=TableFormat.ICEBERG,
|
|
675
679
|
storage=ManagedStorage(),
|
|
@@ -689,23 +693,23 @@ assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
|
|
|
689
693
|
- Raises `TableflowTopicAlreadyExistsError` if Tableflow is already enabled (HTTP 409), or
|
|
690
694
|
`ProgrammingError` if no management credential is available or the cluster id can't be resolved.
|
|
691
695
|
|
|
692
|
-
### `
|
|
696
|
+
### `get()` — read current state
|
|
693
697
|
|
|
694
698
|
```python
|
|
695
|
-
topic =
|
|
699
|
+
topic = tableflow.get("orders")
|
|
696
700
|
print(topic.phase) # TableflowPhase.PENDING / RUNNING / FAILED
|
|
697
701
|
print(topic.spec.table_formats) # [TableFormat.ICEBERG, ...]
|
|
698
702
|
```
|
|
699
703
|
|
|
700
704
|
Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404). There is
|
|
701
|
-
no separate health check — health is read off `
|
|
705
|
+
no separate health check — health is read off `get(...).phase`.
|
|
702
706
|
|
|
703
|
-
### `
|
|
707
|
+
### `update()` — change formats/config on an existing sink
|
|
704
708
|
|
|
705
709
|
```python
|
|
706
710
|
from confluent_sql import TableflowTopicConfig, TableFormat, TableflowPhase
|
|
707
711
|
|
|
708
|
-
topic =
|
|
712
|
+
topic = tableflow.update(
|
|
709
713
|
"orders",
|
|
710
714
|
table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
|
|
711
715
|
config=TableflowTopicConfig(retention_ms="1209600000"),
|
|
@@ -716,7 +720,7 @@ assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
|
|
|
716
720
|
Lets a caller change only `table_formats`/`config` on an already-enabled topic — a `PATCH`, not a
|
|
717
721
|
disable/re-enable — so an in-place config change doesn't drop and rebuild the sink. `storage` and
|
|
718
722
|
the table name itself are immutable server-side and have no in-place path; changing either requires
|
|
719
|
-
`
|
|
723
|
+
`disable` + `enable` instead.
|
|
720
724
|
|
|
721
725
|
**Behavior notes:**
|
|
722
726
|
|
|
@@ -726,16 +730,16 @@ the table name itself are immutable server-side and have no in-place path; chang
|
|
|
726
730
|
way: every `config` field has a server-enforced default and the server rejects an explicit null.
|
|
727
731
|
- When `table_formats` is given, it replaces the full list rather than adding to it.
|
|
728
732
|
- This method sends whatever it's given — it does not diff against the topic's current state.
|
|
729
|
-
Compare against a prior `
|
|
733
|
+
Compare against a prior `get()` yourself if you only want to send what actually changed.
|
|
730
734
|
- Blocks until `RUNNING` by default (`wait_for_running=True`), raising `OperationalError` on
|
|
731
|
-
`FAILED`, same as `
|
|
735
|
+
`FAILED`, same as `enable`. Pass `wait_for_running=False` to return as soon as the
|
|
732
736
|
update is accepted.
|
|
733
737
|
- Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404).
|
|
734
738
|
|
|
735
|
-
### `
|
|
739
|
+
### `disable()` — tear down the sink
|
|
736
740
|
|
|
737
741
|
```python
|
|
738
|
-
|
|
742
|
+
tableflow.disable("orders") # blocks until confirmed gone by default
|
|
739
743
|
```
|
|
740
744
|
|
|
741
745
|
**Behavior notes:**
|
|
@@ -743,7 +747,7 @@ connection.disable_tableflow("orders") # blocks until confirmed gone by defaul
|
|
|
743
747
|
- All-or-nothing in v1: removes the entire Tableflow topic. (Removing just one of two enabled
|
|
744
748
|
formats needs a future API and is not yet supported.)
|
|
745
749
|
- Deletion is asynchronous. Blocks until removal is confirmed by default (`wait_for_removal=True`),
|
|
746
|
-
polling `
|
|
750
|
+
polling `get` until it `404`s. This is why a following `DROP TABLE` is safe by default —
|
|
747
751
|
dropping the Flink table drops its backing topic, so Tableflow must be confirmed gone first to
|
|
748
752
|
avoid racing an active materialization. Pass `wait_for_removal=False` to return as soon as the
|
|
749
753
|
`DELETE` is accepted.
|
|
@@ -762,7 +766,7 @@ storage = ManagedStorage()
|
|
|
762
766
|
config = TableflowTopicConfig(retention_ms="604800000")
|
|
763
767
|
|
|
764
768
|
for table in ("orders", "shipments", "returns"):
|
|
765
|
-
|
|
769
|
+
tableflow.enable(
|
|
766
770
|
table,
|
|
767
771
|
table_formats=TableFormat.ICEBERG,
|
|
768
772
|
storage=storage,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: confluent-sql
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.9.0
|
|
4
4
|
Summary: DB-API v2 compliant driver for Confluent Cloud Flink SQL
|
|
5
5
|
Project-URL: Repository, https://github.com/confluentinc/confluent-sql
|
|
6
6
|
Project-URL: Documentation, https://github.com/confluentinc/confluent-sql?tab=readme-ov-file#confluent-sql
|
|
@@ -253,12 +253,13 @@ The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/f
|
|
|
253
253
|
- **Confluent Cloud account** with Flink environment
|
|
254
254
|
- **Existing Flink Database** (Confluent Cloud Kafka cluster)
|
|
255
255
|
- **API credentials**, one of:
|
|
256
|
+
- an **interactive browser login**, with `auth="oauth"` (see [Interactive login](#interactive-browser-login) below), or
|
|
256
257
|
- a **"Global" Confluent Cloud API key** and secret, passed as `global_api_key` / `global_api_secret`, or
|
|
257
258
|
- a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`, or
|
|
258
259
|
- 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).
|
|
259
260
|
|
|
260
|
-
|
|
261
|
-
- **Organization ID** — required
|
|
261
|
+
The interactive browser login is the simplest way to get started, at the cost of one browser sign-in per process. A Global key works against every route this driver touches. A Flink Region key only works against the core Flink SQL routes (the main DB-API functionality), not other features such as Tableflow, Connectors, or Artifacts.
|
|
262
|
+
- **Organization ID** — required with a Flink Region API key or a BYOIDC bearer token, neither of which can discover it. With a Global API key or `auth="oauth"` it can usually be omitted: see [Inferred connection parameters](#inferred-connection-parameters).
|
|
262
263
|
|
|
263
264
|
### How to Obtain a Flink Region API Key
|
|
264
265
|
|
|
@@ -279,6 +280,35 @@ To create or find a Flink Region API key:
|
|
|
279
280
|
|
|
280
281
|
API keys may also be generated using the Confluent CLI or by API access, outside the scope of this document.
|
|
281
282
|
|
|
283
|
+
### Interactive browser login
|
|
284
|
+
|
|
285
|
+
Instead of API keys, sign in once through your browser:
|
|
286
|
+
|
|
287
|
+
```python
|
|
288
|
+
conn = confluent_sql.connect(
|
|
289
|
+
auth="oauth",
|
|
290
|
+
environment_id="env-...",
|
|
291
|
+
database="my_cluster",
|
|
292
|
+
)
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Only `environment_id` and `database` are needed: the organization, the cluster id, and the cloud provider and region are all inferred (see [Inferred connection parameters](#inferred-connection-parameters)).
|
|
296
|
+
|
|
297
|
+
The browser opens once per process; the login is shared by every connection the process opens. See [examples/interactive_oauth_login.py](examples/interactive_oauth_login.py). The resulting login can reach everything your user account can, so all of the driver's functionality, including Tableflow, Connectors, and Artifacts, is available.
|
|
298
|
+
|
|
299
|
+
**Callback port.** To catch the browser's redirect after you sign in, the driver listens on `127.0.0.1:26642` (path `/callback-confluent-sql-docs`) while the login is in progress. This port is fixed by the driver's registered OAuth client and cannot be changed, so it must be free; if something else holds it, `connect()` raises `OAuthLoginError` with reason `PORT_IN_USE`. Only one login can be in progress per machine at a time. If you don't finish signing in within five minutes, it raises `OAuthLoginError` with reason `TIMED_OUT`.
|
|
300
|
+
|
|
301
|
+
**Login lifetime and signing out.** The login is held for the life of the process: closing a `Connection` does not sign you out, and a later `connect(auth="oauth", ...)` in the same process reuses it without another browser bounce. To explicitly discard the login (and its tokens), for example in a long-lived notebook kernel or server, call `confluent_sql.oauth_discard_login()`. The next `connect(auth="oauth", ...)` will then open the browser again. `oauth_discard_login()` closes the shared login's HTTP client immediately, so it must only be called once nothing is using the login: stop any OAuth activity and close every OAuth `Connection` first. A connection left open will fail at its next token refresh (including one triggered by a 401), and a refresh already in progress can be interrupted, even if the refresh token is still valid.
|
|
302
|
+
|
|
303
|
+
**Session lifetime and re-authentication.** A login's refresh token has a hard ~8 hour absolute lifetime (and expires sooner if idle for too long or revoked), after which the session can no longer be silently refreshed. What happens next is controlled by the `reauth` argument to `connect()`:
|
|
304
|
+
|
|
305
|
+
- `reauth="auto"` (the default): the driver opens the browser for a fresh sign-in and retries the failed request. Every connection in the process shares the new login. This suits interactive use such as notebooks and scripts run by a person.
|
|
306
|
+
- `reauth="raise"`: the request raises `confluent_sql.ReauthenticationRequired` instead. Use this for unattended runs (a long batch job or dbt run started and left running), where nobody would be at the browser. Its `reason` is `ABSOLUTE_EXPIRY` (the ~8 hour wall) or `REFRESH_REJECTED` (idle expiry or revocation); catch it to abort or restart the job cleanly.
|
|
307
|
+
|
|
308
|
+
Re-authentication must be completed as the same user who originally signed in. If a different user signs in, even within the same organization, the driver raises `OAuthLoginError` with reason `OAuthLoginFailure.USER_MISMATCH` and the session stays unauthenticated, so you can sign in again as the original user.
|
|
309
|
+
|
|
310
|
+
This check relies on the user identity claims in the login's token, and is strict: a re-authentication whose token carries no identity comparable to the original's is refused the same way, as is one that names a user when the original login's token named none. The only case let through unchecked is a login whose token never named a user at all, where the driver logs a warning at login and has nothing to compare.
|
|
311
|
+
|
|
282
312
|
### BYOIDC bearer-token authentication
|
|
283
313
|
|
|
284
314
|
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:
|
|
@@ -304,10 +334,43 @@ The driver stamps `Authorization: Bearer <external_access_token>` and `Confluent
|
|
|
304
334
|
Things to know:
|
|
305
335
|
|
|
306
336
|
- **`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.
|
|
307
|
-
- **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 (`
|
|
337
|
+
- **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 (`TableflowApi`), 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.
|
|
308
338
|
- **`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.
|
|
309
339
|
- **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.
|
|
310
340
|
|
|
341
|
+
## Inferred connection parameters
|
|
342
|
+
|
|
343
|
+
With a credential that can reach the Confluent Cloud control plane -- a **Global API key** (`global_api_key` / `global_api_secret`) or **`auth="oauth"`** -- most of what `connect()` needs can be looked up for you. The only non-credential inputs required are `environment_id` and `database` (the database's display name):
|
|
344
|
+
|
|
345
|
+
```python
|
|
346
|
+
# Interactive browser login
|
|
347
|
+
conn = confluent_sql.connect(auth="oauth", environment_id="env-...", database="my_cluster")
|
|
348
|
+
|
|
349
|
+
# Global API key
|
|
350
|
+
conn = confluent_sql.connect(
|
|
351
|
+
global_api_key="...", global_api_secret="...", environment_id="env-...", database="my_cluster"
|
|
352
|
+
)
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
| Parameter | Inferred from | When |
|
|
356
|
+
|---|---|---|
|
|
357
|
+
| `organization_id` | The organizations the credential can reach (`GET /org/v2/organizations`; under OAuth, as part of the login) | During `connect()`. Exactly one is used; none raises `OperationalError`; several raise `AmbiguousOrganizationError` (its `.organizations` lists them), so pass `organization_id` to choose. |
|
|
358
|
+
| `cloud_provider`, `cloud_region` | The cloud and region of the Kafka cluster named by `database` (CMK cluster list) | During `connect()`, which then builds the public Flink endpoint from them. Either may be supplied and the other is filled in. Also used to scope Artifacts calls. |
|
|
359
|
+
| `database_kafka_cluster_id` | The `lkc-…` id of the cluster named by `database` (CMK cluster list) | During `connect()` when cloud and region are being inferred (the same single lookup serves both), otherwise on first use of Tableflow or Connectors. You normally never pass it; see below. |
|
|
360
|
+
|
|
361
|
+
Because inference happens during `connect()`, an unknown or ambiguous organization or database name fails there, not on the first statement.
|
|
362
|
+
|
|
363
|
+
**Precedence.** An explicit `endpoint` always wins, then an explicit `cloud_provider` *and* `cloud_region` pair, then inference, and anything you pass explicitly costs no extra requests. Supplying only one of `cloud_provider` / `cloud_region` makes the driver fill in the other from the cluster, and check the one you gave against it: a wrong one raises `ClusterMismatchError` (its `.mismatches` lists each parameter with what you supplied and what the cluster has), so a typo fails at `connect()`. A complete pair is trusted as given, with no lookup and no check.
|
|
364
|
+
|
|
365
|
+
**`database_kafka_cluster_id` is optional and rarely needed.** Pass it only to disambiguate, when several clusters share the `database` name (`AmbiguousClusterError`, whose `.clusters` lists the candidates), or to skip the lookup, e.g. to use Tableflow or Connectors with only their dedicated key pair. When you do pass it, the cluster is fetched directly by id, which is cheaper and means `database` is not needed to infer cloud and region. If you pass `database` too, it must match that cluster's name, or `ClusterMismatchError` is raised; that check only happens when the driver looks the cluster up anyway (the cloud/region inference above), never on paths that trust what you gave.
|
|
366
|
+
|
|
367
|
+
**What is never inferred.**
|
|
368
|
+
|
|
369
|
+
- `environment_id` is always required.
|
|
370
|
+
- `database` is required for cloud and region inference (an environment can span regions, so there is nothing else to go on); without it, pass `endpoint` or `cloud_provider` and `cloud_region`.
|
|
371
|
+
- **Private networking.** Inference only yields the public Flink endpoint. If your cluster needs private networking, pass `endpoint` (see [Private Networking Considerations](#private-networking-considerations)). When the cluster looks private-only (attached to a network, with no public access point), the driver logs a warning at `connect()` telling you so; it still connects with the public endpoint.
|
|
372
|
+
- **Flink Region API keys and BYOIDC** have no control-plane reach, so they keep their usual requirements: `organization_id`, plus `cloud_provider` and `cloud_region` (or `endpoint`).
|
|
373
|
+
|
|
311
374
|
## Installation
|
|
312
375
|
|
|
313
376
|
```bash
|
|
@@ -327,7 +390,7 @@ import confluent_sql
|
|
|
327
390
|
|
|
328
391
|
# Connect to Confluent Cloud Flink SQL
|
|
329
392
|
connection = confluent_sql.connect(
|
|
330
|
-
organization_id="your-org-uuid", # optional
|
|
393
|
+
organization_id="your-org-uuid", # optional with a Global key -- see "Inferred connection parameters"
|
|
331
394
|
environment_id="env-123456",
|
|
332
395
|
cloud_provider="aws",
|
|
333
396
|
cloud_region="us-east-2",
|
|
@@ -437,7 +500,7 @@ For type support and examples, see **[TYPES.md](https://github.com/confluentinc/
|
|
|
437
500
|
|
|
438
501
|
## Private Networking Considerations
|
|
439
502
|
|
|
440
|
-
By default, this driver uses the public Confluent Cloud API networking endpoint for the provided cloud provider and region. However, if the Flink database / Kafka cluster you intend to query requires private networking connectivity, then provide the appropriate Flink private networking base URL as the `endpoint` parameter
|
|
503
|
+
By default, this driver uses the public Confluent Cloud API networking endpoint for the provided (or [inferred](#inferred-connection-parameters)) cloud provider and region; inference only ever yields the public endpoint. However, if the Flink database / Kafka cluster you intend to query requires private networking connectivity, then provide the appropriate Flink private networking base URL as the `endpoint` parameter
|
|
441
504
|
to `connect()` or `Connection.__init__()`. Refer to the Confluent Cloud [Flink private networking documentation](https://docs.confluent.io/cloud/current/flink/concepts/flink-private-networking.html) for more information on composing your endpoint URL.
|
|
442
505
|
|
|
443
506
|
Symptoms of using the public endpoint when private networking is required include:
|
|
@@ -488,3 +551,20 @@ Run tests:
|
|
|
488
551
|
```bash
|
|
489
552
|
uv run pytest
|
|
490
553
|
```
|
|
554
|
+
|
|
555
|
+
#### OAuth tests
|
|
556
|
+
|
|
557
|
+
Every OAuth test (unit and integration) carries the `oauth` pytest marker. The OAuth *integration* tests open your browser for a real Confluent Cloud sign-in, so they are opt-in: they skip unless `RUN_OAUTH_TESTS` is set (they also need `CONFLUENT_ENV_ID`, `CONFLUENT_CLOUD_PROVIDER` and `CONFLUENT_CLOUD_REGION`; some need `CONFLUENT_TEST_DBNAME`). A plain `uv run pytest` therefore runs the OAuth unit tests only.
|
|
558
|
+
|
|
559
|
+
```bash
|
|
560
|
+
# Fast, browser-free OAuth unit tests only
|
|
561
|
+
uv run pytest -m "oauth and unit"
|
|
562
|
+
|
|
563
|
+
# The browser-driven OAuth integration tests only
|
|
564
|
+
RUN_OAUTH_TESTS=1 uv run pytest -n0 -m "oauth and integration"
|
|
565
|
+
|
|
566
|
+
# Every OAuth test, unit and integration
|
|
567
|
+
RUN_OAUTH_TESTS=1 uv run pytest -n0 -m oauth tests
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
`-n0` is required for any run that includes the integration tests: the loopback callback port is fixed, so parallel workers would collide (and open several browsers at once).
|