🔥 xbatis-ddl-auto 1.0.1 发布全自动 DDL，最强 orm xbatis ！！！
官网https://xbatis.cn xbatis-ddl-auto 是一个基于 xbatis 实体元数据的轻量自动建表工具。 它复用 xbatis 的@Table、@TableId、@TableField、@ColumnDefinition等注解解析结果，根据实体类生成并执行数据库 DDL，提供接近 JPAddl-auto=create/update的使用体验，但不引入 JPA 或 Hibernate。 功能 根据 xbatis 实体生成CREATE TABLESQL 表不存在时自动建表 表存在时可在UPDATE模式下自动追加新增字段 支持只生成 SQL，不执行数据库操作 通过 JDBCDatabaseMetaData判断表、字段和索引是否存在 支持常见 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) 实现 xbatisEnumSupport<T>的枚举 -> 按T的类型映射，例如EnumSupport<Integer>->INTEGER 具体类型会根据DbType做方言调整。
