fix: default geospatial results to strings

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-- Add the default-enabled `enableGeoSpatialSupport` option for kernel-backed GEOMETRY / GEOGRAPHY results. Enabled mode returns the canonical `{ srid, wkb }` Arrow value; disabled mode returns WKT / EWKT.
+- Add the `enableGeoSpatialSupport` option (default `false`) for kernel-backed GEOMETRY / GEOGRAPHY results. Enabled mode returns the canonical `{ srid, wkb }` Arrow value; disabled mode returns WKT / EWKT.
 - Preserve DECIMAL precision and scale qualifiers in kernel-backed result metadata, matching the Thrift path.
 - Pin transitive `brace-expansion` 1.x / 2.x and `ip-address` dependencies for repository and CI installs to patched releases for GHSA-6j4f-fj2g-mc7p, GHSA-qhr7-859c-m2p7, GHSA-j6r3-76f7-8jcv, and GHSA-h3mg-xc3c-68pw.
 - Add `escapeMetadataCatalogName` (default `false`) to escape catalog underscores in Thrift and kernel metadata requests.

CONNECTION_PARAMETERS.md

@@ -102,7 +102,7 @@ disabling verification.
 | ----------------------------- | --------- | :----: | :----: | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `preserveBigNumericPrecision` | `boolean` |   ✅   |   ✅   | `false`       | Returns DECIMAL as an exact string and BIGINT as `bigint` on both.                                                                                                                 |
 | `disableRowMaterialization`   | `boolean` |   ✅   |   ✅   | `false`       | Fetches and parses Arrow batches but returns `null` row placeholders instead of converting cells. Intended for fetch-throughput tests.                                             |
-| `enableGeoSpatialSupport`     | `boolean` |   ❌   |   ✅   | `true`        | Returns GEOMETRY / GEOGRAPHY as canonical `{ srid: number, wkb: Buffer }` values when `true`, or WKT / EWKT strings when `false`. The choice is local and is not forwarded to SEA. |
+| `enableGeoSpatialSupport`     | `boolean` |   ❌   |   ✅   | `false`       | Returns GEOMETRY / GEOGRAPHY as canonical `{ srid: number, wkb: Buffer }` values when `true`, or WKT / EWKT strings when `false`. The choice is local and is not forwarded to SEA. |
 | `enableMetricViewMetadata`    | `boolean` |   ✅   |   ⚠️   | `false`       | Injected into session configuration on both paths. Kernel may drop its non-allowlisted configuration key.                                                                          |
 
 ## Metadata catalog filters

lib/contracts/IDBSQLClient.ts

@@ -166,8 +166,8 @@ export type ConnectionOptions = {
 
   /**
    * Enable native kernel-backed `GEOMETRY` and `GEOGRAPHY` results. `true`
-   * (the default) returns the canonical Arrow value as
-   * `{ srid: number, wkb: Buffer }`; `false` returns WKT / EWKT strings.
+   * returns the canonical Arrow value as
+   * `{ srid: number, wkb: Buffer }`; `false` (the default) returns WKT / EWKT strings.
    * This is a client-side conversion choice and is never forwarded to the SQL
    * Execution API.
    *

lib/kernel/KernelAuth.ts

@@ -116,8 +116,8 @@ export interface KernelSessionDefaults {
    */
   complexTypesAsJson?: boolean;
   /**
-   * Enable native GEOMETRY / GEOGRAPHY values. `true` (the default) returns
-   * canonical `struct<srid:int32,wkb:binary>` values; `false` returns WKT /
+   * Enable native GEOMETRY / GEOGRAPHY values. `true` returns
+   * canonical `struct<srid:int32,wkb:binary>` values; `false` (the default) returns WKT /
    * EWKT strings. Applied locally by the kernel and never sent to SEA.
    */
   enableGeoSpatialSupport?: boolean;
@@ -840,9 +840,9 @@ export function buildKernelConnectionOptions(options: ConnectionOptions): Kernel
     // (native Arrow) — they already decode identically to Thrift via the
     // shared Arrow converter, so `complexTypesAsJson` is not forced on.
     intervalsAsString: true,
-    // Match the public driver contract and the kernel default: geospatial
-    // support is enabled unless the caller explicitly requests WKT / EWKT.
-    enableGeoSpatialSupport: true,
+    // Preserve string results by default, including automatic kernel recovery.
+    // Callers can explicitly opt into native geospatial values.
+    enableGeoSpatialSupport: false,
     // TLS knobs (server-cert verification toggle + custom CA + mTLS client
     // identity). Validated and normalised (string PEM → Buffer) here so the
     // napi shape only sees a Buffer.

tests/unit/kernel/_helpers/nativeOptions.ts

@@ -81,7 +81,7 @@ export default function expectNativeConnectionOptions(actual: unknown, expectedR
   ]) {
     delete rest[key];
   }
-  expect(rest).to.deep.equal({ enableGeoSpatialSupport: true, ...expectedRest });
+  expect(rest).to.deep.equal({ enableGeoSpatialSupport: false, ...expectedRest });
   expect(customHeaders, 'customHeaders').to.be.an('array').with.lengthOf(1);
   expect(customHeaders?.[0].name).to.equal('User-Agent');
   expect(customHeaders?.[0].value).to.match(/NodejsDatabricksSqlConnector\//);

tests/unit/kernel/connectionOptions.test.ts

@@ -41,9 +41,9 @@ describe('KernelAuth connection options — intervalsAsString default', () => {
 });
 
 describe('KernelAuth connection options — geospatial result representation', () => {
-  it('enables native geospatial support by default', () => {
+  it('defaults to string geospatial results', () => {
     const native = buildKernelConnectionOptions(opts({})) as { enableGeoSpatialSupport?: boolean };
-    expect(native.enableGeoSpatialSupport).to.equal(true);
+    expect(native.enableGeoSpatialSupport).to.equal(false);
   });
 
   for (const value of [true, false]) {