数据库：迁移

简介
生成迁移
- 压缩迁移
迁移结构
运行迁移
- 回滚迁移
数据表 (Tables)
列
索引
活动

简介

迁移就像是数据库的版本控制，允许你的团队定义和共享应用程序的数据库模式定义。如果你曾经在从源代码管理中拉取更改后，还要告诉队友手动向他们的本地数据库模式添加列，那么你已经遇到了数据库迁移所能解决的问题。

Laravel 的 Schema 门面（facade）在 Laravel 支持的所有数据库系统中提供了与数据库无关的表创建和操作支持。通常，迁移会使用此门面来创建和修改数据库表和列。

生成迁移

你可以使用 make:migration Artisan 命令来生成数据库迁移。新的迁移文件将被放置在你的 database/migrations 目录中。每个迁移文件名都包含一个时间戳，允许 Laravel 确定迁移的执行顺序。

1php artisan make:migration create_flights_table

php artisan make:migration create_flights_table

Laravel 会使用迁移名称来尝试猜测表名，以及该迁移是否正在创建新表。如果 Laravel 能够从迁移名称中确定表名，它将预先填充生成的迁移文件中的指定表。否则，你可以在迁移文件中手动指定表名。

如果你想为生成的迁移指定自定义路径，可以在执行 make:migration 命令时使用 --path 选项。给定的路径应相对于你的应用程序根目录。

可以使用存根发布（stub publishing）来自定义迁移存根。

压缩迁移

随着应用程序的构建，你可能会随着时间的推移积累越来越多的迁移文件。这可能会导致你的 database/migrations 目录变得臃肿，包含数百个迁移文件。如果你愿意，可以将这些迁移“压缩”成单个 SQL 文件。要开始使用，请执行 schema:dump 命令。

1php artisan schema:dump
2 
3# Dump the current database schema and prune all existing migrations...
4php artisan schema:dump --prune

php artisan schema:dump

# Dump the current database schema and prune all existing migrations...
php artisan schema:dump --prune

执行此命令后，Laravel 会将“模式（schema）”文件写入应用程序的 database/schema 目录。模式文件的名称将对应于数据库连接名称。现在，当你尝试迁移数据库且没有其他迁移尚未执行时，Laravel 将首先执行你正在使用的数据库连接的模式文件中的 SQL 语句。执行完模式文件的 SQL 语句后，Laravel 将执行任何未包含在模式转储中的剩余迁移。

如果你的应用程序测试使用的数据库连接与你在本地开发中通常使用的连接不同，请确保你已使用该数据库连接转储了模式文件，以便你的测试能够构建数据库。你可能希望在转储本地开发中通常使用的数据库连接后再执行此操作。

1php artisan schema:dump
2php artisan schema:dump --database=testing --prune

php artisan schema:dump
php artisan schema:dump --database=testing --prune

你应该将数据库模式文件提交到源代码管理中，以便团队中的新开发人员能够快速创建应用程序的初始数据库结构。

迁移压缩仅适用于 MariaDB、MySQL、PostgreSQL 和 SQLite 数据库，并利用了数据库的命令行客户端。

迁移结构

迁移类包含两个方法：up 和 down。up 方法用于向数据库添加新表、列或索引，而 down 方法应撤销 up 方法执行的操作。

在这两个方法中，你都可以使用 Laravel 模式构建器来表达性地创建和修改表。要了解 Schema 构建器上可用的所有方法，请查看其文档。例如，以下迁移创建了一个 flights 表：

 1<?php
 2 
 3use Illuminate\Database\Migrations\Migration;
 4use Illuminate\Database\Schema\Blueprint;
 5use Illuminate\Support\Facades\Schema;
 6 
 7return new class extends Migration
 8{
 9    /**
10     * Run the migrations.
11     */
12    public function up(): void
13    {
14        Schema::create('flights', function (Blueprint $table) {
15            $table->id();
16            $table->string('name');
17            $table->string('airline');
18            $table->timestamps();
19        });
20    }
21 
22    /**
23     * Reverse the migrations.
24     */
25    public function down(): void
26    {
27        Schema::drop('flights');
28    }
29};

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('flights', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('airline');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::drop('flights');
    }
};

设置迁移连接

如果你的迁移将与应用程序默认数据库连接以外的数据库连接进行交互，你应该设置迁移的 $connection 属性。

 1/**
 2 * The database connection that should be used by the migration.
 3 *
 4 * @var string
 5 */
 6protected $connection = 'pgsql';
 7 
 8/**
 9 * Run the migrations.
10 */
11public function up(): void
12{
13    // ...
14}

/**
 * The database connection that should be used by the migration.
 *
 * @var string
 */
protected $connection = 'pgsql';

/**
 * Run the migrations.
 */
public function up(): void
{
    // ...
}

跳过迁移

有时，某个迁移可能旨在支持尚未启用的功能，而你不想立即运行它。在这种情况下，你可以在迁移中定义一个 shouldRun 方法。如果 shouldRun 方法返回 false，则会跳过该迁移。

 1use App\Models\Flight;
 2use Laravel\Pennant\Feature;
 3 
 4/**
 5 * Determine if this migration should run.
 6 */
 7public function shouldRun(): bool
 8{
 9    return Feature::active(Flight::class);
10}

use App\Models\Flight;
use Laravel\Pennant\Feature;

/**
 * Determine if this migration should run.
 */
public function shouldRun(): bool
{
    return Feature::active(Flight::class);
}

运行迁移

要运行所有未执行的迁移，请执行 migrate Artisan 命令。

1php artisan migrate

php artisan migrate

如果你想查看哪些迁移已经运行，哪些还在等待中，可以使用 migrate:status Artisan 命令。

1php artisan migrate:status

php artisan migrate:status

如果为 migrate 命令提供了 --step 选项，该命令会将每个迁移作为一个单独的批次运行，从而允许你在稍后使用 migrate:rollback 命令回滚单个迁移。

1php artisan migrate --step

php artisan migrate --step

如果你想查看迁移将要执行的 SQL 语句而不实际运行它们，可以为 migrate 命令提供 --pretend 标志。

1php artisan migrate --pretend

php artisan migrate --pretend

隔离迁移执行

如果你在多台服务器上部署应用程序并将迁移作为部署过程的一部分运行，你可能不希望两台服务器同时尝试迁移数据库。为了避免这种情况，可以在调用 migrate 命令时使用 isolated 选项。

当提供 isolated 选项时，Laravel 将在尝试运行迁移之前使用应用程序的缓存驱动程序获取原子锁。在持有该锁时，所有其他尝试运行 migrate 命令的请求都不会执行；不过，命令仍会以成功的退出状态码退出。

1php artisan migrate --isolated

php artisan migrate --isolated

要使用此功能，您的应用程序必须使用 memcached、redis、dynamodb、database、file 或 array 缓存驱动作为应用程序的默认缓存驱动。此外，所有服务器必须与同一个中央缓存服务器通信。

强制在生产环境中运行迁移

某些迁移操作是破坏性的，这意味着它们可能会导致数据丢失。为了保护你不在生产数据库上运行这些命令，在命令执行前会提示确认。要强制在没有提示的情况下运行命令，请使用 --force 标志。

1php artisan migrate --force

php artisan migrate --force

回滚迁移

要回滚最新的迁移操作，可以使用 rollback Artisan 命令。此命令会回滚最后一“批”迁移，其中可能包含多个迁移文件。

1php artisan migrate:rollback

php artisan migrate:rollback

你可以通过向 rollback 命令提供 step 选项来回滚有限数量的迁移。例如，以下命令将回滚最近的五个迁移：

1php artisan migrate:rollback --step=5

php artisan migrate:rollback --step=5

你可以通过向 rollback 命令提供 batch 选项来回滚特定的“批次”迁移，其中 batch 选项对应于应用程序 migrations 数据表中的批次值。例如，以下命令将回滚第三批中的所有迁移：

1php artisan migrate:rollback --batch=3

php artisan migrate:rollback --batch=3

如果你想查看迁移将要执行的 SQL 语句而不实际运行它们，可以为 migrate:rollback 命令提供 --pretend 标志。

1php artisan migrate:rollback --pretend

php artisan migrate:rollback --pretend

migrate:reset 命令将回滚应用程序的所有迁移。

1php artisan migrate:reset

php artisan migrate:reset

使用单个命令回滚并迁移

migrate:refresh 命令将回滚所有迁移，然后执行 migrate 命令。此命令有效地重新创建了整个数据库。

1php artisan migrate:refresh
2 
3# Refresh the database and run all database seeds...
4php artisan migrate:refresh --seed

php artisan migrate:refresh

# Refresh the database and run all database seeds...
php artisan migrate:refresh --seed

你可以通过向 refresh 命令提供 step 选项来回滚并重新迁移有限数量的迁移。例如，以下命令将回滚并重新迁移最近的五个迁移：

1php artisan migrate:refresh --step=5

php artisan migrate:refresh --step=5

删除所有表并迁移

migrate:fresh 命令将从数据库中删除所有表，然后执行 migrate 命令。

1php artisan migrate:fresh
2 
3php artisan migrate:fresh --seed

php artisan migrate:fresh

php artisan migrate:fresh --seed

默认情况下，migrate:fresh 命令仅删除默认数据库连接中的表。但是，你可以使用 --database 选项来指定应迁移的数据库连接。数据库连接名称应对应于应用程序 database 配置文件中定义的连接。

1php artisan migrate:fresh --database=admin

php artisan migrate:fresh --database=admin

migrate:fresh 命令将删除所有数据库表，无论它们的前缀是什么。在与其他应用程序共享的数据库上进行开发时，应谨慎使用此命令。

数据表 (Tables)

创建数据表

要创建新的数据库表，请在 Schema 门面上使用 create 方法。create 方法接受两个参数：第一个是表名，第二个是一个闭包，接收一个 Blueprint 对象，该对象可用于定义新表。

1use Illuminate\Database\Schema\Blueprint;
2use Illuminate\Support\Facades\Schema;
3 
4Schema::create('users', function (Blueprint $table) {
5    $table->id();
6    $table->string('name');
7    $table->string('email');
8    $table->timestamps();
9});

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email');
    $table->timestamps();
});

在创建表时，你可以使用模式构建器的任何列方法来定义表的列。

确定表/列是否存在

你可以使用 hasTable、hasColumn 和 hasIndex 方法来确定表、列或索引是否存在。

 1if (Schema::hasTable('users')) {
 2    // The "users" table exists...
 3}
 4 
 5if (Schema::hasColumn('users', 'email')) {
 6    // The "users" table exists and has an "email" column...
 7}
 8 
 9if (Schema::hasIndex('users', ['email'], 'unique')) {
10    // The "users" table exists and has a unique index on the "email" column...
11}

if (Schema::hasTable('users')) {
    // The "users" table exists...
}

if (Schema::hasColumn('users', 'email')) {
    // The "users" table exists and has an "email" column...
}

if (Schema::hasIndex('users', ['email'], 'unique')) {
    // The "users" table exists and has a unique index on the "email" column...
}

数据库连接和表选项

如果你想在非默认数据库连接上执行模式操作，请使用 connection 方法。

1Schema::connection('sqlite')->create('users', function (Blueprint $table) {
2    $table->id();
3});

Schema::connection('sqlite')->create('users', function (Blueprint $table) {
    $table->id();
});

此外，还可以使用其他一些属性和方法来定义表创建的其他方面。在使用 MariaDB 或 MySQL 时，engine 属性可用于指定表的存储引擎。

1Schema::create('users', function (Blueprint $table) {
2    $table->engine('InnoDB');
3 
4    // ...
5});

Schema::create('users', function (Blueprint $table) {
    $table->engine('InnoDB');

    // ...
});

在使用 MariaDB 或 MySQL 时，charset 和 collation 属性可用于指定创建表的字符集和排序规则。

1Schema::create('users', function (Blueprint $table) {
2    $table->charset('utf8mb4');
3    $table->collation('utf8mb4_unicode_ci');
4 
5    // ...
6});

Schema::create('users', function (Blueprint $table) {
    $table->charset('utf8mb4');
    $table->collation('utf8mb4_unicode_ci');

    // ...
});

temporary 方法可用于指示表应为“临时表”。临时表仅对当前连接的数据库会话可见，并在连接关闭时自动删除。

1Schema::create('calculations', function (Blueprint $table) {
2    $table->temporary();
3 
4    // ...
5});

Schema::create('calculations', function (Blueprint $table) {
    $table->temporary();

    // ...
});

如果你想为数据库表添加“注释”，可以调用表实例上的 comment 方法。表注释目前仅由 MariaDB、MySQL 和 PostgreSQL 支持。

1Schema::create('calculations', function (Blueprint $table) {
2    $table->comment('Business calculations');
3 
4    // ...
5});

Schema::create('calculations', function (Blueprint $table) {
    $table->comment('Business calculations');

    // ...
});

更新数据表

Schema 门面上的 table 方法可用于更新现有表。与 create 方法一样，table 方法接受两个参数：表名和一个接收 Blueprint 实例的闭包，你可以使用该实例向表中添加列或索引。

1use Illuminate\Database\Schema\Blueprint;
2use Illuminate\Support\Facades\Schema;
3 
4Schema::table('users', function (Blueprint $table) {
5    $table->integer('votes');
6});

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes');
});

重命名 / 删除数据表

要重命名现有的数据库表，请使用 rename 方法。

1use Illuminate\Support\Facades\Schema;
2 
3Schema::rename($from, $to);

use Illuminate\Support\Facades\Schema;

Schema::rename($from, $to);

要删除现有的表，可以使用 drop 或 dropIfExists 方法。

1Schema::drop('users');
2 
3Schema::dropIfExists('users');

Schema::drop('users');

Schema::dropIfExists('users');

重命名带有外键的表

在重命名表之前，你应该确保表上的任何外键约束在迁移文件中都有明确的名称，而不是让 Laravel 分配基于约定的名称。否则，外键约束名称将引用旧的表名。

列

创建列

Schema 门面上的 table 方法可用于更新现有表。与 create 方法一样，table 方法接受两个参数：表名和一个接收 Illuminate\Database\Schema\Blueprint 实例的闭包，你可以使用该实例向表中添加列。

1use Illuminate\Database\Schema\Blueprint;
2use Illuminate\Support\Facades\Schema;
3 
4Schema::table('users', function (Blueprint $table) {
5    $table->integer('votes');
6});

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes');
});

可用列类型

模式构建器蓝图提供了多种方法，对应于你可以添加到数据库表中的不同类型的列。下表中列出了所有可用的方法。

`bigIncrements()`

bigIncrements 方法创建一个自动递增的 UNSIGNED BIGINT（主键）等效列。

1$table->bigIncrements('id');

$table->bigIncrements('id');

`bigInteger()`

bigInteger 方法创建一个 BIGINT 等效列。

1$table->bigInteger('votes');

$table->bigInteger('votes');

`binary()`

binary 方法创建一个 BLOB 等效列。

1$table->binary('photo');

$table->binary('photo');

在使用 MySQL、MariaDB 或 SQL Server 时，你可以传递 length 和 fixed 参数来创建 VARBINARY 或 BINARY 等效列。

1$table->binary('data', length: 16); // VARBINARY(16)
2 
3$table->binary('data', length: 16, fixed: true); // BINARY(16)

$table->binary('data', length: 16); // VARBINARY(16)

$table->binary('data', length: 16, fixed: true); // BINARY(16)

`boolean()`

boolean 方法创建一个 BOOLEAN 等效列。

1$table->boolean('confirmed');

$table->boolean('confirmed');

`char()`

char 方法创建一个具有指定长度的 CHAR 等效列。

1$table->char('name', length: 100);

$table->char('name', length: 100);

`dateTimeTz()`

dateTimeTz 方法创建一个 DATETIME（带时区）等效列，并带有可选的分秒精度。

1$table->dateTimeTz('created_at', precision: 0);

$table->dateTimeTz('created_at', precision: 0);

`dateTime()`

dateTime 方法创建一个 DATETIME 等效列，并带有可选的分秒精度。

1$table->dateTime('created_at', precision: 0);

$table->dateTime('created_at', precision: 0);

`date()`

date 方法创建一个 DATE 等效列。

1$table->date('created_at');

$table->date('created_at');

`decimal()`

decimal 方法创建一个具有指定精度（总位数）和标度（小数点位数）的 DECIMAL 等效列。

1$table->decimal('amount', total: 8, places: 2);

$table->decimal('amount', total: 8, places: 2);

`double()`

double 方法创建一个 DOUBLE 等效列。

1$table->double('amount');

$table->double('amount');

`enum()`

enum 方法创建一个具有给定有效值的 ENUM 等效列。

1$table->enum('difficulty', ['easy', 'hard']);

$table->enum('difficulty', ['easy', 'hard']);

当然，你可以使用 Enum::cases() 方法而不是手动定义允许值的数组。

1use App\Enums\Difficulty;
2 
3$table->enum('difficulty', Difficulty::cases());

use App\Enums\Difficulty;

$table->enum('difficulty', Difficulty::cases());

`float()`

float 方法创建一个具有指定精度的 FLOAT 等效列。

1$table->float('amount', precision: 53);

$table->float('amount', precision: 53);

`foreignId()`

foreignId 方法创建一个 UNSIGNED BIGINT 等效列。

1$table->foreignId('user_id');

$table->foreignId('user_id');

`foreignIdFor()`

foreignIdFor 方法为给定的模型类添加一个 {column}_id 等效列。根据模型键类型的不同，列类型将为 UNSIGNED BIGINT、CHAR(36) 或 CHAR(26)。

1$table->foreignIdFor(User::class);

$table->foreignIdFor(User::class);

`foreignUlid()`

foreignUlid 方法创建一个 ULID 等效列。

1$table->foreignUlid('user_id');

$table->foreignUlid('user_id');

`foreignUuid()`

foreignUuid 方法创建一个 UUID 等效列。

1$table->foreignUuid('user_id');

$table->foreignUuid('user_id');

`geography()`

geography 方法创建一个具有给定空间类型和 SRID（空间参考系统标识符）的 GEOGRAPHY 等效列。

1$table->geography('coordinates', subtype: 'point', srid: 4326);

$table->geography('coordinates', subtype: 'point', srid: 4326);

空间类型的支持取决于你的数据库驱动程序。请参考你的数据库文档。如果你的应用程序使用的是 PostgreSQL 数据库，则必须先安装 PostGIS 扩展，然后才能使用 geography 方法。

`geometry()`

geometry 方法创建一个具有给定空间类型和 SRID（空间参考系统标识符）的 GEOMETRY 等效列。

1$table->geometry('positions', subtype: 'point', srid: 0);

$table->geometry('positions', subtype: 'point', srid: 0);

空间类型的支持取决于你的数据库驱动程序。请参考你的数据库文档。如果你的应用程序使用的是 PostgreSQL 数据库，则必须先安装 PostGIS 扩展，然后才能使用 geometry 方法。

`id()`

id 方法是 bigIncrements 方法的别名。默认情况下，该方法将创建一个 id 列；但是，如果你想为该列指定不同的名称，可以传递一个列名。

1$table->id();

$table->id();

`increments()`

increments 方法创建一个自动递增的 UNSIGNED INTEGER 等效列作为主键。

1$table->increments('id');

$table->increments('id');

`integer()`

integer 方法创建一个 INTEGER 等效列。

1$table->integer('votes');

$table->integer('votes');

`ipAddress()`

ipAddress 方法创建一个 VARCHAR 等效列。

1$table->ipAddress('visitor');

$table->ipAddress('visitor');

使用 PostgreSQL 时，将创建一个 INET 列。

`json()`

json 方法创建一个 JSON 等效列。

1$table->json('options');

$table->json('options');

使用 SQLite 时，将创建一个 TEXT 列。

`jsonb()`

jsonb 方法创建一个 JSONB 等效列。

1$table->jsonb('options');

$table->jsonb('options');

使用 SQLite 时，将创建一个 TEXT 列。

`longText()`

longText 方法创建一个 LONGTEXT 等效列。

1$table->longText('description');

$table->longText('description');

在使用 MySQL 或 MariaDB 时，你可以为该列应用 binary 字符集，以创建 LONGBLOB 等效列。

1$table->longText('data')->charset('binary'); // LONGBLOB

$table->longText('data')->charset('binary'); // LONGBLOB

`macAddress()`

macAddress 方法创建一个旨在存储 MAC 地址的列。某些数据库系统（例如 PostgreSQL）具有专门针对此类数据的列类型。其他数据库系统将使用字符串等效列。

1$table->macAddress('device');

$table->macAddress('device');

`mediumIncrements()`

mediumIncrements 方法创建一个自动递增的 UNSIGNED MEDIUMINT 等效列作为主键。

1$table->mediumIncrements('id');

$table->mediumIncrements('id');

`mediumInteger()`

mediumInteger 方法创建一个 MEDIUMINT 等效列。

1$table->mediumInteger('votes');

$table->mediumInteger('votes');

`mediumText()`

mediumText 方法创建一个 MEDIUMTEXT 等效列。

1$table->mediumText('description');

$table->mediumText('description');

在使用 MySQL 或 MariaDB 时，你可以为该列应用 binary 字符集，以创建 MEDIUMBLOB 等效列。

1$table->mediumText('data')->charset('binary'); // MEDIUMBLOB

$table->mediumText('data')->charset('binary'); // MEDIUMBLOB

`morphs()`

morphs 方法是一个便捷方法，它添加一个 {column}_id 等效列和一个 {column}_type VARCHAR 等效列。{column}_id 的列类型将根据模型键类型的不同而为 UNSIGNED BIGINT、CHAR(36) 或 CHAR(26)。

此方法旨在定义多态 Eloquent 关系所需的列。在以下示例中，将创建 taggable_id 和 taggable_type 列：

1$table->morphs('taggable');

$table->morphs('taggable');

`nullableMorphs()`

该方法类似于 morphs 方法；但是，所创建的列将是“可为空的”（nullable）。

1$table->nullableMorphs('taggable');

$table->nullableMorphs('taggable');

`nullableUlidMorphs()`

该方法类似于 ulidMorphs 方法；但是，所创建的列将是“可为空的”。

1$table->nullableUlidMorphs('taggable');

$table->nullableUlidMorphs('taggable');

`nullableUuidMorphs()`

该方法类似于 uuidMorphs 方法；但是，所创建的列将是“可为空的”。

1$table->nullableUuidMorphs('taggable');

$table->nullableUuidMorphs('taggable');

`rememberToken()`

rememberToken 方法创建一个可为空的 VARCHAR(100) 等效列，旨在存储当前的“记住我” 身份验证令牌。

1$table->rememberToken();

$table->rememberToken();

`set()`

set 方法创建一个具有给定有效值列表的 SET 等效列。

1$table->set('flavors', ['strawberry', 'vanilla']);

$table->set('flavors', ['strawberry', 'vanilla']);

`smallIncrements()`

smallIncrements 方法创建一个自动递增的 UNSIGNED SMALLINT 等效列作为主键。

1$table->smallIncrements('id');

$table->smallIncrements('id');

`smallInteger()`

smallInteger 方法创建一个 SMALLINT 等效列。

1$table->smallInteger('votes');

$table->smallInteger('votes');

`softDeletesTz()`

softDeletesTz 方法添加一个可为空的 deleted_at TIMESTAMP（带时区）等效列，并带有可选的分秒精度。该列旨在存储 Eloquent “软删除”功能所需的 deleted_at 时间戳。

1$table->softDeletesTz('deleted_at', precision: 0);

$table->softDeletesTz('deleted_at', precision: 0);

`softDeletes()`

softDeletes 方法添加一个可为空的 deleted_at TIMESTAMP 等效列，并带有可选的分秒精度。该列旨在存储 Eloquent “软删除”功能所需的 deleted_at 时间戳。

1$table->softDeletes('deleted_at', precision: 0);

$table->softDeletes('deleted_at', precision: 0);

`string()`

string 方法创建一个指定长度的 VARCHAR 等效列。

1$table->string('name', length: 100);

$table->string('name', length: 100);

`text()`

text 方法创建一个 TEXT 等效列。

1$table->text('description');

$table->text('description');

在使用 MySQL 或 MariaDB 时，你可以为该列应用 binary 字符集，以创建 BLOB 等效列。

1$table->text('data')->charset('binary'); // BLOB

$table->text('data')->charset('binary'); // BLOB

`timeTz()`

timeTz 方法创建一个 TIME（带时区）等效列，并带有可选的分秒精度。

1$table->timeTz('sunrise', precision: 0);

$table->timeTz('sunrise', precision: 0);

`time()`

time 方法创建一个 TIME 等效列，并带有可选的分秒精度。

1$table->time('sunrise', precision: 0);

$table->time('sunrise', precision: 0);

`timestampTz()`

timestampTz 方法创建一个 TIMESTAMP（带时区）等效列，并带有可选的分秒精度。

1$table->timestampTz('added_at', precision: 0);

$table->timestampTz('added_at', precision: 0);

`timestamp()`

timestamp 方法创建一个 TIMESTAMP 等效列，并带有可选的分秒精度。

1$table->timestamp('added_at', precision: 0);

$table->timestamp('added_at', precision: 0);

`timestampsTz()`

timestampsTz 方法创建 created_at 和 updated_at TIMESTAMP（带时区）等效列，并带有可选的分秒精度。

1$table->timestampsTz(precision: 0);

$table->timestampsTz(precision: 0);

`timestamps()`

timestamps 方法创建 created_at 和 updated_at TIMESTAMP 等效列，并带有可选的分秒精度。

1$table->timestamps(precision: 0);

$table->timestamps(precision: 0);

`tinyIncrements()`

tinyIncrements 方法创建一个自动递增的 UNSIGNED TINYINT 等效列作为主键。

1$table->tinyIncrements('id');

$table->tinyIncrements('id');

`tinyInteger()`

tinyInteger 方法创建一个 TINYINT 等效列。

1$table->tinyInteger('votes');

$table->tinyInteger('votes');

`tinyText()`

tinyText 方法创建一个 TINYTEXT 等效列。

1$table->tinyText('notes');

$table->tinyText('notes');

在使用 MySQL 或 MariaDB 时，你可以为该列应用 binary 字符集，以创建 TINYBLOB 等效列。

1$table->tinyText('data')->charset('binary'); // TINYBLOB

$table->tinyText('data')->charset('binary'); // TINYBLOB

`unsignedBigInteger()`

unsignedBigInteger 方法创建一个 UNSIGNED BIGINT 等效列。

1$table->unsignedBigInteger('votes');

$table->unsignedBigInteger('votes');

`unsignedInteger()`

unsignedInteger 方法创建一个 UNSIGNED INTEGER 等效列。

1$table->unsignedInteger('votes');

$table->unsignedInteger('votes');

`unsignedMediumInteger()`

unsignedMediumInteger 方法创建一个 UNSIGNED MEDIUMINT 等效列。

1$table->unsignedMediumInteger('votes');

$table->unsignedMediumInteger('votes');

`unsignedSmallInteger()`

unsignedSmallInteger 方法创建一个 UNSIGNED SMALLINT 等效列。

1$table->unsignedSmallInteger('votes');

$table->unsignedSmallInteger('votes');

`unsignedTinyInteger()`

unsignedTinyInteger 方法创建一个 UNSIGNED TINYINT 等效列。

1$table->unsignedTinyInteger('votes');

$table->unsignedTinyInteger('votes');

`ulidMorphs()`

ulidMorphs 方法是一个便捷方法，它添加一个 {column}_id CHAR(26) 等效列和一个 {column}_type VARCHAR 等效列。

此方法旨在定义使用 ULID 标识符的多态 Eloquent 关系所需的列。在以下示例中，将创建 taggable_id 和 taggable_type 列：

1$table->ulidMorphs('taggable');

$table->ulidMorphs('taggable');

`uuidMorphs()`

uuidMorphs 方法是一个便捷方法，它添加一个 {column}_id CHAR(36) 等效列和一个 {column}_type VARCHAR 等效列。

此方法旨在定义使用 UUID 标识符的多态 Eloquent 关系所需的列。在以下示例中，将创建 taggable_id 和 taggable_type 列：

1$table->uuidMorphs('taggable');

$table->uuidMorphs('taggable');

`ulid()`

ulid 方法创建一个 ULID 等效列。

1$table->ulid('id');

$table->ulid('id');

`uuid()`

uuid 方法创建一个 UUID 等效列。

1$table->uuid('id');

$table->uuid('id');

`vector()`

vector 方法创建一个 vector 等效列。

1$table->vector('embedding', dimensions: 100);

$table->vector('embedding', dimensions: 100);

在使用 PostgreSQL 时，必须先加载 pgvector 扩展，然后才能创建 vector 列。

1Schema::ensureVectorExtensionExists();

Schema::ensureVectorExtensionExists();

`year()`

year 方法创建一个 YEAR 等效列。

1$table->year('birth_year');

$table->year('birth_year');

列修饰符

除了上面列出的列类型外，当你向数据库表中添加列时，还可以使用几种“列修饰符”。例如，要使列“可为空”，可以使用 nullable 方法。

1use Illuminate\Database\Schema\Blueprint;
2use Illuminate\Support\Facades\Schema;
3 
4Schema::table('users', function (Blueprint $table) {
5    $table->string('email')->nullable();
6});

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('users', function (Blueprint $table) {
    $table->string('email')->nullable();
});

下表包含所有可用的列修饰符。此列表不包括索引修饰符。

修饰符	描述
`->after('column')`	将列放置在另一个列“之后”（MariaDB / MySQL）。
`->autoIncrement()`	将 `INTEGER` 列设置为自动递增（主键）。
`->charset('utf8mb4')`	为列指定字符集（MariaDB / MySQL）。
`->collation('utf8mb4_unicode_ci')`	为列指定排序规则。
`->comment('my comment')`	为列添加注释（MariaDB / MySQL / PostgreSQL）。
`->default($value)`	为列指定“默认”值。
`->first()`	将列放置在表中的“第一位”（MariaDB / MySQL）。
`->from($integer)`	设置自动递增字段的起始值（MariaDB / MySQL / PostgreSQL）。
`->instant()`	使用即时操作添加或修改列（MySQL）。
`->invisible()`	使列对 `SELECT *` 查询“不可见”（MariaDB / MySQL）。
`->lock($mode)`	为列操作指定锁定模式（MySQL）。
`->nullable($value = true)`	允许将 `NULL` 值插入到该列中。
`->storedAs($expression)`	创建存储的生成列（MariaDB / MySQL / PostgreSQL / SQLite）。
`->unsigned()`	将 `INTEGER` 列设置为 `UNSIGNED`（MariaDB / MySQL）。
`->useCurrent()`	将 `TIMESTAMP` 列设置为使用 `CURRENT_TIMESTAMP` 作为默认值。
`->useCurrentOnUpdate()`	将 `TIMESTAMP` 列设置为在记录更新时使用 `CURRENT_TIMESTAMP`（MariaDB / MySQL）。
`->virtualAs($expression)`	创建虚拟生成列（MariaDB / MySQL / SQLite）。
`->generatedAs($expression)`	创建具有指定序列选项的标识列（PostgreSQL）。
`->always()`	为标识列定义序列值优于输入值的优先级（PostgreSQL）。

默认表达式

default 修饰符接受一个值或一个 Illuminate\Database\Query\Expression 实例。使用 Expression 实例可以防止 Laravel 将值用引号引起来，并允许你使用数据库特定的函数。当你需要为 JSON 列分配默认值时，这特别有用。

 1<?php
 2 
 3use Illuminate\Support\Facades\Schema;
 4use Illuminate\Database\Schema\Blueprint;
 5use Illuminate\Database\Query\Expression;
 6use Illuminate\Database\Migrations\Migration;
 7 
 8return new class extends Migration
 9{
10    /**
11     * Run the migrations.
12     */
13    public function up(): void
14    {
15        Schema::create('flights', function (Blueprint $table) {
16            $table->id();
17            $table->json('movies')->default(new Expression('(JSON_ARRAY())'));
18            $table->timestamps();
19        });
20    }
21};

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Query\Expression;
use Illuminate\Database\Migrations\Migration;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('flights', function (Blueprint $table) {
            $table->id();
            $table->json('movies')->default(new Expression('(JSON_ARRAY())'));
            $table->timestamps();
        });
    }
};

默认表达式的支持取决于你的数据库驱动程序、数据库版本和字段类型。请参考你的数据库文档。

列顺序

在使用 MariaDB 或 MySQL 数据库时，after 方法可用于在模式中的现有列之后添加列。

1$table->after('password', function (Blueprint $table) {
2    $table->string('address_line1');
3    $table->string('address_line2');
4    $table->string('city');
5});

$table->after('password', function (Blueprint $table) {
    $table->string('address_line1');
    $table->string('address_line2');
    $table->string('city');
});

即时列操作

在使用 MySQL 时，你可以将 instant 修饰符链接到列定义上，以指示应使用 MySQL 的“即时”算法来添加或修改该列。此算法允许在不进行完整表重建的情况下执行某些模式更改，从而使它们几乎是瞬时的，无论表的大小如何。

1$table->string('name')->nullable()->instant();

$table->string('name')->nullable()->instant();

即时列添加只能将列追加到表的末尾，因此 instant 修饰符不能与 after 或 first 修饰符结合使用。此外，该算法不支持所有列类型或操作。如果请求的操作不兼容，MySQL 将引发错误。

请参考 MySQL 文档以确定哪些操作与即时列修改兼容。

DDL 锁定

在使用 MySQL 时，你可以将 lock 修饰符链接到列、索引或外键定义上，以控制模式操作期间的表锁定。MySQL 支持几种锁定模式：none 允许并发读写，shared 允许并发读取但阻止写入，exclusive 阻止所有并发访问，default 让 MySQL 选择最合适的模式。

1$table->string('name')->lock('none');
2 
3$table->index('email')->lock('shared');

$table->string('name')->lock('none');

$table->index('email')->lock('shared');

如果请求的锁定模式与操作不兼容，MySQL 将引发错误。lock 修饰符可以与 instant 修饰符结合使用，以进一步优化模式更改。

1$table->string('name')->instant()->lock('none');

$table->string('name')->instant()->lock('none');

修改列

change 方法允许你修改现有列的类型和属性。例如，你可能希望增加 string 列的大小。要查看 change 方法的实际效果，让我们将 name 列的大小从 25 增加到 50。为此，我们只需定义列的新状态，然后调用 change 方法。

1Schema::table('users', function (Blueprint $table) {
2    $table->string('name', 50)->change();
3});

Schema::table('users', function (Blueprint $table) {
    $table->string('name', 50)->change();
});

修改列时，必须显式包含要保留在列定义上的所有修饰符——任何缺失的属性都将被删除。例如，要保留 unsigned、default 和 comment 属性，你必须在更改列时显式调用每个修饰符。

1Schema::table('users', function (Blueprint $table) {
2    $table->integer('votes')->unsigned()->default(1)->comment('my comment')->change();
3});

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->unsigned()->default(1)->comment('my comment')->change();
});

change 方法不会更改列的索引。因此，在修改列时，你可以使用索引修饰符来显式添加或删除索引。

1// Add an index...
2$table->bigIncrements('id')->primary()->change();
3 
4// Drop an index...
5$table->char('postal_code', 10)->unique(false)->change();

// Add an index...
$table->bigIncrements('id')->primary()->change();

// Drop an index...
$table->char('postal_code', 10)->unique(false)->change();

重命名列

要重命名列，可以使用模式构建器提供的 renameColumn 方法。

1Schema::table('users', function (Blueprint $table) {
2    $table->renameColumn('from', 'to');
3});

Schema::table('users', function (Blueprint $table) {
    $table->renameColumn('from', 'to');
});

删除列

要删除列，可以使用模式构建器上的 dropColumn 方法。

1Schema::table('users', function (Blueprint $table) {
2    $table->dropColumn('votes');
3});

Schema::table('users', function (Blueprint $table) {
    $table->dropColumn('votes');
});

你可以通过将包含列名的数组传递给 dropColumn 方法，从表中删除多个列。

1Schema::table('users', function (Blueprint $table) {
2    $table->dropColumn(['votes', 'avatar', 'location']);
3});

Schema::table('users', function (Blueprint $table) {
    $table->dropColumn(['votes', 'avatar', 'location']);
});

可用的命令别名

Laravel 提供了几种与删除常见类型列相关的便捷方法。下表中描述了每种方法。

命令	描述
`$table->dropMorphs('morphable');`	删除 `morphable_id` 和 `morphable_type` 列。
`$table->dropRememberToken();`	删除 `remember_token` 列。
`$table->dropSoftDeletes();`	删除 `deleted_at` 列。
`$table->dropSoftDeletesTz();`	`dropSoftDeletes()` 方法的别名。
`$table->dropTimestamps();`	删除 `created_at` 和 `updated_at` 列。
`$table->dropTimestampsTz();`	`dropTimestamps()` 方法的别名。

索引

创建索引

Laravel 模式构建器支持多种类型的索引。以下示例创建了一个新的 email 列，并指定其值应该是唯一的。为了创建索引，我们可以将 unique 方法链接到列定义上。

1use Illuminate\Database\Schema\Blueprint;
2use Illuminate\Support\Facades\Schema;
3 
4Schema::table('users', function (Blueprint $table) {
5    $table->string('email')->unique();
6});

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('users', function (Blueprint $table) {
    $table->string('email')->unique();
});

或者，你也可以在定义列后创建索引。为此，你应该在模式构建器蓝图上调用 unique 方法。此方法接受应接收唯一索引的列名。

1$table->unique('email');

$table->unique('email');

你甚至可以将列数组传递给索引方法，以创建复合索引。

1$table->index(['account_id', 'created_at']);

$table->index(['account_id', 'created_at']);

创建索引时，Laravel 会自动根据表名、列名和索引类型生成索引名称，但你可以将第二个参数传递给该方法以自行指定索引名称。

1$table->unique('email', 'unique_email');

$table->unique('email', 'unique_email');

可用的索引类型

Laravel 的模式构建器蓝图类提供了用于创建 Laravel 支持的每种类型索引的方法。每个索引方法都接受一个可选的第二个参数来指定索引名称。如果省略，名称将根据用于索引的表名、列名以及索引类型推导出来。下表中描述了每个可用的索引方法。

命令	描述
`$table->primary('id');`	添加主键。
`$table->primary(['id', 'parent_id']);`	添加复合键。
`$table->unique('email');`	添加唯一索引。
`$table->index('state');`	添加普通索引。
`$table->fullText('body');`	添加全文索引（MariaDB / MySQL / PostgreSQL）。
`$table->fullText('body')->language('english');`	添加指定语言的全文索引（PostgreSQL）。
`$table->spatialIndex('location');`	添加空间索引（SQLite 除外）。

在线索引创建

默认情况下，在大表上创建索引可能会锁定表，并在构建索引时阻止读取或写入。在使用 PostgreSQL 或 SQL Server 时，你可以将 online 方法链接到索引定义上，以在不锁定表的情况下创建索引，从而允许你的应用程序在索引创建期间继续读取和写入数据。

1$table->string('email')->unique()->online();

$table->string('email')->unique()->online();

使用 PostgreSQL 时，这会为索引创建语句添加 CONCURRENTLY 选项。使用 SQL Server 时，这会添加 WITH (online = on) 选项。

重命名索引

要重命名索引，可以使用模式构建器蓝图提供的 renameIndex 方法。此方法接受当前索引名称作为第一个参数，接受期望的名称作为第二个参数。

1$table->renameIndex('from', 'to')

$table->renameIndex('from', 'to')

删除索引

要删除索引，必须指定索引的名称。默认情况下，Laravel 会自动根据表名、索引列的名称和索引类型分配索引名称。以下是一些示例：

命令	描述
`$table->dropPrimary('users_id_primary');`	从“users”表中删除主键。
`$table->dropUnique('users_email_unique');`	从“users”表中删除唯一索引。
`$table->dropIndex('geo_state_index');`	从“geo”表中删除普通索引。
`$table->dropFullText('posts_body_fulltext');`	从“posts”表中删除全文索引。
`$table->dropSpatialIndex('geo_location_spatialindex');`	从“geo”表中删除空间索引（SQLite 除外）。

如果你将列数组传递给删除索引的方法，常规索引名称将根据表名、列和索引类型生成。

1Schema::table('geo', function (Blueprint $table) {
2    $table->dropIndex(['state']); // Drops index 'geo_state_index'
3});

Schema::table('geo', function (Blueprint $table) {
    $table->dropIndex(['state']); // Drops index 'geo_state_index'
});

外键约束

Laravel 还支持创建外键约束，这些约束用于在数据库级别强制实施引用完整性。例如，让我们在 posts 表上定义一个 user_id 列，该列引用 users 表上的 id 列。

1use Illuminate\Database\Schema\Blueprint;
2use Illuminate\Support\Facades\Schema;
3 
4Schema::table('posts', function (Blueprint $table) {
5    $table->unsignedBigInteger('user_id');
6 
7    $table->foreign('user_id')->references('id')->on('users');
8});

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('posts', function (Blueprint $table) {
    $table->unsignedBigInteger('user_id');

    $table->foreign('user_id')->references('id')->on('users');
});

由于这种语法比较冗长，Laravel 提供了额外的、更简洁的方法，利用约定来提供更好的开发体验。使用 foreignId 方法创建列时，上面的示例可以改写如下：

1Schema::table('posts', function (Blueprint $table) {
2    $table->foreignId('user_id')->constrained();
3});

Schema::table('posts', function (Blueprint $table) {
    $table->foreignId('user_id')->constrained();
});

foreignId 方法创建一个 UNSIGNED BIGINT 等效列，而 constrained 方法将使用约定来确定所引用的表和列。如果你的表名不符合 Laravel 的约定，你可以手动将其传递给 constrained 方法。此外，还可以指定应分配给生成的索引的名称。

1Schema::table('posts', function (Blueprint $table) {
2    $table->foreignId('user_id')->constrained(
3        table: 'users', indexName: 'posts_user_id'
4    );
5});

Schema::table('posts', function (Blueprint $table) {
    $table->foreignId('user_id')->constrained(
        table: 'users', indexName: 'posts_user_id'
    );
});

你还可以为约束的“删除时”和“更新时”属性指定期望的操作。

1$table->foreignId('user_id')
2    ->constrained()
3    ->onUpdate('cascade')
4    ->onDelete('cascade');

$table->foreignId('user_id')
    ->constrained()
    ->onUpdate('cascade')
    ->onDelete('cascade');

还提供了这些操作的另一种表达性语法。

方法	描述
`$table->cascadeOnUpdate();`	更新应级联。
`$table->restrictOnUpdate();`	更新应受到限制。
`$table->nullOnUpdate();`	更新应将外键值设置为 null。
`$table->noActionOnUpdate();`	更新时无操作。
`$table->cascadeOnDelete();`	删除应级联。
`$table->restrictOnDelete();`	删除应受到限制。
`$table->nullOnDelete();`	删除应将外键值设置为 null。
`$table->noActionOnDelete();`	如果存在子记录，则阻止删除。

任何额外的列修饰符都必须在 constrained 方法之前调用。

1$table->foreignId('user_id')
2    ->nullable()
3    ->constrained();

$table->foreignId('user_id')
    ->nullable()
    ->constrained();

删除外键

要删除外键，可以使用 dropForeign 方法，并将要删除的外键约束名称作为参数传递。外键约束使用与索引相同的命名约定。换句话说，外键约束名称基于表名和约束中的列名，并带有“_foreign”后缀。

1$table->dropForeign('posts_user_id_foreign');

$table->dropForeign('posts_user_id_foreign');

或者，你可以将包含持有外键的列名的数组传递给 dropForeign 方法。该数组将根据 Laravel 的约束命名约定转换为外键约束名称。

1$table->dropForeign(['user_id']);

$table->dropForeign(['user_id']);

切换外键约束

你可以使用以下方法在迁移中启用或禁用外键约束。

1Schema::enableForeignKeyConstraints();
2 
3Schema::disableForeignKeyConstraints();
4 
5Schema::withoutForeignKeyConstraints(function () {
6    // Constraints disabled within this closure...
7});

Schema::enableForeignKeyConstraints();

Schema::disableForeignKeyConstraints();

Schema::withoutForeignKeyConstraints(function () {
    // Constraints disabled within this closure...
});

SQLite 默认禁用外键约束。在使用 SQLite 时，请确保在尝试在迁移中创建外键之前，在你的数据库配置中启用外键支持。

活动

为方便起见，每个迁移操作都会调度一个事件。以下所有事件都扩展了基础 Illuminate\Database\Events\MigrationEvent 类。

类	描述
`Illuminate\Database\Events\MigrationsStarted`	即将执行一批迁移。
`Illuminate\Database\Events\MigrationsEnded`	一批迁移已执行完毕。
`Illuminate\Database\Events\MigrationStarted`	即将执行单个迁移。
`Illuminate\Database\Events\MigrationEnded`	单个迁移已执行完毕。
`Illuminate\Database\Events\NoPendingMigrations`	迁移命令未发现待处理的迁移。
`Illuminate\Database\Events\SchemaDumped`	数据库模式转储已完成。
`Illuminate\Database\Events\SchemaLoaded`	现有的数据库模式转储已加载。

数据库：迁移

在此页面上

产品

Packages

资源

合作伙伴