# migration

**Repository Path**: fiberphp/migration

## Basic Information

- **Project Name**: migration
- **Description**: 📋 FiberPHP 数据库迁移组件 —— 版本化管理数据库结构，支持 Schema 构建、回滚、状态查看，开箱即用。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Migration

FiberPHP 数据库迁移子包。提供 Schema 构建器（Blueprint）、迁移执行器（Migrator）、迁移文件生成器（Creator）与一组命令行工具，支持表结构版本管理、批量回滚、刷新重置，覆盖
MySQL / PostgreSQL / SQLite 三种驱动方言。

## 特性

- **Schema 构建器**：`Schema::create/table/drop/dropIfExists/rename/hasTable/hasColumn` 静态门面，内部委托 `Blueprint`
  链式声明字段与索引
- **Blueprint 字段链**：`id/string/text/integer/bigInteger/float/decimal/boolean/datetime/date/timestamp/json/enum` +
  `nullable/default/comment/after` 修饰；`timestamps/softDelete` 快捷；`index/unique/primary/dropIndex/dropColumn` 索引与列操作
- **外键链式**：`foreign(columns).references(columns).on(table).onDelete(action).onUpdate(action)`，`dropForeign` 解除
- **驱动感知 DDL**：`toSql()` 按 `driver`（mysql/pgsql/sqlite）生成方言化建表 / 改表语句，表选项（engine/charset/collate/表注释）按需应用
- **迁移版本管理**：`migrations` 日志表记录已执行迁移与批次号（batch），`run` 计算 pending 差集按序执行
- **事务包裹**：MySQL / PgSQL 迁移在事务内执行（失败自动回滚）；SQLite 对 DDL 事务支持有限，直接执行
- **时间戳文件名**：`YYYY_MM_DD_His_Snake_name.php`，按字典序天然保证执行顺序
- **匿名类迁移**：迁移文件 `return new class extends Migration { up()/down() };`，无需显式命名空间
- **命令行工具**：`make:migration` / `migrate:run` / `migrate:rollback` / `migrate:refresh` / `migrate:status`

## 环境要求

- PHP >= 8.5
- `fiberphp/framework` dev-master
- `fiberphp/database` dev-master
- `fiberphp/console` dev-master
- `fiberphp/container` dev-master
- `fiberphp/helper` dev-master

## 安装

```bash
composer require fiberphp/migration
```

安装后由 `extra.fiberphp.pathRelation` 自动发布 `config/migration.php`，并通过 `extra.fiberphp.commands` 注册 5 个迁移命令。

## 配置

`config/migration.php`：

```php
return [
    // 迁移文件所在目录（相对于 BASE_PATH）
    'path' => base_path('database/migrations'),

    // 迁移记录表名
    'table' => 'migrations',

    // 使用的数据库连接名（null 表示使用默认连接）
    'connection' => null,
];
```

## 命令

| 命令                               | 说明                                                              |
|------------------------------------|-------------------------------------------------------------------|
| `make:migration <name> [--table=]` | 创建迁移文件（传 `--table` 生成 create 表模板，否则生成空白模板） |
| `migrate:run`                      | 执行所有 pending 迁移（按文件名顺序，记入下一批次）               |
| `migrate:rollback`                 | 回滚最后一批迁移（按 batch 降序执行 down）                        |
| `migrate:refresh`                  | 回滚全部迁移后重新执行（refresh = rollback + run）                |
| `migrate:status`                   | 列出所有迁移与执行状态（Ran=Yes/No）                              |

示例：

```bash
# 创建建表迁移
php fiber make:migration CreateUsersTable --table=users

# 执行迁移
php fiber migrate:run

# 查看状态
php fiber migrate:status

# 回滚最后一批
php fiber migrate:rollback

# 全部回滚并重新迁移
php fiber migrate:refresh
```

## 编写迁移

迁移文件位于 `database/migrations/`，命名格式 `YYYY_MM_DD_His_Snake_name.php`（由 `Creator` 自动生成时间戳前缀），文件须返回一个继承
`Migration` 的匿名类实例：

```php
<?php

declare(strict_types=1);

use FiberPHP\Migration\Blueprint;
use FiberPHP\Migration\Migration;
use FiberPHP\Migration\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table): void {
            $table->id();
            $table->string('name', 64)->comment('用户名');
            $table->string('email', 128)->unique();
            $table->string('password_hash', 255);
            $table->boolean('active')->default(true);
            $table->timestamps();
            $table->softDelete();

            // 外键示例
            $table->foreign('dept_id')
                ->references('id')
                ->on('departments')
                ->onDelete('cascade');
        });
    }

    public function down(): void
    {
        Schema::drop('users');
    }
};
```

修改已有表用 `Schema::table()`：

```php
Schema::table('users', function (Blueprint $table): void {
    $table->string('phone', 20)->after('email')->nullable();
    $table->dropColumn('password_hash');
    $table->index(['name', 'active']);
});
```

## Blueprint 主要字段方法

| 类别   | 方法                                                                                      |
|--------|-------------------------------------------------------------------------------------------|
| 主键   | `id()` / `incrementId($column)`                                                           |
| 数值   | `integer` / `bigInteger` / `float` / `decimal` / `boolean`                                |
| 字符串 | `string($col, $len=255)` / `text` / `enum($col, $allowed)` / `json`                       |
| 时间   | `datetime` / `date` / `timestamp` / `timestamps()` / `softDelete()`                       |
| 修饰   | `nullable()` / `default($col, $val)` / `defaultVal($val)` / `comment($c)` / `after($col)` |
| 索引   | `index` / `unique` / `primary` / `dropIndex` / `dropColumn` / `renameColumn`              |
| 外键   | `foreign` → `references` → `on` → `onDelete` / `onUpdate` / `dropForeign`                 |
| 表选项 | `engine` / `charset` / `collate` / `tableComment`                                         |

## 目录结构

```
src/
├── Blueprint.php                         # 表结构构建器（链式字段 + 驱动感知 toSql）
├── Creator.php                           # 迁移文件生成器（时间戳命名 + stub）
├── Migration.php                         # 迁移基类（up/down + schema() 代理）
├── MigrationRepository.php               # 迁移日志表读写（migrations 表）
├── Migrator.php                          # 迁移执行器（run/rollback/refresh/status）
├── Schema.php                            # Schema 静态门面（委托给 Blueprint）
├── Command/
│   ├── AbstractMigrationCommand.php      # 命令基类（惰性绑定 Migrator 单例）
│   ├── Make.php                          # make:migration
│   ├── Migrate.php                       # migrate:run
│   ├── Refresh.php                      # migrate:refresh
│   ├── Rollback.php                     # migrate:rollback
│   └── Status.php                       # migrate:status
└── Exception/
    └── MigrationException.php
```

## License

MIT License (c) 2026 庞斌，详见 [LICENSE](LICENSE)。