KnowForge/Apache Kyuubi 1.9.1 简体中文
JDBC 驱动

Kyuubi Hive JDBC 驱动

师成师成· 更新于 2026-09-29· 阅读 13 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

新增于 1.4.0 版本：Kyuubi 社区维护了一个 fork 的 Hive JDBC 驱动模块，并同时提供 shaded 和非 shaded 两种打包方式。

该包旨在支持原版 Hive JDBC 驱动所缺少的一些功能。对于支持多 catalog 的 Kyuubi 引擎，它提供了元数据 API 以提供更好的支持。原版 Hive JDBC 驱动的行为保持不变。

要使用 Apache Kyuubi 的 Kyuubi JDBC 驱动访问 Hive 数据仓库或新的 Lakehouse 格式（如 Apache Iceberg/Hudi、Delta Lake），你需要配置以下内容：

引用 JDBC 驱动库

在使用 Apache Kyuubi 的 JDBC 驱动之前，你用来连接数据的 JDBC 应用或 Java 代码必须能够访问驱动的 JAR 文件。

在 Java 代码中使用驱动

在代码中，根据你所使用的构建工具，从 Maven Central 指定构件 kyuubi-hive-jdbc-shaded。

Maven

<dependency>
    <groupId>org.apache.kyuubi</groupId>
    <artifactId>kyuubi-hive-jdbc-shaded</artifactId>
    <version>1.9.1</version>
</dependency>

sbt

libraryDependencies += "org.apache.kyuubi" % "kyuubi-hive-jdbc-shaded" % "1.9.1"

Gradle

implementation group: 'org.apache.kyuubi', name: 'kyuubi-hive-jdbc-shaded', version: '1.9.1'

在 JDBC 应用中使用驱动

关于 JDBC 应用（例如 BI 工具、SQL IDE），请查阅相应指南以获取详细信息。

注意

你心仪的工具没有收录？提交功能请求，或者帮助我们补充相关文档。

注册驱动类

在连接数据之前，必须先为你的应用注册 JDBC 驱动类。

  • org.apache.kyuubi.jdbc.KyuubiHiveDriver
  • org.apache.kyuubi.jdbc.KyuubiDriver（已废弃）

以下示例代码展示了如何使用 java.sql.DriverManager 类为 JDBC 建立连接：

private static Connection newKyuubiConnection() throws Exception {
  Connection connection = DriverManager.getConnection(CONNECTION_URL);
  return connection;
}

构建连接 URL

基本连接 URL 格式

使用连接 URL 向您要访问的 kyuubi 服务器或集群提供连接信息。以下是 Kyuubi Hive JDBC 驱动的连接 URL 格式：

jdbc:subprotocol://host:port[/catalog]/[schema];<clientProperties;><[#|?]sessionProperties>
  • subprotocol：kyuubi 或 hive2
  • host：Kyuubi 服务器的 DNS 名称或 IP 地址
  • port：服务器用于监听客户端请求的 TCP 端口号
  • catalog：可选的 catalog 名称，用于设置执行查询时所使用的当前 catalog。
  • schema：可选的数据库名称，用于设置执行查询时所使用的当前数据库，缺省时使用默认值。
  • clientProperties：可选的以分号（;）分隔的 key=value 参数，用于标识并影响客户端本地行为。例如：user=foo;password=bar。
  • sessionProperties：可选的以分号（;）分隔的 key=value 参数，用于配置会话、操作或后台引擎。例如，kyuubi.engine.share.level=CONNECTION 表示后台引擎实例仅供当前连接使用；spark.ui.enabled=false 则禁用引擎的 Spark UI。

重要

  • sessionProperties 必须位于前导的井号（#）或问号（?）之后。
  • 属性名区分大小写
  • 请勿在连接 URL 中重复定义属性

通过 HTTP 建立连接

1.6.0 版本新增。

jdbc:subprotocol://host:port/schema;transportMode=http;httpPath=<http_endpoint>
  • http_endpoint 是服务端通过 kyuubi.frontend.thrift.http.path 配置的对应 HTTP 端点。

通过服务发现建立连接 URL

jdbc:subprotocol://<zookeeper quorum>/;serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=kyuubi
  • zookeeper quorum 是服务端由 kyuubi.ha.addresses 配置的对应 ZooKeeper 集群。
  • zooKeeperNamespace 是服务端由 kyuubi.ha.namespace 配置的对应命名空间。

HiveServer2 兼容性

1.8.0 版本新增。

JDBC 驱动在连接时需要与 Kyuubi Server/HiveServer2 协商协议版本。

Kyuubi Hive JDBC Driver 默认向服务端提供协议版本 v10（clientProtocolVersion=9，自 Hive 2.3.0 起支持）。

如果需要连接 2.3.0 之前的 HiveServer2，请将客户端属性 clientProtocolVersion 设置为更小的数值。

jdbc:subprotocol://host:port[/catalog]/[schema];clientProtocolVersion=9;

提示

所有受支持的协议版本及对应的 Hive 版本可以在 TProtocolVersion.java 及其 git 提交历史中找到。

Kerberos 认证

从 1.6.0 版本起，Kyuubi JDBC 驱动基于 JAAS 框架实现 Kerberos 认证，不再依赖 Hadoop UserGroupInformation，这意味着它不再强制依赖 Hadoop 依赖项来连接启用了 Kerberos 的 Kyuubi Server。

Kyuubi JDBC 驱动支持多种连接启用了 Kerberos 的 Kyuubi Server 的方式。首先，请按照 krb5.conf 说明 正确配置 krb5.conf。

通过 Principal 和 Keytab 进行认证

1.6.0 版本新增。

提示

这是进行 Kerberos 认证最简单的方式，对配置要求最低。

使用 principal 和 keytab 进行 Kerberos 认证非常直接，只需在 JDBC URL 中配置它们即可。

jdbc:kyuubi://host:port/schema;kyuubiClientPrincipal=<clientPrincipal>;kyuubiClientKeytab=<clientKeytab>;kyuubiServerPrincipal=<serverPrincipal>
  • kyuubiClientPrincipal：用于客户端认证的 Kerberos principal
  • kyuubiClientKeytab：用于客户端认证的 Kerberos keytab 文件路径
  • kyuubiClientTicketCache：用于客户端认证的 Kerberos ticketCache 文件路径，自 1.8.0 起可用。
  • kyuubiServerPrincipal：服务端通过 kyuubi.kinit.principal 配置的 Kerberos principal。自 1.7.0 起，principal 可作为 kyuubiServerPrincipal 的别名使用，更早的版本请使用 principal。

通过 Principal 和 TGT 缓存进行认证

Kybernos 认证的另一种典型用法是：先使用 kinit 生成 TGT 缓存，然后应用程序通过该 TGT 缓存完成 Kerberos 认证。

jdbc:kyuubi://host:port/schema;kyuubiServerPrincipal=<serverPrincipal>

通过 Hadoop UserGroupInformation doAs 进行身份验证（仅限编程方式）

提示

这种方式可以让已经使用 Hadoop UserGroupInformation 进行 Kerberos 认证的项目轻松连接启用了 Kerberos 的 Kyuubi Server。该方式在 [1.6.0, 1.7.0) 区间内无法正常工作，已于 1.7.1 中修复。

String jdbcUrl = "jdbc:kyuubi://host:port/schema;kyuubiServerPrincipal=<serverPrincipal>"
UserGroupInformation ugi = UserGroupInformation.loginUserFromKeytab(clientPrincipal, clientKeytab);
ugi.doAs((PrivilegedExceptionAction<String>) () -> {
  Connection conn = DriverManager.getConnection(jdbcUrl);
  ...
});

通过 Subject 认证（仅限编程方式）

String jdbcUrl = "jdbc:kyuubi://host:port/schema;kyuubiServerPrincipal=<serverPrincipal>;kerberosAuthType=fromSubject"
Subject kerberizedSubject = ...;
Subject.doAs(kerberizedSubject, (PrivilegedExceptionAction<String>) () -> {
  Connection conn = DriverManager.getConnection(jdbcUrl);
  ...
});

评论

登录后参与评论

正在加载评论…