Created OceanBase (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 索引简介

+索引也叫二级索引，是一种可选的表结构。OceanBase 数据库采用聚集索引表模型，系统会自动生成主键索引，用户创建的其他索引为二级索引。可以根据业务需求在字段上创建索引，以加快查询速度。

+

+### 5.2 创建索引的限制

+- 索引名称必须在数据库范围内唯一，长度不能超过 64 字节。

+- 唯一索引的列值必须保持唯一，局部唯一索引必须包含表的分区函数中的所有列。

+- 全局索引的分区规则不一定需要与表的分区规则完全相同。

+

+### 5.3 创建索引的建议

+- 使用简洁的名称描述索引所涵盖的列和用途，例如 `idx_customer_name`。

+- 如果全局索引的分区规则和主表的分区规则相同且分区数相同，建议创建局部索引。

+- 并行下发创建索引的 SQL 语句条数，不要超过租户 Unit 规格中的核数上限。例如，租户的 Unit 规格为 4 核（4C），则建议并发创建索引不超过 4 条。

+- 对经常更新的表要避免对其进行过多的索引，对经常用于查询的字段应该创建索引。

+- 数据量小的表建议不要使用索引，因为由于数据较少，可能查询全部数据花费的时间比遍历索引的时间还要短，索引就可能不会产生优化效果。

+- 当修改性能远远大于检索性能时，不建议创建索引。

+- 创建高效索引。

+

+---

+

+## 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=Passw0rd -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;

+```

+

+