🔥xbatis-ddl-auto 1.0.2 ORM DDL，最强 mybatis ORM DDL
官网 https://xbatis.cn xbatis-ddl-auto 是一个基于 xbatis 实体元数据的轻量自动建表工具。 它复用 xbatis 的 @Table、@TableId、@TableField、@ColumnDefinition 等注解解析结果，根据实体类生成并执行数据库 DDL，提供接近 JPA ddl-auto=create/update 的使用体验，但不引入 JPA 或 Hibernate。 1.0.2 更新 增加SYNC模式，支持 列 索引 变更同步模式 功能 根据 xbatis 实体生成 CREATE TABLE SQL 表不存在时自动建表 表存在时可在 UPDATE 模式下自动追加新增字段 支持只生成 SQL，不执行数据库操作 通过 JDBC DatabaseMetaData 判断表、字段和索引是否存在 支持常见 Java 类型到数据库列类型映射 支持 @ColumnDefinition 配置字段长度、精度、小数位、默认值、唯一约束、非空和字段注释 支持类级 @Index 创建普通索引和唯一索引 安全边界 UPDATE 模式只会自动新增字段和缺失索引，不会自动执行以下高风险操作： 删除数据库已有字段 修改字段类型 修改字段长度 修改字段是否可空 修改默认值 重命名字段 修改或删除已有索引 删除或重建表 这些操作可能造成数据丢失或生产事故，建议通过人工审核 SQL 或专业迁移工具处理。 Maven 本工具 Maven 坐标： <dependency> <groupId>cn.xbatis</groupId> <artifactId>xbatis-ddl-auto</artifactId> <version>1.0.1</version> </dependency> 运行依赖 xbatis core <dependency> <groupId>cn.xbatis</groupId> <artifactId>xbatis-core</artifactId> <version>1.10.6</version> </dependency> 默认测试使用 JUnit 5 和 H2；需要真实数据库的集成测试通过 Maven profile 单独执行。 快速开始 定义 xbatis 实体 import cn.xbatis.db.annotations.ColumnDefinition; import cn.xbatis.db.annotations.Table; import cn.xbatis.db.annotations.TableId; import java.math.BigDecimal; import java.time.LocalDateTime; @Table("sys_user") public class SysUser { @TableId private Long id; @ColumnDefinition(length = 64, nullable = false) private String username; @ColumnDefinition(precision = 10, scale = 2, defaultValue = "0") private BigDecimal balance; private LocalDateTime createdAt; } 执行自动建表： import db.sql.api.DbType; DDLAuto.of(DbType.MYSQL) .add(SysUser.class) .execute(dataSource); CREATE 模式 CREATE 是默认模式： DDLAuto.of(DbType.MYSQL) .add(SysUser.class) .execute(dataSource); 行为： 表不存在：执行 CREATE TABLE 表已存在：跳过，不做任何变更 UPDATE 模式 UPDATE 模式用于补新增字段和缺失索引： import cn.xbatis.ddl.auto.Mode; DDLAuto.of(DbType.MYSQL) .mode(Mode.UPDATE) .add(SysUser.class) .execute(dataSource); 行为： 表不存在：执行 CREATE TABLE 表已存在：读取数据库已有列和索引，只对实体中新增的字段执行 ALTER TABLE ... ADD COLUMN ...，并创建缺失索引 重复执行 UPDATE 模式不会重复添加已存在字段或已存在索引。 只生成 SQL / 预览 SQL 不连接数据库，只生成建表 SQL： List<String> sqlList = DDLAuto.of(DbType.PGSQL) .add(SysUser.class) .sqlList(); 如果要按当前数据库状态预览将要执行的 SQL，可以传入 DataSource 或 Connection。该方法只读取 JDBC 元数据并生成 SQL，不会执行 DDL： List<String> sqlList = DDLAuto.of(DbType.MYSQL) .mode(Mode.UPDATE) .add(SysUser.class) .sqlList(dataSource); 行为： 表不存在：返回 CREATE TABLE 及附属 DDL 表已存在且是 CREATE 模式：返回空列表 表已存在且是 UPDATE 模式：只返回缺失字段的 ALTER TABLE ... ADD COLUMN ... 及附属 DDL，以及缺失索引的 CREATE INDEX 也可以使用底层构建器生成单个字段的新增列 SQL： import cn.xbatis.ddl.auto.DDLBuilder; import cn.xbatis.ddl.auto.DefaultDDLBuilder; DDLBuilder builder = new DefaultDDLBuilder(); String sql = builder.addColumnSql(DbType.MYSQL, SysUser.class, "email"); 生产或准生产环境建议先通过 sqlList(dataSource) 或 sqlList(connection) 生成 SQL 并审核，再决定是否执行。 执行监听 DDL 会按 SQL 列表逐条执行。若中途失败，数据库可能已经保留前面成功执行的 DDL。可以配置执行监听器记录已执行 SQL： import cn.xbatis.ddl.auto.Mode; import cn.xbatis.ddl.auto.DDLExecutionListener; import java.util.ArrayList; import java.util.List; List<String> executedSqlLog = new ArrayList<>(); DDLAuto.of(DbType.MYSQL) .mode(Mode.UPDATE) .executionListener(new DDLExecutionListener() { @Override public void afterExecute(String sql, List<String> executedSqlList) { executedSqlLog.add(sql); } @Override public void onExecuteError(String sql, SQLException exception, List<String> executedSqlList) { // sql 为当前失败 SQL，executedSqlList 为失败前已成功执行的 SQL。 } }) .add(SysUser.class) .execute(dataSource); 生产或准生产环境建议先通过 sqlList(dataSource) 或 sqlList(connection) 生成 SQL 并审核，再决定是否执行。 执行监听 DDL 会按 SQL 列表逐条执行。若中途失败，数据库可能已经保留前面成功执行的 DDL。可以配置执行监听器记录已执行 SQL： import cn.xbatis.ddl.auto.Mode; import cn.xbatis.ddl.auto.DDLExecutionListener; import java.util.ArrayList; import java.util.List; List<String> executedSqlLog = new ArrayList<>(); DDLAuto.of(DbType.MYSQL) .mode(Mode.UPDATE) .executionListener(new DDLExecutionListener() { @Override public void afterExecute(String sql, List<String> executedSqlList) { executedSqlLog.add(sql); } @Override public void onExecuteError(String sql, SQLException exception, List<String> executedSqlList) { // sql 为当前失败 SQL，executedSqlList 为失败前已成功执行的 SQL。 } }) .add(SysUser.class) .execute(dataSource); 执行失败时抛出的 SQLException 消息也会包含当前失败 SQL 和失败前已执行 SQL。 支持的注解 @Table 用于解析表名和 schema： @Table("sys_user") public class SysUser { } @TableId 用于识别主键和数据库自增： @TableId private Long id; 默认自增类型为 xbatis 的 IdAutoType.AUTO。 单主键会按数据库方言生成自增片段；联合主键不会为每个主键字段自动生成自增片段。 如果主键使用 IdAutoType.SQL 通过数据库序列取值，会从 sql 中解析序列名并在建表前生成 CREATE SEQUENCE： @TableId(dbType = DbType.Name.PGSQL, value = IdAutoType.SQL, sql = "select nextval('id_test_id_seq')") @TableId(dbType = DbType.Name.ORACLE, value = IdAutoType.SQL, sql = "select id_test_seq.NEXTVAL FROM dual") @TableId(dbType = DbType.Name.SQL_SERVER, value = IdAutoType.SQL, sql = "select next value for id_test_sqlserver_seq") @TableId(dbType = DbType.Name.DB2, value = IdAutoType.SQL, sql = "select next value for id_test_db2_seq from sysibm.sysdummy1") private Long id; 当前支持解析 PostgreSQL：nextval('sequence_name') Oracle / DM：sequence_name.NEXTVAL SQL Server / DB2：NEXT VALUE FOR sequence_name 其他数据库：兜底解析上述常见形式，并生成通用序列 DDL： CREATE SEQUENCE my_sequence START WITH 1 INCREMENT BY 1; UPDATE 模式会读取数据库已有序列，只创建缺失序列，不重复创建。 @ColumnDefinition 用于控制建表字段定义： @ColumnDefinition( length = 64, nullable = false, unique = true, comment = "用户名" ) private String username; 常用配置： length：字符串长度 precision：数值精度 scale：小数位数 defaultValue：数据库默认值 SQL 片段 nullable：是否允许为空 unique：是否唯一 definition：字段类型片段，配置后优先替代 Java 类型到数据库类型的自动推导，length、precision、scale、defaultValue、nullable、unique、comment 等其他配置仍会继续生效 comment：字段注释；MySQL 使用列内联 COMMENT，PostgreSQL / Oracle / DM 使用独立 COMMENT ON COLUMN，SQL Server 使用 sys.sp_addextendedproperty 当 definition 本身没有包含括号参数时，会按配置补齐长度或精度，例如 @ColumnDefinition(definition = "VARCHAR", length = 64) 会生成 VARCHAR(64)；如果已经写成 VARCHAR(64)，则不会再追加参数。 unique = true 目前表示单字段唯一约束： CREATE 模式下，多数关系型数据库使用列内联 UNIQUE UPDATE 模式新增字段时，SQLite 不支持 ALTER TABLE ADD COLUMN ... UNIQUE，会改为先新增字段再生成 CREATE UNIQUE INDEX ClickHouse 不支持传统唯一约束，配置 unique = true 时会直接抛出异常，避免生成无效 SQL 不支持联合唯一、部分唯一索引、命名唯一约束和已存在字段的唯一约束同步 @Index 用于在实体类上声明数据库索引： import cn.xbatis.db.IndexDirection; import cn.xbatis.db.annotations.Index; import cn.xbatis.db.annotations.IndexField; import cn.xbatis.db.annotations.Table; @Index(name = "idx_sys_user_username", fields = @IndexField(name = "username")) @Index( name = "uk_sys_user_username_created_at", unique = true, fields = { @IndexField(name = "username"), @IndexField(name = "createdAt", direction = IndexDirection.DESC) } ) @Table("sys_user") public class SysUser { } 说明： name：索引名；为空时按表名和列名生成稳定索引名 unique：是否唯一索引 fields：索引字段，name 使用实体字段名，也兼容已映射的列名 direction：索引字段排序，支持 ASC、DESC，默认不追加排序片段 CREATE 模式下，建表后生成 CREATE INDEX UPDATE 模式下，只按索引名创建数据库中缺失的索引，不修改或删除已有索引 ClickHouse 不支持传统 CREATE INDEX 时会直接抛出异常，避免生成无效 SQL PostgreSQL 字段注释会生成额外 SQL： COMMENT ON COLUMN sys_user.username IS '用户名'; SQL Server 字段注释会生成扩展属性 SQL： DECLARE @schema sysname = SCHEMA_NAME(); EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'用户名', @level0type=N'SCHEMA', @level0name=@schema, @level1type=N'TABLE', @level1name=N'sys_user', @level2type=N'COLUMN', @level2name=N'username'; 类型映射 默认类型映射包括： String / Character / UUID -> VARCHAR Integer / int -> INTEGER Long / long / BigInteger -> BIGINT Short / short -> SMALLINT Boolean / boolean -> BOOLEAN、MySQL 为 TINYINT(1) BigDecimal -> DECIMAL(precision, scale) Float / Double -> 浮点类型 byte[] -> 二进制大字段 LocalDate -> DATE LocalTime -> TIME，Oracle / DM 使用 TIMESTAMP LocalDateTime / Timestamp / Date -> TIMESTAMP，MySQL 使用 DATETIME，SQL Server 使用 DATETIME2 普通 enum -> VARCHAR(64) 实现 xbatis EnumSupport<T> 的枚举 -> 按 T 的类型映射，例如 EnumSupport<Integer> -> INTEGER 具体类型会根据 DbType 做方言调整。
