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 如何强制实施用户隔离？。

Requirements

若要在无服务器群集和标准群集上使用与 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 中嵌入凭据，因为日志或错误可能会公开凭据。 使用所选 身份验证方法的专用凭据选项。
• 用于 externalOptionsAllowList 控制用户可以在查询时指定的 Spark 数据源选项。 如果未指定，则默认值为 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'。 将其设置为空字符串，以仅将用户限制为在连接中定义的选项。 用户永远不能指定 url 或 host。
• 如果目标数据库要求在查询时选择数据库（例如 SQL Server，其数据库不是由连接 URL 固定的），请在 externalOptionsAllowList 中包含 database，以便发起查询的用户可以传入该数据库。 database 不在默认允许列表中。

目录浏览器

1. 在 Azure Databricks 工作区中，单击 Catalog。

2. 单击 连接，然后单击 “连接”。

3. 单击“ 创建连接”。

4. 在“设置连接”向导的“连接基本信息”页上，输入一个用户友好的“连接名称”。

5. 对于 “连接类型”，请选择 “JDBC”。

6. （可选）添加注释。

7. 单击 “下一步” 。

8. 在 “连接详细信息 ”页上，输入以下连接属性：

   财产	Description
   网址	用于您的数据库的 JDBC URL，格式为 jdbc:subprotocol:subname（例如 jdbc:oracle:thin:@<host>:<port>:<SID>）。
   Java依赖项	Unity 目录卷中的 JDBC 驱动程序 JAR 文件。 单击“ 添加 JAR 依赖项 ”以添加每个 JAR（例如 /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar）。
   外部选项允许列表	查询用户可以在查询时指定的 Spark 数据源选项 的逗号分隔列表。 默认值为 dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions. 设置为空值时，用户将只能使用该连接上定义的选项。
   其他选项	任意 JDBC 驱动程序选项，以键值对形式传递给驱动程序。 使用本节设置数据库凭据（例如，键 user 和键 password）以及任何其他特定于驱动程序的属性。 根据需要在 UI 和 JSON 输入模式之间进行切换。

9. 单击“ 创建连接”。

SQL

在笔记本或 Databricks SQL 查询编辑器中使用 CREATE CONNECTION SQL 命令。

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>;

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'
);

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>',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint '<https://authorization-server.com/oauth/token>',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '<driver-token-parameter-name>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

CREATE CONNECTION postgres_oauth_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/postgresql-42.7.3.jar"]'
)
OPTIONS (
  url 'jdbc:postgresql://<host>:<port>/<database>?sslmode=require',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint 'https://authorization-server.com/oauth/token',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '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

对于需要在查询时选择目标数据库的数据库，跳过 database 该选项。 以下 SQL Server 示例还引用了带括号的[...]模式和表名，用于处理特殊字符和保留词：

SELECT * FROM remote_query(
  '<JDBC-connection-name>',
  database => 'test-db',
  query => 'SELECT TOP 100 * FROM [dbo].[FactFinance]'
);

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。
• Spark JDBC 数据源不支持针对外部数据库的任意 DML 语句，例如 UPDATE 或 DELETE。 它支持读取数据和追加或覆盖整个表，而不是行级修改。

Support

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

Authentication

• 此连接器支持静态凭据和 OAuth 计算机到计算机。 它不支持 Unity 目录凭据或服务凭据。

网络

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

网络连接

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

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

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

如果Azure Databricks工作区和目标数据库系统位于同一 VNet 中，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>');

FAQ

以下常见问题涵盖了 JDBC 连接的谓词下推行为。

JDBC 是否支持谓词下推？

Yes. 默认情况下，对于 Spark 数据源 API（format('jdbc')）和 remote_query SQL 函数，筛选器会向下推送到远程数据库。 可推送哪些谓词取决于 JDBC 驱动程序和方言，因此，请对查询运行 EXPLAIN 并检查物理执行计划，以确认哪些过滤条件被下推到数据源。 对于 remote_query SQL 函数，可以使用 pushdown.filters.enabled 等选项来控制特定的下推操作（过滤、限制、偏移和聚合）；这些选项默认均处于启用状态。

谓词下推有别于向查询优化器提供表统计信息。 无论是否进行谓词下推，JDBC 和 PySpark 数据源都不会向查询优化器暴露统计信息以帮助确定操作顺序。