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

m0_73669661

463人浏览 · 2026-05-21 16:34:21

m0_73669661 · 2026-05-21 16:34:21 发布

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参数，包含以下必填配置项

参数	说明
type	资源类型，固定取值为 `jdbc`。
user	目标数据库登录用户名。
password	目标数据库用户登录密码。
jdbc_uri	JDBC 驱动程序连接目标数据库的 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.jar` 和 `file:///home/disk1/postgresql-42.3.3.jar`。说明您也可以把 JDBC 驱动程序部署在 FE 或 BE（或 CN）所在节点上任意相同路径下，然后把 `driver_url` 设置为该路径，格式为 `file:///<path>/to/the/driver`。
driver_class	JDBC 驱动程序的类名称。以下是常见数据库引擎支持的 JDBC 驱动程序类名称： MySQL：`com.mysql.jdbc.Driver`（MySQL 5.x 及之前版本）、`com.mysql.cj.jdbc.Driver`（MySQL 6.x 及之后版本） PostgreSQL: `org.postgresql.Driver` Oracle: `oracle.jdbc.driver.OracleDriver`
schema_resolver	（可选）显式指定要使用的 Schema Resolver。有效值：`postgresql`、`mysql`、`oracle`、`sqlserver`、`clickhouse`。当使用非标准 JDBC 驱动程序且无法通过驱动类名自动检测时，请使用此参数。如果未指定，StarRocks 将根据 `driver_class` 参数自动检测相应的 Resolver。

可选 Oracle 属性

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

参数	默认	描述
oracle.number.default-scale	6	当 Oracle `NUMBER` 元数据未明确指定精度和规模时，请设置此参数。有效范围：`0` 至 `38`。
oracle.temporal.to-datetime	false	控制 Oracle `DATE`、`TIMESTAMP` 和 `TIMESTAMP WITH LOCAL TIME ZONE` 的映射。如果设置为 `true`，这些数据类型将映射到 StarRocks 的 `DATETIME` 类型；否则，`DATE` 保持为 `DATE`，而 `TIMESTAMP` / `TIMESTAMP WITH LOCAL TIME ZONE` 将映射到 `VARCHAR(64)`。
oracle.timestamptz.to-datetime	false	控制 Oracle `TIMESTAMP WITH TIME ZONE` 的映射。如果设置为 `true`，则映射为 StarRocks 的 `DATETIME` 类型；否则，则映射为 `VARCHAR(64)`。

说明

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

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

3分钟掌握Codex技能安装：一键部署你的AI助手工具库

想要为你的Codex AI助手安装新技能？不用再手动复制文件了！skill-installer为你提供了一套完整的解决方案，让你能够从GitHub仓库快速获取和安装各种实用的Codex技能。无论你是AI开发新手还是经验丰富的开发者，这个工具都能让你在几分钟内扩展Codex的功能边界。## 为什么选择skill-installer？ 🤔在AI辅助编程的时代，Codex技能已经成为提升开发效

AI编程社区

DB-GPT分布式AI数据引擎：企业级智能分析平台架构解析

DB-GPT作为新一代AI数据助手，通过分布式架构和智能代理引擎重构了传统数据分析范式。该平台将大型语言模型的自然语言理解能力与企业级数据处理需求深度融合，构建了面向生产环境的可扩展AI数据平台。其核心价值在于将复杂的SQL生成、数据分析和可视化任务转化为简单的自然语言交互，同时确保系统安全性、可追溯性和企业级可靠性。## 技术定位与生态分析在当前数据智能生态中，DB-GPT填补了传统BI

AI编程社区

如何用Awesome Claude Skills将AI助手打造成你的全能创作伙伴和职业顾问

你是否曾想过，如果有一个AI伙伴能帮你完成从专业文章撰写到完美简历定制的所有工作，工作效率会提升多少倍？Awesome Claude Skills正是这样一个神奇的AI技能宝库，它汇集了1000+个精心筛选的Claude技能，覆盖内容创作、职业发展、文档处理等各个方面，让你在AI的帮助下轻松应对各种工作挑战。## 痛点分析：传统工作流程的三大瓶颈在内容创作和职业发展中，我们常常面临这样的困