---
description: >
  Hyperf 数据库迁移技能。数据库 Schema 变更（增删改表/字段/索引）时激活。
  确保迁移安全可回滚。
globs:
  - "**/database/migrations/**/*.php"
alwaysApply: false
---

# Database Migration

> 本文件是精简执行摘要。完整流程、模板和深度参考见：
> Read `.cursor/skills/database-migration/SKILL.md`

> **适用性**：本技能用于**数据库 Schema 变更**。
> 仅查询数据库或读取 Model 时可忽略本技能。

安全等级：ORANGE — 执行前必须确认。

## 核心原则

1. 每次变更都是迁移 — 禁止手动 DDL
2. Schema 与 Data 严格分离 — DDL 和 DML 分文件
3. 迁移部署后不可变 — 已执行迁移禁止修改
4. 新字段安全 — 新增字段必须 nullable 或有默认值

## 执行流程

1. 加载规范：Read `014-database.mdc`
2. 确认变更需求（变更内容、是否涉及数据迁移、是否可逆、数据量级）
3. 生成迁移：`php bin/hyperf.php gen:migration <name>`
4. 编写迁移（Schema::create / Schema::table，down() 必须完整可逆）
5. 高并发表设计检查（主键 BIGINT、utf8mb4、金额 DECIMAL、索引 <=6）
6. 执行：`migrate` → `migrate:status` → 更新 Model、Service、data-model.md

## 验证

- [ ] migrate 无错误
- [ ] migrate:rollback 可回滚
- [ ] Model $fillable / $casts 正确
- [ ] 外键有索引
- [ ] 新字段 nullable 或有默认值
- [ ] Schema 与 Data 迁移分文件
- [ ] data-model.md 已更新

## 深度参考

- `.cursor/skills/database-migration/references/migration-patterns.md`