104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# 数据库架构 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 // 更新记录
|
||
```
|