Apache Zeppelin 的通用 JDBC 解释器

概述

JDBC解释器允许您无缝地创建到任何数据源的JDBC连接。

插入、更新和更新插入操作在运行每条语句后立即应用。

到目前为止，已经测试过：

Postgresql - JDBC Driver

Mysql - JDBC Driver

MariaDB - JDBC Driver

Redshift - JDBC Driver

Apache Hive - JDBC Driver

Presto/Trino - JDBC Driver

Impala - JDBC Driver

Apache Phoenix itself is a JDBC driver

Apache Drill - JDBC Driver

Apache Tajo - JDBC Driver

如果您使用的是上述列表中未包含的其他数据库，请随时分享您的使用案例。这将有助于改进JDBC解释器的功能。

创建一个新的JDBC解释器

首先，点击解释器设置页面右上角的+ Create按钮。

在Interpreter name字段中填写您想要使用的别名（例如mysql, mysql2, hive, redshift等）。请注意，此别名将用作%interpreter_name以在段落中调用解释器。然后选择jdbc作为Interpreter group。

JDBC解释器的默认驱动程序设置为PostgreSQL。这意味着Zeppelin本身包含了PostgreSQL驱动程序的jar包。因此，您不需要为PostgreSQL连接添加任何依赖项（例如PostgreSQL驱动程序jar的工件名称或路径）。 JDBC解释器的属性默认定义如下。

名称	默认值	描述
common.max_count	1000	显示SQL结果的最大数量
default.driver	org.postgresql.Driver	JDBC 驱动名称
default.password		JDBC 用户密码
default.url	jdbc:postgresql://localhost:5432/	JDBC的URL
default.user	gpadmin	JDBC 用户名
default.precode		每次解释器初始化后执行的SQL（参见绑定模式）
default.statementPrecode		在同一个数据库会话（数据库连接）中，在段落中的SQL之前执行的SQL代码
default.completer.schemaFilters		逗号分隔的模式（模式 = 目录 = 数据库）过滤器，用于获取完成元数据。支持'%'符号，相当于任何字符集。（例如：prod_v_%,public%,info）
default.completer.ttlInSeconds	120	SQL 补全器的存活时间（以秒为单位）（-1 表示每次更新，0 表示禁用更新）

如果你想连接其他数据库，如Mysql、Redshift和Hive，你需要编辑属性值。你也可以使用Credential进行JDBC认证。如果在解释器设置页面中删除了数据库连接的default.user和default.password属性（使用X按钮）， JDBC解释器将从Credential获取账户信息。

下面的示例是用于 Mysql 连接的。

最后一步是依赖设置。由于Zeppelin默认只包含PostgreSQL驱动jar，因此您需要为其他数据库添加每个驱动的Maven坐标或JDBC驱动的jar文件路径。

就是这样。你可以在本节中找到更多的JDBC连接设置示例（Mysql, MariaDB, Redshift, Apache Hive, Presto/Trino, Impala, Apache Kyuubi, Apache Phoenix, 和 Apache Tajo）。

JDBC 解释器数据源池配置

Jdbc解释器使用连接池技术，并支持用户对连接池进行一些个性化配置。例如，我们可以在解释器配置中配置default.validationQuery='select 1'和default.testOnBorrow=true，以避免通过JDBC解释器连接HiveServer2时因会话超时导致的“Invalid SessionHandle”运行时错误。

Jdbc 解释器支持以下数据库连接池配置：

属性名称	默认值	描述
testOnBorrow	false	指示在从池中借用对象之前是否对其进行验证。如果对象验证失败，它将被从池中移除，我们将尝试借用另一个对象。
testOnCreate	false	指示对象在创建后是否会被验证。如果对象验证失败，触发对象创建的借用尝试将失败。
testOnReturn	false	指示在将对象返回到池之前是否对其进行验证。
testWhileIdle	false	指示空闲对象驱逐器（如果有）是否将验证对象。如果对象验证失败，它将被从池中移除。
timeBetweenEvictionRunsMillis	-1L	空闲对象驱逐线程运行之间的睡眠毫秒数。当值为非正数时，不会运行空闲对象驱逐线程。
maxWaitMillis	-1L	连接池在没有可用连接时，抛出异常前等待连接返回的最大毫秒数，或-1表示无限等待。
maxIdle	8	连接池中可以保持空闲的最大连接数，超过这个数目的空闲连接将被释放，负数表示没有限制。
minIdle	0	连接池中可以保持空闲的最小连接数，不会创建额外的连接，或者为零则不创建。
maxTotal	-1	可以从该池同时分配的最大活动连接数，负数表示无限制。
validationQuery	show database	用于在将连接返回给调用者之前验证此池中的连接的SQL查询。如果指定，此查询必须是一个SQL SELECT语句，并且至少返回一行。如果未指定，将通过调用isValid()方法来验证连接。

属性名称	描述
common.max_result	显示SQL结果的最大数量，以防止浏览器过载。这是所有连接的通用属性
zeppelin.jdbc.auth.type	支持的认证方法类型有 `SIMPLE` 和 `KERBEROS`
zeppelin.jdbc.principal	从keytab加载的主体名称
zeppelin.jdbc.keytab.location	keytab文件的路径
zeppelin.jdbc.auth.kerberos.proxy.enable	当认证类型为Kerberos时，启用/禁用使用登录用户的Kerberos代理来获取连接。默认值为true。
default.jceks.file	jceks 存储路径 (例如: jceks://file/tmp/zeppelin.jceks)
default.jceks.credentialKey	jceks 凭证密钥
zeppelin.jdbc.interpolation	启用ZeppelinContext变量插入到段落文本中。默认值为false。
zeppelin.jdbc.maxConnLifetime	连接的最大生命周期，以毫秒为单位。零或更小的值表示连接具有无限的生命周期。

名称	值
default.schema	schema_name

如何使用

使用JDBC解释器运行段落

要测试您的数据库和Zeppelin是否成功连接，请在段落的顶部输入%jdbc_interpreter_name（例如%mysql）并运行show databases。

%jdbc_interpreter_name

show databases

如果段落FINISHED没有任何错误，一个新的段落将自动添加在前一个段落后，使用%jdbc_interpreter_name。因此，您不需要在每个段落的标题中键入此前缀。

多个SQL语句

你可以在一个段落中写多个SQL语句，只需用分号分隔它们。例如

%jdbc_interpreter_name

USE zeppelin_demo;

CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
       species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);

SQL 注释

支持两种SQL注释：

单行注释以 -- 开始
多行注释使用 /* ... */ 包围

%jdbc_interpreter_name

-- single line comment
show tables;
/* multiple 
   line 
   comment
 */
select * from test_1;

应用Zeppelin动态表单

您可以在查询中利用Zeppelin动态表单。您可以使用文本输入和选择表单参数化功能。

持续运行SQL

默认情况下，一段中的SQL语句只执行一次。但你可以通过指定本地属性refreshInterval（单位：毫秒）来连续运行它，这样SQL语句就会每隔refreshInterval毫秒执行一次。当数据库中的数据由外部系统持续更新时，这非常有用，你可以通过这种方法在Zeppelin中构建动态仪表板。

例如，这里我们查询由其他外部系统持续更新的mysql。

用法 precode

您可以为每个数据源设置precode。代码在打开连接时运行一次。

属性

两个数据源的解释器设置示例，每个数据源都有其precode参数。

属性名称	值
default.driver	org.postgresql.Driver
默认密码	1
default.url	jdbc:postgresql://localhost:5432/
默认用户	postgres
default.precode	set search_path='test_path'

默认驱动程序	com.mysql.jdbc.Driver
默认密码	1
default.url	jdbc:mysql://localhost:3306/
默认用户	root
default.precode	set @v=12

用法

测试每个数据源的执行precode。

%jdbc

show search_path

返回在默认的JDBC（使用PostgreSQL）解释器的default.precode中设置的search_path的值。

%mysql

select @v

返回在mysql解释器的default.precode中设置的v的值。

示例

以下是一些你可以参考的例子。包括以下连接器，只要可以配置其JDBC驱动程序，你就可以连接每个数据库。

Postgres

属性

名称	值
default.driver	org.postgresql.Driver
default.url	jdbc:postgresql://localhost:5432/
默认用户	mysql_user
默认密码	mysql_password

Postgres JDBC 驱动文档

依赖项

工件	排除项
org.postgresql:postgresql:42.3.3

Maven 仓库: org.postgresql:postgresql

Mysql

属性

名称	值
默认驱动程序	com.mysql.jdbc.Driver
default.url	jdbc:mysql://localhost:3306/
默认用户	mysql_user
默认密码	mysql_password

Mysql JDBC Driver Docs

依赖项

工件	排除项
mysql:mysql-connector-java:5.1.38

Maven 仓库: mysql:mysql-connector-java

MariaDB

属性

名称	值
default.driver	org.mariadb.jdbc.Driver
default.url	jdbc:mariadb://localhost:3306
默认用户	mariadb_user
默认密码	mariadb_password

MariaDB JDBC 驱动文档

依赖项

工件	排除项
org.mariadb.jdbc:mariadb-java-client:1.5.4

Maven 仓库: org.mariadb.jdbc:mariadb-java-client

红移

属性

名称	值
default.driver	com.amazon.redshift.jdbc42.Driver
default.url	jdbc:redshift://your-redshift-instance-address.redshift.amazonaws.com:5439/your-database
default.user	redshift_user
默认密码	redshift_password

AWS Redshift JDBC 驱动文档

依赖项

工件	排除项
com.amazon.redshift:redshift-jdbc42:2.1.0.18

Maven 仓库: com.amazon.redshift:redshift-jdbc42

Apache Hive

Zeppelin 只是通过 hiveserver2 使用 hive jdbc 来运行 hive sql。连接 Hive 有两种情况：

连接到没有KERBEROS的Hive
使用KERBEROS连接到Hive

每种情况需要不同的设置。

连接到没有KERBEROS的Hive

在这种情况下，您至少需要进行以下设置。默认情况下，hive作业以default.user用户身份运行。如果您希望在启用身份验证时hive作业以Zeppelin登录用户身份运行，请参考impersonation。

名称	值
default.driver	org.apache.hive.jdbc.HiveDriver
default.url	jdbc:hive2://localhost:10000
default.user	hive_user

工件	排除项
org.apache.hive:hive-jdbc:2.3.4

使用KERBEROS连接到Hive

在这种情况下，您至少需要进行以下设置。默认情况下，hive作业以客户端主体的用户身份运行（zeppelin.jdbc.principal）。如果您希望在启用身份验证时hive作业以Zeppelin登录用户的身份运行，请参考impersonation。

名称	值
default.driver	org.apache.hive.jdbc.HiveDriver
default.url	jdbc:hive2://emr-header-1:10000/default;principal={hive_server2_principal}
zeppelin.jdbc.auth.type	KERBEROS
zeppelin.jdbc.keytab.location	客户端的keytab
zeppelin.jdbc.principal	客户端的主体

工件	排除项
org.apache.hive:hive-jdbc:2.3.4
org.apache.hive:hive-exec:2.3.4

Maven 仓库 : org.apache.hive:hive-jdbc

模拟

当Zeppelin服务器启用身份验证运行时，解释器可以利用Hive的用户代理功能，即发送额外的参数来创建和运行会话（"hive.server2.proxy.user=": "${loggedInUser}"）。这在多个用户共享一个笔记本时特别有用。

要启用此设置，请设置以下内容：

default.proxy.user.property 作为 hive.server2.proxy.user

请参阅解释器中的用户模拟以获取更多信息。

示例配置

名称	值
default.driver	org.apache.hive.jdbc.HiveDriver
default.url	jdbc:hive2://hive-server-host:2181/;serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=hiveserver2
默认代理用户属性	默认服务器2代理用户
zeppelin.jdbc.auth.type	SIMPLE

有关Hive解释器的更多属性，请参见Hive Interpreter。

Presto/Trino

属性

名称	值
default.driver	io.prestosql.jdbc.PrestoDriver
default.url	jdbc:presto://presto-server:9090/hive
默认用户	presto_user

Trino JDBC 驱动文档
 Presto JDBC 驱动文档

依赖项

工件	排除项
io.prestosql:presto-jdbc:350

Impala

属性

名称	值
default.driver	org.apache.hive.jdbc.HiveDriver
default.url	jdbc:hive2://emr-header-1.cluster-47080:21050/;auth=noSasl

依赖项

工件	排除项
org.apache.hive:hive-jdbc:2.3.4

Impala JDBC 驱动文档

依赖项

工件	排除项
io.prestosql:presto-jdbc:350

Apache Kyuubi

Zeppelin 连接到 Kyuubi 通过 KyuubiHiveDriver 运行 SQL。与 Kyuubi 连接有两种情况：

连接到Kyuubi而不使用KERBEROS
使用KERBEROS连接到Kyuubi

每种情况需要不同的设置。

连接到没有KERBEROS的Kyuubi

在这种情况下，您至少需要进行以下设置。Kyuubi引擎以default.user的用户身份运行。

属性

名称	值
default.driver	org.apache.kyuubi.jdbc.KyuubiHiveDriver
default.url	jdbc:hive2://kyuubi-server:10009

依赖项

工件	排除项
org.apache.kyuubi:kyuubi-hive-jdbc-shaded:1.6.1-incubating
org.apache.hive:hive-jdbc:3.1.2

使用KERBEROS连接到Kyuubi

在这种情况下，您至少需要进行以下设置。Kyuubi引擎以客户端主体的用户身份运行（zeppelin.jdbc.principal）。

属性

名称	值
default.driver	org.apache.kyuubi.jdbc.KyuubiHiveDriver
default.url	jdbc:hive2://kyuubi-server:10009/default;principal={kyuubi_principal}
zeppelin.jdbc.auth.type	KERBEROS
zeppelin.jdbc.keytab.location	客户端的keytab
zeppelin.jdbc.principal	客户端的主体

依赖项

工件	排除项
org.apache.kyuubi:kyuubi-hive-jdbc-shaded:1.6.1-incubating
org.apache.hive:hive-jdbc:3.1.2

Apache Phoenix

Phoenix 支持 thick 和 thin 连接类型：

Thick client 速度更快，但必须直接连接到 ZooKeeper 和 HBase RegionServers。
Thin client 依赖较少，并通过 Phoenix Query Server 实例进行连接。

使用适当的 default.driver、default.url 以及适合您连接类型的依赖项工件。

厚客户端连接

属性

名称	值
default.driver	org.apache.phoenix.jdbc.PhoenixDriver
default.url	jdbc:phoenix:localhost:2181:/hbase-unsecure
default.user	phoenix_user
默认密码	phoenix_password

依赖项

工件	排除项
org.apache.phoenix:phoenix-core:4.4.0-HBase-1.0

Maven 仓库: org.apache.phoenix:phoenix-core

瘦客户端连接

属性

名称	值
default.driver	org.apache.phoenix.queryserver.client.Driver
default.url	jdbc:phoenix:thin:url=http://localhost:8765;serialization=PROTOBUF
default.user	phoenix_user
default.password	phoenix_password

依赖项

在添加以下依赖项之前，请先检查Phoenix版本。

工件	排除	描述
org.apache.phoenix:phoenix-server-client:4.7.0-HBase-1.1		适用于 Phoenix `4.7`
org.apache.phoenix:phoenix-queryserver-client:4.8.0-HBase-1.2		适用于 Phoenix `4.8+`

Maven 仓库: org.apache.phoenix:phoenix-queryserver-client

Apache Tajo

属性

名称	值
default.driver	org.apache.tajo.jdbc.TajoDriver
default.url	jdbc:tajo://localhost:26002/default

Apache Tajo JDBC 驱动文档

依赖项

工件	排除项
org.apache.tajo:tajo-jdbc:0.11.2

Maven 仓库: org.apache.tajo:tajo-jdbc

对象插值

JDBC 解释器还支持将 ZeppelinContext 对象插入到段落文本中。以下示例展示了此功能的一种用法：

在Scala单元格中：

z.put("country_code", "KR")
    // ...

在后面的JDBC单元格中：

%jdbc_interpreter_name

select * from patents_list where 
priority_country = '{country_code}' and filing_date like '2015-%'

默认情况下，对象插值是禁用的，可以通过将属性zeppelin.jdbc.interpolation的值设置为true来为JDBC解释器的所有实例启用（参见上面的更多属性）。有关此功能的更多详细信息，可以在Spark解释器文档中的Zeppelin-Context下找到。

错误报告

如果您在使用JDBC解释器时发现了一个错误，请创建一个JIRA工单。