CakePHP/Phinx 数据库迁移指南：从入门到精通-优快云博客

CakePHP/Phinx 数据库迁移指南：从入门到精通

【免费下载链接】phinx PHP Database Migrations for Everyone 项目地址: https://gitcode.com/gh_mirrors/ph/phinx

前言：为什么需要数据库迁移？

在传统开发中，数据库Schema（模式）变更往往是个令人头疼的问题。开发团队经常面临这样的困境：

开发环境、测试环境、生产环境的数据库结构不一致
手动执行SQL脚本容易出错且难以追踪
团队协作时数据库变更冲突频发
回滚操作复杂且容易丢失数据

Phinx作为CakePHP生态中的数据库迁移工具，完美解决了这些问题。它让数据库变更像代码一样可版本控制、可测试、可回滚。

快速入门：5分钟搭建迁移环境

安装Phinx

通过Composer安装Phinx：

composer require robmorgan/phinx

初始化配置

vendor/bin/phinx init

这会生成默认的配置文件 phinx.php：

<?php

return [
    'paths' => [
        'migrations' => '%%PHINX_CONFIG_DIR%%/db/migrations',
        'seeds' => '%%PHINX_CONFIG_DIR%%/db/seeds'
    ],
    'environments' => [
        'default_migration_table' => 'phinxlog',
        'default_environment' => 'development',
        'production' => [
            'adapter' => 'mysql',
            'host' => 'localhost',
            'name' => 'production_db',
            'user' => 'root',
            'pass' => '',
            'port' => 3306,
            'charset' => 'utf8',
        ],
        'development' => [
            'adapter' => 'mysql',
            'host' => 'localhost',
            'name' => 'development_db',
            'user' => 'root',
            'pass' => '',
            'port' => 3306,
            'charset' => 'utf8',
        ]
    ],
    'version_order' => 'creation'
];

创建第一个迁移

vendor/bin/phinx create CreateUsersTable

生成的迁移文件示例：

<?php
declare(strict_types=1);

use Phinx\Migration\AbstractMigration;

final class CreateUsersTable extends AbstractMigration
{
    public function change(): void
    {
        $table = $this->table('users');
        $table->addColumn('username', 'string', ['limit' => 20])
              ->addColumn('email', 'string', ['limit' => 100])
              ->addColumn('password', 'string', ['limit' => 255])
              ->addColumn('created_at', 'datetime')
              ->addColumn('updated_at', 'datetime', ['null' => true])
              ->addIndex(['username', 'email'], ['unique' => true])
              ->create();
    }
}

执行迁移

vendor/bin/phinx migrate

核心概念深度解析

迁移生命周期

mermaid

环境配置详解

Phinx支持多环境配置，这是企业级应用的关键特性：

environments:
  default_migration_table: phinxlog
  default_environment: development
  
  # 开发环境
  development:
    adapter: mysql
    host: localhost
    name: myapp_dev
    user: dev_user
    pass: dev_password
    port: 3306
    charset: utf8mb4
    collation: utf8mb4_unicode_ci
  
  # 测试环境  
  testing:
    adapter: mysql  
    host: test-db.example.com
    name: myapp_test
    user: test_user
    pass: test_password
    port: 3306
  
  # 生产环境
  production:
    adapter: mysql
    host: prod-db.example.com
    name: myapp_prod
    user: prod_user
    pass: ${DB_PASSWORD}  # 使用环境变量
    port: 3306

迁移文件命名规范

Phinx使用时间戳前缀确保迁移顺序：

格式	示例	说明
YYYYMMDDHHMMSS	20231201143000	年月日时分秒
迁移名称	CreateUsersTable	驼峰命名法
完整文件名	20231201143000_create_users_table.php	组合格式

高级迁移技巧

1. 复杂表结构设计

public function change(): void
{
    $table = $this->table('products', [
        'id' => false,
        'primary_key' => ['id'],
        'engine' => 'InnoDB',
        'collation' => 'utf8mb4_unicode_ci'
    ]);
    
    $table->addColumn('id', 'biginteger', ['identity' => true, 'signed' => false])
          ->addColumn('name', 'string', ['limit' => 255])
          ->addColumn('description', 'text')
          ->addColumn('price', 'decimal', ['precision' => 10, 'scale' => 2])
          ->addColumn('category_id', 'integer')
          ->addColumn('is_active', 'boolean', ['default' => true])
          ->addColumn('metadata', 'json')
          ->addColumn('created_at', 'timestamp', [
              'default' => 'CURRENT_TIMESTAMP'
          ])
          ->addColumn('updated_at', 'timestamp', [
              'default' => 'CURRENT_TIMESTAMP',
              'update' => 'CURRENT_TIMESTAMP'
          ])
          ->addForeignKey('category_id', 'categories', 'id', [
              'delete' => 'RESTRICT',
              'update' => 'CASCADE'
          ])
          ->addIndex(['name'], ['unique' => true])
          ->addIndex(['category_id', 'is_active'])
          ->create();
}

2. 数据迁移与转换

public function up(): void
{
    // 创建新表
    $table = $this->table('new_users');
    $table->addColumn('username', 'string')
          ->addColumn('email', 'string')
          ->create();
    
    // 从旧表迁移数据
    $oldUsers = $this->fetchAll('SELECT * FROM old_users');
    foreach ($oldUsers as $user) {
        $this->table('new_users')->insert([
            'username' => $user['user_name'],
            'email' => $user['email_address']
        ])->saveData();
    }
}

public function down(): void
{
    $this->execute('TRUNCATE TABLE new_users');
    $this->dropTable('new_users');
}

3. 条件迁移与业务逻辑

public function change(): void
{
    if ($this->isMigratingUp()) {
        // 只在升级时执行的逻辑
        $this->execute('UPDATE settings SET value = "new_value" WHERE key = "feature_flag"');
    }
    
    // 可逆操作
    $table = $this->table('posts');
    $table->addColumn('title', 'string')
          ->addColumn('content', 'text')
          ->create();
    
    if ($this->isMigratingUp()) {
        // 初始化数据
        $this->table('posts')->insert([
            ['title' => 'Welcome', 'content' => 'First post content']
        ])->saveData();
    }
}

数据库适配器支持对比

Phinx支持多种数据库系统，各适配器特性对比如下：

特性	MySQL	PostgreSQL	SQLite	SQL Server
事务支持	部分*	完全	完全	完全
JSON类型	✅	✅	❌	✅
枚举类型	✅	❌	❌	❌
表注释	✅	✅	❌	✅
外键约束	✅	✅	✅	✅

*注：MySQL的DDL操作（CREATE/ALTER/DROP TABLE）会隐式提交事务

企业级最佳实践

1. 多模块迁移管理

paths:
  migrations:
    - '%%PHINX_CONFIG_DIR%%/module_a/migrations'
    - '%%PHINX_CONFIG_DIR%%/module_b/migrations'
    - '%%PHINX_CONFIG_DIR%%/module_c/migrations'
  seeds:
    - '%%PHINX_CONFIG_DIR%%/module_a/seeds'  
    - '%%PHINX_CONFIG_DIR%%/module_b/seeds'

2. 安全的凭证管理

使用环境变量避免敏感信息泄露：

'environments' => [
    'production' => [
        'adapter' => 'mysql',
        'host' => getenv('DB_HOST'),
        'name' => getenv('DB_NAME'),
        'user' => getenv('DB_USER'),
        'pass' => getenv('DB_PASS'),
        'port' => getenv('DB_PORT', 3306)
    ]
]

3. 迁移测试策略

class MigrationTest extends TestCase
{
    public function testMigrationUpDown(): void
    {
        $config = require 'phinx.php';
        $config['environments']['test'] = [
            'adapter' => 'sqlite',
            'name' => ':memory:'
        ];
        
        $manager = new Manager($config, new StringInput(' '), new NullOutput());
        
        // 测试迁移
        $manager->migrate('test');
        $this->assertTrue($this->hasTable('users'));
        
        // 测试回滚
        $manager->rollback('test', 0);
        $this->assertFalse($this->hasTable('users'));
    }
}

常见问题解决方案

1. 迁移冲突处理

当多个开发者同时创建迁移时，可能产生时间戳冲突。解决方案：

# 重新生成时间戳
vendor/bin/phinx create MyMigration --date=20231201150000

2. 大表迁移性能优化

对于大数据表，采用分阶段迁移：

public function up(): void
{
    // 第一阶段：创建新表结构
    $this->createNewTableStructure();
    
    // 第二阶段：分批迁移数据
    $this->migrateDataInBatches();
    
    // 第三阶段：切换表名
    $this->switchTables();
}

private function migrateDataInBatches(): void
{
    $batchSize = 1000;
    $offset = 0;
    
    do {
        $data = $this->fetchAll(
            "SELECT * FROM old_table LIMIT {$batchSize} OFFSET {$offset}"
        );
        
        foreach ($data as $row) {
            $this->table('new_table')->insert($row)->saveData();
        }
        
        $offset += $batchSize;
    } while (!empty($data));
}

3. 回滚失败处理

当自动回滚不可行时，使用手动回滚方法：

public function down(): void
{
    // 不可逆操作需要手动实现
    throw new IrreversibleMigrationException(
        'This migration cannot be reversed automatically. ' .
        'Please implement manual rollback logic.'
    );
}

进阶特性探索

自定义迁移模板

创建个性化迁移模板：

【免费下载链接】phinx PHP Database Migrations for Everyone 项目地址: https://gitcode.com/gh_mirrors/ph/phinx

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考