跳到主要内容
版本:Stable-3.1

JDBC catalog

StarRocks 从 3.0 版本开始支持 JDBC Catalog。

JDBC Catalog 是一种 External Catalog。通过 JDBC Catalog,您不需要执行数据导入就可以直接查询 JDBC 数据源里的数据。

此外,您还可以基于 JDBC Catalog ,结合 INSERT INTO 能力对 JDBC 数据源的数据实现转换和导入。

目前 JDBC Catalog 支持 MySQL 和 PostgreSQL。

前提条件

  • 确保 FE 和 BE(或 CN)可以通过 driver_url 指定的下载路径,下载所需的 JDBC 驱动程序。
  • BE(或 CN)所在机器的启动脚本 $BE_HOME/bin/start_be.sh 中需要配置 JAVA_HOME,要配置成 JDK 环境,不能配置成 JRE 环境,比如 export JAVA_HOME = <JDK 的绝对路径>。注意需要将该配置添加在 BE(或 CN)启动脚本最开头,添加完成后需重启 BE(或 CN)。

创建 JDBC Catalog

语法

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES ("key"="value", ...)

参数说明

catalog_name

JDBC Catalog 的名称。命名要求如下:

  • 必须由字母 (a-z 或 A-Z)、数字 (0-9) 或下划线 (_) 组成,且只能以字母开头。
  • 总长度不能超过 1023 个字符。
  • Catalog 名称大小写敏感。

comment

JDBC Catalog 的描述。此参数为可选。

PROPERTIES

JDBC Catalog 的属性,包含如下必填配置项:

参数说明
type资源类型,固定取值为 jdbc
user目标数据库登录用户名。
password目标数据库用户登录密码。
jdbc_uriJDBC 驱动程序连接目标数据库的 URI。如果使用 MySQL,格式为:"jdbc:mysql://ip:port"。如果使用 PostgreSQL,格式为 "jdbc:postgresql://ip:port/db_name"
driver_url用于下载 JDBC 驱动程序 JAR 包的 URL。支持使用 HTTP 协议或者 file 协议,例如https://repo1.maven.org/maven2/org/postgresql/postgresql/42.3.3/postgresql-42.3.3.jarfile:///home/disk1/postgresql-42.3.3.jar
说明
您也可以把 JDBC 驱动程序部署在 FE 或 BE(或 CN)所在节点上任意相同路径下,然后把 driver_url 设置为该路径,格式为 file:///<path>/to/the/driver
driver_classJDBC 驱动程序的类名称。以下是常见数据库引擎支持的 JDBC 驱动程序类名称:
  • MySQL:com.mysql.jdbc.Driver(MySQL 5.x 及之前版本)、com.mysql.cj.jdbc.Driver(MySQL 6.x 及之后版本)
  • PostgreSQL: org.postgresql.Driver

说明

FE 会在创建 JDBC Catalog 时去获取 JDBC 驱动程序,BE(或 CN)会在第一次执行查询时去获取驱动程序。获取驱动程序的耗时跟网络条件相关。

创建示例

以下示例创建了两个 JDBC Catalog:jdbc0jdbc1

CREATE EXTERNAL CATALOG jdbc0
PROPERTIES
(
"type"="jdbc",
"user"="postgres",
"password"="changeme",
"jdbc_uri"="jdbc:postgresql://127.0.0.1:5432/jdbc_test",
"driver_url"="https://repo1.maven.org/maven2/org/postgresql/postgresql/42.3.3/postgresql-42.3.3.jar",
"driver_class"="org.postgresql.Driver"
);

CREATE EXTERNAL CATALOG jdbc1
PROPERTIES
(
"type"="jdbc",
"user"="root",
"password"="changeme",
"jdbc_uri"="jdbc:mysql://127.0.0.1:3306",
"driver_url"="https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.28/mysql-connector-java-8.0.28.jar",
"driver_class"="com.mysql.cj.jdbc.Driver"
);

查看 JDBC Catalog

您可以通过 SHOW CATALOGS 查询当前所在 StarRocks 集群里所有 Catalog:

SHOW CATALOGS;

您也可以通过 SHOW CREATE CATALOG 查询某个 External Catalog 的创建语句。例如,通过如下命令查询 JDBC Catalog jdbc0 的创建语句:

SHOW CREATE CATALOG jdbc0;

删除 JDBC Catalog

您可以通过 DROP CATALOG 删除一个 JDBC Catalog。

例如,通过如下命令删除 JDBC Catalog jdbc0

DROP Catalog jdbc0;

查询 JDBC Catalog 中的表数据

  1. 通过 SHOW DATABASES 查看指定 Catalog 所属的集群中的数据库:

    SHOW DATABASES FROM <catalog_name>;
  2. 通过 SET CATALOG 切换当前会话生效的 Catalog:

    SET CATALOG <catalog_name>;

    再通过 USE 指定当前会话生效的数据库:

    USE <db_name>;

    或者,也可以通过 USE 直接将会话切换到目标 Catalog 下的指定数据库:

    USE <catalog_name>.<db_name>;
  3. 通过 SELECT 查询目标数据库中的目标表:

    SELECT * FROM <table_name>;

常见问题

系统返回 "Malformed database URL, failed to parse the main URL sections" 报错应该如何处理?

该报错通常是由于 jdbc_uri 中传入的 URI 有误而引起的。请检查并确保传入的 URI 是否正确无误。参见本文“PROPERTIES”小节相关的参数说明。