版本：3.2

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。

前提条件

确保 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_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`

说明

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

创建示例

以下示例创建了两个 JDBC Catalog：jdbc0 和 jdbc1。

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"
);
 
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"
);
       
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"
);

查看 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 中的表数据

通过 SHOW DATABASES 查看指定 Catalog 所属的集群中的数据库：
```
SHOW DATABASES FROM <catalog_name>;
```
通过 SET CATALOG 切换当前会话生效的 Catalog：
```
SET CATALOG <catalog_name>;
```
再通过 USE 指定当前会话生效的数据库：
```
USE <db_name>;
```
或者，也可以通过 USE 直接将会话切换到目标 Catalog 下的指定数据库：
```
USE <catalog_name>.<db_name>;
```
通过 SELECT 查询目标数据库中的目标表：
```
SELECT * FROM <table_name>;
```

常见问题

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

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

JDBC catalog

前提条件​

创建 JDBC Catalog​

语法​

参数说明​

catalog_name​

comment​

PROPERTIES​

创建示例​

查看 JDBC Catalog​

删除 JDBC Catalog​

查询 JDBC Catalog 中的表数据​

常见问题​

文档是否有帮助？