PHP 数据库迁移治理：架构设计、版本控制与多环境管理

# 问题：
开发改了本地表结构 → 忘了同步给同事 → 同事报错
上线前 DBA 跑脚本 → 顺序错了/漏了/重复了 → 线上故障
回滚时凭记忆手写 DROP → 删错列/丢数据

# 迁移系统解决：
版本化：每个变更一个文件，带时间戳/序号
可重复：php artisan migrate 任意次幂等
可回滚：php artisan migrate:rollback 撤销最近一批
多环境：同一份迁移文件在 dev/test/prod 跑一样结果

php artisan make:migration create_posts_table
php artisan migrate                    # 执行未运行的迁移
php artisan migrate:rollback           # 回滚最近一批
php artisan migrate:rollback --step=3  # 回滚 3 批
php artisan migrate:fresh --seed       # 重建+填充（开发用）
php artisan migrate:status             # 查看迁移状态

public function up(): void {
    Schema::create('posts', function (Blueprint $table) {
        $table->id();                          # 自增主键
        $table->foreignId('user_id')->constrained()->onDelete('cascade');
        $table->string('title', 255);
        $table->text('content');
        $table->enum('status', ['draft', 'published'])->default('draft');
        $table->timestamp('published_at')->nullable();
        $table->timestamps();                   # created_at + updated_at
        $table->softDeletes();                  # deleted_at

        $table->index(['status', 'published_at']);
        $table->fullText('content');            # MySQL 8+
    });
}

public function down(): void {
    Schema::dropIfExists('posts');
}

# 格式：动作_表名_补充说明
# 好：create_posts_table、add_slug_to_posts、create_tags_posts_pivot
# 坏：update_db、fix_something
# 原则：看到文件名就知道做了什么

1NF：原子性，每列不可再分
2NF：1NF + 非主键列完全依赖主键（不是部分）
3NF：2NF + 非主键列不传递依赖（不依赖其他非主键）

# 示例：订单表
# 坏：orders(id, customer_name, customer_address, product_name, product_price)
# 好：orders(id, customer_id, product_id, qty) + customers + products

读多写少：冗余字段减少 JOIN（如订单快照存商品名）
报表聚合：物化视图/汇总表（每日统计预计算）
搜索优化：ES 索引冗余存储（标题+摘要+标签）
# 原则：先范式保证一致性，再按查询模式反范式优化

# 用合适的数据类型：INT(11) vs BIGINT vs UNSIGNED
# 日期用 DATE/DATETIME/TIMESTAMP（不要用字符串）
# 金额用 DECIMAL(19,4)（不要用 FLOAT/DOUBLE）
# 状态用 TINYINT / ENUM（MySQL 8+）或 lookup 表
# 软删必选：deleted_at（物理删除是灾难）
# JSON 字段：MySQL 5.7+ / MariaDB 10.2+ 支持，但别当文档库用

B-Tree（默认）：等值/范围/排序/最左前缀
Hash：等值查找（MEMORY 引擎，InnoDB 不直接支持）
Full-Text：文本搜索（MySQL 8+ 中文支持改善）
Spatial：地理空间（MySQL 5.7+）

# WHERE/JOIN/ORDER BY 的字段优先建索引
# 最左前缀：复合索引 (a,b,c) 能支持 a / a,b / a,b,c
# 选择性高的字段放前面（性别选择性低，不适合单独索引）
# 避免冗余：已有 (a,b)，不必单独建 (a)
# 覆盖索引：查询字段全在索引里 → 不回表
# 写了索引要验证：EXPLAIN 看是否用上

# 大表建索引会锁表 → 用 pt-online-schema-change 或 gh-ost
# 定期 ANALYZE TABLE 更新统计信息
# 删除未使用的索引（performance_schema 查）
# 索引碎片 → OPTIMIZE TABLE（或大表用 ALTER ENGINE=INNODB）

# .env.development / .env.testing / .env.production
DB_HOST、DB_DATABASE、DB_USERNAME 按环境配置
# 生产数据库单独用户（最小权限原则）

# 结构：迁移文件版本控制 → 所有环境跑同一套迁移
# 数据：
#   - 开发：seeders + factories 生成假数据
#   - 测试：每个测试用 DatabaseTransactions 回滚
#   - 生产：不直接同步数据，用导出/ETL/消息队列
# 敏感数据：生产数据脱敏后才能到开发环境（GDPR/隐私法）

# 原则：先建表 → 再改表（加字段/索引）→ 再数据迁移 → 再删旧字段
# 禁止：在迁移中做业务逻辑（如遍历全表改数据）→ 用专门的 Artison Command
# CI：migrate 在部署流程的早期执行（代码依赖新表/字段）

# down() 中 DROP COLUMN 会丢数据
# 加了 NOT NULL 默认值的列 → 回滚后数据可能不一致
# 外键约束：回滚顺序与正序相反
# 原则：down() 只删表/删列，不处理数据逻辑

# 1) 数据备份：迁移前 mysqldump 或快照
# 2) 逆向迁移：写 down() 谨慎测试
# 3) 分步发布：先加新列（nullable）→ 应用代码改用新列 → 下一版本删旧列
# 4) 数据迁移单独做：大表数据变更用后台 Job，不在迁移里遍历

// 不用迁移做数据修复，用 Artisan Command
class FixUserEmails extends Command {
    public function handle() {
        User::whereNull('email_verified_at')->chunk(1000, function ($users) {
            foreach ($users as $user) {
                $user->update(['email_verified_at' => now()]);
            }
        });
    }
}

阶段 1（扩展）：
  - 加新列/表/索引（不影响旧代码）
  - 双写：旧代码同时写入新旧列
阶段 2（迁移）：
  - 后台脚本把旧数据补到新列
阶段 3（收缩）：
  - 代码切到新列
  - 下一版本删旧列
# 全程无停机，但需两次发布

# 先绿环境跑迁移（用户还在蓝环境）
# 验证绿环境 → 切流量到绿
# 蓝环境再跑相同迁移（或保持只读）
# 数据库Schema变更在切流量前完成

# 删列：先确认无代码引用
# 改列类型：可能需要新建列+迁移+删旧
# 重命名：先加别名或视图，逐步切
# 主键变更：最危险，考虑新表+数据迁移+改名

# MySQL ALTER TABLE 复制全表到新结构 → 锁表/写阻塞
# 1000万行表：ALTER 可能跑 30 分钟，期间写全部卡住
# 风险：主从延迟、连接打满、MQ 积压

# Percona Toolkit 工具
pt-online-schema-change \
  --alter "ADD COLUMN slug VARCHAR(255)" \
  --execute D=mydb,t=posts

原理：
1) 建新表（带变更）
2) 建触发器（同步旧表增量到新表）
3) 分批复制数据（chunk）
4) 重命名（旧→_old，新→原表名）
5) 删旧表
# 注意：有触发器开销、不能用于含外键的表（MySQL 限制）

# 无触发器设计——用 binlog 订阅增量
gh-ost \
  --database=mydb --table=posts \
  --alter="ADD COLUMN slug VARCHAR(255)" \
  --execute

优势：
- 不建触发器 → 无触发器性能开销
- 可暂停/继续/动态调整复制速度
- 可测试（--test-on-replica）
- 回滚安全（切换前可取消）

< 100 万行：直接 Laravel migrate（ALTER 很快）
100 万 - 1000 万：pt-online-schema-change（简单稳定）
> 1000 万 / 高并发：gh-ost（无触发器、可控）

# 1. 构建阶段：composer install
# 2. 测试阶段：php artisan migrate:fresh --seed（CI 用 SQLite）
# 3. 部署阶段：
#    a) 代码上传
#    b) php artisan migrate --force（非交互，生产必需）
#    c) 清除缓存（config/cache/route/view）
#    d) 健康检查
#    e) 切流量
# 注意：migrate 在代码切换之后、服务启动之前

# PHPUnit 测试迁移一致性
$this->artisan('migrate:fresh');
$this->artisan('migrate:rollback');
$this->artisan('migrate');
// 验证 rollback 后再 migrate 保持一致

# 数据完整性测试：seed 后查关键表结构和约束

# 部署脚本带迁移回滚能力
# 如果 migrate 后健康检查失败 → 自动 rollback
# 或：蓝绿部署，绿环境失败不切换