数据库架构 DSL (Schema-as-Code)

本模块提供了一种基于文本的 DSL（领域专用语言）来定义数据库架构。它支持 MySQL、PostgreSQL 和 SQLite，旨在实现 AI 友好的“架构即代码”。

语法概览

一个架构描述由 分组 (Groups)、数据表 (Tables) 和 字段 (Fields) 组成。

分组 (Groups)

分组由以 == 开头的行定义，用于逻辑隔离不同的表集合。

== 用户系统 ==

数据表 (Tables)

数据表在分组下顶格定义。可以在 // 后添加注释。在表名后添加 SD 标记可启用 影子删除 (Shadow Deletion)。启用后，删除的数据会自动移动到 [表名]_deleted 表中。

users SD // 系统用户表

字段 (Fields)

字段在数据表下通过缩进（空格或制表符）定义。格式：[名称] [类型标记][长度] [索引标记] // [注释]

  id AI // 主键，自动递增
  username v32 U // Varchar(32)，唯一索引
  password v64 // Varchar(64)
  version ver // Bigint 版本号，用于乐观锁和增量同步
  create_time ct // 创建时间 (CURRENT_TIMESTAMP)
  update_time ctu // 更新时间 (ON UPDATE CURRENT_TIMESTAMP)

类型标记 (Type Tags)

标记	对应数据库类型 (MySQL)	说明
`i`	`int`	整型
`ui`	`int unsigned`	无符号整型
`bi`	`bigint`	长整型
`ubi`	`bigint unsigned`	无符号长整型
`ti`	`tinyint`	短整型
`v`	`varchar`	默认长度由驱动决定或忽略
`v[N]`	`varchar(N)`	例如：`v50` -> `varchar(50)`
`c[N]`	`char(N)`	例如：`c32` -> `char(32)`
`t`	`text`	文本
`dt`	`datetime`	日期时间
`d`	`date`	日期
`tm`	`time`	时间
`f`	`float`	浮点数
`ff`	`double`	双精度浮点数
`b`	`tinyint unsigned`	布尔值别名
`bb`	`blob`	二进制大对象

索引与特殊标记

标记	含义
`PK`	主键 (Primary Key)
`AI`	自动递增 + 主键 (Auto Increment)
`U`	唯一索引 (Unique Index)
`I`	普通索引 (Index)
`TI`	全文索引 (Fulltext Index, 仅 MySQL)
`ver`	版本号字段 (用于乐观锁和增量同步)
`ct`	创建时间 (Created Time)
`ctu`	更新时间 (Updated Time)
`nn`	非空 (NOT NULL)
`n`	可为空 (NULL)

复合索引

在 I 或 U 后添加数字可以将多个字段组合成一个复合索引。

  first_name v32 I1
  last_name v32 I1 // 在 (first_name, last_name) 上创建复合索引 'ik_table_1'

高级特性

1. 影子删除 (SD - Shadow Deletion)

当表标记为 SD 时，调用 db.Remove() 方法不会真正删除数据，而是将其从原表移动到 _deleted 后缀的影子表中。

优点：主表查询不包含已删除数据，效率更高；历史数据可追溯。
API: 使用 db.Remove(table, conditions, args...) 触发。

2. 乐观锁与增量同步 (ver)

标记为 ver 的字段（通常命名为 version）具有特殊行为：

自动递增：每次调用 db.Update() 时，该字段会自动 +1。
冲突检测：如果在更新数据中包含了当前版本号，db.Update() 会在 WHERE 条件中自动加入版本校验。如果版本不一致，更新将失败（影响行数为 0）。
增量同步：外部系统可以通过 WHERE version > last_version 轻松获取自上次同步以来的所有变更。

完整示例

== 默认分组 ==
users SD // 用户表
  id AI // 用户 ID
  username v32 U // 登录名
  email v64 U // 联系邮箱
  password v128 // 加密后的密码
  status ti I // 0: 活跃, 1: 禁用
  version ver // 行版本号
  created_at ct // 创建记录
  updated_at ctu // 更新记录

3.8 KiB Raw Permalink Blame History Unescape Escape