資料庫：遷移

• 簡介
• 產生遷移
  • 合併遷移
• 遷移結構
• 執行遷移
  • 復原遷移
• 資料表
  • 建立資料表
  • 更新資料表
  • 重新命名／刪除資料表
• 欄位
  • 建立欄位
  • 可用的欄位類型
  • 欄位修飾符
  • 修改欄位
  • 重新命名欄位
  • 刪除欄位
• 索引
  • 建立索引
  • 重新命名索引
  • 刪除索引
  • 外部鍵約束
• 事件

簡介

遷移就像是資料庫的版本控制，讓您的團隊能夠定義和共享應用程式的資料庫綱要定義。如果您曾經需要在同事從版本控制拉取您的變更後，告訴他們手動在其本地資料庫綱要中新增一個欄位，那麼您就遇到了資料庫遷移所要解決的問題。

Laravel 的 Schema facade 提供了與資料庫無關的支援，可在所有 Laravel 支援的資料庫系統中建立和操作資料表。通常，遷移會使用此 facade 來建立和修改資料庫資料表和欄位。

產生遷移

您可以使用 make:migration Artisan 命令來產生資料庫遷移。新的遷移將放置在您的 database/migrations 目錄中。每個遷移檔案名稱都包含一個時間戳記，允許 Laravel 確定遷移的順序：

php artisan make:migration create_flights_table

Laravel 將使用遷移名稱來嘗試猜測資料表名稱以及遷移是否將建立新資料表。如果 Laravel 能夠從遷移名稱中確定資料表名稱，Laravel 將在產生的遷移檔案中預先填入指定的資料表。否則，您可以簡單地在遷移檔案中手動指定資料表。

如果您想為產生的遷移指定自訂路徑，可以在執行 make:migration 命令時使用 --path 選項。給定的路徑應相對於應用程式的基礎路徑。

[!NOTE] 遷移模板可以透過模板發佈來自訂。

合併遷移

隨著您建立應用程式，隨著時間推移，您可能會累積越來越多的遷移。這可能導致您的 database/migrations 目錄變得臃腫，包含數百個遷移。如果您願意，可以將遷移「合併」到一個單一的 SQL 檔案中。首先，執行 schema:dump 命令：

php artisan schema:dump

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

當您執行此命令時，Laravel 將把一個「綱要」檔案寫入應用程式的 database/schema 目錄。綱要檔案的名稱將對應於資料庫連線。現在，當您嘗試遷移資料庫並且尚未執行任何其他遷移時，Laravel 將首先執行您正在使用的資料庫連線的綱要檔案中的 SQL 語句。在執行綱要檔案的 SQL 語句之後，Laravel 將執行不屬於綱要轉儲的任何剩餘遷移。

如果您的應用程式測試使用了與本地開發期間通常使用的資料庫連線不同的連線，您應確保使用該資料庫連線轉儲了一個綱要檔案，以便您的測試能夠建立您的資料庫。您可能希望在轉儲本地開發期間通常使用的資料庫連線之後執行此操作：

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

您應將資料庫綱要檔案提交到版本控制，以便團隊中的其他新開發人員可以快速建立應用程式的初始資料庫結構。

[!WARNING] 遷移合併僅適用於 MariaDB、MySQL、PostgreSQL 和 SQLite 資料庫，並且使用資料庫的命令列客戶端。

遷移結構

遷移類別包含兩個方法：up 和 down。up 方法用於為資料庫新增新的資料表、欄位或索引，而 down 方法應反轉 up 方法執行的操作。

在這兩個方法中，您可以使用 Laravel 綱要建構器來表達式地建立和修改資料表。要了解 Schema 建構器上可用的所有方法，請查看其文件。例如，以下遷移建立了一個 flights 資料表：

<?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 屬性：

/**
 * 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，則該遷移將被跳過：

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 命令：

php artisan migrate

如果您想查看哪些遷移已經執行以及哪些仍在待處理，可以使用 migrate:status Artisan 命令：

php artisan migrate:status

如果您向 migrate 命令提供 --step 選項，該命令將每個遷移作為自己的批次執行，允許您稍後使用 migrate:rollback 命令復原個別遷移：

php artisan migrate --step

如果您想查看遷移將執行的 SQL 語句而不實際執行它們，可以向 migrate 命令提供 --pretend 標誌：

php artisan migrate --pretend

隔離遷移執行

如果您正在跨多個伺服器部署應用程式，並在部署過程中執行遷移，您可能不希望兩台伺服器同時嘗試遷移資料庫。為了避免這種情況，您可以在呼叫 migrate 命令時使用 isolated 選項。

當提供 isolated 選項時，Laravel 將在嘗試執行遷移之前使用應用程式的快取驅動程式取得一個原子鎖定。在該鎖定持有期間，所有其他嘗試執行 migrate 命令的操作都不會執行；但命令仍會以成功的退出狀態碼退出：

php artisan migrate --isolated

[!WARNING] 要使用此功能，您的應用程式必須使用 memcached、redis、dynamodb、database、file 或 array 快取驅動程式作為應用程式的預設快取驅動程式。此外，所有伺服器必須與同一個中央快取伺服器通訊。

強制在生產環境中執行遷移

某些遷移操作具有破壞性，這意味著它們可能導致您遺失資料。為了保護您免於在生產資料庫上執行這些命令，系統會在執行命令之前提示您進行確認。要強制命令執行而不提示，請使用 --force 標誌：

php artisan migrate --force

復原遷移

要復原最新的遷移操作，您可以使用 rollback Artisan 命令。此命令會復原最後一個「批次」的遷移，其中可能包含多個遷移檔案：

php artisan migrate:rollback

您可以透過向 rollback 命令提供 step 選項來復原有限數量的遷移。例如，以下命令將復原最後五個遷移：

php artisan migrate:rollback --step=5

您可以透過向 rollback 命令提供 batch 選項來復原特定「批次」的遷移，其中 batch 選項對應於應用程式 migrations 資料庫表中的一個批次值。例如，以下命令將復原批次三中的所有遷移：

php artisan migrate:rollback --batch=3

如果您想查看遷移將執行的 SQL 語句而不實際執行它們，可以向 migrate:rollback 命令提供 --pretend 標誌：

php artisan migrate:rollback --pretend

migrate:reset 命令將復原應用程式的所有遷移：

php artisan migrate:reset

使用單一命令復原並遷移

migrate:refresh 命令將復原所有遷移，然後執行 migrate 命令。此命令有效地重新建立整個資料庫：

php artisan migrate:refresh

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

您可以透過向 refresh 命令提供 step 選項來復原並重新遷移有限數量的遷移。例如，以下命令將復原並重新遷移最後五個遷移：

php artisan migrate:refresh --step=5

刪除所有資料表並遷移

migrate:fresh 命令將刪除資料庫中的所有資料表，然後執行 migrate 命令：

php artisan migrate:fresh

php artisan migrate:fresh --seed

預設情況下，migrate:fresh 命令僅刪除預設資料庫連線中的資料表。但是，您可以使用 --database 選項指定應遷移的資料庫連線。資料庫連線名稱應對應於應用程式 database 配置檔案中定義的連線：

php artisan migrate:fresh --database=admin

[!WARNING] migrate:fresh 命令將刪除所有資料庫資料表，無論其前綴為何。在與其他應用程式共享的資料庫上開發時，應謹慎使用此命令。

資料表

建立資料表

要建立新的資料庫資料表，請在 Schema facade 上使用 create 方法。create 方法接受兩個參數：第一個是資料表的名稱，第二個是一個閉包，它接收一個 Blueprint 物件，可用於定義新的資料表：

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 方法來確定資料表、欄位或索引是否存在：

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 方法：

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

此外，還可以使用一些其他屬性和方法來定義資料表建立的其他方面。engine 屬性可用於在使用 MariaDB 或 MySQL 時指定資料表的儲存引擎：

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

    // ...
});

charset 和 collation 屬性可用於在使用 MariaDB 或 MySQL 時指定所建立資料表的字元集和排序規則：

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

    // ...
});

temporary 方法可用於指示資料表應該是「暫存」的。暫存資料表僅對目前連線的資料庫工作階段可見，並在連線關閉時自動刪除：

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

    // ...
});

如果您想為資料庫資料表新增「註解」，可以在資料表實例上呼叫 comment 方法。資料表註解目前僅受 MariaDB、MySQL 和 PostgreSQL 支援：

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

    // ...
});

更新資料表

Schema facade 上的 table 方法可用於更新現有資料表。與 create 方法一樣，table 方法接受兩個參數：資料表的名稱和一個閉包，該閉包接收一個 Blueprint 實例，您可以使用它來向資料表新增欄位或索引：

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

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

重新命名／刪除資料表

要重新命名現有的資料庫資料表，請使用 rename 方法：

use Illuminate\Support\Facades\Schema;

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

要刪除現有資料表，您可以使用 drop 或 dropIfExists 方法：

Schema::drop('users');

Schema::dropIfExists('users');

重新命名具有外部鍵的資料表

在重新命名資料表之前，您應該驗證資料表上的任何外部鍵約束在遷移檔案中都有明確的名稱，而不是讓 Laravel 分配基於慣例的名稱。否則，外部鍵約束名稱將引用舊的資料表名稱。

欄位

建立欄位

Schema facade 上的 table 方法可用於更新現有資料表。與 create 方法一樣，table 方法接受兩個參數：資料表的名稱和一個閉包，該閉包接收一個 Illuminate\Database\Schema\Blueprint 實例，您可以使用它來向資料表新增欄位：

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

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

可用的欄位類型

綱要建構器藍圖提供了多種方法，對應於您可以新增到資料庫資料表中的不同欄位類型。以下表格列出了所有可用的方法：

布林類型

字串與文字類型

數字類型

日期與時間類型

二進位類型

物件與 JSON 類型

UUID 與 ULID 類型

空間類型

關聯類型

特殊類型

bigIncrements()

bigIncrements 方法建立一個自動遞增的 UNSIGNED BIGINT（主鍵）等效欄位：

$table->bigIncrements('id');

bigInteger()

bigInteger 方法建立一個 BIGINT 等效欄位：

$table->bigInteger('votes');

binary()

binary 方法建立一個 BLOB 等效欄位：

$table->binary('photo');

使用 MySQL、MariaDB 或 SQL Server 時，您可以傳遞 length 和 fixed 參數來建立 VARBINARY 或 BINARY 等效欄位：

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

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

boolean()

boolean 方法建立一個 BOOLEAN 等效欄位：

$table->boolean('confirmed');

char()

char 方法建立一個指定長度的 CHAR 等效欄位：

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

dateTimeTz()

dateTimeTz 方法建立一個 DATETIME（含時區）等效欄位，可選的小數秒精度：

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

dateTime()

dateTime 方法建立一個 DATETIME 等效欄位，可選的小數秒精度：

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

date()

date 方法建立一個 DATE 等效欄位：

$table->date('created_at');

decimal()

decimal 方法建立一個具有給定精度（總位數）和小數位數的 DECIMAL 等效欄位：

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

double()

double 方法建立一個 DOUBLE 等效欄位：

$table->double('amount');

enum()

enum 方法建立一個具有給定有效值的 ENUM 等效欄位：

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

當然，您可以使用 Enum::cases() 方法而不是手動定義允許值的陣列：

use App\Enums\Difficulty;

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

float()

float 方法建立一個具有給定精度的 FLOAT 等效欄位：

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

foreignId()

foreignId 方法建立一個 UNSIGNED BIGINT 等效欄位：

$table->foreignId('user_id');

foreignIdFor()

foreignIdFor 方法為給定的模型類別新增一個 {column}_id 等效欄位。欄位類型將是 UNSIGNED BIGINT、CHAR(36) 或 CHAR(26)，取決於模型金鑰類型：

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

foreignUlid()

foreignUlid 方法建立一個 ULID 等效欄位：

$table->foreignUlid('user_id');

foreignUuid()

foreignUuid 方法建立一個 UUID 等效欄位：

$table->foreignUuid('user_id');

foreignUuidFor()

foreignUuidFor 方法為給定的模型類別新增一個 {column}_id UUID 等效欄位：

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

geography()

geography 方法建立一個具有給定空間類型和 SRID（空間參考系統識別碼）的 GEOGRAPHY 等效欄位：

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

[!NOTE] 對空間類型的支援取決於您的資料庫驅動程式。請參閱資料庫的文件。如果您的應用程式使用 PostgreSQL 資料庫，則必須在使用 geography 方法之前安裝 PostGIS 擴充功能。

geometry()

geometry 方法建立一個具有給定空間類型和 SRID 的 GEOMETRY 等效欄位：

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

[!NOTE] 對空間類型的支援取決於您的資料庫驅動程式。請參閱資料庫的文件。如果您的應用程式使用 PostgreSQL 資料庫，則必須在使用 geometry 方法之前安裝 PostGIS 擴充功能。

id()

id 方法是 bigIncrements 方法的別名。預設情況下，該方法將建立一個 id 欄位；但是，如果您想為欄位分配不同的名稱，可以傳遞一個欄位名稱：

$table->id();

increments()

increments 方法建立一個自動遞增的 UNSIGNED INTEGER 等效欄位作為主鍵：

$table->increments('id');

integer()

integer 方法建立一個 INTEGER 等效欄位：

$table->integer('votes');

ipAddress()

ipAddress 方法建立一個 VARCHAR 等效欄位：

$table->ipAddress('visitor');

使用 PostgreSQL 時，將建立一個 INET 欄位。

json()

json 方法建立一個 JSON 等效欄位：

$table->json('options');

使用 SQLite 時，將建立一個 TEXT 欄位。

jsonb()

jsonb 方法建立一個 JSONB 等效欄位：

$table->jsonb('options');

使用 SQLite 時，將建立一個 TEXT 欄位。

longText()

longText 方法建立一個 LONGTEXT 等效欄位：

$table->longText('description');

使用 MySQL 或 MariaDB 時，您可以將 binary 字元集應用於欄位，以建立一個 LONGBLOB 等效欄位：

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

macAddress()

macAddress 方法建立一個用於存放 MAC 位址的欄位。某些資料庫系統（如 PostgreSQL）有專用的欄位類型用於此類資料。其他資料庫系統將使用字串等效欄位：

$table->macAddress('device');

mediumIncrements()

mediumIncrements 方法建立一個自動遞增的 UNSIGNED MEDIUMINT 等效欄位作為主鍵：

$table->mediumIncrements('id');

mediumInteger()

mediumInteger 方法建立一個 MEDIUMINT 等效欄位：

$table->mediumInteger('votes');

mediumText()

mediumText 方法建立一個 MEDIUMTEXT 等效欄位：

$table->mediumText('description');

使用 MySQL 或 MariaDB 時，您可以將 binary 字元集應用於欄位，以建立一個 MEDIUMBLOB 等效欄位：

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

morphs()

morphs 方法是一個便捷方法，用於新增一個 {column}_type VARCHAR 等效欄位和一個 {column}_id 等效欄位。{column}_id 的欄位類型將是 UNSIGNED BIGINT、CHAR(36) 或 CHAR(26)，取決於模型金鑰類型。

此方法旨在用於定義多態 Eloquent 關聯所需的欄位。在以下範例中，將建立 taggable_type 和 taggable_id 欄位：

$table->morphs('taggable');

nullableMorphs()

該方法類似於 morphs 方法；但建立的欄位將是「可空」的：

$table->nullableMorphs('taggable');

nullableUlidMorphs()

該方法類似於 ulidMorphs 方法；但建立的欄位將是「可空」的：

$table->nullableUlidMorphs('taggable');

nullableUuidMorphs()

該方法類似於 uuidMorphs 方法；但建立的欄位將是「可空」的：

$table->nullableUuidMorphs('taggable');

rememberToken()

rememberToken 方法建立一個可空的 VARCHAR(100) 等效欄位，用於存放當前的「記住我」認證令牌：

$table->rememberToken();

set()

set 方法建立一個具有給定有效值列表的 SET 等效欄位：

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

smallIncrements()

smallIncrements 方法建立一個自動遞增的 UNSIGNED SMALLINT 等效欄位作為主鍵：

$table->smallIncrements('id');

smallInteger()

smallInteger 方法建立一個 SMALLINT 等效欄位：

$table->smallInteger('votes');

softDeletesTz()

softDeletesTz 方法新增一個可空的 deleted_at TIMESTAMP（含時區）等效欄位，可選的小數秒精度。此欄位用於存放 Eloquent「軟刪除」功能所需的 deleted_at 時間戳：

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

softDeletes()

softDeletes 方法新增一個可空的 deleted_at TIMESTAMP 等效欄位，可選的小數秒精度。此欄位用於存放 Eloquent「軟刪除」功能所需的 deleted_at 時間戳：

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

string()

string 方法建立一個給定長度的 VARCHAR 等效欄位：

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

text()

text 方法建立一個 TEXT 等效欄位：

$table->text('description');

使用 MySQL 或 MariaDB 時，您可以將 binary 字元集應用於欄位，以建立一個 BLOB 等效欄位：

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

timeTz()

timeTz 方法建立一個 TIME（含時區）等效欄位，可選的小數秒精度：

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

time()

time 方法建立一個 TIME 等效欄位，可選的小數秒精度：

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

timestampTz()

timestampTz 方法建立一個 TIMESTAMP（含時區）等效欄位，可選的小數秒精度：

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

timestamp()

timestamp 方法建立一個 TIMESTAMP 等效欄位，可選的小數秒精度：

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

timestampsTz()

timestampsTz 方法建立 created_at 和 updated_at TIMESTAMP（含時區）等效欄位，可選的小數秒精度：

$table->timestampsTz(precision: 0);

timestamps()

timestamps 方法建立 created_at 和 updated_at TIMESTAMP 等效欄位，可選的小數秒精度：

$table->timestamps(precision: 0);

tinyIncrements()

tinyIncrements 方法建立一個自動遞增的 UNSIGNED TINYINT 等效欄位作為主鍵：

$table->tinyIncrements('id');

tinyInteger()

tinyInteger 方法建立一個 TINYINT 等效欄位：

$table->tinyInteger('votes');

tinyText()

tinyText 方法建立一個 TINYTEXT 等效欄位：

$table->tinyText('notes');

使用 MySQL 或 MariaDB 時，您可以將 binary 字元集應用於欄位，以建立一個 TINYBLOB 等效欄位：

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

unsignedBigInteger()

unsignedBigInteger 方法建立一個 UNSIGNED BIGINT 等效欄位：

$table->unsignedBigInteger('votes');

unsignedInteger()

unsignedInteger 方法建立一個 UNSIGNED INTEGER 等效欄位：

$table->unsignedInteger('votes');

unsignedMediumInteger()

unsignedMediumInteger 方法建立一個 UNSIGNED MEDIUMINT 等效欄位：

$table->unsignedMediumInteger('votes');

unsignedSmallInteger()

unsignedSmallInteger 方法建立一個 UNSIGNED SMALLINT 等效欄位：

$table->unsignedSmallInteger('votes');

unsignedTinyInteger()

unsignedTinyInteger 方法建立一個 UNSIGNED TINYINT 等效欄位：

$table->unsignedTinyInteger('votes');

ulidMorphs()

ulidMorphs 方法是一個便捷方法，用於新增一個 {column}_type VARCHAR 等效欄位和一個 {column}_id CHAR(26) 等效欄位。

此方法旨在用於定義使用 ULID 識別碼的多態 Eloquent 關聯所需的欄位。在以下範例中，將建立 taggable_type 和 taggable_id 欄位：

$table->ulidMorphs('taggable');

uuidMorphs()

uuidMorphs 方法是一個便捷方法，用於新增一個 {column}_type VARCHAR 等效欄位和一個 {column}_id CHAR(36) 等效欄位。

此方法旨在用於定義使用 UUID 識別碼的多態 Eloquent 關聯所需的欄位。在以下範例中，將建立 taggable_type 和 taggable_id 欄位：

$table->uuidMorphs('taggable');

ulid()

ulid 方法建立一個 ULID 等效欄位：

$table->ulid('id');

uuid()

uuid 方法建立一個 UUID 等效欄位：

$table->uuid('id');

vector()

vector 方法建立一個 vector 等效欄位：

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

使用 PostgreSQL 時，必須先載入 pgvector 擴充功能才能建立 vector 欄位：

Schema::ensureVectorExtensionExists();

year()

year 方法建立一個 YEAR 等效欄位：

$table->year('birth_year');

欄位修飾符

除了上面列出的欄位類型之外，在向資料庫資料表新增欄位時，還可以使用幾個欄位「修飾符」。例如，要使欄位「可空」，您可以使用 nullable 方法：

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

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

下表包含所有可用的欄位修飾符。此列表不包括索引修飾符：

預設表達式

default 修飾符接受一個值或一個 Illuminate\Database\Query\Expression 實例。使用 Expression 實例將阻止 Laravel 將值包在引號中，並允許您使用資料庫特定的函數。在需要為 JSON 欄位分配預設值時，這一點特別有用：

<?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();
        });
    }
};

[!WARNING] 對預設表達式的支援取決於您的資料庫驅動程式、資料庫版本和欄位類型。請參閱資料庫的文件。

欄位順序

使用 MariaDB 或 MySQL 資料庫時，after 方法可用於在現有欄位之後新增欄位：

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

即時欄位操作

使用 MySQL 時，您可以將 instant 修飾符鏈接到欄位定義上，以指示應使用 MySQL 的「即時」演算法來新增或修改該欄位。此演算法允許某些綱要更改在不重建整個資料表的情況下執行，無論資料表大小如何，幾乎都是即時的：

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

即時欄位新增只能將欄位附加到資料表的末尾，因此 instant 修飾符不能與 after 或 first 修飾符結合使用。此外，該演算法不支援所有欄位類型或操作。如果請求的操作不相容，MySQL 將引發錯誤。

請參閱 MySQL 的文件以確定哪些操作與即時欄位修改相容。

DDL 鎖定

使用 MySQL 時，您可以將 lock 修飾符鏈接到欄位、索引或外部鍵定義上，以控制綱要操作期間的資料表鎖定。MySQL 支援幾種鎖定模式：none 允許並發讀取和寫入，shared 允許並發讀取但阻止寫入，exclusive 阻止所有並發存取，default 讓 MySQL 選擇最合適的模式：

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

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

如果請求的鎖定模式與操作不相容，MySQL 將引發錯誤。lock 修飾符可以與 instant 修飾符結合使用，以進一步最佳化綱要變更：

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

修改欄位

change 方法允許您修改現有欄位的類型和屬性。例如，您可能希望增加 string 欄位的大小。要查看 change 方法的實際應用，讓我們將 name 欄位的大小從 25 增加到 50。為此，我們只需定義欄位的新狀態，然後呼叫 change 方法：

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

修改欄位時，您必須明確包含所有希望在欄位定義中保留的修飾符 - 任何缺失的屬性都將被刪除。例如，要保留 unsigned、default 和 comment 屬性，在更改欄位時必須明確呼叫每個修飾符：

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

change 方法不會更改欄位的索引。因此，您可以使用索引修飾符在修改欄位時明確新增或刪除索引：

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

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

重新命名欄位

要重新命名欄位，您可以使用綱要建構器提供的 renameColumn 方法：

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

刪除欄位

要刪除欄位，您可以在綱要建構器上使用 dropColumn 方法：

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

您可以透過向 dropColumn 方法傳遞欄位名稱陣列來從資料表中刪除多個欄位：

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

可用的命令別名

Laravel 提供了幾個與刪除常見欄位類型相關的便捷方法。下表描述了每個方法：

索引

建立索引

Laravel 綱要建構器支援多種類型的索引。以下範例建立一個新的 email 欄位，並指定其值應是唯一的。要建立索引，我們可以將 unique 方法鏈接到欄位定義上：

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

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

或者，您可以在定義欄位之後建立索引。為此，您應該在綱要建構器藍圖上呼叫 unique 方法。此方法接受應接收唯一索引的欄位名稱：

$table->unique('email');

您甚至可以向索引方法傳遞一個欄位陣列來建立複合索引：

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

建立索引時，Laravel 將根據資料表名稱、欄位名稱和索引類型自動產生索引名稱，但您可以將第二個參數傳遞給方法來自行指定索引名稱：

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

可用的索引類型

Laravel 的綱要建構器藍圖類別提供了用於建立 Laravel 支援的每種索引類型的方法。每個索引方法接受一個可選的第二個參數來指定索引的名稱。如果省略，名稱將從用於索引的資料表名稱和欄位名稱以及索引類型中推導出來。下表描述了每個可用的索引方法：

線上索引建立

預設情況下，在大型資料表上建立索引可能會鎖定資料表，並在建立索引期間阻止讀取或寫入。使用 PostgreSQL 或 SQL Server 時，您可以將 online 方法鏈接到索引定義上，以在不鎖定資料表的情況下建立索引，允許您的應用程式在索引建立期間繼續讀取和寫入資料：

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

使用 PostgreSQL 時，這會將 CONCURRENTLY 選項新增到索引建立語句中。使用 SQL Server 時，這會新增 WITH (online = on) 選項。

重新命名索引

要重新命名索引，您可以使用綱要建構器藍圖提供的 renameIndex 方法。此方法接受當前索引名稱作為第一個參數，接受所需名稱作為第二個參數：

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

刪除索引

要刪除索引，您必須指定索引的名稱。預設情況下，Laravel 會根據資料表名稱、索引欄位名稱和索引類型自動分配索引名稱。以下是一些範例：

如果您將一個欄位陣列傳遞給刪除索引的方法，則將根據資料表名稱、欄位和索引類型產生慣例的索引名稱：

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

外部鍵約束

Laravel 還提供了對建立外部鍵約束的支援，這些約束用於在資料庫層級強制參照完整性。例如，讓我們在 posts 資料表上定義一個 user_id 欄位，該欄位引用 users 資料表上的 id 欄位：

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 方法建立欄位時，上面的範例可以改寫如下：

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

foreignId 方法建立一個 UNSIGNED BIGINT 等效欄位，而 constrained 方法將使用慣例來確定被引用的資料表和欄位。如果您的資料表名稱與 Laravel 的慣例不匹配，您可以手動將其提供給 constrained 方法。此外，也可以指定應分配給所產生索引的名稱：

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

您還可以指定約束的「on delete」和「on update」屬性的所需操作：

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

此外還提供了這些操作的替代性表達語法：

任何額外的欄位修飾符必須在 constrained 方法之前呼叫：

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

刪除外部鍵

要刪除外部鍵，您可以使用 dropForeign 方法，傳遞要刪除的外部鍵約束名稱作為參數。外部鍵約束使用與索引相同的命名慣例。換句話說，外部鍵約束名稱基於資料表名稱和約束中的欄位名稱，後跟 "_foreign" 後綴：

$table->dropForeign('posts_user_id_foreign');

或者，您可以將包含持有外部鍵的欄位名稱的陣列傳遞給 dropForeign 方法。該陣列將使用 Laravel 的約束命名慣例轉換為外部鍵約束名稱：

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

切換外部鍵約束

您可以在遷移中使用以下方法啟用或停用外部鍵約束：

Schema::enableForeignKeyConstraints();

Schema::disableForeignKeyConstraints();

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

[!WARNING] SQLite 預設情況下會停用外部鍵約束。使用 SQLite 時，請確保在嘗試在遷移中建立外部鍵之前，先在資料庫配置中啟用外部鍵支援。

事件

為方便起見，每個遷移操作都會分發一個事件。以下所有事件都擴展了基礎的 Illuminate\Database\Events\MigrationEvent 類別：