doctrine/dbalが必要になるLaravelマイグレーションの落とし穴

概要

Laravel のマイグレーションで既存カラムの型やオプションを変更しようとしたとき、doctrine/dbal を要求するエラーに遭遇することがあります。さらに厄介なのは、「指示通り doctrine/dbal を入れたら、今度は別のエラー(Unknown database type enum requested)で落ちる」という二段構えのハマりどころです。

この記事では、なぜ doctrine/dbal が必要になるのか、そこで起きる典型的なトラブル、そしてバージョンごとの正しい対処方法を整理します。

環境

  • PHP 8.x
  • Laravel 9.x / 10.x / 11.x(挙動差を明記して解説します)
  • MySQL 8.x(enum カラムを含むテーブルで問題が起きやすい)

発生した問題

既存テーブルのカラムを変更するマイグレーションを書いて php artisan migrate を実行すると、次のエラーで停止します。

Changing columns for table "users" requires Doctrine DBAL.
Please install the "doctrine/dbal" package.

対象のマイグレーションは、ごく普通の型変更です。

public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->string('nickname', 100)->change();
    });
}

言われるがままに composer require doctrine/dbal を実行すると、今度は変更対象とは無関係なカラムが原因で別のエラーが出ることがあります。

Unknown database type enum requested, Doctrine\DBAL\Platforms\MySQL80Platform may not support it.

カラム変更自体は nickname に対してなのに、なぜか同テーブルの status enum(...) が原因で落ちる、という不可解な状態です。

原因

なぜ doctrine/dbal が必要なのか

Laravel のスキーマビルダは、create や単純な addColumn のような操作は自前で SQL を生成できます。しかし既存カラムの変更(change())やリネーム(renameColumn())は、「現在のカラム定義を読み取って差分を適用する」処理が必要です。

Laravel 10 以前は、この「既存定義の読み取り」を doctrine/dbal というスキーマ抽象化ライブラリに委譲していました。そのため、change() を含むマイグレーションには doctrine/dbal が必須だったのです。

操作 Laravel 9 以前 Laravel 10 Laravel 11 以降
renameColumn() dbal 必須 不要 不要
dropColumn()(SQLite) dbal 必須 不要 不要
change()(型・属性変更) dbal 必須 dbal 必須 不要

Laravel 11 で change() もネイティブ実装に置き換えられ、doctrine/dbal 依存が解消されました。つまり冒頭のエラーは Laravel 10 以前(特に change() 利用時) に出るものです。

なぜ enum で二次被害が起きるのか

doctrine/dbal は、カラムを変更する際に テーブル全体のカラム定義を一度オブジェクトとして読み取ります。このとき MySQL の enum 型は DBAL が標準でサポートしておらず、Unknown database type enum requested として例外を投げます。

ここがハマりどころの本質です。変更したいカラムが enum でなくても、同じテーブルのどこかに enum カラムがあるだけで全体の読み取りに失敗するのです。

対応方法

対処1: Laravel 11 以降なら doctrine/dbal は不要

まず前提確認として、Laravel 11 以降であれば change() に doctrine/dbal は要りません。古いプロジェクトの慣習でなんとなく入れているだけなら、アップグレード後に外せます。ただし Laravel 11 のネイティブ change() にも重要な注意点があります(後述)。

対処2: Laravel 10 以前で enum エラーを回避する

doctrine/dbal を使わざるを得ないバージョンで enum エラーが出る場合は、enum を string として扱うよう型マッピングを登録します。

use Illuminate\Support\Facades\DB;

public function up(): void
{
    DB::getDoctrineConnection()
        ->getDatabasePlatform()
        ->registerDoctrineTypeMapping('enum', 'string');

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

これで DBAL がテーブル定義を読む際、enum カラムを string とみなすため読み取りが通ります。変更対象の enum カラム自体をいじらない限り、この回避で十分です。

対処3: change() を避け、生SQLで変更する

そもそも change() に頼らず、生の ALTER TABLE を発行する手もあります。DBAL の挙動差に振り回されないため、複雑なテーブルではこちらが確実なことも多いです。

public function up(): void
{
    DB::statement('ALTER TABLE users MODIFY nickname VARCHAR(100) NOT NULL');
}

public function down(): void
{
    DB::statement('ALTER TABLE users MODIFY nickname VARCHAR(50) NOT NULL');
}

生SQLはDBエンジン依存になるトレードオフがありますが、「属性が勝手に落ちる」事故を避けられます。

実装例

Laravel 10 以前で、enum を含むテーブルの別カラムを安全に変更する実際の形です。

<?php

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

return new class extends Migration {
    public function up(): void
    {
        // enum を string 扱いにしてDBALの読み取り失敗を回避
        DB::getDoctrineConnection()
            ->getDatabasePlatform()
            ->registerDoctrineTypeMapping('enum', 'string');

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

    public function down(): void
    {
        DB::getDoctrineConnection()
            ->getDatabasePlatform()
            ->registerDoctrineTypeMapping('enum', 'string');

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

確認方法

  1. ステージング相当のDBに対し php artisan migrate --pretend で発行SQLを確認する
  2. 実行後に SHOW CREATE TABLE users; で、意図しない属性の欠落(unsigned・comment・default など)がないかを確認する
  3. ロールバックも php artisan migrate:rollback で検証し、down() が対称になっているか確かめる

注意点

  • change() は「書いた属性以外を落とす」。これは DBAL 時代も Laravel 11 ネイティブ版も同じ思想で、change() に渡した定義が新しい状態として適用されます。nullable() や unsigned、default、comment を省くと既存の属性が消える可能性があるため、変更時は維持したい属性も明示するのが鉄則です。
  • enum の型マッピング回避は「読み取りを通すための応急処置」です。enum カラム自体を change() で変更したい場合は、生SQL(ALTER TABLE ... MODIFY)に切り替えるほうが安全です。
  • Laravel 11 へ上げるなら doctrine/dbal は依存から外せますが、他のライブラリが間接依存していないか composer why doctrine/dbal で確認してから削除します。
  • 本番適用前に、必ずステージングで同一スキーマに対して流し、SHOW CREATE TABLE 前後比較を行うこと。属性欠落は一見成功したように見えて後から効いてくる事故になりがちです。

まとめ

  • change() / renameColumn() は過去バージョンで doctrine/dbal を要求した。Laravel 10 で rename、Laravel 11 で change のネイティブ化が進み、依存は解消された。
  • doctrine/dbal 導入後に出る Unknown database type enum requested は、変更対象と無関係な enum カラムが原因。registerDoctrineTypeMapping('enum', 'string') で回避できる。
  • change() は指定しなかった属性を落とす。維持したい属性は必ず明示し、--pretend と SHOW CREATE TABLE で前後確認する。
  • 複雑なテーブルや enum の変更は、change() に固執せず生SQLに切り替えるのも有効な選択肢。

\ 最新情報をチェック /

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。