OceanBase 数据库使用指南

default

markdown

# OceanBase 数据库使用指南

## 1. OceanBase 与 MySQL 兼容性总结及 JDBC 配置指南

### 1.1 兼容性概述

OceanBase 数据库在以下方面高度兼容 MySQL（接近 100%）：

- SQL 语法
- 数据读取和写入
- 事务处理机制
- 系统表结构

### 1.2 JDBC 连接配置调整

从 MySQL 迁移到 OceanBase 时，需要修改 `dbcp.properties` 的 JDBC 连接 URL，添加以下两个关键参数：

- `rewriteBatchedStatements=TRUE`
- `allowMultiQueries=TRUE`

**MySQL 模式下的 JDBC 参数配置建议：**

```plaintext
url=jdbc:mysql://xxx.xxx.xxx.xxx:2881/test?rewriteBatchedStatements=TRUE&allowMultiQueries=TRUE&useLocalSessionState=TRUE&useUnicode=TRUE&characterEncoding=utf-8&socketTimeout=3000000&connectTimeout=60000&zeroDateTimeBehavior=convertToNull&allowPublicKeyRetrieval=true
```

- **allowMultiQueries**：默认为 `FALSE`，必须设置为 `TRUE`，以允许使用分号连接的多语句文本格式。对使用文本协议的场景，只需开启此配置即可实现批量优化。
- **rewriteBatchedStatements**：默认为 `FALSE`，若使用 PS 协议，则必须设置为 `TRUE`，以在执行 `executeBatch()` 时将多条语句改写为分号连接的多语句格式。

**特例说明**：开启 `rewriteBatchedStatements` 后，对于多条 multi queries 插入语句（无论使用文本协议或 PS 协议），JDBC 驱动会将其改写为一条 Multi Values Insert 语句。

**参考文档**：

- [JDBC 配置示例](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013674)
- [数据库 URL-V2.4.13-OceanBase JDBC 驱动程序文档](https://www.oceanbase.com/docs/common-oceanbase-connector-j-cn-1000000001506761)
- [配置 JDBC 和 OBServer 实现 Batch DML 最佳性能的最佳实践](https://www.oceanbase.com/docs/common-best-practices-1000000001489651)

---

## 2. OceanBase 概述

OceanBase 数据库是一款完全自研的企业级原生分布式数据库，具有以下特性：

- 在普通硬件上实现金融级高可用
- 首创“三地五中心”城市级故障自动无损容灾新标准
- 单集群规模超过 1500 节点
- 支持云原生、强一致性、高度兼容 Oracle/MySQL

**官方文档**：[OceanBase 概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002012646)

---

## 3. 与 MySQL 兼容性对比

OceanBase 数据库的 MySQL 模式兼容 MySQL 5.7/8.0 的绝大部分功能和语法。由于产品架构不同，或者客户需求不大，有些功能并没有被支持。以下是 OceanBase 数据库的 MySQL 模式与原生 MySQL 数据库的不同之处：

- 数据类型
- SQL 语法
- 过程性语言
- 系统视图
- 字符集
- 字符序
- 函数与表达式
- 分区支持
- 备份恢复
- 存储引擎
- 优化器

**数据类型**：

- 数值类型：`BOOL`/`BOOLEAN`/`TINYINT`、`SMALLINT`、`MEDIUMINT`、`INT`/`INTEGER`、`BIGINT`、`DECIMAL`、`NUMERIC`、`FLOAT`、`DOUBLE`、`BIT`
- 日期时间类型：`DATETIME`、`TIMESTAMP`、`DATE`、`TIME`、`YEAR`
- 字符类型：`CHAR`、`VARCHAR`、`BINARY`、`VARBINARY`
- 大对象类型：`TINYBLOB`、`BLOB`、`MEDIUMBLOB`、`LONGBLOB`
- 文本类型：`TINYTEXT`、`TEXT`、`MEDIUMTEXT`、`LONGTEXT`、`STRING`

---

## 4. MySQL 模式使用限制

### 4.1 集群名长度限制

| 数据项 | 最大长度 |
| ------ | -------- |
| 集群名 | 128 字节 |

### 4.2 标识符长度限制

| 数据项   | 最大长度 |
| -------- | -------- |
| 用户名   | 64 字节  |
| 租户名   | 63 字节  |
| 数据库名 | 128 字节 |
| 表名     | 64 字符  |
| 列名     | 128 字节 |
| 索引名   | 64 字节  |
| 视图名   | 64 字节  |
| 别名     | 255 字节 |
| 表组名   | 127 字节 |

### 4.3 单个表的限制

| 类型       | 最大限制                                                     |
| ---------- | ------------------------------------------------------------ |
| 行长度     | 1.5M 字节                                                    |
| 列数       | 4096 列                                                      |
| 索引个数   | 128 个                                                       |
| 索引总列数 | 512 列                                                       |
| 索引长度   | 16K                                                          |
| 主键总列数 | 64 列                                                        |
| 主键长度   | 16K                                                          |
| 分区个数   | Oracle 模式：65536 个，MySQL 模式：8192 个（从 V4.2.1 BP3 版本开始，MySQL 模式下单个表允许的最大分区数由租户级配置项 `max_partition_num` 控制，默认为 8192 个） |

### 4.4 单列的限制

| 类型           | 最大限制 |
| -------------- | -------- |
| 索引单个列长度 | 16K      |

### 4.5 字符串类型限制

| 类型         | 最大长度       |
| ------------ | -------------- |
| `CHAR`       | 256 字符       |
| `VARCHAR`    | 262144 字符    |
| `BINARY`     | 256 字节       |
| `VARBINARY`  | 1048576 字节   |
| `TINYBLOB`   | 255 字节       |
| `BLOB`       | 65535 字节     |
| `MEDIUMBLOB` | 16777215 字节  |
| `LONGBLOB`   | 536870910 字节 |
| `TINYTEXT`   | 255 字节       |
| `TEXT`       | 65535 字节     |
| `MEDIUMTEXT` | 16777215 字节  |
| `LONGTEXT`   | 536870910 字节 |

---

## 5. 创建索引

**参考文档**：[创建索引](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013233)

### 5.1 创建索引的限制

- 索引名称必须在数据库范围内唯一，长度不能超过 64 字节。
- 唯一索引的列值必须保持唯一，局部唯一索引必须包含表的分区函数中的所有列。
- 全局索引的分区规则不一定需要与表的分区规则完全相同。

---

## 6. 数据写入

**参考文档**：

- [插入数据](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013243)
- [更新数据](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013240)
- [删除数据](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013244)
- [替换数据](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013241)

---

## 7. 数据读取

**参考文档**：

- [单表查询](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013225)
- [多表关联查询](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013650)
- [在查询中使用操作符和函数](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013225)

---

## 8. 事务

事务机制和 MySQL 一样，完全兼容 MySQL。

**事务控制语句**：

- [BEGIN](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013247)：显式开启一个事务。
- [SAVEPOINT](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013673)：在事务过程中标记一个“保存点”。
- [COMMIT](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013246)：提交并结束当前事务。
- [ROLLBACK](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013245)：回滚整个事务或回滚到某个保存点。

**相关文档**：

- [开启事务](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013247)
- [事务保存点](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013673)
- [提交事务](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013246)
- [回滚事务](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013245)

---

## 9. 租户管理

OceanBase 数据库采用了多租户架构。集群是 Zone 和节点的集合，租户则是资源层面的逻辑概念，通过资源池与资源关联。

**相关文档**：

- [租户介绍](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002012845)
- [租户容量](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002012845)
- [租户类型](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002012845)
- [用户租户介绍](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002012842)
- [租户系统变量](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002012845)
- [租户常见操作](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013128)

---

## 10. 批量操作配置

**异常 SQL 示例**：

```sql
SQL出错：DELETE FROM ui_file_seed WHERE id = 'mbm-mdm.master.mbm_mdm_wip_resource_template',异常信息:Not supported feature or function
2025-03-27 14:52:05.083 [main] ERROR c.s.snest.engine.db.relationdb.RelationDBAccessor -数据源:main,批量执行SQL出错：DELETE FROM ui_file_seed WHERE id = 'mbm-mdm.master.whm_storage_location_template',异常信息:批量执行SQL出错
```

遇到批量执行 SQL 出错时，需要添加参数到 JDBC URL：`rewriteBatchedStatements=TRUE&allowMultiQueries=TRUE`

**参考文档**：[JDBC 配置示例](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013674)

**JDBC 连接示例**：

```plaintext
url=jdbc:oceanbase://xxx.xxx.xxx.xxx:3306/test?rewriteBatchedStatements=TRUE&allowMultiQueries=TRUE&useLocalSessionState=TRUE&useUnicode=TRUE&characterEncoding=utf-8&socketTimeout=10000&connectTimeout=30000
```

**相关参数说明**：

- `rewriteBatchedStatements`：建议设置为 `TRUE`，以提高批量插入的性能。
- `allowMultiQueries`：建议设置为 `TRUE`，允许使用分号连接的多语句文本格式。
- `useLocalSessionState`：建议设置为 `TRUE`，避免频繁向 OB 数据库发送 session 变量查询 SQL。
- `socketTimeout`：执行 SQL 时，socket 等待 SQL 返回的时间。
- `connectTimeout`：建立连接时，等待连接的时间。
- `useCursorFetch`：建议设置为 `TRUE`，适用于大数据量查询。
- `useServerPrepStms`：控制是否使用 PS 协议发送 SQL。
- `cachePrepStmts`：控制是否开启 PS cache，避免重复执行 prepare。
- `prepStmtCacheSQLLimit`：可放入 PS cache 的 SQL 长度限制。
- `prepStmtCacheSize`：PS cache 可保存的 SQL 数量。
- `maxBatchTotalParamsNum`：针对 batch 操作，一条 SQL 最多支持的参数个数。

---

## 11. 数据类型转换规则

数据类型转换和 MySQL 一致。

---

## 12. Docker 部署 OceanBase

**安装参考文档**：[Docker 部署 OceanBase](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013494)

**部署步骤**：

```shell
sudo docker pull quay.io/oceanbase/oceanbase-ce
sudo docker run -p 2881:2881 --name oceanbase -e MODE=MINI -e OB_TENANT_PASSWORD=****** -d quay.io/oceanbase/oceanbase-ce
sudo docker logs oceanbase | tail -1
sudo docker exec -it oceanbase bash
docker logs oceanbase | tail -1

obclient -uroot@sys -h127.0.0.1 -P2881 -p
-- 默认密码为空，直接回车

-- 修改密码
ALTER USER 'root' IDENTIFIED BY 'your_password';

obclient -uroot@sys -h127.0.0.1 -P2881 -p your_password

CREATE DATABASE snest_changwen DEFAULT CHARACTER SET utf8mb4 READ WRITE;

show databases;
```

## 13. 本地 JDBC连接 OceanBase
dbcp.properties添加oceanbase配置

```shell
########OceanBase########
driverClassName=com.mysql.cj.jdbc.Driver
url=jdbc:mysql://xxx.xxx.xxx.xxx:2881/snest?rewriteBatchedStatements=TRUE&allowMultiQueries=TRUE&useLocalSessionState=TRUE&useUnicode=TRUE&characterEncoding=utf-8&socketTimeout=10000&connectTimeout=30000&zeroDateTimeBehavior=convertToNull&allowPublicKeyRetrieval=true
username=root
password=******
validationQuery=SELECT 1
```

Uploading file...

Edit message:

Cancel

Editing OceanBase 数据库使用指南

Sidebar