JDBC Unity 目录连接

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

使用 JDBC 连接的好处

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

JDBC 与联邦查询

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

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

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

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

为何使用 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 Catalog 存储空间
• 用户通过连接查询进行卷访问
• 后面的每个基于任务的部分中都指定了其他权限要求。

第一步：创建一个卷，并安装 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 连接

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

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

在笔记本或 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>;

连接所有者或管理器可以添加到连接中，JDBC 驱动程序支持的任何额外选项。

出于安全原因，连接中定义的选项在查询时不能被重写。 用户只能指定尚未在连接中定义的 Spark 数据源选项。

这使 externalOptionsAllowList 连接创建者能够指定用户可以在查询时提供的 Spark 数据源选项。 在此示例中，用户只能使用： 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions' externalOptionsAllowList可以是空字符串，以确保仅使用 UC 连接中指定的选项。 用户绝不允许指定 URL 和主机。

URL 是创建连接时的唯一必需选项。 如果未指定允许列表，则使用包含： 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'的默认允许列表。

Databricks 建议在连接中指定凭据。

步骤 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 和 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'）。 若要查看允许的选项，请运行以下查询：

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 Database native SQL language - Option specified by querying user
.load()

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in Database native 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 中指定的选项。

Support

• 不支持 Spark 数据源。
• Spark Declarative Pipelines 不被支持。
• 创建时的连接依赖项： java_dependencies 仅支持 JDBC 驱动程序 JAR 的卷位置。
• 查询中的连接依赖项：连接用户需要 READ 访问 JDBC 驱动程序 JAR 所在的卷。

Authentication

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

网络

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

网络连接

需要从计算资源到目标数据库系统的网络连接。 有关常规网络指导，请参阅 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>');