🗃️ 多数据库适配指南

说明：TduckX 项目通过 MyBatis-Plus 实现对多数据库的高度兼容，已适配以下主流数据库。

---

支持数据库列表

数据库	版本要求
MySQL	≥ 5.7  推荐
PostgreSQL	≥ 9.2
SQL Server	≥ 2017
Oracle	≥ 12c

---

🧪 示例演示：PostgreSQL 环境配置

以下为以 PostgreSQL 为例的配置流程。

1️⃣ 安装 PostgreSQL

建议使用轻量镜像版本：postgres:17.3-alpine

可通过 Docker 安装：

docker run --name pgsql -e POSTGRES_PASSWORD=123456 -p 5432:5432 -d postgres:17.3-alpine

---

2️⃣ 初始化 SQL 脚本

🟡 注意事项：

• 系统默认提供 MySQL 初始化脚本，适配最完整，推荐优先使用 MySQL。
• 其他数据库如 PostgreSQL、Oracle 的脚本可能不随版本实时更新。

SQL 脚本位置

• 所有数据库初始化脚本目录：tduck-x-platform/doc/db/
• PostgreSQL 示例：pgsql-2.4.sql 表示为 PostgreSQL 的 2.4 版本结构脚本
• 更新脚本示例：update_2.5.sql 为从 2.4 → 2.5 的升级 SQL（需自行迁移至其他数据库）

数据库要求

• 数据库名称需为 tduckx，否则初始化脚本可能报错
• PostgreSQL 模式建议使用默认 public 模式

---

3️⃣ 配置数据库连接

系统已内置常用数据库驱动，只需在 application.yml 中修改连接信息：

PostgreSQL 配置示例：

spring:
  datasource:
    url: jdbc:postgresql://192.168.1.6:5432/tduckx
    username: user_hJ4yJX
    password: password_834RJ5
    driver-class-name: org.postgresql.Driver

Oracle 配置示例：

spring:
  datasource:
    url: jdbc:oracle:thin:@192.168.1.6:1521/XE
    username: TDUCKX
    password: myuserpassword
    driver-class-name: oracle.jdbc.OracleDriver

SQL Server 配置示例：

spring:
  datasource:
    url: jdbc:sqlserver://192.168.1.6:1433;databaseName=tduckx
    username: sa
    password: mssql_7N2RNz
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver

---

🔐 主键策略说明

• MySQL 默认使用自增主键（兼容 Snowflake 算法）
• PostgreSQL / Oracle 等数据库默认使用 Snowflake ID（雪花算法）

💡如需更改为数据库自增主键，请手动修改表结构及代码生成策略。

---

雪花算法分布式部署注意事项

雪花算法使用 workId + dataCenterId 构成唯一 ID。

部署多节点时必须确保每个实例的 workId 和 dataCenterId 不重复。可通过配置中心动态下发或配置文件指定。

---

🧭 常见问题及处理方式

PostgreSQL 类型不匹配异常

错误信息示例：

Caused by: org.postgresql.util.PSQLException:
ERROR: operator does not exist: bigint = character varying

🔧 原因：PG 类型严格匹配，Java 中为 String，PG 中为 BIGINT 会导致类型冲突

✅ 解决方案：确保数据库与 Java 字段类型一致，或使用显示类型转换（如 ::bigint）

---

Oracle 表名字段自动大写问题

Oracle 默认会将所有表名和字段名转换为 大写，可能导致 SQL 找不到表或列。

🔧 系统已通过 MybatisPlusConfig.java 中的插件自动处理，统一将表名转为大写。

---

总结

项目	状态
多数据库驱动支持	✅ 内置
初始化 SQL 支持	✅ MySQL 优先🔶 PostgreSQL/Oracle 基础支持
分布式部署兼容性	✅ 支持雪花算法
自定义主键策略	🔧 手动调整

---