Phinx数据库迁移工具：编写迁移脚本完全指南

Phinx数据库迁移工具：编写迁移脚本完全指南

phinx 项目地址: https://gitcode.com/gh_mirrors/phi/phinx

什么是Phinx迁移

Phinx是一个强大的数据库迁移工具，它通过PHP类文件来管理数据库结构变更。每个迁移文件代表一次数据库变更操作，可以创建表、修改字段、添加索引等。Phinx支持两种编写方式：使用其提供的PHP API或直接编写SQL语句。

创建新迁移文件

生成迁移骨架

使用命令行工具创建新迁移文件：

vendor/bin/phinx create MyNewMigration

这会生成一个带时间戳的迁移文件，格式为YYYYMMDDHHMMSS_MyNewMigration.php。文件内容包含一个基本的迁移类结构：

<?php
use Phinx\Migration\AbstractMigration;

class MyNewMigration extends AbstractMigration
{
    public function change()
    {
        // 迁移逻辑写在这里
    }
}

迁移方法详解

change方法（推荐）

Phinx 0.2.0引入了可逆迁移的概念，这是目前推荐的写法。只需定义"up"逻辑，Phinx会自动推导如何回滚：

public function change()
{
    $table = $this->table('user_logins');
    $table->addColumn('user_id', 'integer')
          ->addColumn('created', 'datetime')
          ->create();
}

Phinx会自动处理以下操作的回滚：

• 创建表
• 重命名表
• 添加列
• 重命名列
• 添加索引
• 添加外键

对于不可逆操作，可以使用条件判断：

if ($this->isMigratingUp()) {
    // 仅在上行迁移时执行
}

传统方法：up和down

虽然change方法更简洁，但也可以使用传统的up/down方法：

public function up()
{
    // 执行迁移
}

public function down()
{
    // 回滚迁移
}

其他辅助方法

• init(): 在迁移方法前执行，用于初始化
• shouldExecute(): 控制是否执行当前迁移

执行SQL查询

Phinx支持直接执行SQL语句：

// 执行并返回影响行数
$count = $this->execute('DELETE FROM users WHERE id = ?', [5]);

// 查询并返回结果集
$stmt = $this->query('SELECT * FROM users WHERE id > ?', [5]);
$rows = $stmt->fetchAll();

数据操作

插入数据

$table = $this->table('status');

// 单行插入
$table->insert([
    'id' => 1,
    'name' => 'In Progress'
])->saveData();

// 多行插入
$table->insert([
    ['id' => 2, 'name' => 'Stopped'],
    ['id' => 3, 'name' => 'Queued']
])->saveData();

表操作API

创建表

$users = $this->table('users');
$users->addColumn('username', 'string', ['limit' => 20])
      ->addColumn('password', 'string', ['limit' => 40])
      ->addColumn('email', 'string', ['limit' => 100])
      ->addColumn('created', 'datetime')
      ->addIndex(['username', 'email'], ['unique' => true])
      ->create();

主键设置

默认情况下，Phinx会自动创建名为id的自增主键。可以自定义：

// 禁用自动id，设置复合主键
$this->table('followers', [
    'id' => false,
    'primary_key' => ['user_id', 'follower_id']
]);

// 修改主键名称
$this->table('followers', ['id' => 'user_id']);

表选项

MySQL支持的表选项：

• comment: 表注释
• engine: 存储引擎（默认InnoDB）
• collation: 排序规则（默认utf8mb4_unicode_ci）
• signed: 主键是否带符号（默认false）

最佳实践

1. 优先使用change()方法实现可逆迁移
2. 表操作后必须调用create()或update()保存变更
3. 复杂操作考虑使用up()/down()方法
4. 批量插入数据考虑使用种子功能而非迁移
5. 为表添加适当的注释和索引

通过掌握这些核心概念，你可以高效地使用Phinx管理数据库结构变更，确保开发环境的数据库与生产环境保持同步。

phinx 项目地址: https://gitcode.com/gh_mirrors/phi/phinx