Fix: use public user_agent_entry connect parameter (#64)

The databricks-sql-connector 4.0.1 release renamed the connect
parameter `_user_agent_entry` to `user_agent_entry` and emits a
deprecation warning when the old name is passed. Switch the dialect's
`do_connect` listener and all call sites to the new name, pop any
legacy `_user_agent_entry` callers still supply so it isn't forwarded,
and bump the connector floor to >=4.0.1 to guarantee the new key is
understood. Fixes #36.

Author: jprakash-db

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release History
 
+# 2.0.10 (unreleased)
+
+- Fix: Use public `user_agent_entry` connect parameter instead of deprecated `_user_agent_entry` to silence the deprecation warning from `databricks-sql-connector >= 4.0.1` (databricks/databricks-sqlalchemy#36)
+
 # 2.0.9 (2026-02-20)
 
 - Feature: Added `pool_pre_ping` support via `do_ping()` override to detect and recycle dead connections (databricks/databricks-sqlalchemy#54 by @msrathore-db)

pyproject.toml

@@ -10,7 +10,7 @@ include = ["CHANGELOG.md"]
 
 [tool.poetry.dependencies]
 python = "^3.8.0"
-databricks_sql_connector = { version = ">=4.0.0"}
+databricks_sql_connector = { version = ">=4.0.1"}
 pyarrow = { version = ">=14.0.1"}
 sqlalchemy = { version = ">=2.0.21" }
 

sqlalchemy_example.py

@@ -53,7 +53,7 @@
 # See src/databricks/sql/thrift_backend.py for complete list
 extra_connect_args = {
 	"_tls_verify_hostname": True,
-	"_user_agent_entry": "PySQL Example Script",
+	"user_agent_entry": "PySQL Example Script",
 }
 
 

src/databricks/sqlalchemy/base.py

@@ -429,7 +429,7 @@ def receive_do_connect(dialect, conn_rec, cargs, cparams):
     if not dialect.name == "databricks":
         return
 
-    ua = cparams.get("_user_agent_entry", "")
+    ua = cparams.pop("_user_agent_entry", "") or cparams.get("user_agent_entry", "")
 
     def add_sqla_tag_if_not_present(val: str):
         if not val:
@@ -443,7 +443,7 @@ def add_sqla_tag_if_not_present(val: str):
 
         return output
 
-    cparams["_user_agent_entry"] = add_sqla_tag_if_not_present(ua)
+    cparams["user_agent_entry"] = add_sqla_tag_if_not_present(ua)
 
     if sqlalchemy.__version__.startswith("1.3"):
         # SQLAlchemy 1.3.x fails to parse the http_path, catalog, and schema from our connection string

tests/test_local/e2e/test_basic.py

@@ -55,7 +55,7 @@ def version_agnostic_connect_arguments(connection_details) -> Tuple[str, dict]:
     CATALOG = connection_details["catalog"]
     SCHEMA = connection_details["schema"]
 
-    ua_connect_args = {"_user_agent_entry": USER_AGENT_TOKEN}
+    ua_connect_args = {"user_agent_entry": USER_AGENT_TOKEN}
 
     if sqlalchemy_1_3():
         conn_string = f"databricks://token:{ACCESS_TOKEN}@{HOST}"
@@ -510,7 +510,7 @@ def engine(self, connection_details: dict):
         SCHEMA = connection_details["schema"]
 
         connection_string = f"databricks://token:{ACCESS_TOKEN}@{HOST}?http_path={HTTP_PATH}&catalog={CATALOG}&schema={SCHEMA}"
-        connect_args = {"_user_agent_entry": USER_AGENT_TOKEN}
+        connect_args = {"user_agent_entry": USER_AGENT_TOKEN}
 
         engine = create_engine(connection_string, connect_args=connect_args)
         return engine

tests/test_local/e2e/test_setup.py

@@ -16,7 +16,7 @@ def db_engine(self) -> Engine:
         CATALOG = self.arguments["catalog"]
         SCHEMA = self.arguments["schema"]
 
-        connect_args = {"_user_agent_entry": "SQLAlchemy e2e Tests"}
+        connect_args = {"user_agent_entry": "SQLAlchemy e2e Tests"}
 
         conn_string = f"databricks://token:{ACCESS_TOKEN}@{HOST}?http_path={HTTP_PATH}&catalog={CATALOG}&schema={SCHEMA}"
         return create_engine(conn_string, connect_args=connect_args)