JDBC Catalog
StarRocks 从 v3.0 版本开始支持 JDBC catalog。
JDBC catalog 是一种外部 catalog，使您无需导入即可查询通过 JDBC 访问的数据源中的数据。
此外，您还可以使用基于 JDBC catalog 的 INSERT INTO 直接转换和加载 JDBC 数据源中的数据。
JDBC catalog 从 v3.0 开始支持 MySQL 和 PostgreSQL，从 v3.2.9 和 v3.3.1 开始支持 Oracle 和 SQLServer，从 v3.3.0 开始支持 ClickHouse（实验性功能）。
前提条件
- StarRocks 集群中的 FE 和 BE 或 CN 可以从
driver_url参数指定的下载 URL 下载 JDBC 驱动程序。 - 每个 BE 或 CN 节点上的 $BE_HOME/bin/start_be.sh 文件中的
JAVA_HOME已正确配置为 JDK 环境中的路径，而不是 JRE 环境中的路径。例如，您可以配置export JAVA_HOME = <JDK_absolute_path>。您必须将此配置添加到脚本的开头，然后重新启动 BE 或 CN 才能使配置生效。
创建 JDBC catalog
语法
CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES ("key"="value", ...)
参数
catalog_name
JDBC catalog 的名称。命名规范如下
- 该名称可以包含字母、数字 (0-9) 和下划线 (_)。它必须以字母开头。
- 该名称区分大小写，长度不能超过 1023 个字符。
comment
JDBC catalog 的描述。此参数是可选的。
PROPERTIES
JDBC Catalog 的属性。PROPERTIES 必须包含以下参数
| 参数 | 描述 |
|---|---|
| type | 资源的类型。将值设置为 jdbc。 |
| user | 用于连接目标数据库的用户名。 |
| password | 用于连接目标数据库的密码。 |
| jdbc_uri | JDBC 驱动程序用于连接目标数据库的 URI。对于 MySQL，URI 的格式为 "jdbc:mysql://ip:port"。对于 PostgreSQL，URI 的格式为 "jdbc:postgresql://ip:port/db_name"。有关更多信息：PostgreSQL。 |
| driver_url | JDBC 驱动程序 JAR 包的下载 URL。支持 HTTP URL 或文件 URL，例如 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 驱动程序类名如下
|
注意
FE 在创建 JDBC catalog 时下载 JDBC 驱动程序 JAR 包，BE 或 CN 在首次查询时下载 JDBC 驱动程序 JAR 包。下载所需的时间因网络状况而异。
示例
以下示例创建五个不同的 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"
);
-- MySQL
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"
);
-- 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"
);
-- 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"="file:///path/to/clickhouse-jdbc-0.4.6.jar",
"driver_class"="com.clickhouse.jdbc.ClickHouseDriver"
);
查看 JDBC catalog
您可以使用 SHOW CATALOGS 查询当前 StarRocks 集群中的所有 Catalog
SHOW CATALOGS;
您还可以使用 SHOW CREATE CATALOG 查询外部 catalog 的创建语句。以下示例查询名为 jdbc0 的 JDBC catalog 的创建语句
SHOW CREATE CATALOG jdbc0;
删除 JDBC catalog
您可以使用 DROP CATALOG 删除 JDBC catalog。
以下示例删除名为 jdbc0 的 JDBC catalog
DROP Catalog jdbc0;
查询 JDBC catalog 中的表
-
使用 SHOW DATABASES 查看与 JDBC 兼容的集群中的数据库
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”部分中的参数说明。