laravel-migrations

涵盖 Laravel 13 数据库迁移：用于创建、修改和删除表的 Schema Builder API、50 多种列类型和修饰符、索引类型（primary、unique、fulltext、spatial）、带级联选项的外键约束、Artisan 迁移命令、Seeder、迁移测试、安全的生产环境发布、故障排查，以及通过 Schema::ensureVectorExtensionExists() 启用 pgvector 以支持向量列（查询向量列请参阅 laravel-vector-search）。

Laravel 迁移

Agent 工作流（强制）

任何实现开始前，先并行启动 3 个 Agent，每个使用一个 Agent 调用，并指定 name：

1. fuse-ai-pilot:explore-codebase - 检查现有迁移
2. fuse-ai-pilot:research-expert - 通过 Context7 验证 Laravel 13 模式
3. mcp__context7__query-docs - 检查特定的 Schema Builder 功能

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

功能	说明
Schema Builder	创建、修改、删除表
列	50 多种列类型及修饰符
索引	Primary、unique、fulltext、spatial
外键	带级联选项的约束
Seeder	填充表数据

---

关键规则

1. 始终定义 down() - 确保迁移可回滚
2. 使用 foreignId()->constrained() - 不要使用原始 unsignedBigInteger
3. 为外键添加索引 - 对性能至关重要
4. 部署前测试回滚 - 验证 down() 是否正常工作
5. 绝不修改已部署的迁移 - 创建新的迁移

---

决策指南

迁移类型

Need schema change?
├── New table → make:migration create_X_table
├── Add column → make:migration add_X_to_Y_table
├── Modify column → make:migration modify_X_in_Y_table
├── Add index → make:migration add_index_to_Y_table
└── Seed data → make:seeder XSeeder

列类型选择

使用场景	类型	示例
主键	id()	自增 BIGINT
外键	foreignId()->constrained()	引用父级
UUID 主键	uuid()->primary()	UUID
布尔值	boolean()	is_active
枚举	enum('status', [...])	order_status
JSON	json()	preferences
金额	decimal('price', 10, 2)	99999999.99
时间戳	timestamps()	created_at、updated_at
软删除	softDeletes()	deleted_at

外键级联

场景	onDelete	使用场景
严格完整性	restrictOnDelete()	财务记录
自动清理	cascadeOnDelete()	帖子 → 评论
保留并设为 null	nullOnDelete()	可选关系
不采取操作	noActionOnDelete()	审计日志

---

参考指南

核心概念

主题	参考资料	何时查阅
Schema	schema.md	表操作
列	columns.md	列类型
索引	indexes.md	性能索引
外键	foreign-keys.md	约束
命令	commands.md	Artisan 命令
数据填充	seeding.md	填充数据

高级主题

主题	参考资料	何时查阅
测试	testing.md	测试迁移
生产环境	production.md	安全部署
故障排查	troubleshooting.md	修复错误

模板

模板	使用场景
CreateTableMigration.php.md	新建表
ModifyTableMigration.php.md	修改表
PivotTableMigration.php.md	多对多关系
Seeder.php.md	数据填充模式
MigrationTest.php.md	测试迁移

---

快速参考

创建表

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('title');
    $table->text('content');
    $table->enum('status', ['draft', 'published'])->default('draft');
    $table->timestamps();
    $table->softDeletes();

    $table->index(['user_id', 'status']);
});

修改表

Schema::table('posts', function (Blueprint $table) {
    $table->string('slug')->after('title')->unique();
    $table->boolean('featured')->default(false);
});

命令

php artisan make:migration create_posts_table
php artisan migrate
php artisan migrate:rollback --step=1
php artisan migrate:fresh --seed

---

最佳实践

应该做

• 对外键使用 foreignId()->constrained()
• 为常见查询添加复合索引
• 部署前测试 down() 方法
• 使用 --pretend 预览 SQL

不应该做

• 修改已部署的迁移
• 忘记 down() 方法
• 不使用 Schema Builder 而直接编写原始 SQL
• 忽略外键上的索引

---

Laravel 13 说明

Schema::ensureVectorExtensionExists()（pgvector）

Laravel 13 提供了一个辅助方法，可在迁移中为 PostgreSQL 启用 pgvector 扩展。适用于嵌入向量和语义搜索。

use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::ensureVectorExtensionExists();

        Schema::create('documents', function (Blueprint $table) {
            $table->id();
            $table->text('content');
            $table->vector('embedding', dimensions: 1536)->index(); // OpenAI text-embedding-3-small; HNSW cosine vector index
            $table->timestamps();
            // equivalent: $table->vectorIndex('embedding'); — removal: dropVectorIndex() (13.30+)
        });
    }
};

MariaDB 11.7+ 也支持 vector 列/索引（无需扩展）。有关 whereVectorSimilarTo() 查询，请参阅 [[laravel-vector-search]]。

Schema Builder 13.x 新特性

• $table->foreignUuidFor(User::class)（13.9+）和 foreignUlidFor()（13.25+）
• 无锁索引：$table->string('email')->unique()->online();（PostgreSQL / SQL Server）
• 在索引或外键上使用 ->inplace()（13.33+，MySQL），采用 INPLACE DDL 算法