# Database Migration

> Use when writing, reviewing, or applying any database schema migration or deciding what belongs in the database vs object storage. Do NOT use for read-only queries or seed data scripts.

- Skill: `photonics-dhl/database-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add photonics-dhl/database-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/photonics-dhl/database-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: photonics-dhl (https://skillmd.com/u/photonics-dhl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/photonics-dhl/database-migration

---


# Database Migration — 数据库迁移规范

迁移必须可部署、可回滚，且数据库职责边界清晰（只存元数据）。

## 何时使用 / 何时不使用

- **使用**：新增/修改表结构；写迁移脚本；评审迁移 PR；决定新数据存数据库还是对象存储。
- **不使用**：纯查询、只读报表、与 schema 无关的应用代码。

## 检查清单

1. **向前可部署**：迁移必须与旧版应用代码兼容（先加后删：先 expand 后 contract），部署中途新旧代码共存不炸（Spec §15 末段）。
2. **可回滚或有补偿步骤**：每个迁移必须有明确回滚脚本，或写明不可逆时的补偿步骤（Spec §15："数据库迁移必须向前可部署、可回滚或有明确补偿步骤"）。
3. **生产禁自动破坏性迁移**：删列、改类型、删表等破坏性迁移禁止在生产自动执行；必须人工确认 + 备份验证后运行（Spec §15："生产环境禁止自动执行破坏性迁移"；权限分级见 §20.5：数据库迁移属"询问"级）。
4. **数据库只存元数据**：大型二进制（PDF、图片、Artifact 内容）不得入数据库；数据库只保存元数据和对象键，二进制走 Storage Adapter（Spec §13.1）。
5. **实体覆盖**：新实体设计对照 Spec §15 核心实体清单（User、Workspace、ResearchObject、SDFDocument、Branch、Commit、Version、Publication、Issue、PullRequest、Review、AgentSession、SandboxJob、UsageLedger、AuditLog 等），不得私自发明与既有实体重复的表。
6. **迁移文件归位**：迁移脚本放 `infra/migrations/`（Spec §14.1 Monorepo 结构）。
7. **迁移检查不得跳过**：验收前必须实际运行迁移与回滚验证，禁止"跳过迁移检查"（Spec §20.1-7）。

## 评审迁移 PR 时必问

- 回滚脚本跑过吗？输出是什么？
- 破坏性变更的补偿步骤写在哪？
- 新列是否可空/有默认值，旧代码会不会写入失败？
- 大二进制有没有被存进数据库？（应为对象键 + Storage Adapter，§13.1）