JDBC 连接

Azure Databricks 支持使用 JDBC 连接到外部数据库。 可以使用 JDBC Unity Catalog 连接器通过 Spark 数据源 API 或 Azure Databricks 远程查询 SQL API读取和写入数据源。 JDBC 连接是 Unity 目录中的安全对象，指定用于访问外部数据库的 JDBC 驱动程序、URL 路径和凭据。 Unity 目录计算类型支持 JDBC 连接，包括无服务器群集、标准群集、专用群集和 Databricks SQL。

使用 JDBC 连接的好处

• 使用 JDBC 和 Spark 数据源 API 读取和写入数据源。
• 使用远程查询 SQL API 从具有 JDBC 的数据源中读取数据。
• 使用 Unity Catalog 连接受控访问数据源。
• 创建连接一次，并在任何 Unity 目录计算中重复使用它。
• 稳定适用于 Spark 和计算升级。
• 连接凭据对执行查询的用户是隐藏的。

JDBC 与查询融合

JDBC 是对 查询联合的补充。 Databricks 建议出于以下原因选择使用查询联邦：

• 查询联合使用外部目录在表级别提供精细的访问控制和治理。 JDBC Unity 目录连接仅在连接级别提供治理。
• 查询联合会向下推送 Spark 查询，以获得最佳的查询性能。

但是，选择在以下方案中使用 JDBC Unity 目录连接：

• 您的数据库不受查询联合的支持。
• 你想要使用特定的 JDBC 驱动程序。
• 由于查询联合不支持写入操作，因此需要使用 Spark 来写入数据源。
• 需要通过 Spark 数据源 API 选项实现更大的灵活性、性能和并行控制。
• 想要使用 Spark query 选项向下推送源 SQL 查询。

为何使用 JDBC 与 PySpark 数据源？

PySpark 数据源 是 JDBC Spark 数据源的替代方法。

使用 JDBC 连接：

• 如果要使用内置的 Spark JDBC 支持。
• 如果想要使用已存在的开箱即用的 JDBC 驱动程序。
• 需要在连接级别进行 Unity Catalog 治理时。
• 如果要从任何 Unity 目录计算类型进行连接：无服务器、标准、专用、SQL API。
• 如果要将连接与 Python、Scala 和 SQL API 配合使用。

使用 PySpark 数据源：

• 如果想要灵活地使用 Python 开发和设计 Spark 数据源或数据接收器。
• 如果你仅在笔记本电脑或 PySpark 工作负载中使用它。
• 如果要实现自定义分区逻辑。

JDBC 和 PySpark 数据源都不会向查询优化器公开统计信息，以帮助选择操作顺序。

工作原理

若要使用 JDBC 连接连接到数据源，请在 Spark 计算上安装 JDBC 驱动程序。 通过连接，可以在 Spark 计算可访问的独立沙盒中指定和安装 JDBC 驱动程序，以确保 Spark 安全性和 Unity 目录治理。 有关沙盒的详细信息，请参阅 Databricks 如何强制实施用户隔离？。

在您开始之前

若要在无服务器群集和标准群集上使用与 Spark 数据源 API 的 JDBC 连接，必须首先满足以下要求：

工作区要求：

• 为 Unity 目录启用了 Azure Databricks 工作区

计算要求：

• 从计算资源到目标数据库系统的网络连接。 请参阅 网络连接。
• Azure Databricks 计算必须在无服务器、标准模式或专用访问模式下，使用 Databricks Runtime 17.3 LTS 或更高版本。
• SQL 仓库必须是专业或无服务器，并且必须使用 2025.35 或更高版本。

所需的权限：

• 若要创建连接，您必须拥有对附加到工作区的元存储的 CREATE CONNECTION 权限。
• CREATE 或 MANAGE 由连接创建者访问 Unity 目录卷。
• 用户查询连接时的卷访问权限。
• 以下每个基于任务的部分中都指定了其他权限。

第一步：创建一个卷，并安装 JDBC 驱动程序 JAR 文件

JDBC 连接从 Unity 目录卷读取并安装 JDBC 驱动程序 JAR。

1. 如果您没有对现有卷的写入和读取访问权限，创建新卷：

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. 将 JDBC 驱动 JAR 上传至 卷。

3. 向查询连接的用户授予对卷的读取访问权限：

   GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`
   

步骤 2：创建 JDBC 连接

JDBC 连接是 Unity 目录中的安全对象，它指定 JDBC 驱动程序、URL 路径和凭据，用于访问外部数据库系统和查询用户要使用的允许列表选项。 若要创建连接，请在 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中使用目录资源管理器或 CREATE CONNECTION SQL 命令。

所需的权限：具有 CREATE CONNECTION 特权的元存储管理员或用户。

在创建连接之前，请注意以下事项：

• URL 和凭据是唯一必需的选项。 不要在 URL 中嵌入凭据，因为它们可以通过日志或错误公开。 请改用 user 和 password 选项。
• 用于 externalOptionsAllowList 控制用户可以在查询时指定的 Spark 数据源选项。 如果未指定，则默认值为 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'。 将其设置为空字符串，以仅将用户限制为在连接中定义的选项。 用户永远不能指定 url 或 host。

目录浏览器

1. 在 Azure Databricks 工作区中，单击 Catalog。
2. 在“目录”窗格顶部，单击“添加”或“加号”图标，然后从菜单中选择“创建连接”。
3. 在“设置连接”向导的“连接基本信息”页上，输入一个用户友好的“连接名称”。
4. 选择 JDBC的连接类型。
5. （可选）添加注释。
6. 单击 “下一步” 。
7. 在 “身份验证 ”页上，输入以下连接属性：
   • JDBC URL：数据库的 JDBC 连接 URL（例如 jdbc:oracle:thin:@<host>:<port>:<SID>）。
   • 用户：数据库用户名。
   • 密码：数据库密码。
   • JDBC 驱动程序路径：JDBC 驱动程序 JAR 的 Unity 目录卷路径（例如 /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar）。
8. 单击“ 创建连接”。

SQL

在笔记本或 SQL 查询编辑器中运行以下命令，调整相应的卷、URL、凭据和externalOptionsAllowList。

DROP CONNECTION IF EXISTS <JDBC-connection-name>;

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<Schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  user '<user>',
  password '<password>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

DESCRIBE CONNECTION <JDBC-connection-name>;

示例：Oracle JDBC 连接

以下示例使用 Oracle 精简驱动程序创建与 Oracle 数据库的 JDBC 连接。 从 ojdbc11.jar下载 Oracle JDBC 驱动程序 JAR（例如，），并在运行此命令之前将其上传到 Unity Catalog 卷。

CREATE CONNECTION oracle_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/ojdbc11.jar"]'
)
OPTIONS (
  url 'jdbc:oracle:thin:@<host>:<port>:<SID>',
  user '<oracle_user>',
  password '<oracle_password>',
  externalOptionsAllowList 'dbtable,query'
);

连接所有者或管理器可以向该连接添加 JDBC 驱动程序支持的任何额外选项。 出于安全原因，在查询时无法重写连接中定义的选项。

步骤 3：授予 USE 权限

USE向用户授予连接的权限：

GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-name>;

有关管理现有连接的信息，请参阅管理 Lakehouse Federation 的连接。

步骤 4：查询数据源

具有 USE CONNECTION 特权的用户可以通过 Spark 或远程查询 SQL API 使用 JDBC 连接查询数据源。 用户可以添加由 JDBC 驱动程序支持并在 JDBC 连接中指定的任何 Spark 数据源选项（例如，在本例中：externalOptionsAllowList）。 若要查看允许的选项，请运行以下查询：

DESCRIBE CONNECTION <JDBC-connection-name>;

Python

df = (
  spark.read.format('jdbc')
  .option('databricks.connection', '<JDBC-connection-name>')
  .option('query', 'select * from <table_name>') # query in source SQL language - Option specified by querying user
  .load()
)

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in source SQL language - Option specified by querying user

Migration

若要从现有 Spark 数据源 API 工作负载迁移，Databricks 建议执行以下作：

• 从 Spark 数据源 API 中的选项中删除 URL 和凭据。
• 在 Spark 数据源 API 的选项中添加 databricks.connection。
• 使用相应的 URL 和凭据创建 JDBC 连接。
• 在连接中，指定应保持静态的选项，不应由用户查询来指定。
• 在连接的externalOptionsAllowList中指定在 Spark 数据源 API 代码中用户应在查询时调整或修改的数据源选项 (例如 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions')。

局限性

Spark 数据源 API

• URL 和主机不能包含在 Spark 数据源 API 中。
• .option("databricks.connection", "<Connection_name>") 必需。
• 在查询时，连接中定义的选项不能在代码中的数据源 API 上使用。
• 只有查询用户才能使用在选项 externalOptionsAllowList 中指定的选项。
• JDBC 驱动程序的内存限制为 400 MiB。 如果达到限制，请考虑使用更小的fetchSize。

Support

• 不支持 Spark 数据源。
• 不支持 Spark 声明性管道。
• 创建时的连接依赖项： java_dependencies 仅支持 JDBC 驱动程序 JAR 的卷位置。
• 查询中的连接依赖项：连接用户需要READ访问 JDBC 驱动程序 JAR 所在的卷。
• 在专用访问模式（以前是单用户访问模式）上，你必须是连接的所有者或经理才能使用它。
• 不支持 SSL 证书。
• JDBC 连接不支持外部目录。

Authentication

• 仅支持基本身份验证（用户名和密码）。 不支持 Unity 目录凭据、OAuth 或服务凭据。

网络

• 目标数据库系统和 Azure Databricks 工作区不能位于同一个VP中。

网络连接

需要从计算资源到目标数据库系统的网络连接。 有关常规网络指导，请参阅 Lakehouse Federation 的网络建议。

经典计算：标准和专用群集

Azure Databricks VPN 配置为仅允许 Spark 群集。 若要连接到另一个基础结构，请将目标数据库系统放置在不同的VPC中，并使用VPC对等连接。 建立 VPC 对等连接后，请检查集群或仓库上的 connectionTest UDF 连接。

如果Azure Databricks 工作区和目标数据库系统位于同一个VPC，Databricks 建议以下之一：

• 使用无服务器计算。
• 将目标数据库配置为允许通过端口 80 和 443 的 TCP 和 UDP 流量，并在连接中指定这些端口。

Serverless

在无服务器计算上使用 JDBC 连接时， 请为无服务器计算访问配置防火墙 以获取稳定的 IP，或配置专用连接。

连接测试

若要测试 Azure Databricks 计算与数据库系统之间的连接，请使用以下 UDF：

CREATE OR REPLACE TEMPORARY FUNCTION connectionTest(host string, port string) RETURNS string LANGUAGE PYTHON AS $$
import subprocess
try:
    command = ['nc', '-zv', host, str(port)]
    result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    return str(result.returncode) + "|" + result.stdout.decode() + result.stderr.decode()
except Exception as e:
    return str(e)
$$;

SELECT connectionTest('<database-host>', '<database-port>');