confluent-sql 0.5.5__tar.gz → 0.6.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.
Files changed (75) hide show
  1. confluent_sql-0.6.0/.claude/rules/software-engineering.md +52 -0
  2. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/.semaphore/publish_to_pypi.yml +2 -3
  3. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/.semaphore/semaphore.yml +1 -1
  4. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/ARCHITECTURE.md +26 -17
  5. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/CHANGELOG.md +31 -1
  6. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/DBAPI_EXTENSIONS.md +42 -8
  7. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/PKG-INFO +1 -1
  8. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/TYPES.md +1 -0
  9. confluent_sql-0.6.0/examples/tableflow_gcs_example.py +98 -0
  10. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/examples/tableflow_lifecycle_example.py +1 -1
  11. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/pyproject.toml +5 -1
  12. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/__init__.py +15 -1
  13. confluent_sql-0.6.0/src/confluent_sql/__version__.py +3 -0
  14. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/connection.py +205 -116
  15. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/cursor.py +14 -1
  16. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/statement.py +115 -26
  17. confluent_sql-0.6.0/src/confluent_sql/tableflow.py +585 -0
  18. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/types.py +72 -39
  19. confluent_sql-0.6.0/src/confluent_sql/utils.py +35 -0
  20. confluent_sql-0.6.0/src/confluent_sql/variant.py +239 -0
  21. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/integration/test_connection.py +41 -3
  22. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/integration/test_cursor.py +132 -4
  23. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/integration/test_fetch.py +165 -43
  24. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/integration/test_tableflow.py +1 -1
  25. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/conftest.py +2 -0
  26. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_connection_unit.py +104 -71
  27. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_cursor_unit.py +114 -11
  28. confluent_sql-0.6.0/tests/unit/test_package_unit.py +10 -0
  29. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_statement_unit.py +347 -17
  30. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_tableflow_connection_unit.py +203 -9
  31. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_tableflow_unit.py +131 -5
  32. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_types_unit.py +220 -20
  33. confluent_sql-0.6.0/uv.lock +466 -0
  34. confluent_sql-0.5.5/src/confluent_sql/__version__.py +0 -10
  35. confluent_sql-0.5.5/src/confluent_sql/tableflow.py +0 -368
  36. confluent_sql-0.5.5/uv.lock +0 -439
  37. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/.github/CODEOWNERS +0 -0
  38. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/.gitignore +0 -0
  39. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/CLAUDE.md +0 -0
  40. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/LICENSE.txt +0 -0
  41. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/Makefile +0 -0
  42. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/README.md +0 -0
  43. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/STREAMING.md +0 -0
  44. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/examples/byoidc_bearer_token_example.py +0 -0
  45. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/examples/errors.py +0 -0
  46. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/examples/simple_append_only_streaming_query_example.py +0 -0
  47. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/examples/snapshot_mode_tuple_cursor_simple_example.py +0 -0
  48. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/examples/statement_properties_example.py +0 -0
  49. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/service.yml +0 -0
  50. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/auth.py +0 -0
  51. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/changelog_compressor.py +0 -0
  52. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/connectors.py +0 -0
  53. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/exceptions.py +0 -0
  54. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/execution_mode.py +0 -0
  55. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/polling.py +0 -0
  56. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/result_readers.py +0 -0
  57. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/retry.py +0 -0
  58. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/src/confluent_sql/statement_properties.py +0 -0
  59. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/__init__.py +0 -0
  60. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/conftest.py +0 -0
  61. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/integration/conftest.py +0 -0
  62. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/integration/test_connector.py +0 -0
  63. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_auth_unit.py +0 -0
  64. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_changelog_compressor_unit.py +0 -0
  65. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_changelog_unit.py +0 -0
  66. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_connection_byoidc_unit.py +0 -0
  67. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_connection_connector_unit.py +0 -0
  68. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_connection_unit_properties.py +0 -0
  69. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_connectors_connection_unit.py +0 -0
  70. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_connectors_unit.py +0 -0
  71. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_execution_mode_unit.py +0 -0
  72. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_polling_unit.py +0 -0
  73. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_result_readers_unit.py +0 -0
  74. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_retry_unit.py +0 -0
  75. {confluent_sql-0.5.5 → confluent_sql-0.6.0}/tests/unit/test_statement_properties_unit.py +0 -0
@@ -0,0 +1,52 @@
1
+ ---
2
+ paths: ["**"]
3
+ ---
4
+ # Repo Software Engineering Rules
5
+
6
+ ## Claude / Human Interactions
7
+ 1. PR descriptions can be drafted by Claude, but should always be revised and finalized by a human before submission. PRs over-laden with automated content without human review are highly discouraged.
8
+ 2. Claude should never directly reply to humans in contexts such as PR comments, etc. A PR is an artifact by humans for humans with agents assisting in the process. It is demeaning for humans at PR to be interacting with someone else's Claude, be they the PR author or a reviewer. Claude should never directly comment on a PR using "/code-review --comment" or other tooling.
9
+ 3. Agents may be asked to author new issue descriptions, but these should always be reviewed and finalized by a human before submission, and the associated PR description should definitely err on human-authored content, never fully relying on agent-generated content.
10
+ 4. Humans should always validate claude findings when reviewing PRs, issue descriptions, or any other content generated by agents, ensuring accuracy and relevance before taking any action based on those findings, then decide the subset to describe to the human audience, using their own language to describe the issue. Claudeisms should not make it into PR conversations.
11
+
12
+
13
+ ## Pull Request Lifecycle Rules
14
+ ### Branches must adhere to the following lifecycle rules:
15
+ 1. A branch should be focused on a single logical change or feature. More complex changes should be split into multiple branches and pull requests.
16
+ - At most a handful of small, pithy 'also seen and fixed or improved here' changes can be included, and must always be explicitly pointed out in the pull request description.
17
+ 2. A branch should have a human-readable reasonable number of lines of changes relative to its parent branch:
18
+ - At most 500-700 lines of actual primary codebase changes (excluding docs, docstrings, tests).
19
+ - Test suite and / or documentation changes can at most double the number of lines of primary codebase changes for a total maximum of around 2,100 lines including the non-primary codebase changes.
20
+ - package lock files (e.g., package-lock.json, uv.lock, other purely mechanical changes) are not counted towards the line limits.
21
+ - Exceptions to these limits must be explicitly justified in the pull request description, but should be truly exceptional.
22
+ 3. Introducing new tooling, development practices, or changes to the development or CI/CD workflow should be done through consensus and discussion, such as through Slack (citing the thread in the PR description) or an issue written by a separate team member.
23
+
24
+ ### Pull requests must adhere to the following rules:
25
+ 1. A pull request should be raised only after the branch is up-to-date with its parent branch and passing unit tests and linting.
26
+ 2. Do not raise, or advise raising, a pull request for a branch that violates the branch lifecycle rules unless a strong justification is given.
27
+ - Instead, determine ways to bring the branch into compliance with the branch lifecycle rules, such as through splitting separate concerns into independent or stacked branches, compacting wordy separate tests into parameterized ones, better use of fixtures, etc.
28
+ - If it is not possible to bring the branch into compliance, ask the human to provide a strong justification in the pull request description.
29
+ 3. When merging a multi-commit pull request, the human should hand-write the ultimate merge commit message, summarizing the changes in a clear and concise manner.
30
+
31
+ ### PR Descriptions
32
+ 1. A PR description should clearly outline the single logical change or feature being introduced.
33
+ 2. Any small, pithy 'also seen and fixed or improved here' changes must be explicitly pointed out in the PR description.
34
+ 3. The PR description should include any justifications for exceptions to the branch or PR lifecycle rules.
35
+ 4. Breaking changes to existing released interfaces must be highlighted in the PR description (as well as the corresponding changelog entry).
36
+ 5. The PR description should reference any related issues ("Closes #131"), previous PR numbers, or relevant slack threads.
37
+ 6. PRs for branches other than main for new tip development should clearly indicate the target branch in the PR title: "[v0.3.x] Fix the thing", "[oauth-integration] Make epic progress"
38
+ 7. Security related issues should be called out very clearly in the PR description and should be PR'd in isolated branches.
39
+ - This includes those for "maintenance" dependency updates.
40
+ - Maintenance dependency updates should never be combined with feature development changes. New features which require new dependencies should only introduce those new dependencies and not also update unrelated dependencies.
41
+
42
+ ## Branching
43
+ 1. The main branch is used for the tip of development. It must always pass unit and integration/functional tests.
44
+ 2. Larger development epics which might leave main in temporary broken state should be developed against a child integration branch and then have rule-following PRs make that branch grow in reasonable chunks. The integration branch is then PR cycled back into main, bypassing the size rules, since every line of change in the integration branch has already been reviewed and approved through the smaller, rule-following PRs.
45
+ - The only way non-present-in-main code should be introduced into an integration branch is through a rule-following PR being approved.
46
+ - Other techniques may include pseudo-feature flags as implemented by environment variable or other opt-in mechanisms, as pre-determined by developer and target reviewers.
47
+ 3. Release branches (`v0.5.x`) will be cut from main when preparing for a release.
48
+ - The initial PR cutting the release branch should have zero changes from main.
49
+ - "Final" testing, bugbashing, etc. should be performed on the release branch, with fixes following the normal branch/PR size rules.
50
+ - After deciding that a release is a "go", then the PR to into the release branch stamping the new version and changelog date header should be made, then the release actually made, then merge-back into main.
51
+ - Any hotfixes required after the release should be developed against the release branch *first*, verified, then patch release made, then finally the changes merged back into main, including the patch release changelog updates.
52
+
@@ -8,7 +8,6 @@ global_job_config:
8
8
  prologue:
9
9
  commands:
10
10
  - checkout
11
- - . vault-setup
12
11
  - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
13
12
  - uv sync --frozen
14
13
 
@@ -18,8 +17,8 @@ blocks:
18
17
  jobs:
19
18
  - name: Publish `confluent_sql` to PyPi
20
19
  commands:
21
- - export VERSION=$(grep '^version' pyproject.toml | cut -d'"' -f2)
20
+ - export VERSION=$(grep '^__version__' src/confluent_sql/__version__.py | cut -d'"' -f2)
22
21
  - echo "Publishing confluent-sql $VERSION to PyPi"
23
22
  - uv build
24
- - CONFLUENT_SQL_KEY=$(vault kv get -field=confluent-sql v1/ci/kv/pypi/pypi.org)
23
+ - . vault-get-secret --secret-key=pypi_token --export-as=CONFLUENT_SQL_KEY pypi/confluent-sql
25
24
  - uv publish -u __token__ -p "$CONFLUENT_SQL_KEY" dist/*
@@ -22,7 +22,7 @@ global_job_config:
22
22
  - . vault-setup
23
23
  - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
24
24
  - uv sync --frozen
25
- - export VERSION=$(grep '^version' pyproject.toml | cut -d'"' -f2)
25
+ - export VERSION=$(grep '^__version__' src/confluent_sql/__version__.py | cut -d'"' -f2)
26
26
 
27
27
  blocks:
28
28
  - name: "Test"
@@ -35,13 +35,13 @@ When you submit a statement (query, DDL, or data ingestion job), it becomes a fi
35
35
 
36
36
  Every statement progresses through these phases:
37
37
 
38
- | Phase | Meaning | Can Fetch Results Through This Driver? |
39
- | ------------- | --------------------------------- | ---------------------------------------------------- |
40
- | **PENDING** | Queued on server, not yet started | No |
41
- | **RUNNING** | Actively executing | No if snapshot query/cursor, Yes if streaming cursor |
42
- | **COMPLETED** | Finished successfully | Yes (for both query/cursor types) |
43
- | **FAILED** | Error during execution | No |
44
- | **STOPPED** | Explicitly stopped through API. | No |
38
+ | Phase | Meaning | Can Fetch Results Through This Driver? |
39
+ | ------------- | --------------------------------- | ------------------------------------------------ |
40
+ | **PENDING** | Queued on server, not yet started | No |
41
+ | **RUNNING** | Actively executing | Depends on statement kind and traits (see below) |
42
+ | **COMPLETED** | Finished successfully | Yes (for both query/cursor types) |
43
+ | **FAILED** | Error during execution | No |
44
+ | **STOPPED** | Explicitly stopped through API. | No |
45
45
 
46
46
  ### How Phases Progress
47
47
 
@@ -51,16 +51,22 @@ Every statement progresses through these phases:
51
51
  PENDING → RUNNING → COMPLETED
52
52
  ```
53
53
 
54
- When you call `cursor.execute()` for a snapshot query / default cursor, the driver:
54
+ When you call `cursor.execute()` for a snapshot query / default cursor, the driver submits the
55
+ statement (HTTP POST) and polls until results can be fetched. Whether that's as soon as RUNNING
56
+ or only once COMPLETED depends on the statement's kind and traits, using the exact same logic as
57
+ streaming mode:
55
58
 
56
- 1. Submits the statement (HTTP POST)
57
- 2. Polls the server until it reaches COMPLETED phase
58
- 3. Returns from `.execute()` to let you begin to interact with the cursor / results.
59
+ - A plain query with a finite, append-only result (e.g. a projection or filter with no `GROUP BY`)
60
+ is ready as soon as the statement reaches RUNNING — the server computes snapshot results as one
61
+ batch with nothing left to retract, so the result set is already stable by then.
62
+ - A bounded, non-append-only query (an aggregation that could still retract rows as it settles)
63
+ waits for COMPLETED, since its result isn't guaranteed final until then.
64
+ - A statement with no result set at all — `INSERT INTO`, or a `CREATE TABLE ... AS SELECT` — is a
65
+ genuinely finite write/population job in snapshot mode and also waits for COMPLETED, since its
66
+ side effect isn't guaranteed to have landed until then.
59
67
 
60
- This is blocking—your code pauses until the server finishes statement execution and result set calculation.
61
-
62
- _NOTE_: This behavior may change in future releases, moving to have `.execute()` return once RUNNING phase is entered,
63
- moving the additional blocking to the fetching results interactions.
68
+ Either way, `.execute()` blocks until the statement is ready by that definition, then returns to
69
+ let you begin to interact with the cursor / results.
64
70
 
65
71
  **Streaming queries:**
66
72
 
@@ -233,11 +239,14 @@ print(f"Append-only: {stmt.is_append_only}") # True if statement results change
233
239
 
234
240
  ### Snapshot Mode
235
241
 
236
- Snapshot queries are **blocking**—your code pauses until the server finishes computing the result set:
242
+ Snapshot queries are **blocking**—your code pauses until results are ready to fetch. For most
243
+ queries (a finite, append-only result), that's as soon as the statement reaches `RUNNING`, since
244
+ the result set is already stable by then; a bounded, non-append-only aggregation instead waits for
245
+ `COMPLETED`, since its result could still change:
237
246
 
238
247
  ```python
239
248
  cursor = connection.cursor()
240
- cursor.execute("SELECT * FROM large_table") # ← Blocks here until the statement reaches `COMPLETED` phase.
249
+ cursor.execute("SELECT * FROM large_table") # ← Blocks here until results can be fetched.
241
250
  rows = cursor.fetchall()
242
251
  ```
243
252
 
@@ -2,12 +2,42 @@
2
2
 
3
3
  All notable changes to this dbapi driver will be documented in this file.
4
4
 
5
+ ## Unreleased
6
+
7
+ ## 0.6.0, 2026-09-29
8
+
9
+ ### Changed - Breaking
10
+
11
+ - `Connection.enable_tableflow()`: Renamed the `tableflow_formats` parameter to `table_formats`. Update calls from `enable_tableflow(tableflow_formats=...)` to `enable_tableflow(table_formats=...)`. (#214)
12
+ - `TableflowTopicSpec.config`: Now parsed as a typed `TableflowTopicConfig` instead of being left as a raw mapping. If you need unmodeled wire fields, read `topic.spec.raw.get("config")` instead. (#214)
13
+
14
+ ### Added
15
+
16
+ - Support for enabling TableFlow against GCP/GCS. Use kind=`"GoogleCloudStorage"` and new related class `GcsStorage`, peer to ByobAwsStorage/AzureAdlsStorage/ManagedStorage. See new example `examples/tableflow_gcs_example.py` for more details. (#239)
17
+ - Ability to adjust an existing TableFlow configuration: `Connection.update_tableflow(table_name, *, table_formats=None, config=None, wait_for_running=True, timeout=300)` updates an already-enabled Tableflow topic's `table_formats`/`config` in place via `PATCH /tableflow/v1/tableflow-topics/{display_name}`, avoiding the disable/re-enable cycle `enable_tableflow` would otherwise require. `None` (the default) means "leave unchanged," for both of this method's own arguments and for each of `config`'s own sub-fields. `storage`/`display_name` remain immutable and have no in-place path; a caller needing to change either must recreate the topic. By default blocks until the topic returns to `RUNNING`; pass `wait_for_running=False` to return as soon as the update is accepted. Raises `TableflowTopicNotFoundError` if Tableflow isn't enabled for the table. (#214)
18
+ - Support for the new VARIANT type: VARIANT result columns are now decoded into typed Python values instead of raising `NotImplementedError`. An OBJECT becomes a `dict`, an ARRAY a `list`, and each scalar its matching Python type (`bool`, `int`, `float`, `Decimal`, `str`, `date`, `time`, `datetime`, `bytes`). Nanosecond-precision timestamps are truncated to microseconds. An undecodable node is returned as the new `UndecodableVariant`. VARIANT is not yet supported as a statement parameter (Flink has no VARIANT literal syntax).
19
+ - `Statement.warnings` exposes non-fatal warnings (`severity`, `created_at`, `reason`, `message`) reported by the server for a statement, parsed from `status.warnings` into a list of `StatementWarning`. `Cursor.warnings` is a convenience that delegates to `cursor.statement.warnings`, returning an empty list before a statement has been executed; unlike most cursor state, it remains readable after `Cursor.close()`. (#234)
20
+
21
+ ### Fixed
22
+
23
+ - Type conversion methods across `types.py` now consistently raise dbapi-mandated exceptions (`DataError`, `InterfaceError`) rather than a bare builtin (`ValueError`, `decimal.InvalidOperation`) for problems with a Flink response value, a Python value that can't be represented as a Flink SQL literal, or a converter misconfigured with the wrong column type. (#204)
24
+ - `stop_statement(wait_for_stopped=True)` (the default) on a statement that had already reached FAILED on its own -- before the stop was ever requested -- no longer raises `OperationalError`. The blocking wait mistook "the statement is currently FAILED" for "the statement transitioned to FAILED while we were waiting for it to stop," when the former is really the same "already terminal, nothing to stop" success the `Statement`-object short-circuit already returns for a cached terminal statement; only a transition *into* FAILED partway through the wait is a genuine failure to stop cleanly. (#203)
25
+
26
+ ### Changed
27
+
28
+ - Pushed the remaining `connect()`-only validation (`environment_id` and the endpoint-vs-`cloud_provider`/`cloud_region` requirement) down into `Connection.__init__()` as the single source of truth, so `connect()` and direct `Connection()` construction validate uniformly. `connect()` callers see no new errors; direct `Connection()` construction now fails fast with the same `InterfaceError`s (and the more specific per-field message for missing cloud info) instead of deferring to a confusing server-side failure later. (#213)
29
+ - **Behavior change for direct `Connection()` construction:** `organization_id` validation is now centralized in `Connection.__init__()` as well, extending the same fail-fast treatment to the constructor. Constructing a `Connection` directly with an empty `organization_id` and no global key now raises `InterfaceError("Organization ID is required")` rather than being silently accepted, and the `organization_id` property's former "no global key → return `""`" fallback has been removed as now-unreachable.
30
+ - `Statement.can_fetch_results()`'s snapshot-mode branch is now kind/trait-based (schema presence, `is_pure_ddl`, `is_bounded`, `is_append_only`) instead of unconditionally waiting for a terminal phase -- the same logic streaming mode already used. A bounded, append-only snapshot query that actually produces a result set (e.g. a plain projection) is now reported ready as soon as the statement reaches `RUNNING`, instead of blocking `Cursor.execute()` / `Connection.execute_snapshot_ddl()` until `COMPLETED`. Bounded, non-append-only snapshot queries (aggregations that could still retract) and any statement with no result schema at all -- `INSERT INTO`, snapshot CTAS (`CREATE TABLE ... AS SELECT`), and other DML/DDL that produces no rows -- are unaffected and still wait for terminal, since a finite write or population job isn't guaranteed to have landed until then (unlike its streaming counterpart, which may run forever and is ready once RUNNING). This can make `Cursor.execute()` and iteration/`fetchall()` return sooner for snapshot-mode queries that produce a result set. (#205)
31
+
32
+ ### Removed
33
+
34
+ - The `dbname` parameter of `connect()`, deprecated in favor of `database` since 0.2.0, has been removed. Passing `dbname=` now raises `TypeError` for an unexpected keyword argument instead of emitting a `DeprecationWarning`. Use `database=` instead.
5
35
 
6
36
  ## 0.5.5, 2026-09-09
7
37
 
8
38
  ### Fixed
9
39
 
10
- - Fix TableflowTopicConfig.to_spec() serialization of retention_ms/data_retention_ms -- must be strings, not ints.
40
+ - `TableflowTopicConfig.to_spec()` now serializes `retention_ms`/`data_retention_ms` as strings rather than ints -- the API rejects non-string values for both, since the schema types them as int64, string-encoded to dodge JS/IEEE-754 double precision loss. (#215)
11
41
 
12
42
  ## 0.5.4, 2026-09-08
13
43
 
@@ -569,7 +569,7 @@ cursor.delete_statement()
569
569
  ## Tableflow Lifecycle
570
570
 
571
571
  [Tableflow](https://www.confluent.io/product/tableflow/) materializes the Kafka topic backing a
572
- Flink table into an Iceberg or Delta table. Three `Connection` methods manage that sink. Enabling
572
+ Flink table into an Iceberg or Delta table. Four `Connection` methods manage that sink. Enabling
573
573
  it also unlocks
574
574
  [efficiency gains for snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html#snapshot-queries-and-tableflow)
575
575
  against the table.
@@ -590,13 +590,13 @@ A runnable example covering the full enable/get/disable lifecycle is in
590
590
 
591
591
  There is a single format vocabulary, `TableFormat` (`ICEBERG` / `DELTA`), on both the request and
592
592
  response sides. A topic can carry **both** formats at once (there is no per-format config), so
593
- `enable_tableflow`'s `tableflow_formats` argument accepts either a single `TableFormat` for the
593
+ `enable_tableflow`'s `table_formats` argument accepts either a single `TableFormat` for the
594
594
  common case or a collection for both:
595
595
 
596
596
  ```python
597
- connection.enable_tableflow("orders", tableflow_formats=TableFormat.ICEBERG, storage=...)
597
+ connection.enable_tableflow("orders", table_formats=TableFormat.ICEBERG, storage=...)
598
598
  connection.enable_tableflow(
599
- "orders", tableflow_formats={TableFormat.ICEBERG, TableFormat.DELTA}, storage=...
599
+ "orders", table_formats={TableFormat.ICEBERG, TableFormat.DELTA}, storage=...
600
600
  )
601
601
  ```
602
602
 
@@ -606,7 +606,7 @@ plain set comparison:
606
606
 
607
607
  ```python
608
608
  topic = connection.enable_tableflow(
609
- "orders", tableflow_formats={TableFormat.ICEBERG, TableFormat.DELTA},
609
+ "orders", table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
610
610
  storage=ManagedStorage(), wait_for_running=True,
611
611
  )
612
612
  assert set(topic.spec.table_formats) == {TableFormat.ICEBERG, TableFormat.DELTA}
@@ -620,6 +620,8 @@ assert set(topic.spec.table_formats) == {TableFormat.ICEBERG, TableFormat.DELTA}
620
620
  - `ByobAwsStorage(bucket_name=..., provider_integration_id=...)` — bring-your-own AWS S3 bucket.
621
621
  - `AzureAdlsStorage(storage_account_name=..., container_name=..., provider_integration_id=...)` —
622
622
  customer-owned Azure Data Lake Storage Gen2.
623
+ - `GcsStorage(bucket_name=..., provider_integration_id=...)` — customer-owned Google Cloud Storage
624
+ bucket.
623
625
 
624
626
  ### Cluster-id resolution
625
627
 
@@ -638,7 +640,7 @@ from confluent_sql import ManagedStorage, TableFormat, TableflowPhase
638
640
 
639
641
  topic = connection.enable_tableflow(
640
642
  "orders",
641
- tableflow_formats=TableFormat.ICEBERG,
643
+ table_formats=TableFormat.ICEBERG,
642
644
  storage=ManagedStorage(),
643
645
  )
644
646
  assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
@@ -646,7 +648,7 @@ assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
646
648
 
647
649
  **Behavior notes:**
648
650
 
649
- - `tableflow_formats` and `storage` are required (no defaults); `tableflow_formats` must name at
651
+ - `table_formats` and `storage` are required (no defaults); `table_formats` must name at
650
652
  least one format. `config` is an optional `TableflowTopicConfig` (retention, error-handling)
651
653
  shared across all enabled formats.
652
654
  - Blocks until `RUNNING` by default (`wait_for_running=True`), raising `OperationalError` on
@@ -667,6 +669,38 @@ print(topic.spec.table_formats) # [TableFormat.ICEBERG, ...]
667
669
  Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404). There is
668
670
  no separate health check — health is read off `get_tableflow(...).phase`.
669
671
 
672
+ ### `update_tableflow()` — change formats/config on an existing sink
673
+
674
+ ```python
675
+ from confluent_sql import TableflowTopicConfig, TableFormat, TableflowPhase
676
+
677
+ topic = connection.update_tableflow(
678
+ "orders",
679
+ table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
680
+ config=TableflowTopicConfig(retention_ms="1209600000"),
681
+ )
682
+ assert topic.phase is TableflowPhase.RUNNING # blocked to RUNNING by default
683
+ ```
684
+
685
+ Lets a caller change only `table_formats`/`config` on an already-enabled topic — a `PATCH`, not a
686
+ disable/re-enable — so an in-place config change doesn't drop and rebuild the sink. `storage` and
687
+ the table name itself are immutable server-side and have no in-place path; changing either requires
688
+ `disable_tableflow` + `enable_tableflow` instead.
689
+
690
+ **Behavior notes:**
691
+
692
+ - `table_formats` and `config` are each independently optional, but at least one non-empty update must be given.
693
+ `None` means "leave unchanged" — both for the method's own two arguments and for each field on
694
+ `config` (`retention_ms`, `data_retention_ms`, `error_handling`). A field can't be *cleared* this
695
+ way: every `config` field has a server-enforced default and the server rejects an explicit null.
696
+ - When `table_formats` is given, it replaces the full list rather than adding to it.
697
+ - This method sends whatever it's given — it does not diff against the topic's current state.
698
+ Compare against a prior `get_tableflow()` yourself if you only want to send what actually changed.
699
+ - Blocks until `RUNNING` by default (`wait_for_running=True`), raising `OperationalError` on
700
+ `FAILED`, same as `enable_tableflow`. Pass `wait_for_running=False` to return as soon as the
701
+ update is accepted.
702
+ - Raises `TableflowTopicNotFoundError` if Tableflow is not enabled for the topic (HTTP 404).
703
+
670
704
  ### `disable_tableflow()` — tear down the sink
671
705
 
672
706
  ```python
@@ -699,7 +733,7 @@ config = TableflowTopicConfig(retention_ms="604800000")
699
733
  for table in ("orders", "shipments", "returns"):
700
734
  connection.enable_tableflow(
701
735
  table,
702
- tableflow_formats=TableFormat.ICEBERG,
736
+ table_formats=TableFormat.ICEBERG,
703
737
  storage=storage,
704
738
  config=config,
705
739
  )
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: confluent-sql
3
- Version: 0.5.5
3
+ Version: 0.6.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
@@ -24,6 +24,7 @@ At time of writing, Flink is not able to infer the type of a SQL literal based o
24
24
  | `MAP` | `dict` | `MAP['k1', 1, 'k2', 2]` | Flink MAPs are strongly typed on both the key and value type, so heterogeneous Python dicts are disallowed (outside of `None` keys or values, if the MAP key or value type includes nullability). Provided `dict`s cannot contain only-`None` keys or values, due to the need to infer the type for the corresponding key or value `NULL`. |
25
25
  | `MULTISET` | `collections.Counter` | _(n/a)_ | Driver can deserialize results into `Counter`, but Flink cannot accept MULTISET literals, so submitting `Counter` parameters is unsupported. Any supported Python type corresponding to the MULTISET's key type is supported. |
26
26
  | `ROW` | `tuple`, `namedtuple`, `typing.NamedTuple`, `@dataclass` | `ROW(1, 'foo')` | Parameter `ROW` values require `tuple`, `namedtuple`, `NamedTuple` or `@dataclass` instances, and are transcribed to literal `ROW` values positionally. Statement results containing `ROW` members will by default be mapped to auto-generated `collections.namedtuple` classes with named fields. Users may register their own `collections.namedtuple`, `typing.NamedTuple`, or `@dataclass` for use for `ROW` result mapping using the `connection.register_row_type()` method. |
27
+ | `VARIANT` | `dict` (OBJECT) / `list` (ARRAY) / typed scalar (`bool`, `int`, `float`, `Decimal`, `str`, `date`, `time`, `datetime`, `bytes`) / `UndecodableVariant` | _(n/a)_ | VARIANT values are encountered in results in two broad ways: from an explicit `PARSE_JSON()` (or similar) call within the statement itself, or when an underlying Kafka topic's serialization format maps onto Flink's VARIANT type — for example a JSON Schema carrying an open "{}" field. Result decoding only. A VARIANT toplevel OBJECT or member becomes a `dict`, an ARRAY a `list`, and each scalar its matching Python type (`bool`, `int`, `float`, `Decimal`, `str`, `date`, `time`, `datetime`, `bytes`). Nanosecond timestamps are truncated to microseconds (Python `datetime` limit). An undecodable node is returned as `UndecodableVariant`. Cannot be sent as a statement parameter, as Flink has no VARIANT literal syntax yet. |
27
28
  | `NULL` | `None` | _(n/a)_ | Only produced by results; cannot be sent because Flink needs typed NULLs—use `SqlNone` instead. |
28
29
  | _(any typed NULL)_ | `SqlNone` | `cast(null as INTEGER)` | `SqlNone` enforces Flink type names; parameterized types must match regex (e.g., `ROW<...>`). Results never return `SqlNone`, so mapping is one-way. |
29
30
 
@@ -0,0 +1,98 @@
1
+ """Example of enabling and updating Tableflow on Google Cloud Storage (GCS).
2
+
3
+ This mirrors ``tableflow_lifecycle_example.py`` but targets a customer-owned GCS bucket via the
4
+ new ``GcsStorage`` backend, and additionally shows the ``update_tableflow`` in-place path and a
5
+ non-blocking enable. Tableflow materializes the Kafka topic backing a Flink table into an
6
+ Iceberg/Delta table; here the underlying files land in your own GCS bucket rather than a
7
+ Confluent-managed one.
8
+
9
+ GCS bring-your-own-bucket needs a provider integration (``cspi-...``) already set up for the
10
+ environment, granting Confluent write access to the bucket -- ``provider_integration_id`` below.
11
+ ``bucket_region`` and ``table_path`` are server-assigned and read-only, so they aren't inputs to
12
+ ``GcsStorage``; read them back off ``topic.spec.raw["storage"]`` after enabling if you need them.
13
+
14
+ Tableflow is a control-plane surface and isn't reachable under BYOIDC -- use an API-key connection
15
+ (a Global key, as here, or a narrower tableflow_api_key / tableflow_api_secret pair).
16
+
17
+ Nothing here is meant to be run as-is: it's a tour of the call shapes and the new imports. The
18
+ table (and its backing Kafka topic) must already exist; this only manages the Tableflow sink.
19
+ """
20
+
21
+ import os
22
+
23
+ import confluent_sql
24
+ from confluent_sql import (
25
+ GcsStorage,
26
+ TableflowErrorHandlingLog,
27
+ TableflowPhase,
28
+ TableflowTopicConfig,
29
+ TableFormat,
30
+ )
31
+
32
+ conn = confluent_sql.connect(
33
+ global_api_key=os.environ["CONFLUENT_GLOBAL_API_KEY"],
34
+ global_api_secret=os.environ["CONFLUENT_GLOBAL_API_SECRET"],
35
+ environment_id=os.environ["CONFLUENT_ENV_ID"],
36
+ organization_id=os.environ["CONFLUENT_ORG_ID"],
37
+ cloud_provider="gcp", # GCS storage lives in a GCP environment
38
+ cloud_region=os.environ["CONFLUENT_CLOUD_REGION"], # e.g. "us-central1"
39
+ compute_pool_id=os.getenv("CONFLUENT_COMPUTE_POOL_ID"), # optional; None -> default pool
40
+ database=os.environ["CONFLUENT_DATABASE"], # Kafka cluster name; resolved to lkc-... via CMK
41
+ )
42
+ table_name = os.getenv("CONFLUENT_TABLEFLOW_TABLE", "orders")
43
+
44
+ # A customer-owned GCS bucket. Only bucket_name + provider_integration_id are writable; the
45
+ # server assigns bucket_region and table_path (gs://...) and reports them read-only.
46
+ gcs = GcsStorage(
47
+ bucket_name=os.getenv("CONFLUENT_GCS_BUCKET", "my-gcs-bucket"),
48
+ provider_integration_id=os.environ["CONFLUENT_GCS_PROVIDER_INTEGRATION_ID"], # cspi-...
49
+ )
50
+
51
+ try:
52
+ # Enable Iceberg on the GCS bucket, with a topic-level config. wait_for_running=True (the
53
+ # default) blocks until the topic reaches RUNNING, raising OperationalError if it goes FAILED.
54
+ topic = conn.enable_tableflow(
55
+ table_name,
56
+ table_formats=TableFormat.ICEBERG,
57
+ storage=gcs,
58
+ config=TableflowTopicConfig(
59
+ retention_ms=604_800_000, # 7 days; int in, string-encoded int64 on the wire
60
+ error_handling=TableflowErrorHandlingLog(target="orders_dlq"), # bad records -> DLQ
61
+ ),
62
+ )
63
+ print(f"enabled Tableflow on {table_name!r}: phase={topic.phase}")
64
+ assert topic.phase is TableflowPhase.RUNNING
65
+ # Read-only, server-assigned storage fields live on the raw spec, not the GcsStorage input.
66
+ print(f"table_path: {topic.spec.raw['storage'].get('table_path')}")
67
+ # The read side parses back into the same typed class, with the server-assigned read-only
68
+ # fields dropped -- so it compares equal to the GcsStorage we sent.
69
+ assert isinstance(topic.spec.storage, GcsStorage)
70
+ assert topic.spec.storage == gcs
71
+
72
+ # Add DELTA alongside the existing ICEBERG, in place -- no disable/re-enable cycle. Passing
73
+ # only table_formats leaves config untouched; storage is immutable and has no update path.
74
+ topic = conn.update_tableflow(
75
+ table_name,
76
+ table_formats={TableFormat.ICEBERG, TableFormat.DELTA},
77
+ )
78
+ print(f"updated formats: {topic.spec.table_formats}")
79
+
80
+ # Bump retention without touching the format set. Each of config's own sub-fields is
81
+ # independently "leave unchanged" when None, so this only rewrites retention_ms.
82
+ conn.update_tableflow(
83
+ table_name,
84
+ config=TableflowTopicConfig(retention_ms=2_592_000_000), # 30 days
85
+ )
86
+
87
+ # A non-blocking enable would look like this (shown, not run, since it's already enabled):
88
+ # conn.enable_tableflow(
89
+ # other_table,
90
+ # table_formats=TableFormat.ICEBERG,
91
+ # storage=gcs,
92
+ # wait_for_running=False, # returns immediately with the topic in PENDING
93
+ # )
94
+
95
+ conn.disable_tableflow(table_name)
96
+ print(f"disabled Tableflow on {table_name!r}")
97
+ finally:
98
+ conn.close()
@@ -32,7 +32,7 @@ try:
32
32
  # OperationalError if it goes FAILED instead.
33
33
  topic = conn.enable_tableflow(
34
34
  table_name,
35
- tableflow_formats=TableFormat.ICEBERG,
35
+ table_formats=TableFormat.ICEBERG,
36
36
  storage=ManagedStorage(),
37
37
  )
38
38
  print(f"enabled Tableflow on {table_name!r}: phase={topic.phase}")
@@ -2,9 +2,12 @@
2
2
  requires = ["hatchling"]
3
3
  build-backend = "hatchling.build"
4
4
 
5
+ [tool.hatch.version]
6
+ path = "src/confluent_sql/__version__.py"
7
+
5
8
  [project]
6
9
  name = "confluent-sql"
7
- version = "0.5.5"
10
+ dynamic = ["version"]
8
11
  description = "DB-API v2 compliant driver for Confluent Cloud Flink SQL"
9
12
  readme = "README.md"
10
13
  requires-python = ">=3.10"
@@ -35,6 +38,7 @@ Changelog = "https://github.com/confluentinc/confluent-sql/blob/main/CHANGELOG.m
35
38
 
36
39
  [tool.ruff]
37
40
  line-length = 100
41
+ include = ["src/**/*.py", "tests/**/*.py", "examples/**/*.py"]
38
42
  lint.ignore = [
39
43
  "PLR2004", # stop complaining about inlined constants, mostly in test cases
40
44
  ]
@@ -5,6 +5,7 @@ This module provides a DB-API v2 compliant interface for connecting to and
5
5
  executing SQL queries against Confluent SQL services.
6
6
  """
7
7
 
8
+ from .__version__ import __version__
8
9
  from .changelog_compressor import ChangelogCompressor
9
10
  from .connection import Connection, connect
10
11
  from .connectors import (
@@ -38,7 +39,7 @@ from .exceptions import (
38
39
  )
39
40
  from .execution_mode import ExecutionMode
40
41
  from .result_readers import ChangeloggedRow
41
- from .statement import HIDDEN_LABEL, Op
42
+ from .statement import HIDDEN_LABEL, Op, StatementWarning, WarningSeverity
42
43
  from .statement_properties import (
43
44
  Property,
44
45
  PropertyValue,
@@ -50,17 +51,22 @@ from .statement_properties import (
50
51
  from .tableflow import (
51
52
  AzureAdlsStorage,
52
53
  ByobAwsStorage,
54
+ GcsStorage,
53
55
  ManagedStorage,
54
56
  TableflowErrorHandling,
55
57
  TableflowErrorHandlingLog,
56
58
  TableflowErrorHandlingSkip,
57
59
  TableflowErrorHandlingSuspend,
60
+ TableflowErrorHandlingUnknown,
58
61
  TableflowPhase,
62
+ TableflowStorageUnknown,
59
63
  TableflowTopic,
60
64
  TableflowTopicConfig,
65
+ TableflowTopicSpec,
61
66
  TableFormat,
62
67
  )
63
68
  from .types import PropertiesDict, PropertiesMapping, SqlNone, YearMonthInterval
69
+ from .variant import UndecodableVariant
64
70
 
65
71
  # DB-API v2 module globals
66
72
  apilevel = "2.0"
@@ -68,6 +74,7 @@ threadsafety = 1 # Threads may share the module but not connections
68
74
  paramstyle = "pyformat" # Use question mark style parameters
69
75
 
70
76
  __all__ = [
77
+ "__version__",
71
78
  "connect",
72
79
  "Connection",
73
80
  "Cursor",
@@ -103,13 +110,17 @@ __all__ = [
103
110
  "TableflowPhase",
104
111
  "TableflowTopic",
105
112
  "TableflowTopicConfig",
113
+ "TableflowTopicSpec",
106
114
  "ManagedStorage",
107
115
  "ByobAwsStorage",
108
116
  "AzureAdlsStorage",
117
+ "GcsStorage",
118
+ "TableflowStorageUnknown",
109
119
  "TableflowErrorHandling",
110
120
  "TableflowErrorHandlingSuspend",
111
121
  "TableflowErrorHandlingSkip",
112
122
  "TableflowErrorHandlingLog",
123
+ "TableflowErrorHandlingUnknown",
113
124
  "apilevel",
114
125
  "threadsafety",
115
126
  "paramstyle",
@@ -123,5 +134,8 @@ __all__ = [
123
134
  "StatementProperties",
124
135
  "SqlNone",
125
136
  "YearMonthInterval",
137
+ "UndecodableVariant",
126
138
  "HIDDEN_LABEL",
139
+ "StatementWarning",
140
+ "WarningSeverity",
127
141
  ]
@@ -0,0 +1,3 @@
1
+ """Version information for the confluent_sql package."""
2
+
3
+ __version__ = "0.6.0"