matlab-connect-databricks-jdbc

通过 JDBC 将 MATLAB 连接到 Databricks

使用 Database Toolbox 和 MATLAB Interface for Databricks 包，通过 JDBC 建立从 MATLAB 到 Databricks 的连接。本技能涵盖连接类选择、身份验证配置、驱动程序设置和连接优化。连接后，可在 j.Connection 对象上使用标准 Database Toolbox 函数（sqlread、fetch、sqlwrite、execute）执行数据操作。

先决条件

• 已安装 MATLAB Interface for Databricks 包，且该包位于 MATLAB 路径中
• 已安装 Database Toolbox

适用场景

• 通过 JDBC 将 MATLAB 连接到 Databricks 集群
• 通过 JDBC 将 MATLAB 连接到 Databricks SQL Warehouse
• 配置 Databricks 身份验证（PAT、OauthU2M、OauthM2M）
• 设置 Databricks JDBC 驱动程序（Simba 或 OSS）
• 不使用完整 Databricks 包，创建独立 JDBC 连接
• 在 Databricks 集群上运行 MATLAB，并通过 JDBC 连接回集群
• 优化向 Databricks 大规模传输数据时的写入性能
• 用户提及关键词：Databricks、JDBCConnection、SQL Warehouse、databricks.JDBCConnection、StandaloneJDBCConnection、Databricks JDBC、Databricks connect、Databricks cluster、Databricks authentication

不适用场景

• 通过 ODBC 连接（直接使用 databricks.ODBCConnection）
• 使用 Databricks Connect（基于 Python 的 Spark API，不属于 Database Toolbox）
• 使用 Databricks REST API（Clusters、Jobs、DBFS 等）
• 在 MATLAB 中使用 MLflow（该包中的独立模块）
• 通过 Statement Execution REST API 执行 SQL（非 JDBC）

重要规则

连接

• 始终优先使用 databricks.JDBCConnection 或 StandaloneJDBCConnection，而不是通过 database() 手动构造 JDBC URL。手动构造 URL 并非错误，但其格式复杂且容易出错，还可能在源代码中暴露连接详情。连接类会自动处理 URL 构造、驱动程序类路径和身份验证。
• 如果用户没有安装 MATLAB Interface for Databricks 包，始终使用 StandaloneJDBCConnection。绝不要退而使用 database() 手动构造 JDBC URL。
• 不再需要连接时，始终调用 close(j) 或 close(j.Connection)。
• 始终检查 j.Connection.Message 是否为空，以确认连接成功。消息非空表示存在驱动程序错误。

身份验证

• 始终让连接类通过统一的提供程序链处理身份验证。默认方法为 OauthU2M。不要在源代码中硬编码令牌。
• 在浏览器中运行 Databricks 上的 MATLAB 时，绝不要使用 JDBC 驱动程序内置的 OauthU2M。驱动程序会尝试打开浏览器窗口，导致失败。请改用 useDriverAuth=false。

驱动程序

• Simba 驱动程序（非 OSS，v2.7.3 至 <3.0.0）为默认驱动程序，随包提供。它适用于 MATLAB 默认的 Java 8 环境。
• OSS 驱动程序（v3.0.3+）要求 Java 11 或更高版本。使用前先通过 jenv 设置 MATLAB 的 Java 环境。OSS 驱动程序使用 Arrow 加快大规模数据传输。
• StandaloneJDBCConnection 仅支持 Simba 驱动程序。不要在独立连接中使用 useDriverType="oss"。

函数参考

函数 / 类	用途	适用场景
databricks.JDBCConnection	创建具有完整程序包支持的 JDBC 连接	已安装 MATLAB Interface for Databricks 程序包时的默认选择
StandaloneJDBCConnection	创建零程序包依赖的 JDBC 连接	将 Databricks 连接功能嵌入独立代码库时
databricks.SQLWarehouse.connect()	按 ID 连接到 SQL Warehouse；直接返回 database.jdbc.connection	目标是 SQL Warehouse 而非集群时
j.Connection	JDBCConnection 或 StandaloneJDBCConnection 中底层的 database.jdbc.connection 对象	将此对象传递给 sqlread、fetch、sqlwrite、execute 等。等同于使用 Database Toolbox 创建 database() 时得到的 conn
databricks.internal.isOnDatabricks()	如果 MATLAB 正在 Databricks 集群上运行，则返回 true	用于区分集群内与集群外场景的连接逻辑
j.testConnection()	验证连接是否正常工作	创建连接后，用于确认连接成功
j.saveSource()	将连接保存为 Database Toolbox 数据源	使用 Database Explorer 应用进行交互式探索时
j.copyToken()	将身份验证令牌复制到剪贴板	Database Explorer 提示输入凭据时
close(j)	关闭连接并释放资源	使用完连接后

决策指南

应该使用哪个类？

场景	类	原因
已安装完整程序包，目标是集群	databricks.JDBCConnection	自动处理身份验证、URL 和驱动程序类路径
通过 HTTP 路径指定目标计算终端节点	databricks.JDBCConnection(httpPath="/sql/1.0/warehouses/abc")	覆盖默认集群路由
已安装完整程序包，目标是 SQL Warehouse	databricks.SQLWarehouse.connect()	通过 REST API 根据 Warehouse 元数据构建连接
未安装程序包或需独立集成	StandaloneJDBCConnection	不依赖 Databricks 程序包
已有 databricks.Cluster 对象	databricks.JDBCConnection(cluster=myCluster)	将连接路由到指定的集群对象
MATLAB 正在 Databricks 集群上运行	databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false)	浏览器内运行的 MATLAB 无法使用驱动程序浏览器身份验证

应该使用哪个 JDBC 驱动程序？

场景	驱动程序	说明
Java 8（MATLAB 默认版本）	Simba（默认）	随程序包提供，无需设置
可用 Java 11+，且两个驱动程序都已安装	OSS（自动选择）	使用 Arrow 提升大规模传输性能
需要显式控制	useDriverType='oss' 或 'simba'	覆盖自动选择

有关驱动程序安装和 Java 配置的详细信息，请参阅 references/driver-selection.md。

我应该使用哪种身份验证方式？

场景	身份验证方式	必需配置
个人交互式使用（默认）	OauthU2M	.databrickscfg 中的 host
自动化服务或 CI/CD 管道	OauthM2M	.databrickscfg 中的 host、client_id、client_secret
简单的基于令牌的访问	PAT	.databrickscfg 中的 host、token
.databrickscfg 中有多个工作区	任意方式 + profileName="myprofile"	通过 profileName 参数指定 .databrickscfg 中的命名配置文件
在 Databricks 集群上运行	OauthU2M + useDriverAuth=false	由包管理的身份验证（而非驱动程序管理）
来自外部来源的不透明令牌	令牌透传	passthroughAccessToken 参数
Azure Entra ID 托管工作区	OauthU2M + OauthService="EntraID"	将范围解析设置为 Azure AD，而非 Databricks 原生方式

有关身份验证配置的详细信息，包括 .databrickscfg 格式和环境变量，请参阅 references/authentication.md。

常见模式

模式 1：集群连接（默认）

% Connect to a Databricks cluster using default authentication
j = databricks.JDBCConnection();

% Use Database Toolbox functions on the connection
data = sqlread(j.Connection, "mycatalog.myschema.mytable");

% Close when done
close(j);

模式 2：带目录和架构的集群连接

% Set default catalog and schema to simplify table references
j = databricks.JDBCConnection(catalog="mycatalog", schema="myschema");

% Now table names do not need full qualification
data = sqlread(j.Connection, "mytable");

close(j);

模式 3：SQL Warehouse 连接

% Create a warehouse object and set its ID
warehouse = databricks.SQLWarehouse;
warehouse.id = "abc123def456";

% Connect (defaults to JDBC mode)
conn = warehouse.connect();

% Query data
data = fetch(conn, "SELECT * FROM mycatalog.myschema.mytable LIMIT 10");

% Close when done
close(conn);

模式 4：针对写入优化的连接（Simba 驱动程序）

使用原生查询模式可显著提升 Simba 驱动程序的写入性能。创建连接时默认启用此模式，但也可以显式控制。

% Default behavior: UseNativeQuery=1, EnableNativeParameterizedQuery=0
j = databricks.JDBCConnection();
sqlwrite(j.Connection, "mycatalog.myschema.mytable", data);
close(j);

% To disable the optimization (not recommended for writes)
j = databricks.JDBCConnection(useNativeQuery=false, enableNativeParameterizedQuery=true);

SQL Warehouse 变体：

warehouse = databricks.SQLWarehouse;
warehouse.id = "abc123def456";
conn = warehouse.connect(useNativeQuery=true, enableNativeParameterizedQuery=false);
sqlwrite(conn, "mycatalog.myschema.mytable", data);
close(conn);

模式 5：在 Databricks 上运行时的连接

在 Databricks 集群上直接运行 MATLAB（基于浏览器）时，JDBC 驱动程序的 OAuth 流程无法打开浏览器。请改用由包管理的身份验证。使用 databricks.internal.isOnDatabricks() 检测环境。

% Detect if running on Databricks
if databricks.internal.isOnDatabricks()
    j = databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false);
else
    j = databricks.JDBCConnection();
end

data = fetch(j.Connection, "SELECT * FROM mycatalog.myschema.mytable LIMIT 10");
close(j);

模式 6：独立连接（不使用包）

如果用户没有安装 MATLAB Interface for Databricks 包，请使用 StandaloneJDBCConnection。此类只需要 Database Toolbox 和 Simba JDBC 驱动程序 jar，不依赖 Databricks 包。

设置：

1. 将 StandaloneJDBCConnection.m 和 databricks_standalone_jdbc_settings.json 放到 MATLAB 路径中
2. 编辑 JSON 文件，填写 host、orgId、clusterId 和身份验证设置
3. 创建连接：

% Add standalone class folder to path (if not already)
addpath("path/to/standalone/folder");

% StandaloneJDBCConnection reads config from databricks_standalone_jdbc_settings.json
j = StandaloneJDBCConnection(schema="myschema", catalog="mycatalog");
data = fetch(j.Connection, "SELECT * FROM mytable LIMIT 10");
close(j);

JSON 设置文件（databricks_standalone_jdbc_settings.json）必须包含：

• host：Databricks 工作区 URL（例如，"https://adb-123.1.azuredatabricks.net"）
• orgId：工作区 org ID
• clusterId：集群或 SQL Warehouse ID
• jarFilePath：Simba JDBC 驱动程序 jar 的路径

完整的 JSON 模板和所有字段请参阅 references/standalone-jdbc.md。

模式 7：Database Explorer 集成

% Create and save a connection as a data source
j = databricks.JDBCConnection();
j.saveSource();

% Copy the token to clipboard for pasting into Database Explorer
j.copyToken();

% Open Database Explorer, select the saved data source,
% enter "token" as username, paste the token as password
databaseExplorer

模式 8：安全清理连接以处理错误

使用 onCleanup 或 try/catch，确保即使查询失败也能关闭连接。

j = databricks.JDBCConnection(catalog="main", schema="analytics");
cleanup = onCleanup(@() close(j));

% If this errors, cleanup still runs
data = fetch(j.Connection, "SELECT * FROM large_table WHERE id > 1000");

常见错误

% NOT RECOMMENDED: manually constructing a JDBC URL with database()
% This works but is error-prone and may expose connection details in code
conn = database("default", "token", myToken, ...
    "com.databricks.client.jdbc.Driver", ...
    "jdbc:databricks://myhost:443/default;transportMode=http;ssl=1;...");
% RECOMMENDED: let JDBCConnection handle URL construction
j = databricks.JDBCConnection();
conn = j.Connection;

% WRONG: using driver auth when running MATLAB on Databricks
j = databricks.JDBCConnection();  % Driver tries to open a browser, fails
% CORRECT: disable driver auth in browser environment
j = databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false);

% WRONG: hardcoding a PAT token in source code
j = databricks.JDBCConnection(token="dapi1234567890abcdef");
% CORRECT: store token in .databrickscfg and let the auth chain find it
j = databricks.JDBCConnection(authMethod="PAT");

% WRONG: using the OSS driver with Java 8
j = databricks.JDBCConnection(useDriverType="oss");  % Error: Java 11+ required
% CORRECT: set Java version first, then use OSS driver
jenv("/path/to/java11");  % Requires MATLAB restart
j = databricks.JDBCConnection(useDriverType="oss");

% WRONG: forgetting to close the connection
j = databricks.JDBCConnection();
data = sqlread(j.Connection, "mytable");
% Connection left open, resources leaked
% CORRECT: always close
close(j);

Unity Catalog 命名

访问受 Unity Catalog 管理的资源时，名称中包含连字符的部分必须在 SQL 查询中用反引号括起来：

% Schema name contains a hyphen
data = fetch(j.Connection, "SELECT * FROM mycatalog.`my-schema`.mytable");

对于 sqlread 和 sqlwrite，请改为在连接上设置目录和架构：

j = databricks.JDBCConnection(catalog="mycatalog", schema="my-schema");
data = sqlread(j.Connection, "mytable");

检查清单

完成 Databricks JDBC 连接代码前，请确认：

• 使用 databricks.JDBCConnection、StandaloneJDBCConnection 或 SQLWarehouse.connect()（优先于手动构造 database() URL）
• 身份验证方式适合相应场景（交互式使用 OauthU2M，服务使用 OauthM2M，简单访问使用 PAT）
• 源代码中没有硬编码令牌或密钥
• 使用完毕后调用 close(j) 或 close(conn)
• 如果在 Databricks 上运行：已设置 useDriverAuth=false
• 如果使用 OSS 驱动程序：已通过 jenv 配置 Java 11+
• 如果使用 Simba 写入大量数据：已启用 UseNativeQuery 优化（默认启用）
• 已通过空的 j.Connection.Message 或 j.testConnection() 验证连接

故障排除

问题：连接返回的 database.jdbc.connection 为空，并显示一条消息

• 解决方案：检查 j.Connection.Message 属性。常见原因：主机不正确、令牌已过期、集群未运行，或类路径中使用了错误的驱动程序。

问题："Driver class not found on Java class path"

• 解决方案：JDBC 驱动程序 JAR 不在 MATLAB 的动态 Java 类路径中。databricks.JDBCConnection 会自动添加它。对于 StandaloneJDBCConnection，请先调用 javaaddpath("path/to/Shaded-Databricks-JDBC-Driver-0.0.2.jar")。

问题：OSS 驱动程序因 Java 版本错误而失败

• 解决方案：OSS 驱动程序要求 Java 11+。使用 jenv 检查并设置兼容的 JDK：jenv("/path/to/java11")。更改后请重启 MATLAB。

问题："An ODBC/JDBC datasource exists with the same name as the database"

• 解决方案：已保存的数据源与架构同名。请重命名数据源，或使用不同的 dataSourceName 参数。

问题：建立连接需要很长时间

• 解决方案：Databricks 集群或 SQL Warehouse 可能正在从停止状态启动（冷启动）。这可能需要几分钟。请在 Databricks UI 中或通过 warehouse.refresh() 检查集群/仓库状态。MATLAB 会一直等待，直到计算资源就绪。

问题：连接挂起或超时

• 解决方案：确认集群或 SQL Warehouse 正在运行。对于 SQL Warehouse，warehouse.refresh() 会显示当前状态。停止的仓库启动时，MATLAB 会一直等待。

问题：在 Linux/macOS 上使用驱动程序 v2.7.x 时出现令牌缓存错误

• 解决方案：这是已知的驱动程序错误。请升级到驱动程序 v2.7.3+，或禁用缓存：enableTokenCache=false。有关特定版本的详细信息，请参阅软件包中的 JDBCWorkflow.md 文档。

问题：在 Databricks 上运行 MATLAB 时，OauthU2M 失败

• 解决方案：JDBC 驱动程序的 OAuth 流程会尝试打开浏览器，这在基于浏览器的 MATLAB 中会失败。请使用 databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false)。

仍未解决？ 请参阅随附文档，了解详细指导：

doc databricks.JDBCConnection                          % Class reference
edit(databricksRoot(-2, "Documentation", "JDBCWorkflow.md"))  % JDBC workflow guide
edit(databricksRoot("Standalone", "README.md"))         % Standalone setup guide

如果以上方法均无法解决问题，请发送电子邮件至 [email protected]，直接联系 MATLAB-Databricks 团队获取支持。

---

版权所有 2026 The MathWorks, Inc.