confluent-sql 0.3.0__tar.gz → 0.4.0__tar.gz

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/.semaphore/publish_to_pypi.yml

@@ -10,7 +10,7 @@ global_job_config:
       - checkout
       - . vault-setup
       - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
-      - uv sync
+      - uv sync --frozen
 
 blocks:
   - name: Publish `confluent_sql` to PyPi

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/.semaphore/semaphore.yml

@@ -21,7 +21,7 @@ global_job_config:
       - checkout
       - . vault-setup
       - curl -LsSf https://astral.sh/uv/0.10.11/install.sh | sh
-      - uv sync
+      - uv sync --frozen
       - export VERSION=$(grep '^version' pyproject.toml | cut -d'"' -f2)
 
 blocks:
@@ -31,19 +31,17 @@ blocks:
       jobs:
         - name: "Lint, Type Check, and Test"
           commands:
-            - uv run ruff check && uv run pyright && uv run pytest -m unit --junitxml=test-results.xml
+            - uv run --frozen ruff check && uv run --frozen pyright && uv run --frozen pytest -m unit --junitxml=test-results.xml
       epilogue:
         always:
           commands:
             - "[[ -f test-results.xml ]] && test-results publish test-results.xml"
 
 promotions:
-  - name: Publish confluent-sql to codeartifact
-    pipeline_file: publish_to_codeartifact.yml
-    auto_promote:
-        when: "result = 'passed' and tag =~ '^v\\.'"
   - name: Publish confluent-sql to PyPi
     pipeline_file: publish_to_pypi.yml
+    auto_promote:
+      when: "result = 'passed' and tag =~ '^v\\.'"
 
 after_pipeline:
   task:

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/ARCHITECTURE.md

@@ -109,28 +109,29 @@ print(statement.name)  # "create-summary-table"
 
 **Name Uniqueness:**
 
-Statement names **must be unique within the compute pool** they are submitted to. If you attempt to submit a statement with a name that already exists in the same compute pool, the server will reject it with an error. This means:
+Statement names **must be unique within the environment** they are submitted to. If you attempt to submit a statement with a name that already exists anywhere in the same environment—even from a connection on a different compute pool—the server will reject it with an error. This means:
 
-- Auto-generated names are guaranteed unique per compute pool
-- If using explicit names, you must ensure they don't conflict with existing statements
+- Auto-generated names are guaranteed unique within the environment
+- If using explicit names, you must ensure they don't conflict with any existing statement in the environment
 - After deleting a statement, its name becomes available for reuse
-- Names are scoped to the compute pool, not globally—different compute pools can have statements with the same name
+- Names are scoped to the environment, not to a compute pool—a name in use anywhere in the environment cannot be reused from another compute pool
 
 ```python
-# This will work: same name in different compute pools
+# This will fail: the name is already in use elsewhere in the environment,
+# even though the second connection targets a different compute pool.
 pool_a_cursor = connection_pool_a.cursor()
 pool_a_cursor.execute(
     "SELECT * FROM data",
-    statement_name="my-query"  # OK in pool A
+    statement_name="my-query"  # OK: first use of this name in the environment
 )
 
 pool_b_cursor = connection_pool_b.cursor()
 pool_b_cursor.execute(
     "SELECT * FROM data",
-    statement_name="my-query"  # OK in pool B (different pool)
+    statement_name="my-query"  # ❌ Error: name already exists in the environment
 )
 
-# This will fail: same name in the same compute pool
+# This also fails for the same reason, within a single compute pool:
 cursor1 = connection.cursor()
 cursor1.execute("SELECT * FROM table1", statement_name="my-query")
 
@@ -167,7 +168,7 @@ Labels allow you to organize statements logically without requiring unique names
 
 ### Statement Persistence and Recovery
 
-Statements persist on the server independently of your client connection, but are **scoped to the compute pool** where they were submitted. Statements can only be found, monitored, and recovered within the same compute pool:
+Statements persist on the server independently of your client connection, and are **scoped to the environment** (organization + environment) they were submitted to—not to the compute pool or the submitting connection. Any connection to the same environment can find, monitor, and recover them, regardless of which compute pool ran them (narrow to a single pool with the `compute_pool_id` filter on `list_statements()` when you want pool-level isolation):
 
 1. **Create a statement with a name** for recovery:
 
@@ -180,9 +181,9 @@ Statements persist on the server independently of your client connection, but ar
    )
    ```
 
-2. **Recover it from another connection in the same compute pool:**
+2. **Recover it from another connection in the same environment:**
    ```python
-   # In a different Python process or session (same compute pool)
+   # In a different Python process or session (same environment)
    statements = connection.list_statements(label="daily-jobs")
    for stmt in statements:
        if stmt.name == "daily-summary-job":
@@ -292,7 +293,7 @@ This simplifies your code by eliminating manual polling loops, but your applicat
 
 ### Finding Existing Statements
 
-List statements by label (useful for batch operations):
+List statements—optionally filtered by label, compute pool, and/or name substring (useful for batch operations):
 
 ```python
 # Find all statements with a specific label

confluent_sql-0.4.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Change Log
+
+All notable changes to this dbapi driver will be documented in this file.
+
+## 0.4.0, 2026-06-15
+
+### Added
+
+- Support for "Global" Confluent Cloud API keys: `confluent_sql.connect()` (and `Connection`) now accept `global_api_key` / `global_api_secret`. A Global key works against every route this driver touches, so it is preferred over a Flink Region key when both are supplied. `flink_api_key` / `flink_api_secret` remain supported and are now optional; at least one fully-specified pair must be provided. If both pairs are supplied, the Global pair is used (and the Flink pair ignored, with a warning); a half-specified pair (key without secret, or vice versa) is rejected. (#112)
+- Support for "poolless Flink": `confluent_sql.connect()` now treats `compute_pool_id` as optional. Statements submitted w/o their own overriding `compute_pool_id` via a connection w/o a default compute pool id will make use of the default compute pool in the environment+cloud region (provisioning one if necessary). See [the Confluent documentation](https://docs.confluent.io/cloud/current/flink/concepts/compute-pools.html#default-compute-pools) for more details.
+- New `Connection.stop_statement(statement, *, wait_for_stopped=True, timeout=300)` method to stop a running statement without deleting it, leaving the statement resource around for inspection (unlike `delete_statement()`, which also destroys it). Accepts a statement name or a `Statement` object. By default it blocks until the statement reaches `STOPPED`; pass `wait_for_stopped=False` to return as soon as the stop is accepted. A matching `Cursor.stop_statement()` stops the cursor's current statement. New `Statement.is_stopped`, `Statement.is_stopping`, and `Statement.stop_requested` properties expose the relevant state. (#61)
+
+### Changed
+
+- `Connection.list_statements()`:
+  - New optional parameter `compute_pool_id` to list statements only in a single compute pool (otherwise environment-wide).
+  - New optional parameter `name_contains: str` to filter statements server-side to those whose name contains the given substring (case-sensitive).
+  - Existing parameter `label` is now optional.
+  - The end result is that callers can now provide between zero and all of the possible kwargs to vary between 'no filtering at all, return all current statements in the environment' and 'apply all the possible filters as if ANDed together.'
+
+## 0.3.1, 2026-05-21
+
+### Added
+
+- New `http_timeout_secs` parameter for `connect()` to let the caller control how long to wait in HTTP requests.
+
+## 0.3.0, 2026-04-09
+
+### Changed - Breaking
+
+- `connect()` / `Connection.__init__()`: Renamed `environment` parameter to `environment_id` to clarify that an environment ID (_not_ name) is expected. The internal attribute `Connection.environment` has also been renamed to `Connection.environment_id`. Update all calls from `connect(environment="env-123")` to `connect(environment_id="env-123")`. (#92)
+- `Cursor.execute()` and peers: Respelled and re-typed the `statement_label: str | None` parameter to be `statement_labels: list[str] | None` to allow multiple labels to be applied to a statement, including `HIDDEN_LABEL`.
+
+### Added
+
+- New `Connection.get_statement(statement)` method to retrieve statement metadata by name or refresh a Statement object with the latest server state. Accepts either a statement name (string) or a Statement object. Returns a Statement object with current phase, schema, and execution traits. (#86)
+- New `StatementNotFoundError` exception, a subclass of `OperationalError`, raised by `Connection.get_statement(statement)` when attempting to retrieve a statement that does not exist. Provides programmatic access to the statement name via the `statement_name` attribute.
+- New constant `confluent_sql.HIDDEN_LABEL` used for driving `Cursor.execute()` to indicate that the statement should be hidden in default listings in Confluent Cloud UIs. This feature is intended to be used for minor queries, such as when investigating `INFORMATION_SCHEMA`.
+- Added documentation regarding use of `connect(endpoint=)` parameter to make use of private networking endpoints (README.md, docstrings).
+
+## 0.2.0, 2026-03-26
+
+### Changed
+
+- Respelled the `connect()` parameter `dbname` to `database`. The old spelling `dbname` is deprecated and will be removed in after one release cycle.
+- Class `SqlNone` now gracefully strips trailing `NOT NULL` constraints from type names (case-insensitively), so that `str(SqlNone("DATE NOT NULL"))` returns valid FlinkSQL `"cast (null as DATE)"`.
+- `connect()` is now keyword-only callable.
+- The `host` parameter for `Connection.__init__()` has been renamed to `endpoint`.
+- Clarified and improved documentation around Flink region API key use.
+
+### Added
+
+- New optional keyword parameter `properties: PropertiesDict | None` on `Cursor.execute()` and related methods to allow callers to provide [statement execution properties](https://docs.confluent.io/cloud/current/flink/reference/statements/set.html#table-options). Note: connection or cursor-level properties for default catalog, database, and execution mode cannot be overridden by this parameter.
+- New optional `endpoint` parameter on `connect()` and `Connection.__init__` to allow users to specify a custom Confluent Cloud API base endpoint (e.g., for private networking, staging, etc.). Mutually exclusive with (`cloud_provider`, `cloud_region`) -- either `endpoint` or (`cloud_provider`, `cloud_region`) must be provided. This replaces the `host` parameter in `Connection.__init__()`. (#66)
+
+### Removed
+
+- The unused control-plane `api_key` and `api_secret` `connect()` parameters have been removed. The Flink Region API key params `flink_api_key` and `flink_api_secret` remain.
+
+## 0.1.x
+
+Early access release of the driver.

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/DBAPI_EXTENSIONS.md

@@ -35,7 +35,7 @@ For comprehensive details on streaming queries, polling patterns, and changelog
 
 - [Result Format Extensions](#result-format-extensions) - Dictionary rows, custom types
 - [Streaming Query Support](#streaming-query-support) - Comprehensive streaming guide
-- [Statement Lifecycle Management](#statement-lifecycle-management) - DDL, naming, deletion
+- [Statement Lifecycle Management](#statement-lifecycle-management) - DDL, naming, stopping, deletion
 - [Introspection and Metadata](#introspection-and-metadata) - Properties for query state
 - [Performance Monitoring](#performance-monitoring) - Fetch metrics
 - [Type System Extensions](#type-system-extensions) - Flink type support
@@ -455,11 +455,23 @@ for stmt in statements:
 
 ### Finding and Deleting Statements
 
-**`list_statements()` - Find statements by label**
+**`list_statements()` - Find statements, optionally filtered**
+
+Called with no arguments, returns every statement in the environment. Three optional,
+server-side filters narrow the results and combine with AND semantics:
+
+- `label` — statements carrying the given end-user label.
+- `compute_pool_id` — statements in a specific compute pool.
+- `name_contains` — statements whose name contains the given substring (case-sensitive).
 
 ```python
-# Find all statements with a specific label
+# Every statement in the environment
+statements = connection.list_statements()
+
+# Narrow by label, compute pool, and/or name substring (filters AND together)
 statements = connection.list_statements(label="daily-backups", page_size=100)
+statements = connection.list_statements(compute_pool_id="lfcp-789012")
+statements = connection.list_statements(name_contains="orders-stream")
 
 for statement in statements:
     print(f"Statement: {statement.name}")
@@ -494,6 +506,47 @@ except OperationalError as e:
     print(f"Other error: {e}")
 ```
 
+**`stop_statement()` - Halt a statement without deleting it**
+
+Stops a running statement (for example, a long-lived streaming query) while keeping the
+statement resource around for inspection — unlike `delete_statement()`, which stops *and*
+destroys the statement and its results. The stop is issued as a JSON Patch flipping
+`spec.stopped` to `true`; the statement then transitions through `STOPPING` to the terminal
+`STOPPED` phase.
+
+```python
+# Stop from connection (by name or Statement object), blocking until STOPPED (the default)
+stopped = connection.stop_statement("active-users-query")
+print(stopped.is_stopped)  # True
+
+# Non-blocking: return as soon as the stop is accepted
+stmt = connection.stop_statement(statement_obj, wait_for_stopped=False)
+print(stmt.stop_requested)  # True (the stop was accepted)
+# Note: stmt.phase may still be RUNNING at this instant -- the server transitions the phase
+# to STOPPED asynchronously. Poll get_statement() if you need to observe STOPPED:
+while not connection.get_statement(stmt).is_stopped:
+    time.sleep(0.5)
+
+# Bound the blocking wait (seconds); raises OperationalError on timeout
+stopped = connection.stop_statement("active-users-query", timeout=60)
+
+# Stop from cursor (current statement); updates the cursor's tracked statement
+stopped = cursor.stop_statement()
+```
+
+**Behavior notes:**
+
+- Accepts a statement name (string) or a `Statement` object. A `Statement` already in a terminal
+  phase (`STOPPED`/`COMPLETED`/`FAILED`/`DELETED`) is returned unchanged without an API call.
+- `wait_for_stopped=True` (default) blocks until the statement reaches a terminal phase —
+  normally `STOPPED`, but `COMPLETED` if a bounded query finished before the stop landed — so the
+  caller knows the statement is no longer running. `wait_for_stopped=False` returns once the stop
+  is accepted — confirm acceptance via `Statement.stop_requested` rather than the phase.
+- Raises `StatementNotFoundError` if the statement does not exist, or `OperationalError` on other
+  API errors, on timeout, or if the statement transitions to `FAILED` while stopping.
+- `cursor.stop_statement()` raises `InterfaceError` when the cursor has no executed statement to
+  stop (it is not a silent no-op like `cursor.delete_statement()`).
+
 **`delete_statement()` - Stop and remove a statement**
 
 ```python

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluent-sql
-Version: 0.3.0
+Version: 0.4.0
 Summary: DB-API v2 compliant driver for Confluent Cloud Flink SQL
 Project-URL: Repository, https://github.com/confluentinc/confluent-sql
 Project-URL: Documentation, https://github.com/confluentinc/confluent-sql?tab=readme-ov-file#confluent-sql
@@ -250,13 +250,16 @@ The behavior of snapshot-mode cursors, complying with dbapi semantics, are well
 ## Prerequisites
 
 - **Confluent Cloud account** with Flink environment
-- **Active Flink compute pool** (must be pre-created)
 - **Existing Flink Database** (Confluent Cloud Kafka cluster)
-- **Flink Region API credentials** for Flink SQL Region API access: a user or service account Flink region API key and secret.
+- **API credentials**, one of:
+  - a **"Global" Confluent Cloud API key** and secret, passed as `global_api_key` / `global_api_secret`, or
+  - a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`.
+
+  A Global key works against every route this driver touches, so it is the more future-proof choice; a Flink Region key works against the Flink SQL routes that are the driver's focus today. Provide at least one pair. If you supply both, the Global pair is used and the Flink pair is ignored. A half-supplied pair (a key without its secret, or vice versa) is rejected.
 
 ### How to Obtain a Flink Region API Key
 
-This driver requires a **Flink Region API key** (also called a Flink SQL API key), which is specific to your Flink compute pool and provides access to the regional Flink SQL API endpoints. This is distinct from a Confluent Cloud control-plane API key.
+A **Flink Region API key** (also called a Flink SQL API key) is specific to your Flink region/environment (the environment + cloud provider + cloud region triplet) and provides access to the regional Flink SQL API endpoints. This is distinct from a Confluent Cloud control-plane API key. (A "Global" Confluent Cloud API key is the alternative — see above — and is created the same way but without scoping to a single Flink region.)
 
 To create or find a Flink Region API key:
 
@@ -266,12 +269,13 @@ To create or find a Flink Region API key:
 4. When creating a new key, select either:
    - **My account** - for development/testing
    - **Service account** - for production applications (recommended)
-   and then:   
+     and then:
    - **The Environment, Cloud Provider and Cloud Region** matching the Flink database(s) / Kafka cluster(s) you intend to use this driver against.
 5. Save both the **API key** and **API secret** securely (the secret cannot be retrieved later)
 6. Use these credentials as the `flink_api_key` and `flink_api_secret` parameters in the `connect()` function
 
 API keys may also be generated using the Confluent CLI or by API access, outside the scope of this document.
+
 ## Installation
 
 ```bash
@@ -295,10 +299,10 @@ connection = confluent_sql.connect(
     environment_id="env-123456",
     cloud_provider="aws",
     cloud_region="us-east-2",
-    flink_api_key="your-flink-api-key",
-    flink_api_secret="your-flink-api-secret",
+    flink_api_key="your-flink-api-key",  # or global_api_key=... for a "Global" Confluent Cloud key
+    flink_api_secret="your-flink-api-secret",  # or global_api_secret=...
     database="your-database-name",
-    compute_pool_id="lfcp-789012"
+    compute_pool_id="lfcp-789012"  # optional; omit to use the environment's default compute pool
 )
 ```
 
@@ -398,15 +402,15 @@ For detailed streaming query guidance, see **[STREAMING.md](https://github.com/c
 
 For type support and examples, see **[TYPES.md](https://github.com/confluentinc/confluent-sql/blob/main/TYPES.md)**.
 
-
 ## Private Networking Considerations
 
 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
 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.
 
 Symptoms of using the public endpoint when private networking is required include:
-  * HTTP 429-related exceptions raised when submitting statements querying tables whose backing Kafka topics / clusters are configured for private networking only.
-  * Empty or surprisingly missing results when querying `INFORMATION_SCHEMA` or `SHOW TABLES`, due to silent filtering of private-networking-only tables/topics when querying the system catalog.
+
+- HTTP 429-related exceptions raised when submitting statements querying tables whose backing Kafka topics / clusters are configured for private networking only.
+- Empty or surprisingly missing results when querying `INFORMATION_SCHEMA` or `SHOW TABLES`, due to silent filtering of private-networking-only tables/topics when querying the system catalog.
 
 ## Development
 
@@ -439,8 +443,10 @@ export CONFLUENT_CLOUD_PROVIDER="aws"
 export CONFLUENT_CLOUD_REGION="us-east-2"
 export CONFLUENT_FLINK_API_KEY="your-key" # Flink Region API key for the above cloud/region ...
 export CONFLUENT_FLINK_API_SECRET="your-secret" # and associated secret.
-export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012" # A compute pool within the above cloud/region.
+# Alternatively, a "Global" Confluent Cloud API key (used in preference to the Flink pair if both
+# are set): export CONFLUENT_GLOBAL_API_KEY / CONFLUENT_GLOBAL_API_SECRET instead.
 export CONFLUENT_TEST_DBNAME="test-db" # A database/kafka cluster name within the above cloud/region.
+export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012" # Optional. If set, the integration suite runs against this pool; if unset, the suite runs against the environment's default pool. The driver treats it as optional at connect() either way.
 ```
 
 Run tests:

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/README.md

@@ -19,13 +19,16 @@ The behavior of snapshot-mode cursors, complying with dbapi semantics, are well
 ## Prerequisites
 
 - **Confluent Cloud account** with Flink environment
-- **Active Flink compute pool** (must be pre-created)
 - **Existing Flink Database** (Confluent Cloud Kafka cluster)
-- **Flink Region API credentials** for Flink SQL Region API access: a user or service account Flink region API key and secret.
+- **API credentials**, one of:
+  - a **"Global" Confluent Cloud API key** and secret, passed as `global_api_key` / `global_api_secret`, or
+  - a **Flink Region API key** and secret, passed as `flink_api_key` / `flink_api_secret`.
+
+  A Global key works against every route this driver touches, so it is the more future-proof choice; a Flink Region key works against the Flink SQL routes that are the driver's focus today. Provide at least one pair. If you supply both, the Global pair is used and the Flink pair is ignored. A half-supplied pair (a key without its secret, or vice versa) is rejected.
 
 ### How to Obtain a Flink Region API Key
 
-This driver requires a **Flink Region API key** (also called a Flink SQL API key), which is specific to your Flink compute pool and provides access to the regional Flink SQL API endpoints. This is distinct from a Confluent Cloud control-plane API key.
+A **Flink Region API key** (also called a Flink SQL API key) is specific to your Flink region/environment (the environment + cloud provider + cloud region triplet) and provides access to the regional Flink SQL API endpoints. This is distinct from a Confluent Cloud control-plane API key. (A "Global" Confluent Cloud API key is the alternative — see above — and is created the same way but without scoping to a single Flink region.)
 
 To create or find a Flink Region API key:
 
@@ -35,12 +38,13 @@ To create or find a Flink Region API key:
 4. When creating a new key, select either:
    - **My account** - for development/testing
    - **Service account** - for production applications (recommended)
-   and then:   
+     and then:
    - **The Environment, Cloud Provider and Cloud Region** matching the Flink database(s) / Kafka cluster(s) you intend to use this driver against.
 5. Save both the **API key** and **API secret** securely (the secret cannot be retrieved later)
 6. Use these credentials as the `flink_api_key` and `flink_api_secret` parameters in the `connect()` function
 
 API keys may also be generated using the Confluent CLI or by API access, outside the scope of this document.
+
 ## Installation
 
 ```bash
@@ -64,10 +68,10 @@ connection = confluent_sql.connect(
     environment_id="env-123456",
     cloud_provider="aws",
     cloud_region="us-east-2",
-    flink_api_key="your-flink-api-key",
-    flink_api_secret="your-flink-api-secret",
+    flink_api_key="your-flink-api-key",  # or global_api_key=... for a "Global" Confluent Cloud key
+    flink_api_secret="your-flink-api-secret",  # or global_api_secret=...
     database="your-database-name",
-    compute_pool_id="lfcp-789012"
+    compute_pool_id="lfcp-789012"  # optional; omit to use the environment's default compute pool
 )
 ```
 
@@ -167,15 +171,15 @@ For detailed streaming query guidance, see **[STREAMING.md](https://github.com/c
 
 For type support and examples, see **[TYPES.md](https://github.com/confluentinc/confluent-sql/blob/main/TYPES.md)**.
 
-
 ## Private Networking Considerations
 
 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
 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.
 
 Symptoms of using the public endpoint when private networking is required include:
-  * HTTP 429-related exceptions raised when submitting statements querying tables whose backing Kafka topics / clusters are configured for private networking only.
-  * Empty or surprisingly missing results when querying `INFORMATION_SCHEMA` or `SHOW TABLES`, due to silent filtering of private-networking-only tables/topics when querying the system catalog.
+
+- HTTP 429-related exceptions raised when submitting statements querying tables whose backing Kafka topics / clusters are configured for private networking only.
+- Empty or surprisingly missing results when querying `INFORMATION_SCHEMA` or `SHOW TABLES`, due to silent filtering of private-networking-only tables/topics when querying the system catalog.
 
 ## Development
 
@@ -208,8 +212,10 @@ export CONFLUENT_CLOUD_PROVIDER="aws"
 export CONFLUENT_CLOUD_REGION="us-east-2"
 export CONFLUENT_FLINK_API_KEY="your-key" # Flink Region API key for the above cloud/region ...
 export CONFLUENT_FLINK_API_SECRET="your-secret" # and associated secret.
-export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012" # A compute pool within the above cloud/region.
+# Alternatively, a "Global" Confluent Cloud API key (used in preference to the Flink pair if both
+# are set): export CONFLUENT_GLOBAL_API_KEY / CONFLUENT_GLOBAL_API_SECRET instead.
 export CONFLUENT_TEST_DBNAME="test-db" # A database/kafka cluster name within the above cloud/region.
+export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012" # Optional. If set, the integration suite runs against this pool; if unset, the suite runs against the environment's default pool. The driver treats it as optional at connect() either way.
 ```
 
 Run tests:

{confluent_sql-0.3.0 → confluent_sql-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "confluent-sql"
-version = "0.3.0"
+version = "0.4.0"
 description = "DB-API v2 compliant driver for Confluent Cloud Flink SQL"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -85,7 +85,7 @@ dev = ["pytest", "pytest-cov"]
 
 [dependency-groups]
 dev = [
-    "pyright>=1.1.407",
+    "pyright>=1.1.410",
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "pytest-mock>=3.15.1",