JDBC Catalog

Doris JDBC Catalog 支持通过标准 JDBC 接口连接不同支持 JDBC 协议的数据库。本文档介绍 JDBC Catalog 的通用配置和使用方法。

支持的数据库

Doris JDBC Catalog 支持连接以下数据库：

数据库	说明
MySQL
PostgreSQL
Oracle
SQL Server
ClickHouse
SAP HANA
OceanBase

配置

基本属性

参数	说明
type	固定为 jdbc
user	数据源用户名
password	数据源密码
jdbc_url	数据源连接 URL
driver_url	数据源 JDBC 驱动程序的路径
driver_class	数据源 JDBC 驱动程序的类名

可选属性

参数	默认值	说明
lower_case_table_names	"false"	是否以小写的形式同步 jdbc 外部数据源的库名和表名
only_specified_database	"false"	是否只同步 JDBC URL 中指定的数据源的 Database（此处的 Database 为映射到 Doris 的 Database 层级）
include_database_list	""	当 only_specified_database=true 时，指定同步多个 Database，以','分隔。Database 名称是大小写敏感的。
exclude_database_list	""	当 only_specified_database=true 时，指定不需要同步的多个 Database，以','分割。Database 名称是大小写敏感的。

连接池属性

参数	默认值	说明
connection_pool_min_size	1	定义连接池的最小连接数，用于初始化连接池并保证在启用保活机制时至少有该数量的连接处于活跃状态。
connection_pool_max_size	10	定义连接池的最大连接数，每个 Catalog 对应的每个 FE 或 BE 节点最多可持有此数量的连接。
connection_pool_max_wait_time	5000	如果连接池中没有可用连接，定义客户端等待连接的最大毫秒数。
connection_pool_max_life_time	1800000	设置连接在连接池中保持活跃的最大时长（毫秒）。超时的连接将被回收。同时，此值的一半将作为连接池的最小逐出空闲时间，达到该时间的连接将成为逐出候选对象。
connection_pool_keep_alive	false	仅在 BE 节点上有效，用于决定是否保持达到最小逐出空闲时间但未到最大生命周期的连接活跃。默认关闭，以减少不必要的资源使用。

属性须知

驱动包路径与安全性

driver_url 可以通过以下三种方式指定：

1. 文件名。如 mysql-connector-j-8.3.0.jar。需将 Jar 包预先存放在 FE 和 BE 部署目录下的 jdbc_drivers/ 目录下。系统会自动在这个目录下寻找。该目录的位置，也可以由 fe.conf 和 be.conf 中的 jdbc_drivers_dir 配置修改。

2. 本地绝对路径。如 file:///path/to/mysql-connector-j-8.3.0.jar。需将 Jar 包预先存放在所有 FE/BE 节点指定的路径下。

3. Http 地址。如：http://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.3.0/mysql-connector-j-8.3.0.jar 系统会从这个 Http 地址下载 Driver 文件。仅支持无认证的 Http 服务。

驱动包安全性

为了防止在创建 Catalog 时使用了未允许路径的 Driver Jar 包，Doris 会对 Jar 包进行路径管理和校验和检查。

1. 针对上述方式 1，Doris 默认用户配置的 jdbc_drivers_dir 和其目录下的所有 Jar 包都是安全的，不会对其进行路径检查。

2. 针对上述方式 2、3 ，Doris 会对 Jar 包的来源进行检查，检查规则如下：

   • 通过 FE 配置项 jdbc_driver_secure_path 来控制允许的驱动包路径，该配置项可配置多个路径，以分号分隔。当配置了该项时，Doris 会检查 Catalog properties 中 driver_url 的路径是的部分前缀是否在 jdbc_driver_secure_path 中，如果不在其中，则会拒绝创建 Catalog。
   • 此参数默认为 * ，表示允许所有路径的 Jar 包。
   • 如果配置 jdbc_driver_secure_path 为空，也表示允许所有路径的 Jar 包。
   备注

   如配置 jdbc_driver_secure_path = "file:///path/to/jdbc_drivers;http://path/to/jdbc_drivers" ：

   则只允许以 file:///path/to/jdbc_drivers 或 http://path/to/jdbc_drivers 开头的驱动包路径。

3. 在创建 Catalog 时，可以通过 checksum 参数来指定驱动包的校验和，Doris 会在加载驱动包后，对驱动包进行校验，如果校验失败，则会拒绝创建 Catalog。

备注

上述的校验只会在创建 Catalog 时进行，对于已经创建的 Catalog，不会再次进行校验。

小写名称同步

当 lower_case_table_names 设置为 true 时，Doris 通过维护小写名称到远程系统中实际名称的映射，能够查询非小写的数据库和表

注意：

1. 在 Doris 2.0.3 之前的版本，仅对 Oracle 数据库有效，在查询时，会将所有的库名和表名转换为大写，再去查询 Oracle，例如：

   Oracle 在 TEST 空间下有 TEST 表，Doris 创建 Catalog 时设置 lower_case_table_names 为 true，则 Doris 可以通过 select * from oracle_catalog.test.test 查询到 TEST 表，Doris 会自动将 test.test 格式化成 TEST.TEST 下发到 Oracle，需要注意的是这是个默认行为，也意味着不能查询 Oracle 中小写的表名。

   对于其他数据库，仍需要在查询时指定真实的库名和表名。

2. 在 Doris 2.0.3 及之后的 2.0.x 版本，对所有的数据库都有效，在查询时，会将所有的库名和表名转换为真实的名称，再去查询，如果是从老版本升级到 2.0.3，需要 Refresh <catalog_name> 才能生效。

   但是，如果数据库或者表名只有大小写不同，例如 Doris 和 doris，则 Doris 由于歧义而无法查询它们。

3. 当 FE 参数的 lower_case_table_names 设置为 1 或 2 时，JDBC Catalog 的 lower_case_table_names 参数必须设置为 true。如果 FE 参数的 lower_case_table_names 设置为 0，则 JDBC Catalog 的参数可以为 true 或 false，默认为 false。这确保了 Doris 在处理内部和外部表配置时的一致性和可预测性。

指定同步数据库

only_specified_database: 是否只同步 JDBC URL 中指定的数据源的 Database。默认值为 false，表示同步 JDBC URL 中所有的 Database。

include_database_list: 仅在only_specified_database=true时生效，指定需要同步的 PostgreSQL 的 Schema，以','分隔。Schema 名称是大小写敏感的。

exclude_database_list: 仅在only_specified_database=true时生效，指定不需要同步的 PostgreSQL 的 Schema，以','分隔。Schema 名称是大小写敏感的。

备注

• 上述三个参数中提到的 Database 是指 Doris 中的 Database 层级，而不是外部数据源的 Database 层级，具体的映射关系可以参考各个数据源文档。
• 当 include_database_list 和 exclude_database_list 有重合的database配置时，exclude_database_list会优先生效。

连接池配置

在 Doris 中，每个 FE 和 BE 节点都会维护一个连接池，这样可以避免频繁地打开和关闭单独的数据源连接。连接池中的每个连接都可以用来与数据源建立连接并执行查询。任务完成后，这些连接会被归还到池中以便重复使用，这不仅提高了性能，还减少了建立连接时的系统开销，并帮助防止达到数据源的连接数上限。

可以根据实际情况调整连接池的大小，以便更好地适应您的工作负载。通常情况下，连接池的最小连接数应该设置为 1，以确保在启用保活机制时至少有一个连接处于活跃状态。连接池的最大连接数应该设置为一个合理的值，以避免过多的连接占用资源。

同时为了避免在 BE 上累积过多的未使用的连接池缓存，可以通过设置 BE 的 jdbc_connection_pool_cache_clear_time_sec 参数来指定清理缓存的时间间隔。默认值为 28800 秒（8小时），此间隔过后，BE 将强制清理所有超过该时间未使用的连接池缓存。

Insert 事务

Doris 的数据是由一组 batch 的方式写入 JDBC Catalog 的，如果中途导入中断，之前写入数据可能需要回滚。所以 JDBC Catalog 支持数据写入时的事务，事务的支持需要通过设置 session variable: enable_odbc_transcation 。

set enable_odbc_transcation = true; 

事务保证了 JDBC Catalog 数据写入的原子性，但是一定程度上会降低数据写入的性能，可以考虑酌情开启该功能。

示例

此处以 MySQL 为例，展示如何创建一个 MySQL Catalog 并查询其中的数据。

创建一个名为 mysql 的 Catalog：

CREATE CATALOG mysql PROPERTIES (
    "type"="jdbc",
    "user"="root",
    "password"="secret",
    "jdbc_url" = "jdbc:mysql://example.net:3306",
    "driver_url" = "mysql-connector-j-8.3.0.jar",
    "driver_class" = "com.mysql.cj.jdbc.Driver"
)

通过运行 SHOW DATABASES 查看此 Catalog 所有数据库：

SHOW DATABASES FROM mysql;

如果您有一个名为 test 的 MySQL 数据库，您可以通过运行 SHOW TABLES 查看该数据库中的表：

SHOW TABLES FROM mysql.test;

最后，您可以访问 MySQL 数据库中的表：

SELECT * FROM mysql.test.table;