Force Thrift mode when metadata params require native RPCs (#1416)

## Summary
When a user sets `UseQueryForMetadata=0` or
`TreatMetadataCatalogNameAsPattern=1` without explicitly setting
`UseThriftClient`, the driver now forces Thrift mode. These params
require native Thrift RPCs and don't work with SEA.

If the user explicitly sets `UseThriftClient=0` (wants SEA), that takes
priority — the metadata params will be silently ineffective, but the
user's explicit protocol choice is honoured.

## Decision Matrix

| UseThriftClient | UseQueryForMetadata | TreatCatalogAsPattern | Result
| Reason |
|---|---|---|---|---|
| `1` (explicit) | any | any | **Thrift** | User explicit |
| `0` (explicit) | `0` | `1` | **SEA** | User explicit SEA, metadata
params ignored |
| not set | `0` (explicit) | not set | **Thrift** | Needs native RPCs |
| not set | not set | `1` (explicit) | **Thrift** | Needs native RPCs |
| not set | `0` | `1` | **Thrift** | Needs native RPCs |
| not set | `1` (explicit) | not set | SAFE flag decides | SHOW commands
work in both |
| not set | not set | not set | SAFE flag decides | Default |

## Test plan
- [x] 13 new tests covering all combinations in
DatabricksConnectionContextTest
- [x] Full core suite: 3293 tests, 0 failures

NO_CHANGELOG=true

This pull request was AI-assisted by Isaac.

---------

Signed-off-by: Gopal Lal <gopal.lal@databricks.com>

Author: gopalldb

src/main/java/com/databricks/jdbc/api/impl/DatabricksConnectionContext.java

@@ -456,10 +456,42 @@ public DatabricksClientType getClientTypeFromContext() {
       if (useThriftClient.equals("1")) {
         return DatabricksClientType.THRIFT;
       } else if (useThriftClient.equals("0")) {
+        // Warn if user explicitly chose SEA but also set Thrift-only metadata params
+        String explicitQueryForMetadata =
+            getParameterIgnoreDefault(DatabricksJdbcUrlParams.USE_QUERY_FOR_METADATA);
+        String explicitCatalogAsPattern =
+            getParameterIgnoreDefault(
+                DatabricksJdbcUrlParams.TREAT_METADATA_CATALOG_NAME_AS_PATTERN);
+        if ((explicitQueryForMetadata != null && explicitQueryForMetadata.equals("0"))
+            || (explicitCatalogAsPattern != null && explicitCatalogAsPattern.equals("1"))) {
+          LOGGER.warn(
+              "UseThriftClient=0 (SEA) is set alongside Thrift-only metadata params "
+                  + "(UseQueryForMetadata={}, TreatMetadataCatalogNameAsPattern={}). "
+                  + "Honouring SEA — these metadata params will have no effect.",
+              explicitQueryForMetadata,
+              explicitCatalogAsPattern);
+        }
         return DatabricksClientType.SEA;
       }
     }
-    // Now, user has not provided a value, we will decide based on our checks
+    // Now, user has not provided a value for UseThriftClient, we will decide based on our checks.
+    // If user explicitly requires Thrift-native metadata behavior, stay on Thrift:
+    // - UseQueryForMetadata=0: user wants native Thrift RPCs for metadata (not SHOW commands)
+    // - TreatMetadataCatalogNameAsPattern=1: only works with native Thrift RPCs
+    String explicitUseQueryForMetadata =
+        getParameterIgnoreDefault(DatabricksJdbcUrlParams.USE_QUERY_FOR_METADATA);
+    String explicitTreatCatalogAsPattern =
+        getParameterIgnoreDefault(DatabricksJdbcUrlParams.TREAT_METADATA_CATALOG_NAME_AS_PATTERN);
+    if ((explicitUseQueryForMetadata != null && explicitUseQueryForMetadata.equals("0"))
+        || (explicitTreatCatalogAsPattern != null && explicitTreatCatalogAsPattern.equals("1"))) {
+      LOGGER.info(
+          "Forcing Thrift client: user requires Thrift-native metadata behavior "
+              + "(UseQueryForMetadata={}, TreatMetadataCatalogNameAsPattern={})",
+          explicitUseQueryForMetadata,
+          explicitTreatCatalogAsPattern);
+      return DatabricksClientType.THRIFT;
+    }
+
     // Check if circuit breaker is open due to recent 429 rate limit failures
     if (SeaCircuitBreakerManager.isCircuitOpen()) {
       long remainingMs = SeaCircuitBreakerManager.getTimeRemainingMs();

src/test/java/com/databricks/jdbc/api/impl/DatabricksConnectionContextTest.java

@@ -1487,4 +1487,162 @@ public void testUseQueryForMetadataExplicitFalseOnWarehouse() throws DatabricksS
             TestConstants.VALID_URL_1 + ";UseQueryForMetadata=0", properties);
     assertFalse(ctx.useQueryForMetadata());
   }
+
+  // ---------------------------------------------------------------------------
+  // Client type selection with Thrift-native metadata params
+  // ---------------------------------------------------------------------------
+
+  @Test
+  public void testUseQueryForMetadata0_forcesThrift() throws DatabricksSQLException {
+    // UseQueryForMetadata=0 without UseThriftClient → forces Thrift
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";UseQueryForMetadata=0", properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+  }
+
+  @Test
+  public void testTreatCatalogAsPattern1_forcesThrift() throws DatabricksSQLException {
+    // TreatMetadataCatalogNameAsPattern=1 without UseThriftClient → forces Thrift
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";TreatMetadataCatalogNameAsPattern=1", properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+  }
+
+  @Test
+  public void testBothMetadataParams_forcesThrift() throws DatabricksSQLException {
+    // Both UseQueryForMetadata=0 and TreatMetadataCatalogNameAsPattern=1 → forces Thrift
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1
+                + ";UseQueryForMetadata=0;TreatMetadataCatalogNameAsPattern=1",
+            properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+  }
+
+  @Test
+  public void testUseQueryForMetadata0_withExplicitSEA_honoursSEA() throws DatabricksSQLException {
+    // UseThriftClient=0 (explicit SEA) + UseQueryForMetadata=0 → SEA wins
+    // User explicitly chose SEA, so we honour that even though metadata param won't work
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";UseThriftClient=0;UseQueryForMetadata=0", properties);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+  }
+
+  @Test
+  public void testTreatCatalogAsPattern1_withExplicitSEA_honoursSEA()
+      throws DatabricksSQLException {
+    // UseThriftClient=0 (explicit SEA) + TreatMetadataCatalogNameAsPattern=1 → SEA wins
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";UseThriftClient=0;TreatMetadataCatalogNameAsPattern=1",
+            properties);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+  }
+
+  @Test
+  public void testUseQueryForMetadata0_withExplicitThrift_staysThrift()
+      throws DatabricksSQLException {
+    // UseThriftClient=1 (explicit Thrift) + UseQueryForMetadata=0 → Thrift
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";UseThriftClient=1;UseQueryForMetadata=0", properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+  }
+
+  @Test
+  public void testUseQueryForMetadata1_doesNotForceThrift() throws DatabricksSQLException {
+    // UseQueryForMetadata=1 (SHOW commands) with explicit SEA → should remain SEA
+    // Proves our new check doesn't trigger for UseQueryForMetadata=1
+    // VALID_URL_2 has UseThriftClient=0, so it's SEA
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_2 + ";UseQueryForMetadata=1", properties_with_pwd);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+  }
+
+  @Test
+  public void testTreatCatalogAsPattern0_doesNotForceThrift() throws DatabricksSQLException {
+    // TreatMetadataCatalogNameAsPattern=0 (default, literal match) with explicit SEA → stays SEA
+    // Proves our new check doesn't trigger for the default/disabled value
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_2 + ";TreatMetadataCatalogNameAsPattern=0",
+            properties_with_pwd);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+  }
+
+  @Test
+  public void testNoMetadataParams_defaultBehavior() throws DatabricksSQLException {
+    // No metadata params, no UseThriftClient → other checks decide (Arrow, CF, SAFE flag).
+    // VALID_URL_1 has no UseThriftClient and no SAFE flag in tests, so downstream
+    // checks (Arrow disabled, CF disabled, no flag) fall through to Thrift default.
+    // This tests that our metadata param check doesn't interfere with the default path.
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(TestConstants.VALID_URL_1, properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+  }
+
+  @Test
+  public void testUseQueryForMetadataFalseString_doesNotForceThrift()
+      throws DatabricksSQLException {
+    // "false" is not "0" — our check uses .equals("0"), so "false" doesn't trigger it.
+    // With explicit SEA (VALID_URL_2), should stay SEA.
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_2 + ";UseQueryForMetadata=false", properties_with_pwd);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+  }
+
+  @Test
+  public void testTreatCatalogAsPatternTrueString_doesNotForceThrift()
+      throws DatabricksSQLException {
+    // "true" is not "1" — our check uses .equals("1"), so "true" doesn't trigger it.
+    // With explicit SEA (VALID_URL_2), should stay SEA.
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_2 + ";TreatMetadataCatalogNameAsPattern=true",
+            properties_with_pwd);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+  }
+
+  @Test
+  public void testCluster_metadataParamsIgnored() throws DatabricksSQLException {
+    // All-Purpose Cluster always uses Thrift regardless of metadata params
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_CLUSTER_URL + ";UseQueryForMetadata=0", properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+
+    ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_CLUSTER_URL + ";TreatMetadataCatalogNameAsPattern=1", properties);
+    assertEquals(DatabricksClientType.THRIFT, ctx.getClientType());
+  }
+
+  @Test
+  public void testUseQueryForMetadata0_withExplicitSEA_useQueryForMetadataStillFalse()
+      throws DatabricksSQLException {
+    // Even though SEA is forced, UseQueryForMetadata=0 should still report false
+    // (the metadata param value is independent of client type selection)
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";UseThriftClient=0;UseQueryForMetadata=0", properties);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+    assertFalse(ctx.useQueryForMetadata());
+  }
+
+  @Test
+  public void testTreatCatalogAsPattern1_withExplicitSEA_treatCatalogStillTrue()
+      throws DatabricksSQLException {
+    // Even though SEA is forced, TreatMetadataCatalogNameAsPattern=1 should still report true
+    IDatabricksConnectionContext ctx =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";UseThriftClient=0;TreatMetadataCatalogNameAsPattern=1",
+            properties);
+    assertEquals(DatabricksClientType.SEA, ctx.getClientType());
+    assertTrue(ctx.treatMetadataCatalogNameAsPattern());
+  }
 }