test: document JDBC-compatible metadata backslash escaping

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

Author: vuanhphung

src/databricks/sql/utils.py

@@ -49,7 +49,7 @@
 def escape_metadata_catalog_name(
     catalog_name: Optional[str], enabled: bool
 ) -> Optional[str]:
-    """Escape unescaped underscores, preserving existing escapes and % wildcards."""
+    r"""Match JDBC: escape _ unless immediately preceded by \; preserve %."""
     if not enabled or catalog_name is None:
         return catalog_name
     return re.sub(r"(?<!\\)_", r"\\_", catalog_name)

tests/unit/test_kernel_client.py

@@ -1861,6 +1861,17 @@ def test_sync_execute_leaves_rowcount_default_when_num_modified_rows_none():
         ("a_b_c", r"a\_b\_c"),
         (r"my\_catalog", r"my\_catalog"),
         (r"a\_b_c%", r"a\_b\_c%"),
+        # Match JDBC: preserve the final \_ pair regardless of backslash parity.
+        pytest.param(
+            r"my\\_cat_tail",
+            r"my\\_cat\_tail",
+            id="jdbc-even-backslash-run",
+        ),
+        pytest.param(
+            r"my\\\_cat_tail",
+            r"my\\\_cat\_tail",
+            id="jdbc-odd-backslash-run",
+        ),
     ],
 )
 def test_metadata_catalog_escaping(

tests/unit/test_thrift_backend.py

@@ -73,6 +73,17 @@ def retry_policy_factory():
         ("a_b_c", r"a\_b\_c"),
         (r"my\_catalog", r"my\_catalog"),
         (r"a\_b_c%", r"a\_b\_c%"),
+        # Match JDBC: preserve the final \_ pair regardless of backslash parity.
+        pytest.param(
+            r"my\\_cat_tail",
+            r"my\\_cat\_tail",
+            id="jdbc-even-backslash-run",
+        ),
+        pytest.param(
+            r"my\\\_cat_tail",
+            r"my\\\_cat\_tail",
+            id="jdbc-odd-backslash-run",
+        ),
     ],
 )
 def test_metadata_catalog_escaping(