From b109c768db61028930140fc2fa6595dd7568d292 Mon Sep 17 00:00:00 2001 From: eric-wang-1990 Date: Mon, 17 Aug 2026 19:16:27 -0700 Subject: [PATCH 1/3] docs: correct kernel proxy (SOCKS) and session-conf allowlist caveats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CONNECTION_PARAMETERS.md overstated two behaviors on the kernel path: - Session params: the blanket "passed through on both backends" claim is wrong for kernel, which matches conf keys against an allowlist (dropping non-allowlisted keys, hard-rejecting a few). Note the Thrift-vs-kernel difference and mark WithSessionParams inert (⚠️) on kernel. (PECOBLR-4153) - Proxy: the kernel path accepts http(s) proxies only; a socks* URL honored on Thrift is rejected at connect on kernel. (PECOBLR-4152) Co-authored-by: Isaac Signed-off-by: eric-wang-1990 --- CONNECTION_PARAMETERS.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index 2b13f8e4..28eb9696 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -25,7 +25,11 @@ sections of the README, laid out as one comparison matrix per concern. See [Building](./README.md#building). Any parameter not listed below (e.g. `ansi_mode`) is passed through as a -**session parameter** on both backends. +**session parameter**. On the **Thrift** path the session-conf map is forwarded freely. +On the **kernel** path conf keys are matched (case-insensitively) against an allowlist — +non-allowlisted keys are dropped with a warning, and a few are hard-rejected — so a conf +that takes effect on Thrift may silently be ignored on kernel. Broadening the kernel +allowlist is tracked in PECOBLR-4153. ## Endpoint & routing @@ -65,7 +69,7 @@ Notes for the SEA/kernel backend: | `maxRows` | `WithMaxRows` | ✅ | ⚠️ | `100000` | Max rows per fetch. On the kernel path the kernel manages paging, so this is accepted but has no effect. | | `timeout` | `WithTimeout` | ✅ | ❌ | no timeout | Server-side query timeout, in seconds. On the kernel path use the `STATEMENT_TIMEOUT` session parameter instead. | | `userAgentEntry` | `WithUserAgentEntry` | ✅ | ✅ | | Identifies your application (partners/ISVs), format ``. | -| *(session param)* | `WithSessionParams` | ✅ | ✅ | | Arbitrary session confs (e.g. `ansi_mode`, `STATEMENT_TIMEOUT`, `QUERY_TAGS`). | +| *(session param)* | `WithSessionParams` | ✅ | ⚠️ | | Arbitrary session confs (e.g. `ansi_mode`, `STATEMENT_TIMEOUT`, `QUERY_TAGS`). Allowlisted confs are honored on both; on kernel a non-allowlisted conf is dropped/rejected (see the note above; PECOBLR-4153). | | *(via session param)* | `WithQueryTags` | ✅ | ✅ | | Session-level query tags (serialized into `QUERY_TAGS`). | | `timezone` | `WithSessionParams(timezone=…)` | ✅ | ✅ | | Session time zone (e.g. `America/Los_Angeles`). | | `enableMetricViewMetadata` | `WithEnableMetricViewMetadata` | ✅ | ✅ | `false` | Enables metric-view metadata (`spark.sql.thriftserver.metadata.metricview.enabled=true`). | @@ -109,7 +113,9 @@ BINARY as `sql.RawBytes`). ## Proxy Both backends honor the standard `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` environment -variables. +variables. Note the kernel path accepts **http(s) proxies only**: a `socks*` proxy URL +(honored on the Thrift path) is rejected at connect on the kernel path. Kernel SOCKS +support is tracked in PECOBLR-4152. | Connector option | Thrift | Kernel | Notes | |---|:---:|:---:|---| From d1574c44668a2853d08a4aa19368a8597bb5ba1d Mon Sep 17 00:00:00 2001 From: eric-wang-1990 Date: Mon, 17 Aug 2026 19:26:35 -0700 Subject: [PATCH 2/3] docs: mark enableMetricViewMetadata inert on kernel (currently rejected) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The driver folds spark.sql.thriftserver.metadata.metricview.enabled into SessionConf on both paths (kernel_config.go), but the kernel hard-rejects that conf (HTTP 400 INVALID_CONF_VALUE), so it does not take effect on the kernel path today. Flip the Kernel cell ✅ -> ⚠️ with a caveat. Fix tracked in PECOBLR-4142 / PECOBLR-4153. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 --- CONNECTION_PARAMETERS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index 28eb9696..0ae978fb 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -72,7 +72,7 @@ Notes for the SEA/kernel backend: | *(session param)* | `WithSessionParams` | ✅ | ⚠️ | | Arbitrary session confs (e.g. `ansi_mode`, `STATEMENT_TIMEOUT`, `QUERY_TAGS`). Allowlisted confs are honored on both; on kernel a non-allowlisted conf is dropped/rejected (see the note above; PECOBLR-4153). | | *(via session param)* | `WithQueryTags` | ✅ | ✅ | | Session-level query tags (serialized into `QUERY_TAGS`). | | `timezone` | `WithSessionParams(timezone=…)` | ✅ | ✅ | | Session time zone (e.g. `America/Los_Angeles`). | -| `enableMetricViewMetadata` | `WithEnableMetricViewMetadata` | ✅ | ✅ | `false` | Enables metric-view metadata (`spark.sql.thriftserver.metadata.metricview.enabled=true`). | +| `enableMetricViewMetadata` | `WithEnableMetricViewMetadata` | ✅ | ⚠️ | `false` | Enables metric-view metadata (sets `spark.sql.thriftserver.metadata.metricview.enabled=true`). The driver forwards the conf on both paths, but the kernel currently hard-rejects it (HTTP 400 `INVALID_CONF_VALUE`), so it does not yet take effect on the kernel path (PECOBLR-4142 / PECOBLR-4153). | ## Retry / backoff From 2a283ba349371925b4163828080d64fe4fddfeff Mon Sep 17 00:00:00 2001 From: "peco-engineer-bot[bot]" Date: Tue, 18 Aug 2026 02:35:30 +0000 Subject: [PATCH 3/3] ai: apply changes for #446 (1 review thread) Addresses: - #3800438771 at CONNECTION_PARAMETERS.md:32 Signed-off-by: peco-engineer-bot[bot] --- CONNECTION_PARAMETERS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONNECTION_PARAMETERS.md b/CONNECTION_PARAMETERS.md index 0ae978fb..e50c6753 100644 --- a/CONNECTION_PARAMETERS.md +++ b/CONNECTION_PARAMETERS.md @@ -15,7 +15,7 @@ sections of the README, laid out as one comparison matrix per concern. |:---:|---| | ✅ | Supported and honored. | | ❌ | Not supported — **rejected** at connect/execute (wraps `dbsqlerr.ErrNotSupportedByKernel` or `dbsqlerr.ErrRequiresKernelBackend`), never silently ignored. | -| ⚠️ | Accepted but has no effect ("inert" / silently ignored). | +| ⚠️ | Accepted but not fully honored — either inert ("silently ignored") or only partially/conditionally honored (e.g. some session confs are honored while others are dropped/rejected on the kernel path). | | — | Not applicable. | **Backend selection.** Both backends are selected once per connection via