データベーススキーマ設計の罠：Laravelマイグレーションで起こる「ユニークキーが長すぎる」エラーの正体とは？

2024-05-20

Laravelマイグレーションにおけるユニークキー長エラー：日本語解説

Laravelマイグレーションにおいて、「ユニークキーが長すぎる」というエラーが発生することがあります。このエラーは、MySQLデータベースのデフォルトのインデックス長を超えている場合に発生します。

エラーの原因

このエラーの原因は、MySQLデータベースのデフォルトのインデックス長が制限されていることにあります。MySQL 5.7以前では、インデックスの長さは最大767バイトに制限されています。一方、Laravel 5.4以降では、デフォルトの文字セットであるUTF8mb4を使用しており、これは1バイトで4文字まで表現できます。そのため、長い文字列を含むユニークキーを作成しようとすると、インデックス長の上限を超えてしまう可能性があります。

解決策

このエラーを解決するには、以下のいずれかの方法で対応する必要があります。

MySQLのインデックス長を拡張する

MySQL 5.7以降では、innodb_default_row_format 設定を変更することで、インデックス長を最大1000バイトまで拡張することができます。この設定は、MySQLの構成ファイル (my.cnf など) で変更することができます。

ユニークキーの文字列長を短くすることで、インデックス長の上限内に収めることができます。これは、マイグレーションファイルで string() メソッドの引数として文字列長を指定することで行うことができます。

ハッシュ値を使用する

ユニークキーとしてハッシュ値を使用することで、文字列長を短くすることができます。ハッシュ値は、長い文字列を固定長の値に変換する関数です。

複合ユニークキーを使用する

複数の列を組み合わせてユニークキーを作成することで、個々の列の文字列長を短くすることができます。

Laravel 5.4以降では、Schema::defaultStringLength() メソッドを使用して、デフォルトの文字列長を変更することができます。このメソッドを AppServiceProvider クラスの boot() メソッド内で呼び出すことで、すべてのマイグレーションでデフォルトの文字列長を変更することができます。

例

<?php

namespace App\Providers;

use Illuminate\Database\Schema\Builder;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     *
     * @return void
     */
    public function register()
    {
        // ...
    }

    /**
     * Bootstrap services.
     *
     * @return void
     */
    public function boot()
    {
        Schema::defaultStringLength(191);
    }
}

このコードは、すべてのマイグレーションでデフォルトの文字列長を191バイトに設定します。

Laravelマイグレーションにおける「ユニークキーが長すぎる」というエラーは、MySQLデータベースのデフォルトのインデックス長を超えている場合に発生します。このエラーを解決するには、MySQLのインデックス長を拡張するか、ユニークキーの文字列長を短くする必要があります。また、ハッシュ値や複合ユニークキーを使用する方法もあります。

Laravelマイグレーション：ユニークキーエラー解決例（サンプルコード付）

状況

users テーブルに、email 列を追加しようとしています。この列はユニーク制約を持つ必要がありますが、email アドレスは長い場合があるため、エラーが発生する可能性があります。

エラーメッセージ

SQLSTATE[HY000] [1064] You have an error in your SQL syntax; check the manual for correct usage near 'UNIQUE KEY `users_email_unique` (`email`)' at line 11

原因

このエラーは、email 列のユニークキーが MySQL のデフォルトのインデックス長を超えているために発生しています。

ユニークキーの文字列長を短くする

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

このコードは、email 列の文字列長を191バイトに制限します。

public function up()
{
    Schema::table('users', function (Blueprint $table) {
        $table->string('email_hash', 64)->unique();
    });
}

このコードは、email 列のハッシュ値を64バイトの文字列として保存し、それをユニークキーとして使用します。

public function up()
{
    Schema::table('users', function (Blueprint $table) {
        $table->unique(['email', 'domain']);
    });
}

このコードは、email 列と domain 列を組み合わせてユニークキーを作成します。

Laravelマイグレーションにおける「ユニークキーが長すぎる」というエラーは、いくつかの方法で解決することができます。状況に合わせて適切な方法を選択してください。

補足

上記の例はあくまで一例であり、状況に合わせて変更する必要があります。
マイグレーションを作成する前に、データベースのスキーマを十分に理解しておくことが重要です。
データベースのスキーマを変更する場合は、十分な注意を払って行ってください。

Laravelマイグレーション：ユニークキーエラー解決策その他の方法

Laravel 5.4以降のデフォルト文字列長を変更する

<?php

namespace App\Providers;

use Illuminate\Database\Schema\Builder;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     *
     * @return void
     */
    public function register()
    {
        // ...
    }

    /**
     * Bootstrap services.
     *
     * @return void
     */
    public function boot()
    {
        Schema::defaultStringLength(191);
    }
}