Updated OceanBase 数据库使用指南.md (markdown)

## 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

```

**特例说明**：开启 `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 节点

---

## 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`

## 4. MySQL 模式使用限制

### 4.1 集群名长度限制

| 数据项 | 最大长度 |

| ------ | -------- |

| 集群名 | 128 字节 |

### 4.2 标识符长度限制

| 数据项 | 最大长度 |

| -------- | -------- |

| 用户名 | 64 字节 |

| 表组名 | 127 字节 |

### 4.3 单个表的限制

| 类型 | 最大限制 |

| ---------- | ------------------------------------------------------------ |

| 行长度 | 1.5M 字节 |

| 分区个数 | Oracle 模式：65536 个，MySQL 模式：8192 个（从 V4.2.1 BP3 版本开始，MySQL 模式下单个表允许的最大分区数由租户级配置项 `max_partition_num` 控制，默认为 8192 个） |

### 4.4 单列的限制

| 类型 | 最大限制 |

| -------------- | -------- |

| 索引单个列长度 | 16K |

### 4.5 字符串类型限制

| 类型 | 最大长度 |

| ------------ | -------------- |

| `CHAR` | 256 字符 |

---

## 5. 创建索引

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

- 索引名称必须在数据库范围内唯一，长度不能超过 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)

---

## 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)

---

## 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)

---

## 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出错

**参考文档**：[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。

---

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

数据类型转换和 MySQL 一致。

---

**安装参考文档**：[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=Passw0rd -d quay.io/oceanbase/oceanbase-ce

show databases;

```