CakePHP/Phinx 数据库迁移工具配置详解

CakePHP/Phinx 数据库迁移工具配置详解

phinx PHP Database Migrations for Everyone 项目地址: https://gitcode.com/gh_mirrors/ph/phinx

前言

Phinx 是一个强大的数据库迁移工具，作为 CakePHP 生态的重要组成部分，它提供了简单高效的方式来管理数据库结构变更。本文将深入解析 Phinx 的配置系统，帮助开发者更好地掌握这一工具。

配置文件基础

Phinx 支持多种配置文件格式，包括 YAML、JSON 和 PHP。初始化项目时会自动生成默认配置文件，通常位于项目根目录下。

文件格式选择

• YAML/YML：简洁易读，适合大多数场景
• JSON：结构化强，适合自动化工具处理
• PHP：最灵活，可以直接返回配置数组，支持动态逻辑

安全注意事项

重要：配置文件包含数据库凭证，必须存放在 Web 服务器无法公开访问的目录中，避免敏感信息泄露。

核心配置详解

迁移路径配置

迁移文件默认存储在 %%PHINX_CONFIG_DIR%%/db/migrations 目录下。%%PHINX_CONFIG_DIR%% 是特殊标记，会自动替换为配置文件所在目录。

paths:
  migrations: /custom/path/to/migrations

支持多路径配置和命名空间映射：

paths:
  migrations:
    App\Migrations: app/migrations
    Vendor\Migrations: vendor/package/migrations

种子数据路径

种子文件默认存储在 %%PHINX_CONFIG_DIR%%/db/seeds 目录下，配置方式与迁移路径类似：

paths:
  seeds: /custom/path/to/seeds

环境配置

Phinx 支持多环境配置，是其主要优势之一：

environments:
  default_migration_table: phinxlog
  default_environment: development
  development:
    adapter: mysql
    host: localhost
    name: dev_db
    user: dev_user
    pass: dev_pass
  production:
    adapter: mysql
    host: prod.example.com
    name: prod_db
    user: prod_user
    pass: prod_pass

迁移表配置

Phinx 使用迁移表跟踪迁移状态，可自定义表名和模式：

environments:
  default_migration_table: custom_migration_log
  development:
    migration_table: dev_migration_log

高级配置技巧

自定义基类

可以自定义迁移和种子基类：

migration_base_class: App\Database\Migration
seed_base_class: App\Database\Seed

模板定制

支持自定义迁移和种子模板：

templates:
  file: templates/migration.php
  seedFile: templates/seed.php

表前缀和后缀

为不同环境配置表前缀和后缀：

environments:
  development:
    table_prefix: dev_
    table_suffix: _v1

环境变量

安全地使用环境变量存储凭证：

environments:
  production:
    user: '%%PHINX_DBUSER%%'
    pass: '%%PHINX_DBPASS%%'

数据源名称(DSN)

使用 DSN 简化连接配置：

environments:
  production:
    dsn: mysql://user:pass@host:3306/dbname?charset=utf8

数据库适配器支持

Phinx 原生支持多种数据库：

MySQL 配置

environments:
  development:
    adapter: mysql
    host: localhost
    port: 3306
    name: dbname
    user: username
    pass: password
    charset: utf8mb4

注意：MySQL 的 DDL 操作会隐式提交事务，迁移失败可能导致部分变更已应用。

PostgreSQL 配置

environments:
  development:
    adapter: pgsql
    host: localhost
    port: 5432
    name: dbname
    user: username
    pass: password
    schema: custom_schema

SQLite 配置

environments:
  development:
    adapter: sqlite
    name: /path/to/database
    suffix: .db
  testing:
    adapter: sqlite
    memory: true

SQL Server 配置

environments:
  development:
    adapter: sqlsrv
    host: localhost
    name: dbname
    user: username
    pass: password
    charset: 65001  # UTF-8 编码

其他实用配置

版本排序

控制迁移执行顺序：

version_order: execution  # 或 creation(默认)

引导文件

在命令执行前运行自定义 PHP 脚本：

paths:
  bootstrap: bootstrap.php

最佳实践建议

1. 安全第一：永远不要将配置文件提交到版本控制系统，特别是生产环境凭证
2. 环境隔离：为每个环境配置独立的数据库连接
3. 模板标准化：定制模板确保团队使用一致的代码风格
4. 命名空间：合理使用命名空间组织迁移和种子类
5. 版本控制：将迁移文件与代码一起纳入版本控制

通过合理配置 Phinx，可以显著提升数据库变更管理的效率和可靠性，是现代化开发流程中不可或缺的工具。

phinx PHP Database Migrations for Everyone 项目地址: https://gitcode.com/gh_mirrors/ph/phinx