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

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

@@ -143,20 +143,20 @@ cursor2.execute("SELECT * FROM table2", statement_name="my-query")  # ❌ Error:
 In addition to individual statement names, you can use statement labels to group related statements together for batch operations:
 
 ```python
-# Group multiple statements with a label
+# Group multiple statements with labels
 cursor1 = connection.cursor()
 cursor1.execute(
     "SELECT COUNT(*) FROM events",
-    statement_label="hourly-metrics"
+    statement_labels=["hourly-metrics", "analytics"]
 )
 
 cursor2 = connection.cursor()
 cursor2.execute(
     "SELECT * FROM users",
-    statement_label="hourly-metrics"
+    statement_labels=["hourly-metrics", "analytics"]
 )
 
-# Later, find all statements with that label to then delete
+# Later, find all statements with any of the labels to then delete
 statements = connection.list_statements(label="hourly-metrics")
 for stmt in statements:
     print(f"{stmt.name}: {stmt.phase}")
@@ -175,8 +175,8 @@ Statements persist on the server independently of your client connection, but ar
    statement = connection.execute_snapshot_ddl(
        "CREATE TABLE daily_summary AS SELECT * FROM events WHERE date > %s",
        (start_date,),
-       statement_name="daily-summary-job"
-       statement_label="daily-jobs"
+       statement_name="daily-summary-job",
+       statement_labels=["daily-jobs", "etl"]
    )
    ```
 

confluent_sql-0.3.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Change Log
+
+All notable changes to this dbapi driver will be documented in this file.
+
+## 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.2.0 → confluent_sql-0.3.0}/DBAPI_EXTENSIONS.md

@@ -386,7 +386,7 @@ Use for statements that produce unbounded/continuous results:
 Both `execute_snapshot_ddl()` and `execute_streaming_ddl()` also accept these parameters for controlling statement identity and lifecycle:
 
 - `statement_name` (str | None): Custom statement identifier (defaults to auto-generated UUID)
-- `statement_label` (str | None): Label for grouping related statements
+- `statement_labels` (list[str] | None): List of labels for grouping related statements
 
 Example with statement naming and labeling:
 
@@ -394,10 +394,10 @@ Example with statement naming and labeling:
 statement = connection.execute_streaming_ddl(
     "CREATE TABLE orders_stream AS SELECT * FROM kafka_orders",
     statement_name="orders-stream-job",
-    statement_label="data-pipelines"
+    statement_labels=["data-pipelines", "streaming"]
 )
 
-# Later, find all statements with this label
+# Later, find all statements with any of the labels
 statements = connection.list_statements(label="data-pipelines")
 ```
 
@@ -424,13 +424,21 @@ connection.delete_statement("active-users-query")
 **Statement Labels** - Group related statements for batch operations
 
 ```python
-# Execute multiple statements with same label
+from confluent_sql import HIDDEN_LABEL
+
+# Execute multiple statements with labels
 for source in ["kafka_topic_a", "kafka_topic_b", "kafka_topic_c"]:
     cursor.execute(
         f"CREATE TABLE {source}_backup AS SELECT * FROM {source}",
-        statement_label="daily-backups"
+        statement_labels=["daily-backups", "batch-job"]
     )
 
+# Mark a background job as hidden
+cursor.execute(
+    "SELECT * FROM `INFORMATION_SCHEMA`.`TABLES`",
+    statement_labels=[HIDDEN_LABEL]
+)
+
 # Later, list and delete all backups
 statements = connection.list_statements(label="daily-backups")
 for stmt in statements:
@@ -459,6 +467,33 @@ for statement in statements:
     print(f"Created: {statement.created_at}")
 ```
 
+**`get_statement()` - Retrieve statement by exact name**
+
+```python
+# Get statement by name
+stmt = connection.get_statement("my-statement-name")
+print(f"Status: {stmt.phase}")  # PENDING, RUNNING, COMPLETED, FAILED, etc.
+
+# Check if results are ready
+if stmt.can_fetch_results(ExecutionMode.SNAPSHOT):
+    # Results are available
+    ...
+
+# Refresh a Statement object with latest server state
+stmt = cursor.statement
+time.sleep(5)
+stmt = connection.get_statement(stmt)  # Fetch updated state
+print(f"Updated phase: {stmt.phase}")
+
+# Raises StatementNotFoundError if statement not found
+try:
+    stmt = connection.get_statement("non-existent-statement")
+except StatementNotFoundError as e:
+    print(f"Statement '{e.statement_name}' does not exist")
+except OperationalError as e:
+    print(f"Other error: {e}")
+```
+
 **`delete_statement()` - Stop and remove a statement**
 
 ```python
@@ -807,21 +842,21 @@ cursor.execute(
     *,
     timeout: int = 3000,
     statement_name: str | None = None,
-    statement_label: str | None = None,
+    statement_labels: list[str] | None = None,
     properties: dict[str, str | int | bool] | None = None,
 ) -> None
 ```
 
 ### Parameter Reference
 
-| Parameter         | Type                              | Default    | Description                                                        |
-| ----------------- | --------------------------------- | ---------- | ------------------------------------------------------------------ |
-| `statement_text`  | `str`                             | (required) | SQL statement to execute                                           |
-| `parameters`      | `tuple \| list \| None`           | None       | Parameter values for parameterized statements                      |
-| `timeout`         | `int`                             | 3000       | Max seconds to wait for statement to reach RUNNING/COMPLETED phase |
-| `statement_name`  | `str \| None`                     | None       | Custom statement identifier (defaults to UUID)                     |
-| `statement_label` | `str \| None`                     | None       | Label for grouping related statements                              |
-| `properties`      | `dict[str, str \| int \| bool] \| None` | None | [Statement properties](#statement-properties) to set for execution |
+| Parameter          | Type                              | Default    | Description                                                        |
+| ------------------ | --------------------------------- | ---------- | ------------------------------------------------------------------ |
+| `statement_text`   | `str`                             | (required) | SQL statement to execute                                           |
+| `parameters`       | `tuple \| list \| None`           | None       | Parameter values for parameterized statements                      |
+| `timeout`          | `int`                             | 3000       | Max seconds to wait for statement to reach RUNNING/COMPLETED phase |
+| `statement_name`   | `str \| None`                     | None       | Custom statement identifier (defaults to UUID)                     |
+| `statement_labels` | `list[str] \| None`               | None       | List of labels for grouping related statements                     |
+| `properties`       | `dict[str, str \| int \| bool] \| None` | None | [Statement properties](#statement-properties) to set for execution |
 
 ### Statement Properties
 
@@ -867,7 +902,7 @@ cursor.execute(
 # With statement labeling (for batch operations)
 cursor.execute(
     "CREATE TABLE orders_backup AS SELECT * FROM orders",
-    statement_label="daily-backups"
+    statement_labels=["daily-backups", "batch-job"]
 )
 
 # All together
@@ -876,7 +911,7 @@ cursor.execute(
     (),
     timeout=3000,
     statement_name="product-sales-hourly",
-    statement_label="analytics"
+    statement_labels=["analytics", "hourly"]
 )
 
 # With statement properties

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluent-sql
-Version: 0.2.0
+Version: 0.3.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
@@ -251,8 +251,27 @@ The behavior of snapshot-mode cursors, complying with dbapi semantics, are well
 
 - **Confluent Cloud account** with Flink environment
 - **Active Flink compute pool** (must be pre-created)
-- **Flink Compute Pool API credentials** for Flink SQL API access: a user or service account API key and secret for the compute pool (used as HTTP Basic Auth, for example via `flink_api_key` and `flink_api_secret`).
+- **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.
 
+### 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.
+
+To create or find a Flink Region API key:
+
+1. Go to [https://confluent.cloud/settings/api-keys](https://confluent.cloud/settings/api-keys)
+2. Filter by resource **'Flink Region'**
+3. Find an existing key, or follow the **'+ Add API Key'** path to create a new one
+4. When creating a new key, select either:
+   - **My account** - for development/testing
+   - **Service account** - for production applications (recommended)
+   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
@@ -272,14 +291,14 @@ import confluent_sql
 
 # Connect to Confluent Cloud Flink SQL
 connection = confluent_sql.connect(
-    flink_api_key="your-flink-api-key",
-    flink_api_secret="your-flink-api-secret",
     organization_id="your-org-uuid",
-    environment="env-123456",
-    compute_pool_id="lfcp-789012",
+    environment_id="env-123456",
     cloud_provider="aws",
     cloud_region="us-east-2",
-    database="your-database-name"
+    flink_api_key="your-flink-api-key",
+    flink_api_secret="your-flink-api-secret",
+    database="your-database-name",
+    compute_pool_id="lfcp-789012"
 )
 ```
 
@@ -379,6 +398,16 @@ 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.
+
 ## Development
 
 ### Setup
@@ -404,14 +433,14 @@ Set required environment variables for integration tests.
 If any of the variables is not set, integration tests will be skipped.
 
 ```bash
-export CONFLUENT_FLINK_API_KEY="your-key"
-export CONFLUENT_FLINK_API_SECRET="your-secret"
-export CONFLUENT_ENV_ID="env-123456"
 export CONFLUENT_ORG_ID="org-123456"
-export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012"
+export CONFLUENT_ENV_ID="env-123456"
 export CONFLUENT_CLOUD_PROVIDER="aws"
 export CONFLUENT_CLOUD_REGION="us-east-2"
-export CONFLUENT_TEST_DBNAME="test-db"
+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.
+export CONFLUENT_TEST_DBNAME="test-db" # A database/kafka cluster name within the above cloud/region.
 ```
 
 Run tests:

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

@@ -20,8 +20,27 @@ The behavior of snapshot-mode cursors, complying with dbapi semantics, are well
 
 - **Confluent Cloud account** with Flink environment
 - **Active Flink compute pool** (must be pre-created)
-- **Flink Compute Pool API credentials** for Flink SQL API access: a user or service account API key and secret for the compute pool (used as HTTP Basic Auth, for example via `flink_api_key` and `flink_api_secret`).
+- **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.
 
+### 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.
+
+To create or find a Flink Region API key:
+
+1. Go to [https://confluent.cloud/settings/api-keys](https://confluent.cloud/settings/api-keys)
+2. Filter by resource **'Flink Region'**
+3. Find an existing key, or follow the **'+ Add API Key'** path to create a new one
+4. When creating a new key, select either:
+   - **My account** - for development/testing
+   - **Service account** - for production applications (recommended)
+   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
@@ -41,14 +60,14 @@ import confluent_sql
 
 # Connect to Confluent Cloud Flink SQL
 connection = confluent_sql.connect(
-    flink_api_key="your-flink-api-key",
-    flink_api_secret="your-flink-api-secret",
     organization_id="your-org-uuid",
-    environment="env-123456",
-    compute_pool_id="lfcp-789012",
+    environment_id="env-123456",
     cloud_provider="aws",
     cloud_region="us-east-2",
-    database="your-database-name"
+    flink_api_key="your-flink-api-key",
+    flink_api_secret="your-flink-api-secret",
+    database="your-database-name",
+    compute_pool_id="lfcp-789012"
 )
 ```
 
@@ -148,6 +167,16 @@ 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.
+
 ## Development
 
 ### Setup
@@ -173,14 +202,14 @@ Set required environment variables for integration tests.
 If any of the variables is not set, integration tests will be skipped.
 
 ```bash
-export CONFLUENT_FLINK_API_KEY="your-key"
-export CONFLUENT_FLINK_API_SECRET="your-secret"
-export CONFLUENT_ENV_ID="env-123456"
 export CONFLUENT_ORG_ID="org-123456"
-export CONFLUENT_COMPUTE_POOL_ID="lfcp-789012"
+export CONFLUENT_ENV_ID="env-123456"
 export CONFLUENT_CLOUD_PROVIDER="aws"
 export CONFLUENT_CLOUD_REGION="us-east-2"
-export CONFLUENT_TEST_DBNAME="test-db"
+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.
+export CONFLUENT_TEST_DBNAME="test-db" # A database/kafka cluster name within the above cloud/region.
 ```
 
 Run tests:

{confluent_sql-0.2.0 → confluent_sql-0.3.0}/STREAMING.md

@@ -740,7 +740,7 @@ with connection.closing_streaming_cursor(as_dict=True) as cursor:
 
 ```python
 cursor = connection.streaming_cursor()
-cursor.execute("SELECT * FROM stream WHERE active = %s", (True,), statement_label="my-streaming-job")
+cursor.execute("SELECT * FROM stream WHERE active = %s", (True,), statement_labels=["my-streaming-job"])
 
 # Query statement information
 print(f"Statement name: {cursor.statement.name}")

{confluent_sql-0.2.0 → confluent_sql-0.3.0}/examples/errors.py

@@ -15,7 +15,7 @@ if __name__ == "__main__":
     conn = confluent_sql.connect(
         flink_api_key=os.getenv("CONFLUENT_FLINK_API_KEY", ""),
         flink_api_secret=os.getenv("CONFLUENT_FLINK_API_SECRET", ""),
-        environment=os.getenv("CONFLUENT_ENV_ID", ""),
+        environment_id=os.getenv("CONFLUENT_ENV_ID", ""),
         organization_id=os.getenv("CONFLUENT_ORG_ID", ""),
         compute_pool_id=os.getenv("CONFLUENT_COMPUTE_POOL_ID", ""),
         cloud_provider=os.getenv("CONFLUENT_CLOUD_PROVIDER", "aws"),

{confluent_sql-0.2.0 → confluent_sql-0.3.0}/examples/simple_append_only_streaming_query_example.py

@@ -8,7 +8,7 @@ import confluent_sql
 conn = confluent_sql.connect(
     flink_api_key=os.getenv("CONFLUENT_FLINK_API_KEY", ""),
     flink_api_secret=os.getenv("CONFLUENT_FLINK_API_SECRET", ""),
-    environment=os.getenv("CONFLUENT_ENV_ID", ""),
+    environment_id=os.getenv("CONFLUENT_ENV_ID", ""),
     organization_id=os.getenv("CONFLUENT_ORG_ID", ""),
     compute_pool_id=os.getenv("CONFLUENT_COMPUTE_POOL_ID", ""),
     cloud_provider=os.getenv("CONFLUENT_CLOUD_PROVIDER", ""),

{confluent_sql-0.2.0 → confluent_sql-0.3.0}/examples/snapshot_mode_tuple_cursor_simple_example.py

@@ -7,7 +7,7 @@ import confluent_sql
 conn = confluent_sql.connect(
     flink_api_key=os.getenv("CONFLUENT_FLINK_API_KEY", ""),
     flink_api_secret=os.getenv("CONFLUENT_FLINK_API_SECRET", ""),
-    environment=os.getenv("CONFLUENT_ENV_ID", ""),
+    environment_id=os.getenv("CONFLUENT_ENV_ID", ""),
     organization_id=os.getenv("CONFLUENT_ORG_ID", ""),
     compute_pool_id=os.getenv("CONFLUENT_COMPUTE_POOL_ID", ""),
     cloud_provider=os.getenv("CONFLUENT_CLOUD_PROVIDER", ""),

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "confluent-sql"
-version = "0.2.0"
+version = "0.3.0"
 description = "DB-API v2 compliant driver for Confluent Cloud Flink SQL"
 readme = "README.md"
 requires-python = ">=3.10"

{confluent_sql-0.2.0 → confluent_sql-0.3.0}/src/confluent_sql/__init__.py

@@ -20,13 +20,14 @@ from .exceptions import (
     OperationalError,
     ProgrammingError,
     StatementDeletedError,
+    StatementNotFoundError,
     StatementStoppedError,
     TypeMismatchError,
     Warning,
 )
 from .execution_mode import ExecutionMode
 from .result_readers import ChangeloggedRow
-from .statement import Op
+from .statement import HIDDEN_LABEL, Op
 from .types import PropertiesDict, SqlNone, YearMonthInterval
 
 # DB-API v2 module globals
@@ -51,6 +52,7 @@ __all__ = [
     "ComputePoolExhaustedError",
     "StatementStoppedError",
     "StatementDeletedError",
+    "StatementNotFoundError",
     "IntegrityError",
     "InternalError",
     "ProgrammingError",
@@ -62,4 +64,5 @@ __all__ = [
     "PropertiesDict",
     "SqlNone",
     "YearMonthInterval",
+    "HIDDEN_LABEL",
 ]