xbatis-ddl-auto简介xbatis-ddl-auto是一个基于xbatis实体元数据的轻量自动建表工具。它复用xbatis的 Table、TableId、TableField、ColumnDefinition等注解解析结果根据实体类生成并执行数据库DDL提供接近JPA ddl-autocreate/update的使用体验但不引入JPA或Hibernate。功能特性它具有以下功能根据xbatis实体生成 CREATE TABLE SQL表不存在时自动建表表存在时可在 UPDATE 模式下自动追加新增字段支持只生成SQL不执行数据库操作通过JDBC DatabaseMetaData 判断表、字段和索引是否存在支持常见Java类型到数据库列类型映射支持 ColumnDefinition 配置字段长度、精度、小数位、默认值、唯一约束、非空和字段注释支持类级 Index 创建普通索引和唯一索引。安全边界UPDATE 模式只会自动新增字段和缺失索引不会自动执行以下高风险操作删除数据库已有字段、修改字段类型、修改字段长度、修改字段是否可空、修改默认值、重命名字段、修改或删除已有索引、删除或重建表。这些操作可能造成数据丢失或生产事故建议通过人工审核SQL或专业迁移工具处理。Maven坐标本工具Maven坐标为cn.xbatisxbatis-ddl-auto1.0.1 运行依赖xbatis corecn.xbatisxbatis-core1.10.6 默认测试使用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 sqlList DDLAuto.of(DbType.PGSQL).add(SysUser.class).sqlList();如果要按当前数据库状态预览将要执行的SQL可以传入 DataSource 或 Connection。该方法只读取JDBC元数据并生成SQL不会执行DDLList 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。也可以使用底层构建器生成单个字段的新增列SQLimport 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。可以配置执行监听器记录已执行SQLimport cn.xbatis.ddl.auto.Mode;import cn.xbatis.ddl.auto.DDLExecutionListener;import java.util.ArrayList;import java.util.List;List executedSqlLog new ArrayList();DDLAuto.of(DbType.MYSQL).mode(Mode.UPDATE).executionListener(new DDLExecutionListener() { Override public void afterExecute(String sql, List executedSqlList) { executedSqlLog.add(sql); } Override public void onExecuteError(String sql, SQLException exception, List executedSqlList) { // sql为当前失败SQLexecutedSqlList为失败前已成功执行的SQL。 }}).add(SysUser.class).execute(dataSource);生产或准生产环境建议先通过 sqlList(dataSource) 或 sqlList(connection) 生成SQL并审核再决定是否执行。执行失败时抛出的 SQLException 消息也会包含当前失败SQL和失败前已执行SQL。支持的注解Table用于解析表名和schema示例如下Table(sys_user)public class SysUser {}TableId用于识别主键和数据库自增示例如下TableIdprivate Long id;默认自增类型为xbatis的 IdAutoType.AUTO。单主键会按数据库方言生成自增片段联合主键不会为每个主键字段自动生成自增片段。如果主键使用 IdAutoType.SQL 通过数据库序列取值会从 sql 中解析序列名并在建表前生成 CREATE SEQUENCETableId(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;当前支持解析PostgreSQLnextval(sequence_name)Oracle / DMsequence_name.NEXTVALSQL Server / DB2NEXT VALUE FOR sequence_name其他数据库兜底解析上述常见形式并生成通用序列DDLCREATE 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使用列内联 COMMENTPostgreSQL / Oracle / DM使用独立 COMMENT ON COLUMNSQL Server使用 sys.sp_addextendedproperty。当 definition 本身没有包含括号参数时会按配置补齐长度或精度例如 ColumnDefinition(definition VARCHAR, length 64) 会生成 VARCHAR(64)如果已经写成 VARCHAR(64)则不会再追加参数。unique true 目前表示单字段唯一约束CREATE 模式下多数关系型数据库使用列内联 UNIQUEUPDATE 模式新增字段时SQLite不支持 ALTER TABLE ADD COLUMN ... UNIQUE会改为先新增字段再生成 CREATE UNIQUE INDEXClickHouse不支持传统唯一约束配置 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 INDEXUPDATE 模式下只按索引名创建数据库中缺失的索引不修改或删除已有索引ClickHouse不支持传统 CREATE INDEX 时会直接抛出异常避免生成无效SQL。类型映射默认类型映射包括String / Character / UUID - VARCHARInteger / int - INTEGERLong / long / BigInteger - BIGINTShort / short - SMALLINTBoolean / boolean - BOOLEAN、MySQL为 TINYINT(1)BigDecimal - DECIMAL(precision, scale)Float / Double - 浮点类型byte[] - 二进制大字段LocalDate - DATELocalTime - TIMEOracle / DM使用 TIMESTAMPLocalDateTime / Timestamp / Date - TIMESTAMPMySQL使用 DATETIMESQL Server使用 DATETIME2普通 enum - VARCHAR(64)实现xbatis EnumSupport 的枚举 - 按 T 的类型映射例如 EnumSupport - INTEGER。具体类型会根据 DbType 做方言调整。
