Add opt-in catalog escaping for metadata requests

Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>

Author: vuanhphung

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Add `escapeMetadataCatalogName` (default `false`) to escape catalog underscores in Thrift and kernel metadata requests.
 - Fix Thrift `getFunctions()` to report the requested `FUNCTION_CAT`, matching JDBC and kernel.
 
 ## 2.2.0

CONNECTION_PARAMETERS.md

@@ -104,6 +104,23 @@ disabling verification.
 | `disableRowMaterialization`   | `boolean` |   ✅   |   ✅   | `false`       | Fetches and parses Arrow batches but returns `null` row placeholders instead of converting cells. Intended for fetch-throughput tests. |
 | `enableMetricViewMetadata`    | `boolean` |   ✅   |   ⚠️   | `false`       | Injected into session configuration on both paths. Kernel may drop its non-allowlisted configuration key.                              |
 
+## Metadata catalog filters
+
+| Option                      | Type      | Thrift | Kernel | Default Value | Note                                                                                                          |
+| --------------------------- | --------- | :----: | :----: | ------------- | ------------------------------------------------------------------------------------------------------------- |
+| `escapeMetadataCatalogName` | `boolean` |   ✅   |   ✅   | `false`       | Escapes unescaped `_` in catalog filters; existing `\_` escapes and `%` wildcards are preserved, matching JDBC. |
+
+Set `escapeMetadataCatalogName: true` in `client.connect(...)` to treat catalog
+underscores literally in metadata requests. For example, `comparator_tests`
+matches that catalog rather than also matching `comparatorXtests`. Schema,
+table, column, and function name patterns are unaffected.
+
+Thrift applies this to `getSchemas`, `getTables`, `getColumns`, and
+`getFunctions`. Kernel applies it to `getTables`, avoiding catalog enumeration
+for names without `%` wildcards; its other methods already use exact catalog
+identifiers. `getPrimaryKeys` and `getCrossReference` use exact catalog
+identifiers on both backends.
+
 ## Session defaults (`openSession(request)`)
 
 | Option           | Type                                          | Thrift | Kernel | Default Value | Note                                                                                                                                            |

lib/DBSQLClient.ts

@@ -157,6 +157,8 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
 
       useLZ4Compression: true,
 
+      escapeMetadataCatalogName: false,
+
       preserveBigNumericPrecision: false,
 
       disableRowMaterialization: false,
@@ -696,6 +698,10 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
       this.config.enableMetricViewMetadata = options.enableMetricViewMetadata;
     }
 
+    if (options.escapeMetadataCatalogName !== undefined) {
+      this.config.escapeMetadataCatalogName = options.escapeMetadataCatalogName;
+    }
+
     // Opt-in: preserve DECIMAL (string) / BIGINT (bigint) precision in results.
     if (options.preserveBigNumericPrecision !== undefined) {
       this.config.preserveBigNumericPrecision = options.preserveBigNumericPrecision;

lib/contracts/IClientContext.ts

@@ -25,6 +25,7 @@ export interface ClientConfig {
 
   useLZ4Compression: boolean;
   enableMetricViewMetadata?: boolean;
+  escapeMetadataCatalogName?: boolean;
 
   // When true, DECIMAL values are returned as exact strings and 64-bit
   // integers as JS `bigint`, instead of being coerced to a lossy `number`.

lib/contracts/IDBSQLClient.ts

@@ -68,6 +68,13 @@ export type ConnectionOptions = {
   proxy?: ProxyOptions;
   enableMetricViewMetadata?: boolean;
 
+  /**
+   * Escape unescaped `_` in metadata catalog filters on both backends.
+   * Existing `\_` escapes and `%` wildcards are preserved, matching JDBC.
+   * Defaults to `false` to preserve the current metadata behavior.
+   */
+  escapeMetadataCatalogName?: boolean;
+
   /**
    * Verify the server's TLS certificate on the primary Thrift transport.
    * Secure-by-default: omitting this leaves full chain + hostname verification

lib/kernel/KernelSessionBackend.ts

@@ -14,6 +14,7 @@
 
 import { v4 as uuidv4 } from 'uuid';
 import ISessionBackend from '../contracts/ISessionBackend';
+import escapeCatalogName from '../utils/escapeCatalogName';
 import IOperationBackend from '../contracts/IOperationBackend';
 import IClientContext from '../contracts/IClientContext';
 import {
@@ -367,8 +368,12 @@ export default class KernelSessionBackend implements ISessionBackend {
 
   public async getTables(request: TablesRequest): Promise<IOperationBackend> {
     this.failIfClosed();
+    // Other kernel metadata methods already take exact catalog identifiers.
+    const catalogName = this.context.getConfig().escapeMetadataCatalogName
+      ? escapeCatalogName(request.catalogName)
+      : request.catalogName;
     return this.runMetadata(() =>
-      this.connection.listTables(request.catalogName, request.schemaName, request.tableName, request.tableTypes),
+      this.connection.listTables(catalogName, request.schemaName, request.tableName, request.tableTypes),
     );
   }
 

lib/thrift-backend/ThriftSessionBackend.ts

@@ -32,6 +32,7 @@ import ParameterError from '../errors/ParameterError';
 import { DBSQLParameter, DBSQLParameterValue } from '../DBSQLParameter';
 import { LogLevel } from '../contracts/IDBSQLLogger';
 import ThriftOperationBackend from './ThriftOperationBackend';
+import escapeCatalogName from '../utils/escapeCatalogName';
 
 interface OperationResponseShape {
   status: TStatus;
@@ -151,6 +152,10 @@ export default class ThriftSessionBackend implements ISessionBackend {
     return ProtocolVersion.supportsAsyncMetadataOperations(this.serverProtocolVersion) ? true : undefined;
   }
 
+  private maybeEscapeCatalogName(catalogName: string | undefined): string | undefined {
+    return this.context.getConfig().escapeMetadataCatalogName ? escapeCatalogName(catalogName) : catalogName;
+  }
+
   public get id(): string {
     const sessionId = this.sessionHandle?.sessionId?.guid;
     return sessionId ? stringify(sessionId) : NIL;
@@ -238,7 +243,7 @@ export default class ThriftSessionBackend implements ISessionBackend {
     const driver = await this.context.getDriver();
     const response = await driver.getSchemas({
       sessionHandle: this.sessionHandle,
-      catalogName: request.catalogName,
+      catalogName: this.maybeEscapeCatalogName(request.catalogName),
       schemaName: request.schemaName,
       runAsync: this.getRunAsyncForMetadataOperations(),
       ...getDirectResultsOptions(request.maxRows, this.context.getConfig()),
@@ -250,7 +255,7 @@ export default class ThriftSessionBackend implements ISessionBackend {
     const driver = await this.context.getDriver();
     const response = await driver.getTables({
       sessionHandle: this.sessionHandle,
-      catalogName: request.catalogName,
+      catalogName: this.maybeEscapeCatalogName(request.catalogName),
       schemaName: request.schemaName,
       tableName: request.tableName,
       tableTypes: request.tableTypes,
@@ -274,7 +279,7 @@ export default class ThriftSessionBackend implements ISessionBackend {
     const driver = await this.context.getDriver();
     const response = await driver.getColumns({
       sessionHandle: this.sessionHandle,
-      catalogName: request.catalogName,
+      catalogName: this.maybeEscapeCatalogName(request.catalogName),
       schemaName: request.schemaName,
       tableName: request.tableName,
       columnName: request.columnName,
@@ -289,7 +294,7 @@ export default class ThriftSessionBackend implements ISessionBackend {
     const driver = await this.context.getDriver();
     const response = await driver.getFunctions({
       sessionHandle: this.sessionHandle,
-      catalogName: request.catalogName,
+      catalogName: this.maybeEscapeCatalogName(request.catalogName),
       schemaName: request.schemaName,
       functionName: request.functionName,
       runAsync: this.getRunAsyncForMetadataOperations(),

lib/utils/escapeCatalogName.ts

@@ -0,0 +1,7 @@
+/** Escape catalog underscores without double-escaping existing `\_` sequences. */
+export default function escapeCatalogName(catalogName: string | undefined): string | undefined {
+  if (catalogName == null) {
+    return catalogName;
+  }
+  return catalogName.replace(/\\?_/g, '\\_');
+}

tests/unit/DBSQLClient.test.ts

@@ -793,6 +793,28 @@ describe('DBSQLClient retry-policy ConnectionOptions', () => {
   });
 });
 
+describe('DBSQLClient.escapeMetadataCatalogName', () => {
+  beforeEach(() => {
+    sinon.stub(FeatureFlagCache.prototype as any, 'fetchFeatureFlags').resolves(new Map());
+  });
+  afterEach(() => sinon.restore());
+
+  it('defaults to false and accepts opt-in and opt-out on connect', async () => {
+    const client = new DBSQLClient();
+    expect(client.getConfig().escapeMetadataCatalogName).to.be.false;
+
+    await client.connect({ ...connectOptions, telemetryEnabled: false });
+    expect(client.getConfig().escapeMetadataCatalogName).to.be.false;
+
+    await client.connect({ ...connectOptions, telemetryEnabled: false, escapeMetadataCatalogName: true });
+    expect(client.getConfig().escapeMetadataCatalogName).to.be.true;
+
+    await client.connect({ ...connectOptions, telemetryEnabled: false, escapeMetadataCatalogName: false });
+    expect(client.getConfig().escapeMetadataCatalogName).to.be.false;
+    await client.close();
+  });
+});
+
 describe('DBSQLClient.enableMetricViewMetadata', () => {
   it('should store enableMetricViewMetadata config when enabled', async () => {
     const client = new DBSQLClient();

tests/unit/kernel/execution.test.ts

@@ -1095,6 +1095,56 @@ describe('KernelSessionBackend', () => {
     ]);
   });
 
+  for (const enabled of [undefined, false, true]) {
+    for (const [catalogName, escaped] of [
+      [undefined, undefined],
+      ['', ''],
+      ['main', 'main'],
+      ['comparator_tests', 'comparator\\_tests'],
+      ['a\\_b_c', 'a\\_b\\_c'],
+      ['a_b%c', 'a\\_b%c'],
+      ['%', '%'],
+    ]) {
+      it(`handles catalog ${JSON.stringify(catalogName)} with escapeMetadataCatalogName=${enabled}`, async () => {
+        const connection = new FakeNativeConnection();
+        const session = new KernelSessionBackend({
+          connection,
+          context: makeContext(undefined, { escapeMetadataCatalogName: enabled }),
+        });
+        const request = Object.freeze({
+          catalogName,
+          schemaName: 'schema_%',
+          tableName: 'table_%',
+          columnName: 'column_%',
+          functionName: 'function_%',
+        });
+        await session.getSchemas(request);
+        await session.getTables(request);
+        await session.getColumns(request);
+        await session.getFunctions(request);
+        await session.getPrimaryKeys(request);
+        await session.getCrossReference({
+          parentCatalogName: 'parent_catalog',
+          parentSchemaName: 's',
+          parentTableName: 't',
+          foreignCatalogName: 'foreign_catalog',
+          foreignSchemaName: 's',
+          foreignTableName: 'f',
+        });
+
+        expect(connection.metadataCalls).to.deep.equal([
+          ['listSchemas', catalogName, 'schema_%'],
+          ['listTables', enabled ? escaped : catalogName, 'schema_%', 'table_%', undefined],
+          ['listColumns', catalogName, 'schema_%', 'table_%', 'column_%'],
+          ['listFunctions', catalogName, 'schema_%', 'function_%'],
+          ['getPrimaryKeys', catalogName, 'schema_%', 'table_%'],
+          ['getCrossReference', 'parent_catalog', 's', 't', 'foreign_catalog', 's', 'f'],
+        ]);
+        await session.close();
+      });
+    }
+  }
+
   it('getPrimaryKeys forwards null, omitted, and empty namespace names unchanged', async () => {
     const connection = new FakeNativeConnection();
     const session = makeSession(connection);