88 lines
3.1 KiB
Markdown
88 lines
3.1 KiB
Markdown
---
|
||
name: database-migration
|
||
version: 3.0.0
|
||
description: "使用 Hyperf Migrations 安全管理数据库 Schema 变更。当需要创建表、添加字段或修改索引时使用。确保迁移安全可回滚。"
|
||
---
|
||
|
||
> ⚠️ 核心执行流程已在 `.cursor/rules/skill-database-migration.mdc` 中由 Cursor 自动注入。
|
||
> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
|
||
|
||
# Hyperf Database Migration
|
||
|
||
## ⚠️ 安全等级：ORANGE — 执行前必须确认
|
||
|
||
## 迁移核心原则
|
||
|
||
1. **每次变更都是迁移** — 禁止手动 DDL
|
||
2. **Schema 与 Data 严格分离** — DDL 和 DML 分文件
|
||
3. **迁移部署后不可变** — 已执行迁移禁止修改
|
||
4. **生产前向原则** — 回滚用新前向迁移修正
|
||
5. **新字段安全** — 新增字段必须 nullable 或有默认值
|
||
6. **迁移前测试** — 大表先在副本验证
|
||
|
||
## 目录约定
|
||
|
||
```
|
||
Case-Database-Backend/
|
||
├── database/
|
||
│ ├── migrations/ ← 迁移文件（已通过 DI 工厂注册到 Migrator）
|
||
│ └── seeders/ ← 种子文件（已通过 DI 工厂注册到 Seed）
|
||
```
|
||
|
||
路径配置说明：
|
||
- Hyperf 默认迁移路径为 `migrations/`，本项目通过 `App\Database\MigratorFactory` 覆盖为 `database/migrations/`
|
||
- Seeder 路径通过 `App\Database\SeedFactory` 覆盖为 `database/seeders/`
|
||
- `gen:migration` / `gen:seeder` 路径在 `config/autoload/devtool.php` 中配置
|
||
|
||
## 触发条件
|
||
|
||
用户要求修改数据库结构、添加/删除字段、创建/删除表、修改索引或关联。
|
||
|
||
## 执行流程
|
||
|
||
### 0. 加载规范
|
||
|
||
读取 `.cursor/rules/014-database.mdc`，提取表设计、索引规则、Migration 写法、高并发注意事项。
|
||
|
||
### 1. 理解变更需求
|
||
|
||
确认：变更什么、是否涉及数据迁移、是否可逆、是否有线上数据、数据量级、环境阶段。
|
||
|
||
### 2. 生成迁移
|
||
|
||
```bash
|
||
php bin/hyperf.php gen:migration create_{{table_name}}_table
|
||
# 文件自动生成到 database/migrations/ 目录
|
||
# 命名: create_orders_table | add_status_to_orders | remove_legacy_field_from_users
|
||
```
|
||
|
||
### 3. 编写迁移
|
||
|
||
Schema::create / Schema::table，含 id、audit 字段、索引。down() 必须完整可逆。幂等、Expand-Contract、批量迁移见 **Tier 3**。
|
||
|
||
### 4. 高并发表设计检查
|
||
|
||
主键 BIGINT UNSIGNED、utf8mb4、金额 DECIMAL、状态 VARCHAR/TINYINT、外键索引、常用 WHERE 索引、复合索引最左前缀、单表索引 ≤6、JSON 仅非查询、避免过多 TEXT。
|
||
|
||
### 5. 执行与更新
|
||
|
||
`php bin/hyperf.php migrate`、`migrate:status`、`migrate:rollback`。`gen:model {{table_name}}`。更新 Model、Service、Repository、`docs/architecture/data-model.md`。
|
||
|
||
## 验证
|
||
|
||
1. [ ] `migrate` 无错误
|
||
2. [ ] `migrate:rollback` 可回滚（开发）
|
||
3. [ ] Model `$fillable` / `$casts` 正确
|
||
4. [ ] 外键有索引
|
||
5. [ ] 新字段 nullable 或有默认值
|
||
6. [ ] Schema 与 Data 迁移分文件
|
||
7. [ ] 幂等检查通过
|
||
8. [ ] SQL 人工审查
|
||
9. [ ] data-model.md 已更新
|
||
|
||
## Tier 3 深度参考
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `references/migration-patterns.md` | 幂等、Expand-Contract、批量迁移、大表策略、危险操作 |
|