使用 Spark Catalog 连接 OceanBase 数据库

更新时间：2026-04-09 14:12:04

编辑

OceanBase Spark Connector 从 1.1 版本开始全面支持 Spark Catalog。通过使用 Spark Catalog，用户能够以更加简洁和一致的方式访问和操作 OceanBase 数据库。

本文档将指导您快速完成 OceanBase Spark Catalog 的配置和使用。通过本教程，您将掌握如何通过 Spark Catalog 访问和操作 OceanBase 数据库。

前提条件

您已完成部署 OceanBase 数据库并且创建了 MySQL 模式用户租户。创建用户租户的详细信息，参见创建租户。

操作步骤

步骤一：获取数据库连接信息

联系 OceanBase 数据库部署人员或者管理员获取相应的数据库连接串，例如：

obclient -h$host -P$port -u$user_name -p$password -D$database_name

参数说明：

$host：提供 OceanBase 数据库连接 IP。OceanBase 数据库代理（OceanBase Database Proxy，ODP）连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。
$port：提供 OceanBase 数据库连接端口。ODP 连接的方式默认是 2883，在部署 ODP 时可自定义；直连方式默认是 2881，在部署 OceanBase 数据库时可自定义。
$database_name：需要访问的数据库名称。

注意

连接租户的用户需要拥有该数据库的 CREATE、INSERT、DROP 和 SELECT 权限。更多有关用户权限的信息，请参见 MySQL 模式下的权限分类。
$user_name：提供租户的连接账户。ODP 连接的常用格式：用户名@租户名#集群名 或者 集群名:租户名:用户名；直连方式格式：用户名@租户名。
$password：提供账户密码。

更多连接串的信息，请参见通过 OBClient 连接 OceanBase 租户。

步骤二：准备 Spark 环境

下载 Spark 3.4.4，并解压至指定目录。使用以下命令跳转至 Spark 目录，并设置 SPARK_HOME 环境变量为 Spark 解压后的目录：

请按照以下步骤下载并配置 Spark：

下载 Spark 3.4.4。

wget https://dlcdn.apache.org/spark/spark-3.4.4/spark-3.4.4-bin-hadoop3.tgz

解压 spark-3.4.4-bin-hadoop3.tgz 至指定目录。
```
tar -zxvf spark-3.4.4-bin-hadoop3.tgz -C $SPARK_HOME
```
示例如下：

将 spark-3.4.4-bin-hadoop3.tgz 解压到指定目录 /home/admin/test_spark_catalog。
```
tar -zxvf spark-3.4.4-bin-hadoop3.tgz -C /home/admin/test_spark_catalog
```

设置 SPARK_HOME 环境变量为 Spark 解压后的目录。

export SPARK_HOME=$(pwd)

示例如下：

export SPARK_HOME=/home/admin/test_spark_catalog/spark-3.4.4-bin-hadoop3

步骤三：配置 OceanBase Catalog

下载 OceanBase Spark Connector。
1. 下载对应的 spark-connector-oceanbase Jar 包。
2. 将该 Jar 包移动到 Spark Home 的 jars 目录：
```
cp spark-connector-oceanbase-3.4_2.12-1.1.jar $SPARK_HOME/jars/
```
或者直接在解压 spark-3.4.4-bin-hadoop3.tgz 指定目录中下载 spark-connector-oceanbase Jar 包。
1. 进入到 Spark Home 的 jars 目录。
  
  示例如下：
```
cd /home/admin/test_spark_catalog/spark-3.4.4-bin-hadoop3/jars
```
2. 下载 spark-connector-oceanbase。
```
wget https://repo1.maven.org/maven2/com/oceanbase/spark-connector-oceanbase-3.4_2.12/1.1/spark-connector-oceanbase-3.4_2.12-1.1.jar
```
下载 MySQL 驱动。
1. 下载 MySQL 驱动 Jar 包。
2. 将该 Jar 包移动到 Spark Home 的 jars 目录：
```
cp mysql-connector-j-8.2.0.jar $SPARK_HOME/jars/
```
或者直接在解压 spark-3.4.4-bin-hadoop3.tgz 指定目录中下载 MySQL 驱动 Jar 包。
1. 进入到 Spark Home 的 jars 目录。
  
  示例如下：
```
cd /home/admin/test_spark_catalog/spark-3.4.4-bin-hadoop3/jars
```
2. 下载 spark-connector-oceanbase。
```
wget https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.2.0/mysql-connector-j-8.2.0.jar
```

编辑 Spark 配置文件，默认为 $SPARK_HOME/conf/spark-defaults.conf。

示例如下：

说明

示例 IP 和密码做了脱敏处理，在验证时应根据自己数据库真实环境填写。

进入到 $SPARK_HOME/conf 目录。

cd /home/admin/test_spark_catalog/spark-3.4.4-bin-hadoop3/conf

配置 OceanBase Catalog。

vi spark-defaults.conf

输入以下内容：

spark.sql.catalog.ob=com.oceanbase.spark.catalog.OceanBaseCatalog
spark.sql.catalog.ob.url=jdbc:mysql://10.10.10.1:2881
spark.sql.catalog.ob.username=root@mysql001
spark.sql.catalog.ob.password=******
spark.sql.catalog.ob.schema-name=test

启动 Spark SQL CLI。

$SPARK_HOME/bin/spark-sql

示例如下：

/home/admin/test_spark_catalog/spark-3.4.4-bin-hadoop3/bin/spark-sql

返回结果如下：

Setting default log level to "WARN".
To adjust logging level use sc.setLogLevel(newLevel). For SparkR, use setLogLevel(newLevel).
25/04/07 15:52:02 WARN NativeCodeLoader: Unable to load native-hadoop library for your platform... using builtin-java classes where applicable
25/04/07 15:52:05 WARN HiveConf: HiveConf of name hive.stats.jdbc.timeout does not exist
25/04/07 15:52:05 WARN HiveConf: HiveConf of name hive.stats.retries.wait does not exist
25/04/07 15:52:09 WARN ObjectStore: Version information not found in metastore. hive.metastore.schema.verification is not enabled so recording the schema version 2.3.0
25/04/07 15:52:09 WARN ObjectStore: setMetaStoreSchemaVersion called but recording version is disabled: version = 2.3.0, comment = Set by MetaStore admin@10.10.10.1
25/04/07 15:52:09 WARN ObjectStore: Failed to get database default, returning NoSuchObjectException
Spark master: local[*], Application Id: local-1744012324296
spark-sql (default)>

然后在 Spark SQL CLI 中输入 use ob; 切换到第三步配置的 OceanBase catalog。

spark-sql (default)> use ob;

返回结果如下：

25/04/07 16:11:06 WARN ObjectStore: Failed to get database global_temp, returning NoSuchObjectException
Time taken: 2.544 seconds
spark-sql (test)>

步骤四：通过 Spark CLI 使用 OceanBase Catalog

通过 Spark-SQL 创建 OceanBase 数据库表

Spark SQL CLI 中输入下述建表语句：

spark-sql (test)> CREATE TABLE orders (
    order_id      INT COMMENT 'order id',
    order_date    TIMESTAMP,
    customer_name STRING,
    price         DOUBLE,
    product_id    INT,
    order_status  BOOLEAN);

返回结果如下：

25/04/07 16:14:25 WARN OceanBaseMySQLDialect: Ignored unsupported table property: owner
Time taken: 0.085 seconds

执行成功后，通过 OBClient 连接到 OceanBase 数据库，可以看到 orders 表已经被创建出来了。

$obclient -h10.10.10.1 -P2881 -uroot@mysql001 -p****** -A test
Welcome to the OceanBase.  Commands end with ; or \g.
Your OceanBase connection id is 3221487689
Server version: OceanBase 4.2.1.8 (r108020012024111712-585a11c3514ac7882b041453a529050ac62c6180) (Built Nov 17 2024 12:49:45)

Copyright (c) 2000, 2018, OceanBase and/or its affiliates. All rights reserved.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

obclient [test]> show tables;
+----------------+
| Tables_in_test |
+----------------+
| orders         |
+----------------+
1 row in set

通过在 Spark SQL CLI 中输入 show tables; 也可以查询到刚刚创建的 orders 表：
```
spark-sql (test)> show tables;
```
返回结果如下：
```
orders
Time taken: 0.044 seconds, Fetched 1 row(s)
```

通过 Spark-SQL 写数据到 OceanBase 数据库表

在 Spark SQL CLI 中执行下述写入语句：

spark-sql (test)> INSERT INTO orders VALUES
    (1, now(), 'zs', 12.2, 12, true),
    (2, now(), 'ls', 121.2, 12, true),
    (3, now(), 'xx', 123.2, 12, true),
    (4, now(), 'jac', 124.2, 12, false),
    (5, now(), 'dot', 111.25, 12, true);

返回结果如下：

Time taken: 1.433 seconds

然后通过 OBClient 连接到 OceanBase 数据库，可以查询表 orders 的数据。

obclient [test]> SELECT * FROM orders;

返回结果如下：

+----------+---------------------+---------------+--------+------------+--------------+
| order_id | order_date          | customer_name | price  | product_id | order_status |
+----------+---------------------+---------------+--------+------------+--------------+
|        1 | 2025-04-07 16:22:34 | zs            |   12.2 |         12 |            1 |
|        2 | 2025-04-07 16:22:34 | ls            |  121.2 |         12 |            1 |
|        4 | 2025-04-07 16:22:34 | jac           |  124.2 |         12 |            0 |
|        5 | 2025-04-07 16:22:34 | dot           | 111.25 |         12 |            1 |
|        3 | 2025-04-07 16:22:34 | xx            |  123.2 |         12 |            1 |
+----------+---------------------+---------------+--------+------------+--------------+
5 rows in set

通过 Spark-SQL 查询 OceanBase 数据库表

在 Spark SQL CLI 中查询上方写入的数据。

spark-sql (test)> SELECT * FROM orders;

返回结果如下：

1       2025-04-07 16:22:34     zs      12.2    12      true
2       2025-04-07 16:22:34     ls      121.2   12      true
4       2025-04-07 16:22:34     jac     124.2   12      false
5       2025-04-07 16:22:34     dot     111.25  12      true
3       2025-04-07 16:22:34     xx      123.2   12      true
Time taken: 0.462 seconds, Fetched 5 row(s)

步骤五：同步外部系统数据到 OceanBase 数据库

创建 hive 表并插入数据

在 Spark SQL CLI 中执行以下语句创建 hive 表：

spark-sql (test)> DROP TABLE spark_catalog.default.orders;
Time taken: 0.827 seconds

spark-sql (test)> CREATE TABLE spark_catalog.default.orders (
    order_id      INT,
    order_date    TIMESTAMP,
    customer_name STRING,
    price         DOUBLE,
    product_id    INT,
    order_status  BOOLEAN
    ) USING PARQUET;

返回结果如下：

25/04/07 16:37:54 WARN SessionState: METASTORE_FILTER_HOOK will be ignored, since hive.security.authorization.manager is set to instance of HiveAuthorizerFactory.
25/04/07 16:37:54 WARN HiveConf: HiveConf of name hive.internal.ss.authz.settings.applied.marker does not exist
25/04/07 16:37:54 WARN HiveConf: HiveConf of name hive.stats.jdbc.timeout does not exist
25/04/07 16:37:54 WARN HiveConf: HiveConf of name hive.stats.retries.wait does not exist
Time taken: 0.457 seconds

在 Spark SQL CLI 中执行以下语句向 hive 表插入数据：

spark-sql (test)> INSERT INTO spark_catalog.default.orders VALUES
    (1, now(), 'zs', 12.2, 12, true),
    (2, now(), 'ls', 121.2, 12, true),
    (3, now(), 'xx', 123.2, 12, true),
    (4, now(), 'jac', 124.2, 12, false),
    (5, now(), 'dot', 111.25, 12, true);

返回结果如下：

Time taken: 1.378 seconds

同步 hive 表数据到 OceanBase 数据库

在 Spark SQL CLI 中执行下列写入语句。

spark-sql (test)> INSERT INTO orders
    SELECT * FROM spark_catalog.default.orders;

返回结果如下：

Time taken: 0.523 seconds

通过 OBClient 连接到 OceanBase 数据库，可以查询表 orders 的数据，发现数据被成功同步。

obclient [test]> SELECT * FROM orders;

返回结果如下：

+----------+---------------------+---------------+--------+------------+--------------+
| order_id | order_date          | customer_name | price  | product_id | order_status |
+----------+---------------------+---------------+--------+------------+--------------+
|        1 | 2025-04-07 16:22:34 | zs            |   12.2 |         12 |            1 |
|        2 | 2025-04-07 16:22:34 | ls            |  121.2 |         12 |            1 |
|        4 | 2025-04-07 16:22:34 | jac           |  124.2 |         12 |            0 |
|        5 | 2025-04-07 16:22:34 | dot           | 111.25 |         12 |            1 |
|        3 | 2025-04-07 16:22:34 | xx            |  123.2 |         12 |            1 |
|        4 | 2025-04-07 16:42:04 | jac           |  124.2 |         12 |            0 |
|        5 | 2025-04-07 16:42:04 | dot           | 111.25 |         12 |            1 |
|        1 | 2025-04-07 16:42:04 | zs            |   12.2 |         12 |            1 |
|        2 | 2025-04-07 16:42:04 | ls            |  121.2 |         12 |            1 |
|        3 | 2025-04-07 16:42:04 | xx            |  123.2 |         12 |            1 |
+----------+---------------------+---------------+--------+------------+--------------+
10 rows in set

环境清理

在完成教程后，可以使用以下命令按需停止 Spark- SQL CLI。

spark-sql (test)> quit;

使用 Spark Catalog 连接 OceanBase 数据库

前提条件

操作步骤

步骤一：获取数据库连接信息

注意

步骤二：准备 Spark 环境

步骤三：配置 OceanBase Catalog

说明

步骤四：通过 Spark CLI 使用 OceanBase Catalog

通过 Spark-SQL 创建 OceanBase 数据库表

通过 Spark-SQL 写数据到 OceanBase 数据库表

通过 Spark-SQL 查询 OceanBase 数据库表

步骤五：同步外部系统数据到 OceanBase 数据库

创建 hive 表并插入数据

同步 hive 表数据到 OceanBase 数据库

环境清理