ag-kit 数据库 Schema 设计实战指南规范化、主键、时间戳、关系与外键约束【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit本指南围绕 ag-kit 仓库中 database-design 技能包 的核心文档 schema-design.md 展开系统讲解表结构设计中最关键的五类决策何时规范化、如何选主键、时间戳怎么放、关系如何建模、外键删除行为怎么定。读完你不仅能对照决策树完成一套可落地的数据模型还能借助仓库自带的 schema_validator.py 校验脚本自动检查 Schema 的常见问题把设计原则变成可重复执行的质量门禁。这份文档在技能包中的定位在 ag-kit 的.agents/skills/database-design/目录下schema-design.md与 database-selection.md选库、orm-selection.md选 ORM、indexing.md索引、optimization.md查询优化、migrations.md迁移共同构成一套完整的数据库设计知识体系。其中schema-design.md承担的是建模阶段的骨架职责在选好数据库与 ORM 之后、在考虑索引与迁移之前先把表的形状、主键、时间戳、关系和外键行为定清楚。技能包的 SKILL.md 明确要求Learn to THINK, not copy SQL patterns——本指南的原则不是让你照抄某段 SQL而是学会在具体上下文中做决策。这一点同样体现在 database-architect.md 的说明中该技能teaches PRINCIPLES——apply decision-making based on context, not copying patterns blindly。因此下文每一节都会先给出决策依据再给出可落地的实现方式。规范化决策什么时候拆表什么时候冗余schema-design.md给出了判断是否规范化的核心决策树这是整个 Schema 设计的第一道分岔口When to normalize (separate tables): ├── Data is repeated across rows 数据在行间重复出现 ├── Updates would need multiple changes 更新需要改动多处 ├── Relationships are clear 关系清晰可建模 └── Query patterns benefit 查询模式受益于拆分 When to denormalize (embed/duplicate): ├── Read performance critical 读性能至关重要 ├── Data rarely changes 数据极少变化 ├── Always fetched together 数据总是被一起读取 └── Simpler queries needed 需要更简单的查询规范化的本质当同一份信息在多行中重复例如订单表里每行都冗余存了客户姓名一旦客户改名就要更新大量行这就是典型的更新异常信号——此时应当拆出独立的客户表用外键关联。规范化通常做到第三范式能消除这类重复与异常代价是查询需要更多的 JOIN。反规范化的本质当读多写少且总是一起取时例如商品表冗余一个category_name字段或统计报表里预聚合计数拆表带来的 JOIN 成本反而大于冗余带来的不一致风险。选择反规范化的前提是数据变化频率足够低并且你接受以一致性维护成本换取读性能。一个务实的判断方法是先按规范化建模保证数据完整性再基于真实查询模式而非猜测决定是否对热点路径反规范化。这两条分支并非互斥大型系统中通常是逻辑上规范化、物理上按需冗余。主键选择四种方案与适用场景schema-design.md给出了主键类型的选型表这是分布式与单体应用都要面对的核心决策类型适用场景关键特点UUID分布式系统、安全敏感场景全局唯一、不可预测但随机无序、索引碎片化ULID需要 UUID 优点 按时间排序128 位、可排序时间前缀、比 UUID 对索引更友好Auto-increment简单应用、单数据库自增整数、最紧凑但易被遍历、多库合并会冲突Natural key很少使用业务语义明确时如身份证号、ISO 国家码省掉一层映射但耦合业务规则选型要点分布式场景优先 UUID/ULID多个节点或 Neon/Turso 这类 serverless 分支环境各自生成主键不会冲突且客户端可离线生成、免去一次往返。文档特别点明 ULID 在 UUID 的基础上sortable by time即时间前缀使新插入的行在 B-tree 索引中大致有序可缓解 UUIDv4 随机性带来的页分裂与缓存命中率下降问题。简单单体优先自增单库、写入量可控时BIGSERIAL/AUTO_INCREMENT体积小、人类可读、排序即插入顺序成本最低。Natural key 需克制业务主键一旦被需求变更如改号、多语言、合规波及关联表全部要跟着改文档明确标注 Rarely。另外一个容易忽略的点主键的选择会直接影响外键列的存储开销与 JOIN 性能——宽字符串自然键作主键时所有引用它的外键列都会膨胀。这也是Natural key 很少用的底层原因。时间戳策略每一张表的三件套schema-design.md给出的时间戳基线非常简单但极其实用For every table: ├── created_at → When created 记录创建时间 ├── updated_at → Last modified 记录最近修改时间 └── deleted_at → Soft delete (if needed) 软删除标记按需 Use TIMESTAMPTZ (with timezone) not TIMESTAMP要点拆解created_at与updated_at是默认标配前者标记数据产生时刻后者用于审计与缓存失效判断。许多 ORM如 Prisma、Drizzle都在 schema 层支持自动维护这两个字段数据库层也可用默认值/触发器兜底。deleted_at按需引入软删除让历史数据可恢复、保留外键引用完整性但代价是每一条查询都要带WHERE deleted_at IS NULL且唯一约束需要考虑已删除行占位的问题。简单业务可以不用有审计或回收站诉求再用。必须用TIMESTAMPTZ而非TIMESTAMPTIMESTAMPTZ即带时区的timestamp with time zone在存储时统一换算为 UTC展示时按会话时区呈现彻底避免服务器时区漂移导致同一时刻被记录成两个值的经典事故。TIMESTAMP不带时区存进去是什么就是什么跨时区部署时极易产生歧义。这一原则在仓库的校验工具中也有印证schema_validator.py 在检查 Prisma schema 时会专门核对每个 model 是否包含createdAt/created_at字段缺失会给出提示missing createdAt field (recommended)。关系类型一对一、一对多、多对多schema-design.md将三种关系类型及其实现方式整理为一张表类型适用场景实现方式One-to-One扩展数据extension data独立表 外键FKOne-to-Many父子结构parent-children外键放在子表Many-to-Many双方都有多个中间表junction table以用户与订单为例三种关系的实现模式如下一对一——把低频或敏感字段拆到扩展表主表与扩展表通过唯一外键互指-- 主表 CREATE TABLE users ( id BIGSERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE ); -- 扩展表user_id 既是外键又是唯一键保证 1:1 CREATE TABLE user_profiles ( user_id BIGINT PRIMARY KEY REFERENCES users(id), avatar_url TEXT );一对多——外键永远放在多的一侧子表CREATE TABLE orders ( id BIGSERIAL PRIMARY KEY, user_id BIGINT NOT NULL REFERENCES users(id), created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); -- 子表 orders 携带 user_id即一对多关系多对多——通过中间表解耦中间表通常用双方外键组成复合主键并各建索引CREATE TABLE order_items ( order_id BIGINT NOT NULL REFERENCES orders(id), product_id BIGINT NOT NULL REFERENCES products(id), quantity INT NOT NULL, PRIMARY KEY (order_id, product_id) );建模时的判断顺序是先识别谁属于谁一对多再看是否存在多个对多个这时引入中间表一对一则只在真正需要拆分大表、隔离敏感列或延迟加载大字段时才引入。外键 ON DELETE四种删除行为的取舍外键不仅定义关联还决定了父行删除时子行如何处置。schema-design.md列出了四种标准行为├── CASCADE → Delete children with parent 父删子随删 ├── SET NULL → Children become orphans 子行外键置空孤儿 ├── RESTRICT → Prevent delete if children exist 有子行则禁止删除 └── SET DEFAULT→ Children get default value 子行外键设为默认值对应到实际业务CASCADE父子强依赖、子行离开父行无意义时使用如订单 → 订单明细删订单连明细一起删。注意级联删除是数据库自动执行的隐式操作批量删除大表时可能产生长事务需谨慎评估锁与性能。SET NULL子行需要保留但可脱离父行时使用如文章 → 作者作者被删后文章仍保留author_id置为 NULL。前提是该外键列必须允许 NULL。RESTRICT以及行为相近的NO ACTION默认最安全的选项——存在引用子行时直接拒绝删除父行强制应用层先处理子数据避免意外删掉整棵子树。SET DEFAULT使用场景较少通常需要外键列有明确兜底值如指向一个unknown占位记录。选择原则可以概括为默认 RESTRICT 保安全明确需要级联时才用 CASCADE需要保留历史孤儿数据时用 SET NULL。删除行为的误配比如该 CASCADE 的地方用了 RESTRICT 导致删不掉或反之误删整片数据是线上事故的高发区值得在建模阶段逐表过一遍。需要说明的是部分分布式数据库例如文档在 database-selection.md 中提到的 PlanetScale对外键支持有限此时ON DELETE 行为就需要在应用层实现——这也是选库时要一并评估的点。落地校验用 schema_validator.py 把原则变成检查项原则写进文档只是第一步ag-kit 在 .agents/skills/database-design/scripts/schema_validator.py 中实现了一个 Schema 校验脚本把上述原则自动化。从源码看它的工作流程是自动发现 Schema 文件扫描**/prisma/schema.prismaPrisma 模型以及**/drizzle/*.ts、**/schema/*.tsDrizzle 表定义仅按文件名包含schema或table判定最多处理 10 个文件find_schema_files。逐模型检查 Prisma Schemavalidate_prisma_schema模型名必须PascalCase否则提示Model xxx should be PascalCase必须存在id字段否则提示might be missing id field必须包含createdAt/created_at否则提示缺少创建时间字段对外键列形如xxxId的字段检查是否添加index([xxxId])未加会提示Consider adding index(...) for better query performance——这正是文档外键列要建索引原则的机器化表达枚举enum名称同样要求 PascalCase。输出结构化结果脚本以 JSON 形式汇总schemas_checked、issues_found、issues列表并声明 Schema 问题属于警告而非失败passed恒为 True不影响流水线中断。使用方式python3 .agents/skills/database-design/scripts/schema_validator.py 项目路径 # 不带参数时默认检查当前目录它的集成价值在 checklist.py 中体现得更清楚该脚本把 Schema 校验注册为P2 Data Layer级别的例行检查CheckSpec(Schema Validation, skills/database-design/scripts/schema_validator.py, P2 Data Layer)意味着每次数据库变更后都应运行一遍作为质量门禁的一部分。这正呼应了 database-architect.md 中Quality Control Loop的要求改完 Schema → 校验 → 测试查询 → 确认可回滚 → 才算完成。设计前的检查清单与反模式结合 SKILL.md 的决策清单在设计 Schema 之前应当逐项确认是否已向用户确认数据库偏好是否为当前上下文而非默认偏好选定了数据库是否考虑了部署环境自托管 / serverless / edge是否已规划索引策略详见 indexing.md是否已定义清楚关系类型SKILL.md 同时列出五条高频反模式写作时值得对照自查❌ 简单应用默认上 PostgreSQLSQLite 可能就够❌ 跳过索引❌ 生产环境用SELECT *❌ 该用结构化数据时存 JSON❌ 无视 N1 查询而 database-architect.md 提供的评审清单Review Checklist可以作为建模完成后的收尾检查每张表都有合适的主键外键约束到位索引基于真实查询模式NOT NULL/CHECK/UNIQUE约束齐全列类型恰当命名一致规范化程度匹配用例迁移有回滚方案无明显 N1 或全表扫描Schema 有文档。总结schema-design.md用五张决策卡片覆盖了表结构设计的全部核心决策点规范化 vs 反规范化解决表怎么拆主键选择解决每张表怎么标识时间戳策略解决审计与生命周期字段怎么放关系类型解决表之间怎么连ON DELETE 行为解决删除时怎么兜底。配合仓库中的 schema_validator.py 自动化校验与 database-architect.md 的评审清单这套原则既可以指导从零建模也可以作为审查存量 Schema 的检查依据。建模完成之后可以继续阅读同一技能包下的 indexing.md索引策略、optimization.mdN1 与 EXPLAIN ANALYZE和 migrations.md零停机迁移形成从设计、优化到变更的完整闭环。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ag-kit 数据库 Schema 设计实战指南规范化、主键、时间戳、关系与外键约束【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit本指南围绕 ag-kit 仓库中 database-design 技能包 的核心文档 schema-design.md 展开系统讲解表结构设计中最关键的五类决策何时规范化、如何选主键、时间戳怎么放、关系如何建模、外键删除行为怎么定。读完你不仅能对照决策树完成一套可落地的数据模型还能借助仓库自带的 schema_validator.py 校验脚本自动检查 Schema 的常见问题把设计原则变成可重复执行的质量门禁。这份文档在技能包中的定位在 ag-kit 的.agents/skills/database-design/目录下schema-design.md与 database-selection.md选库、orm-selection.md选 ORM、indexing.md索引、optimization.md查询优化、migrations.md迁移共同构成一套完整的数据库设计知识体系。其中schema-design.md承担的是建模阶段的骨架职责在选好数据库与 ORM 之后、在考虑索引与迁移之前先把表的形状、主键、时间戳、关系和外键行为定清楚。技能包的 SKILL.md 明确要求Learn to THINK, not copy SQL patterns——本指南的原则不是让你照抄某段 SQL而是学会在具体上下文中做决策。这一点同样体现在 database-architect.md 的说明中该技能teaches PRINCIPLES——apply decision-making based on context, not copying patterns blindly。因此下文每一节都会先给出决策依据再给出可落地的实现方式。规范化决策什么时候拆表什么时候冗余schema-design.md给出了判断是否规范化的核心决策树这是整个 Schema 设计的第一道分岔口When to normalize (separate tables): ├── Data is repeated across rows 数据在行间重复出现 ├── Updates would need multiple changes 更新需要改动多处 ├── Relationships are clear 关系清晰可建模 └── Query patterns benefit 查询模式受益于拆分 When to denormalize (embed/duplicate): ├── Read performance critical 读性能至关重要 ├── Data rarely changes 数据极少变化 ├── Always fetched together 数据总是被一起读取 └── Simpler queries needed 需要更简单的查询规范化的本质当同一份信息在多行中重复例如订单表里每行都冗余存了客户姓名一旦客户改名就要更新大量行这就是典型的更新异常信号——此时应当拆出独立的客户表用外键关联。规范化通常做到第三范式能消除这类重复与异常代价是查询需要更多的 JOIN。反规范化的本质当读多写少且总是一起取时例如商品表冗余一个category_name字段或统计报表里预聚合计数拆表带来的 JOIN 成本反而大于冗余带来的不一致风险。选择反规范化的前提是数据变化频率足够低并且你接受以一致性维护成本换取读性能。一个务实的判断方法是先按规范化建模保证数据完整性再基于真实查询模式而非猜测决定是否对热点路径反规范化。这两条分支并非互斥大型系统中通常是逻辑上规范化、物理上按需冗余。主键选择四种方案与适用场景schema-design.md给出了主键类型的选型表这是分布式与单体应用都要面对的核心决策类型适用场景关键特点UUID分布式系统、安全敏感场景全局唯一、不可预测但随机无序、索引碎片化ULID需要 UUID 优点 按时间排序128 位、可排序时间前缀、比 UUID 对索引更友好Auto-increment简单应用、单数据库自增整数、最紧凑但易被遍历、多库合并会冲突Natural key很少使用业务语义明确时如身份证号、ISO 国家码省掉一层映射但耦合业务规则选型要点分布式场景优先 UUID/ULID多个节点或 Neon/Turso 这类 serverless 分支环境各自生成主键不会冲突且客户端可离线生成、免去一次往返。文档特别点明 ULID 在 UUID 的基础上sortable by time即时间前缀使新插入的行在 B-tree 索引中大致有序可缓解 UUIDv4 随机性带来的页分裂与缓存命中率下降问题。简单单体优先自增单库、写入量可控时BIGSERIAL/AUTO_INCREMENT体积小、人类可读、排序即插入顺序成本最低。Natural key 需克制业务主键一旦被需求变更如改号、多语言、合规波及关联表全部要跟着改文档明确标注 Rarely。另外一个容易忽略的点主键的选择会直接影响外键列的存储开销与 JOIN 性能——宽字符串自然键作主键时所有引用它的外键列都会膨胀。这也是Natural key 很少用的底层原因。时间戳策略每一张表的三件套schema-design.md给出的时间戳基线非常简单但极其实用For every table: ├── created_at → When created 记录创建时间 ├── updated_at → Last modified 记录最近修改时间 └── deleted_at → Soft delete (if needed) 软删除标记按需 Use TIMESTAMPTZ (with timezone) not TIMESTAMP要点拆解created_at与updated_at是默认标配前者标记数据产生时刻后者用于审计与缓存失效判断。许多 ORM如 Prisma、Drizzle都在 schema 层支持自动维护这两个字段数据库层也可用默认值/触发器兜底。deleted_at按需引入软删除让历史数据可恢复、保留外键引用完整性但代价是每一条查询都要带WHERE deleted_at IS NULL且唯一约束需要考虑已删除行占位的问题。简单业务可以不用有审计或回收站诉求再用。必须用TIMESTAMPTZ而非TIMESTAMPTIMESTAMPTZ即带时区的timestamp with time zone在存储时统一换算为 UTC展示时按会话时区呈现彻底避免服务器时区漂移导致同一时刻被记录成两个值的经典事故。TIMESTAMP不带时区存进去是什么就是什么跨时区部署时极易产生歧义。这一原则在仓库的校验工具中也有印证schema_validator.py 在检查 Prisma schema 时会专门核对每个 model 是否包含createdAt/created_at字段缺失会给出提示missing createdAt field (recommended)。关系类型一对一、一对多、多对多schema-design.md将三种关系类型及其实现方式整理为一张表类型适用场景实现方式One-to-One扩展数据extension data独立表 外键FKOne-to-Many父子结构parent-children外键放在子表Many-to-Many双方都有多个中间表junction table以用户与订单为例三种关系的实现模式如下一对一——把低频或敏感字段拆到扩展表主表与扩展表通过唯一外键互指-- 主表 CREATE TABLE users ( id BIGSERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE ); -- 扩展表user_id 既是外键又是唯一键保证 1:1 CREATE TABLE user_profiles ( user_id BIGINT PRIMARY KEY REFERENCES users(id), avatar_url TEXT );一对多——外键永远放在多的一侧子表CREATE TABLE orders ( id BIGSERIAL PRIMARY KEY, user_id BIGINT NOT NULL REFERENCES users(id), created_at TIMESTAMPTZ NOT NULL DEFAULT now() ); -- 子表 orders 携带 user_id即一对多关系多对多——通过中间表解耦中间表通常用双方外键组成复合主键并各建索引CREATE TABLE order_items ( order_id BIGINT NOT NULL REFERENCES orders(id), product_id BIGINT NOT NULL REFERENCES products(id), quantity INT NOT NULL, PRIMARY KEY (order_id, product_id) );建模时的判断顺序是先识别谁属于谁一对多再看是否存在多个对多个这时引入中间表一对一则只在真正需要拆分大表、隔离敏感列或延迟加载大字段时才引入。外键 ON DELETE四种删除行为的取舍外键不仅定义关联还决定了父行删除时子行如何处置。schema-design.md列出了四种标准行为├── CASCADE → Delete children with parent 父删子随删 ├── SET NULL → Children become orphans 子行外键置空孤儿 ├── RESTRICT → Prevent delete if children exist 有子行则禁止删除 └── SET DEFAULT→ Children get default value 子行外键设为默认值对应到实际业务CASCADE父子强依赖、子行离开父行无意义时使用如订单 → 订单明细删订单连明细一起删。注意级联删除是数据库自动执行的隐式操作批量删除大表时可能产生长事务需谨慎评估锁与性能。SET NULL子行需要保留但可脱离父行时使用如文章 → 作者作者被删后文章仍保留author_id置为 NULL。前提是该外键列必须允许 NULL。RESTRICT以及行为相近的NO ACTION默认最安全的选项——存在引用子行时直接拒绝删除父行强制应用层先处理子数据避免意外删掉整棵子树。SET DEFAULT使用场景较少通常需要外键列有明确兜底值如指向一个unknown占位记录。选择原则可以概括为默认 RESTRICT 保安全明确需要级联时才用 CASCADE需要保留历史孤儿数据时用 SET NULL。删除行为的误配比如该 CASCADE 的地方用了 RESTRICT 导致删不掉或反之误删整片数据是线上事故的高发区值得在建模阶段逐表过一遍。需要说明的是部分分布式数据库例如文档在 database-selection.md 中提到的 PlanetScale对外键支持有限此时ON DELETE 行为就需要在应用层实现——这也是选库时要一并评估的点。落地校验用 schema_validator.py 把原则变成检查项原则写进文档只是第一步ag-kit 在 .agents/skills/database-design/scripts/schema_validator.py 中实现了一个 Schema 校验脚本把上述原则自动化。从源码看它的工作流程是自动发现 Schema 文件扫描**/prisma/schema.prismaPrisma 模型以及**/drizzle/*.ts、**/schema/*.tsDrizzle 表定义仅按文件名包含schema或table判定最多处理 10 个文件find_schema_files。逐模型检查 Prisma Schemavalidate_prisma_schema模型名必须PascalCase否则提示Model xxx should be PascalCase必须存在id字段否则提示might be missing id field必须包含createdAt/created_at否则提示缺少创建时间字段对外键列形如xxxId的字段检查是否添加index([xxxId])未加会提示Consider adding index(...) for better query performance——这正是文档外键列要建索引原则的机器化表达枚举enum名称同样要求 PascalCase。输出结构化结果脚本以 JSON 形式汇总schemas_checked、issues_found、issues列表并声明 Schema 问题属于警告而非失败passed恒为 True不影响流水线中断。使用方式python3 .agents/skills/database-design/scripts/schema_validator.py 项目路径 # 不带参数时默认检查当前目录它的集成价值在 checklist.py 中体现得更清楚该脚本把 Schema 校验注册为P2 Data Layer级别的例行检查CheckSpec(Schema Validation, skills/database-design/scripts/schema_validator.py, P2 Data Layer)意味着每次数据库变更后都应运行一遍作为质量门禁的一部分。这正呼应了 database-architect.md 中Quality Control Loop的要求改完 Schema → 校验 → 测试查询 → 确认可回滚 → 才算完成。设计前的检查清单与反模式结合 SKILL.md 的决策清单在设计 Schema 之前应当逐项确认是否已向用户确认数据库偏好是否为当前上下文而非默认偏好选定了数据库是否考虑了部署环境自托管 / serverless / edge是否已规划索引策略详见 indexing.md是否已定义清楚关系类型SKILL.md 同时列出五条高频反模式写作时值得对照自查❌ 简单应用默认上 PostgreSQLSQLite 可能就够❌ 跳过索引❌ 生产环境用SELECT *❌ 该用结构化数据时存 JSON❌ 无视 N1 查询而 database-architect.md 提供的评审清单Review Checklist可以作为建模完成后的收尾检查每张表都有合适的主键外键约束到位索引基于真实查询模式NOT NULL/CHECK/UNIQUE约束齐全列类型恰当命名一致规范化程度匹配用例迁移有回滚方案无明显 N1 或全表扫描Schema 有文档。总结schema-design.md用五张决策卡片覆盖了表结构设计的全部核心决策点规范化 vs 反规范化解决表怎么拆主键选择解决每张表怎么标识时间戳策略解决审计与生命周期字段怎么放关系类型解决表之间怎么连ON DELETE 行为解决删除时怎么兜底。配合仓库中的 schema_validator.py 自动化校验与 database-architect.md 的评审清单这套原则既可以指导从零建模也可以作为审查存量 Schema 的检查依据。建模完成之后可以继续阅读同一技能包下的 indexing.md索引策略、optimization.mdN1 与 EXPLAIN ANALYZE和 migrations.md零停机迁移形成从设计、优化到变更的完整闭环。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
