StarRocks Catalog中的JDBC catalog实操（超详细）

StarRocks 自 2.3 版本起支持 Catalog（数据目录）功能，实现在一套系统内同时维护内、外部数据，方便您轻松访问并查询存储在各类外部源的数据。

• 内部数据：指保存在 StarRocks 中的数据。
• 外部数据：指保存在外部数据源（如 Apache Hive™、Apache Iceberg、Apache Hudi、Delta Lake、JDBC）中的数据。

当前 StarRocks 提供两种类型 Catalog：internal catalog 和 external catalog。

• Internal catalog: 内部数据目录，用于管理 StarRocks 所有内部数据。例如，执行 CREATE DATABASE 和 CREATE TABLE 语句创建的数据库和数据表都由 internal catalog 管理。 每个 StarRocks 集群都有且只有一个 internal catalog 名为 default_catalog。

• External catalog: 外部数据目录，用于连接外部 metastore。在 StarRocks 中，您可以通过 external catalog 直接查询外部数据，无需进行数据导入或迁移。当前支持创建以下类型的 external catalog：

• Hive catalog：用于查询 Hive 集群中的数据。
• Iceberg catalog：用于查询 Iceberg 集群中的数据。
• Hudi catalog：用于查询 Hudi 集群中的数据。
• Delta Lake catalog：用于查询 Delta Lake 集群中的数据。
• JDBC catalog：用于查询 JDBC 数据源中的数据。
• Elasticsearch catalog：用于查询 Elasticsearch 中的数据。该特性自 3.1 版本起支持。
• Paimon catalog：用于查询 Paimon 中的数据。该特性自 3.1 版本起支持。
• Unified catalog：把 Hive、Iceberg、Hudi 和 Delta Lake 作为一个融合的数据源，从中查询数据。该特性自 3.2 版本起支持。

使用 external catalog 查询数据时，StarRocks 会用到外部数据源的两个组件：

• 元数据服务：用于将元数据暴露出来供 StarRocks 的 FE 进行查询规划。
• 存储系统：用于存储数据。数据文件以不同的格式存储在分布式文件系统或对象存储系统中。当 FE 将生成的查询计划分发给各个 BE（或 CN）后，各个 BE（或 CN）会并行扫描 Hive 存储系统中的目标数据，并执行计算返回查询结果。

今天我们实操的是JDBC catalog 用于查询 JDBC 数据源中的数据。

JDBC catalog

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

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

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

JDBC Catalog 自 3.0 版本开始支持 MySQL、PostgreSQL，自 3.2.9、3.3.1 版本开始支持 Oracle 和 SQLServer。自 3.3.0 开始支持 ClickHouse（试验性）

前提条件

• 确保 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）。

前置准备

我们现在有一个StarRocks集群，还有一个MySQL数据库的主机，我们先在这个MySQL数据库创建一个表，并输入数据

MySQL

mysql> create database testdb; Query OK, 1 row affected (0.04 sec) mysql> use testdb Database changed mysql> CREATE TABLE test_user ( -> uid int primary key, -> name varchar(64), -> age int, -> phone varchar(16) -> ); Query OK, 0 rows affected (0.21 sec) mysql> insert into test_user values( -> 1,"小红",19,"17852322252" -> ); Query OK, 1 row affected (0.03 sec) mysql> insert into test_user values( -> 2,"小黄",20,"15896324458" -> ); Query OK, 1 row affected (0.03 sec) mysql> insert into test_user values( -> 3,"小贾",19,"18512635552" -> ); Query OK, 1 row affected (0.02 sec) mysql> select * from test_user; +-----+--------+------+-------------+ | uid | name | age | phone | +-----+--------+------+-------------+ | 1 | 小红 | 19 | 17852322252 | | 2 | 小黄 | 20 | 15896324458 | | 3 | 小贾 | 19 | 18512635552 | +-----+--------+------+-------------+ 3 rows in set (0.00 sec)

然后我们进入StarRocks客户端

mysql -uroot -P9030 -h127.0.0.1 -p

先查看一下当前StarRocks集群里所有的Catalog：

mysql> SHOW CATALOGS; +-----------------+----------+------------------------------------------------------------------+ | Catalog | Type | Comment | +-----------------+----------+------------------------------------------------------------------+ | default_catalog | Internal | An internal catalog contains this cluster's self-managed tables. | +-----------------+----------+------------------------------------------------------------------+ 1 row in set (0.01 sec)

可以看到这里有一个default_catalog，这是StarRocks2.3及以上版本提供的 Internal Catalog（内部数据目录），用于管理 StarRocks 的内部数据。每个 StarRocks 集群都有且只有一个 Internal Catalog，名为default_catalog。StarRocks 暂不支持修改 Internal Catalog 的名称，也不支持创建新的 Internal Catalog。

创建 JDBC Catalog

创建的语法

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

catalog_name命名一个catalog标识，因为我们创建的是JDBC catalog，所以我这里是jdbc_test_mysql（与MySQL连接）

[ ]里面的东西代表可选，其中comment 是描述可选

重要的就是properties参数，包含以下必填配置项

可选 Oracle 属性

当driver_class设置为 Oracle 时，您可以配置以下可选属性：

说明

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

已经了解创建的语法和参数之后我们现在来创建一个MySQL的JDBC Catelog

CREATE EXTERNAL CATALOG jdbc_test_mysql PROPERTIES ( "type"="jdbc", "user"="root", "password"="mysql@123", "jdbc_uri"="jdbc:mysql://198.155.125.147: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" ); -- 过程 mysql> CREATE EXTERNAL CATALOG jdbc_test_mysql -> PROPERTIES -> ( -> "type"="jdbc", -> "user"="root", -> "password"="mysql@123", -> "jdbc_uri"="jdbc:mysql://198.155.125.147: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" -> ); Query OK, 0 rows affected (3.61 sec)

198.155.125.147是我MySQL数据库主机打IP，3306是MySQL的端口

还有其他不同的JDBC Catalog，根据需要的来（创建实例）：

-- PostgresSQL 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" ); -- Oracle CREATE EXTERNAL CATALOG jdbc2 PROPERTIES ( "type"="jdbc", "user"="root", "password"="changeme", "jdbc_uri"="jdbc:oracle:thin:@127.0.0.1:1521:ORCL", "driver_url"="https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc10/19.18.0.0/ojdbc10-19.18.0.0.jar", "driver_class"="oracle.jdbc.driver.OracleDriver" ); -- Oracle (with Oracle-specific optional properties) CREATE EXTERNAL CATALOG jdbc2_ext PROPERTIES ( "type"="jdbc", "user"="root", "password"="changeme", "jdbc_uri"="jdbc:oracle:thin:@127.0.0.1:1521/ORCLPDB1", "driver_url"="https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc10/19.18.0.0/ojdbc10-19.18.0.0.jar", "driver_class"="oracle.jdbc.driver.OracleDriver", "oracle.number.default-scale"="6", "oracle.temporal.to-datetime"="true", "oracle.timestamptz.to-datetime"="true" ); -- SQL Server CREATE EXTERNAL CATALOG jdbc3 PROPERTIES ( "type"="jdbc", "user"="root", "password"="changeme", "jdbc_uri"="jdbc:sqlserver://127.0.0.1:1433;databaseName=MyDatabase;", "driver_url"="https://repo1.maven.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.4.2.jre11/mssql-jdbc-12.4.2.jre11.jar", "driver_class"="com.microsoft.sqlserver.jdbc.SQLServerDriver" ); -- ClickHouse CREATE EXTERNAL CATALOG jdbc4 PROPERTIES ( "type"="jdbc", "user"="default", "jdbc_uri"="jdbc:clickhouse://127.0.0.1:8443", "driver_url"="https://repo1.maven.org/maven2/com/clickhouse/clickhouse-jdbc/0.4.6/clickhouse-jdbc-0.4.6.jar", "driver_class"="com.clickhouse.jdbc.ClickHouseDriver" );

如果出现

"Malformed database URL, failed to parse the main URL sections"

一般来说是jdbc_uri中传入的参数有误，确认好ip是否正确等

查看JDBC Catalog

通过SHOW CATALOGS;查询当前所在 StarRocks 集群里所有 Catalog：

mysql> show catalogs; +-----------------+----------+------------------------------------------------------------------+ | Catalog | Type | Comment | +-----------------+----------+------------------------------------------------------------------+ | default_catalog | Internal | An internal catalog contains this cluster's self-managed tables. | | jdbc_test_mysql | Jdbc | NULL | +-----------------+----------+------------------------------------------------------------------+ 2 rows in set (0.01 sec)

可以看到我们创建的JDBC catalog已经创建好了，可以通过SHOW CREATE CATALOG查询某个external catalog的创建语句

mysql> SHOW CREATE CATALOG jdbc_test_mysql; +-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Catalog | Create Catalog | +-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | jdbc_test_mysql | CREATE EXTERNAL CATALOG `jdbc_test_mysql` PROPERTIES ("driver_class" = "com.mysql.cj.jdbc.Driver", "checksum" = "95cde01c78e7b04e13305338d60e056a", "driver_url" = "https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.28/mysql-connector-java-8.0.28.jar", "type" = "jdbc", "user" = "root", "jdbc_uri" = "jdbc:mysql://198.155.125.147:3306" ) | +-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 1 row in set (0.00 sec)

现在已经创建好了

查询 JDBC Catalog 中的表数据

通过 ​​​​​​SHOW DATABASE FROM查看指定 Catalog 所属的集群中的数据库：

mysql> SHOW DATABASES FROM jdbc_test_mysql; +--------------------+ | Database | +--------------------+ | information_schema | | testdb | +--------------------+ 2 rows in set (0.01 sec)

可以看到我们在MySQL主机上创建的数据库testdb

通过SET CATALOG切换当前会话生效的 Catalog：

mysql> SET CATALOG jdbc_test_mysql; Query OK, 0 rows affected (0.00 sec)

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

mysql> use testdb; Reading table information for completion of table and column names You can turn off this feature to get a quicker startup with -A Database changed mysql> show tables; +------------------+ | Tables_in_testdb | +------------------+ | test_user | +------------------+ 1 row in set (0.01 sec)

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

mysql> use jdbc_test_mysql.testdb; Reading table information for completion of table and column names You can turn off this feature to get a quicker startup with -A Database changed mysql> show tables; +------------------+ | Tables_in_testdb | +------------------+ | test_user | +------------------+ 1 row in set (0.01 sec)

通过SELECT查询数据库中的目标表（要执行上面的命令进入到MySQL目标数据库才能查看）

mysql> select * from test_user; +------+--------+------+-------------+ | uid | name | age | phone | +------+--------+------+-------------+ | 1 | 小红 | 19 | 17852322252 | | 2 | 小黄 | 20 | 15896324458 | | 3 | 小贾 | 19 | 18512635552 | +------+--------+------+-------------+ 3 rows in set (0.26 sec)

退出刚才进入会话生效的jdbc_test_mysql catalog

只需要进入到默认catalog即可（StarRocks默认：default_catalog)

mysql> set catalog default_catalog; Query OK, 0 rows affected (0.00 sec) mysql> show databases; +--------------------+ | Database | +--------------------+ | _statistics_ | | information_schema | | sys | +--------------------+ 3 rows in set (0.00 sec) mysql>

删除 JDBC Catalog

mysql> DROP Catalog jdbc_test_mysql; Query OK, 0 rows affected (0.05 sec) mysql> show catalogs; +-----------------+----------+------------------------------------------------------------------+ | Catalog | Type | Comment | +-----------------+----------+------------------------------------------------------------------+ | default_catalog | Internal | An internal catalog contains this cluster's self-managed tables. | +-----------------+----------+------------------------------------------------------------------+ 1 row in set (0.00 sec)

我部署的集群是从CLup一键部署的，可以看看CLup官网也可以看看我这篇部署的文章CLup使用：一键创建StarRocks存算一体集群

https://www.csudata.com/clup/manualhttps://www.csudata.com/clup/manual