Merge remote-tracking branch 'origin/main' into msrathore/nodejs-cross-repo-ci

Author: msrathore-db

.eslintrc

@@ -9,6 +9,12 @@
       "rules": {
         "class-methods-use-this": "off",
         "no-underscore-dangle": "off",
+        "@typescript-eslint/no-unused-vars": [
+          "error",
+          { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "ignoreRestSiblings": true }
+        ],
+        "@typescript-eslint/no-use-before-define": ["error", { "functions": false }],
+        "no-continue": "off",
         "consistent-return": "off",
         "no-param-reassign": "off",
         "no-bitwise": "off",

.gitattributes

@@ -31,3 +31,10 @@ Dockerfile* text
 #
 .gitattributes export-ignore
 .gitignore     export-ignore
+
+# napi-rs auto-generates these files from the kernel's `napi-binding/napi/`
+# crate; regenerated by `npm run build:native`. Tell git/GitHub they're
+# machine-generated so they collapse in diffs and are excluded from
+# blame and language stats.
+native/sea/index.d.ts linguist-generated=true
+native/sea/index.js linguist-generated=true

.gitignore

@@ -10,3 +10,12 @@ coverage_unit
 dist
 *.DS_Store
 lib/version.ts
+
+# SEA native binding — copied/generated from kernel workspace by `npm run build:native`.
+# The committed contract is `native/sea/index.d.ts` (TypeScript declarations) and
+# `native/sea/index.js` (the napi-rs platform router — small, stable, and required in
+# the publish tarball so a missing build step can't ship a tarball that can't load).
+# The `.node` binaries are large per-platform artifacts and must NOT be committed;
+# in production they arrive via the `@databricks/sql-kernel-<triple>` optional deps.
+native/sea/index.node
+native/sea/index.*.node

.npmignore

@@ -3,6 +3,13 @@
 !dist/**/*
 !thrift/**/*
 
+# SEA napi-rs router shim + TypeScript declarations. The router (index.js)
+# selects the per-platform `.node` artifact from `@databricks/sql-kernel-*`
+# optionalDependencies (populated when the kernel CI publishes them);
+# the .d.ts is the consumer-facing type contract.
+!native/sea/index.js
+!native/sea/index.d.ts
+
 !LICENSE
 !NOTICE
 !package.json

.prettierignore

@@ -11,3 +11,9 @@ coverage
 dist
 thrift
 package-lock.json
+
+# Generated by napi-rs from the kernel's `napi-binding/napi/` crate;
+# regenerated by `npm run build:native`. Format follows napi-rs's
+# defaults (no semicolons), not this repo's prettier config.
+native/sea/index.d.ts
+native/sea/index.js

KERNEL_REV

@@ -0,0 +1 @@
+8bedaabf69f5bce5a957a8775f29dbb8dbdd2e71

lib/DBSQLClient.ts

@@ -112,6 +112,8 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
 
   private authType?: string;
 
+  private useProxy?: boolean;
+
   private telemetryClient?: TelemetryClient;
 
   private telemetryEmitter?: TelemetryEventEmitter;
@@ -415,6 +417,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
       // Connection parameters
       httpPath: this.httpPath,
       enableMetricViewMetadata: this.config.enableMetricViewMetadata,
+      useProxy: this.useProxy,
     };
   }
 
@@ -594,6 +597,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
     this.host = options.host;
     this.httpPath = options.path;
     this.authType = this.mapAuthType(options);
+    this.useProxy = Boolean(options.proxy);
 
     // Store enableMetricViewMetadata configuration
     if (options.enableMetricViewMetadata !== undefined) {
@@ -628,7 +632,7 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
     // pattern (see databricks-sql-python/src/databricks/sql/session.py).
     const internalOptions = options as ConnectionOptions & InternalConnectionOptions;
     const backend = internalOptions.useSEA
-      ? new SeaBackend()
+      ? new SeaBackend({ context: this })
       : new ThriftBackend({
           context: this,
           onConnectionEvent: (event, payload) => this.forwardConnectionEvent(event, payload),

lib/DBSQLParameter.ts

@@ -8,6 +8,15 @@ export enum DBSQLParameterType {
   STRING = 'STRING',
   DATE = 'DATE',
   TIMESTAMP = 'TIMESTAMP',
+  // `TIMESTAMP_NTZ` binds a timezone-free (wall-clock) timestamp. It is a real
+  // Spark type, bound natively on both the Thrift and kernel backends (requires
+  // a server that supports TIMESTAMP_NTZ; Spark 3.4+ / recent DBR).
+  TIMESTAMP_NTZ = 'TIMESTAMP_NTZ',
+  // `TIMESTAMP_LTZ` is an alias for `TIMESTAMP`: Spark has no distinct
+  // TIMESTAMP_LTZ type — `TIMESTAMP` already carries local/instant (LTZ)
+  // semantics. `toSparkParameter` therefore binds it as `TIMESTAMP` on the wire
+  // (valid on both backends); it exists only as a self-documenting alias.
+  TIMESTAMP_LTZ = 'TIMESTAMP_LTZ',
   FLOAT = 'FLOAT',
   DECIMAL = 'DECIMAL',
   DOUBLE = 'DOUBLE',
@@ -50,10 +59,16 @@ export class DBSQLParameter {
       return new TSparkParameter({ name }); // for NULL neither `type` nor `value` should be set
     }
 
+    // Map timezone-explicit timestamp aliases to their Spark wire type. Spark
+    // has no distinct TIMESTAMP_LTZ type (TIMESTAMP carries LTZ semantics), so
+    // bind it as TIMESTAMP — valid on both the Thrift and kernel backends.
+    // TIMESTAMP_NTZ is a real Spark type and is bound natively.
+    const wireType = this.type === DBSQLParameterType.TIMESTAMP_LTZ ? DBSQLParameterType.TIMESTAMP : this.type;
+
     if (typeof this.value === 'boolean') {
       return new TSparkParameter({
         name,
-        type: this.type ?? DBSQLParameterType.BOOLEAN,
+        type: wireType ?? DBSQLParameterType.BOOLEAN,
         value: new TSparkParameterValue({
           stringValue: this.value ? 'TRUE' : 'FALSE',
         }),
@@ -63,7 +78,7 @@ export class DBSQLParameter {
     if (typeof this.value === 'number') {
       return new TSparkParameter({
         name,
-        type: this.type ?? (Number.isInteger(this.value) ? DBSQLParameterType.INTEGER : DBSQLParameterType.DOUBLE),
+        type: wireType ?? (Number.isInteger(this.value) ? DBSQLParameterType.INTEGER : DBSQLParameterType.DOUBLE),
         value: new TSparkParameterValue({
           stringValue: Number(this.value).toString(),
         }),
@@ -73,7 +88,7 @@ export class DBSQLParameter {
     if (this.value instanceof Int64 || typeof this.value === 'bigint') {
       return new TSparkParameter({
         name,
-        type: this.type ?? DBSQLParameterType.BIGINT,
+        type: wireType ?? DBSQLParameterType.BIGINT,
         value: new TSparkParameterValue({
           stringValue: this.value.toString(),
         }),
@@ -83,7 +98,7 @@ export class DBSQLParameter {
     if (this.value instanceof Date) {
       return new TSparkParameter({
         name,
-        type: this.type ?? DBSQLParameterType.TIMESTAMP,
+        type: wireType ?? DBSQLParameterType.TIMESTAMP,
         value: new TSparkParameterValue({
           stringValue: this.value.toISOString(),
         }),
@@ -92,7 +107,7 @@ export class DBSQLParameter {
 
     return new TSparkParameter({
       name,
-      type: this.type ?? DBSQLParameterType.STRING,
+      type: wireType ?? DBSQLParameterType.STRING,
       value: new TSparkParameterValue({
         stringValue: this.value,
       }),

lib/contracts/IDBSQLSession.ts

@@ -12,7 +12,18 @@ export type ExecuteStatementOptions = {
    */
   queryTimeout?: number | bigint | Int64;
   /**
-   * @deprecated This option is no longer supported and will be removed in future releases
+   * Selects the execution lifecycle. The only observable effect is WHEN
+   * `executeStatement` resolves; the result data, schema, and error classes are
+   * identical regardless.
+   *
+   * - **Thrift backend:** no-op. The Thrift path always submits asynchronously
+   *   (`runAsync: true` on the wire) and polls during fetch; this option is not
+   *   read.
+   * - **Kernel backend (`useSEA`):** selects the kernel execution path —
+   *   `false`/unset (default) runs the blocking direct-results path (faster,
+   *   cancellable mid-compute); `true` submits and polls (returns a pending
+   *   handle before completion). Default is sync, matching the python
+   *   connector's `cursor.execute()`.
    */
   runAsync?: boolean;
   maxRows?: number | bigint | Int64 | null;
@@ -27,6 +38,18 @@ export type ExecuteStatementOptions = {
    * These tags apply only to this statement and do not persist across queries.
    */
   queryTags?: Record<string, string | null | undefined>;
+  /**
+   * SEA-only: server-side row cap for this statement (kernel `row_limit`). The
+   * Thrift backend has no execute-time server cap, so this is a no-op there;
+   * use `maxRows` for the cross-backend client-side fetch limit.
+   */
+  rowLimit?: number;
+  /**
+   * SEA-only: per-statement Spark conf overlay (kernel `statement_conf`).
+   * Merged with the serialized `queryTags` (which land under the reserved
+   * `query_tags` key). Ignored by the Thrift backend.
+   */
+  statementConf?: Record<string, string>;
 };
 
 export type TypeInfoRequest = {

lib/contracts/InternalConnectionOptions.ts

@@ -18,4 +18,27 @@ export interface InternalConnectionOptions {
    * @internal Not stable; M0 stub only.
    */
   useSEA?: boolean;
+
+  /**
+   * SEA-only: kernel connection-pool size (`ConnectionOptions.max_connections`).
+   * Validated as a positive integer within the napi `u32` range.
+   * @internal SEA path only.
+   */
+  maxConnections?: number;
+
+  /**
+   * SEA-only: verify the server's TLS certificate. Secure-by-default — omit
+   * to keep full chain + hostname verification; set `false` only to opt into
+   * the insecure accept-anything mode.
+   * @internal SEA path only.
+   */
+  checkServerCertificate?: boolean;
+
+  /**
+   * SEA-only: PEM-encoded CA certificate (string or `Buffer`) added to the
+   * trust store on top of the system roots — for TLS-inspecting proxies or
+   * on-prem internal CAs. Honoured regardless of `checkServerCertificate`.
+   * @internal SEA path only.
+   */
+  customCaCert?: Buffer | string;
 }