Schema → 迁移 → Seed 工作流指南
创建日期: 2026-03-19
概述
本指南描述从修改数据库 Schema 到数据就绪的完整工作流。
工作流图
plain
修改 Schema (apps/type)
↓
生成迁移 (pnpm -F @01s-11comm/type db:generate)
↓
推送到数据库 (pnpm db:push 或 pnpm db:migrate)
↓
更新 Seed 数据 (修改 seed/modules/*.seed.ts)
↓
填充数据 (pnpm db:seed)场景 1：修改现有表的字段
- 修改
apps/type/src/business/{domain}/{module}/schema.ts - 运行
pnpm -F @01s-11comm/type db:generate生成迁移文件 - 运行
pnpm db:push推送变更到 Neon 数据库 - TypeScript 编译器会提示 seed 模块中需要修改的地方
- 修改对应的
seed/modules/*.seed.ts - 运行
pnpm db:seed重新填充数据
场景 2：新增一张表
- 在
apps/type/src/business/{domain}/{module}/schema.ts中定义新表 - 遵循 Trinity Pattern：Drizzle Table + Zod Schemas + TypeScript Types
- 确保导出链完整（schema.ts → index.ts → business/index.ts）
- 运行
pnpm -F @01s-11comm/type db:generate生成迁移 - 运行
pnpm db:push推送到数据库 - 在对应的
seed/modules/*.seed.ts中添加数据 - 如果是全新领域，创建新
.seed.ts文件并在_registry.ts注册 - 运行
pnpm db:seed验证 - 更新
.claude/skills/neon-db-query/SKILL.md的表清单
场景 3：大幅度重构表结构
当改动较大（如重命名表、合并/拆分表）时：
- 完成 schema 修改
- 运行
pnpm db:reset（核弹级重置） - 这会自动：DROP 全部表 → 清除迁移 → 从 schema 重建 → 填充数据
关键文件位置
| 用途 | 路径 |
|---|---|
| Schema 定义 | apps/type/src/business/{domain}/{module}/schema.ts |
| Drizzle 配置 | apps/admin/drizzle.config.ts |
| Seed 模块 | apps/admin/server/db/seed/modules/*.seed.ts |
| Seed 基础设施 | apps/admin/server/db/seed/helpers.ts, runner.ts, index.ts |
| 迁移文件 | apps/admin/drizzle/ |
注意事项
- 永远先改 Schema，再改 Seed — Seed 文件依赖 Schema 的类型定义
- TRUNCATE CASCADE —
db:seed会清空全部数据再重填，不会有 key 冲突 - 确定性 UUID —
sid()保证多次运行结果一致 - 参考 schema-change-sync 技能 — 确保改表后全项目同步更新
贡献者
ruan-cat