Files

2026-03-05 21:27:11 +08:00

3.1 KiB

Raw Permalink Blame History

name, version, description

name	version	description
database-migration	3.0.0	使用 Hyperf Migrations 安全管理数据库 Schema 变更。当需要创建表、添加字段或修改索引时使用。确保迁移安全可回滚。

⚠️ 核心执行流程已在 .cursor/rules/skill-database-migration.mdc 中由 Cursor 自动注入。本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。

Hyperf Database Migration

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

迁移核心原则

每次变更都是迁移 — 禁止手动 DDL
Schema 与 Data 严格分离 — DDL 和 DML 分文件
迁移部署后不可变 — 已执行迁移禁止修改
生产前向原则 — 回滚用新前向迁移修正
新字段安全 — 新增字段必须 nullable 或有默认值
迁移前测试 — 大表先在副本验证

目录约定

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. 生成迁移

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。

验证

migrate 无错误
migrate:rollback 可回滚（开发）
Model $fillable / $casts 正确
外键有索引
新字段 nullable 或有默认值
Schema 与 Data 迁移分文件
幂等检查通过
SQL 人工审查
data-model.md 已更新

Tier 3 深度参考

文件	内容
`references/migration-patterns.md`	幂等、Expand-Contract、批量迁移、大表策略、危险操作

3.1 KiB Raw Permalink Blame History Unescape Escape