GCP Databricks连接SQL Server报ClassNotFoundException解决方法

架构老林

2026-8-29

问题根因

报错核心为SQL Server JDBC驱动无法加载com.google.cloud.sql.sqlserver.SocketFactory类，和SQL Server实例运行状态、端口防火墙规则无关，本质是Databricks运行环境下依赖配置、类加载规则、连接参数不匹配导致的，按以下步骤逐一排查修复即可。

排查修复步骤

确认依赖安装范围与集群重启状态
绝大多数类找不到问题都是安装配置错误导致：
- 进入集群配置的「库」页签，确认cloud-sql-connector-jdbc-sqlserver和mssql-jdbc两个依赖的安装范围为集群范围，不能选择绑定单个笔记本的安装模式——笔记本范围安装的库不会同步到所有Executor节点，分布式读取时必然报类缺失
- 安装或修改依赖后必须重启集群，Spark JDBC连接的类加载逻辑在集群启动时完成，热加载的库不会被Executor节点的隔离类加载器识别
- 检查所有节点（Driver+Executor）的库状态均为「已安装」，如有节点安装失败，重新触发安装流程
替换不兼容的依赖版本
你当前选择的依赖版本和Databricks 9.1 LTS存在已知兼容问题：
- cloud-sql-connector-jdbc-sqlserver:1.6.1版本修改了打包逻辑，SocketFactory类未被放在类加载器默认扫描路径下，直接降级为1.4.4版本即可，该版本是经过Databricks 9.1 LTS验证的兼容版本，无类路径缺失问题
- mssql-jdbc:10.2.0.jre8存在JAR包签名校验冲突，Databricks 9.1 LTS自带的OpenJDK 8运行环境会触发该版本驱动的安全校验拦截，替换为9.4.1.jre8版本即可
- 替换依赖时先卸载原有版本的两个库，再安装指定版本，避免多版本共存引发类冲突，安装完成后重启集群
修正JDBC连接参数配置
现有连接代码未显式指定驱动类、缺少强制加密参数，会触发类加载优先级异常，替换为以下写法：

password = "..."
connection_name = "...:...:..."  # 固定格式为GCP项目ID:实例所在区域:Cloud SQL实例名
jdbc_url = f"jdbc:sqlserver://localhost;databaseName=avoidable_events;user=sqlserver;password={password};socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;socketFactoryConstructorArg={connection_name};encrypt=true;trustServerCertificate=false"

display(
    spark.read.jdbc(
        url=jdbc_url,
        table="thedb.thetable",
        driver="com.microsoft.sqlserver.jdbc.SQLServerDriver"
    )
)

调整点说明：

显式传入driver参数指定JDBC驱动类，避免Spark自动探测驱动时使用错误的类加载器过滤掉SocketFactory类
增加encrypt=true参数，Cloud SQL for SQL Server强制要求TLS加密连接，缺失该参数会在SocketFactory加载完成后触发握手失败
调整参数顺序，将SocketFactory相关参数放在JDBC URL末尾，避免驱动提前解析参数时目标类尚未完成加载
类加载有效性验证
如果完成上述操作后仍报类找不到，在笔记本中运行以下代码直接在Driver端验证类是否可被正常加载：

# 直接调用JVM类加载器测试目标类是否存在
socket_factory_class = spark._jvm.java.lang.Class.forName("com.google.cloud.sql.sqlserver.SocketFactory")
print("SocketFactory类加载成功，类来源路径：", socket_factory_class.getProtectionDomain().getCodeSource().getLocation())

如果这段代码执行报错，直接去集群Driver日志中搜索cloud-sql-connector关键字，排查是否存在依赖冲突：如果日志中出现类版本冲突、类重复定义的报错，卸载集群中所有其他版本的Cloud SQL连接器、MSSQL驱动，仅保留前述兼容版本后重启集群即可。

前置配置IAM权限
类加载问题解决后，提前确认Databricks集群绑定的服务账号已被授予roles/cloudsql.client（Cloud SQL客户端）权限，否则会在SocketFactory建立连接时触发权限拒绝错误。

内容的提问来源于stack exchange，提问作者kelloti