laravel-database-optimization

Laravel データベース最適化

Laravel 13 アプリケーション向けの包括的なデータベース最適化ガイドです。Laravel 13 でパフォーマンスの高いデータベースクエリを作成するための、適切なインデックス設定、効率的なキャッシュ、命名規則、遅いクエリのデバッグに関する9カテゴリ、33のルールを掲載しています。

メタデータ

• バージョン： 1.1.0
• フレームワーク： Laravel 13.x
• PHP： 8.3+

適用するタイミング

次の作業を行う際に、これらのガイドラインを参照してください。

• Eloquent クエリを記述する、またはクエリビルダーを使用する
• N+1 クエリの問題を診断して修正する
• マイグレーションにデータベースインデックスを追加する
• Redis またはキャッシュベースの最適化を実装する
• 大規模なデータセットをページネーションまたは処理する
• データベーストランザクションで処理を囲む
• 本番データベースのマイグレーションを作成または変更する
• EXPLAIN または Laravel Debugbar で遅いクエリをデバッグする

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	クエリパフォーマンスとN+1	CRITICAL	query-
2	インデックス戦略	CRITICAL	index-
3	Eloquent の最適化	HIGH	eloquent-
4	Redis によるキャッシュ	HIGH	cache-
5	ページネーションと大規模データセット	HIGH	data-
6	トランザクションとロック	HIGH	lock-
7	マイグレーション	HIGH	migrate-
8	クエリのデバッグ	MEDIUM	debug-
9	命名と構造	HIGH	naming-

クイックリファレンス

1. クエリパフォーマンスとN+1（CRITICAL）

• query-eager-loading - イーガーローディングを使ってN+1クエリを解消する
• query-prevent-lazy-loading - 開発環境でレイジーローディングを防止する
• query-auto-eager-loading - モデルで自動イーガーローディングを設定する
• query-select-columns - SELECT * の代わりに必要なカラムだけを選択する

2. インデックス戦略（CRITICAL）

• index-foreign-keys - すべての外部キー列にインデックスを設定する
• index-composite-indexes - 複数列を使うクエリには複合インデックスを作成する
• index-covering-indexes - 読み取りが多いクエリにはカバリングインデックスを使う
• index-full-text - 検索機能には全文検索インデックスを使う

3. Eloquent の最適化（HIGH）

• eloquent-query-builder-hot-paths - パフォーマンスが重要な処理ではクエリビルダーを使う
• eloquent-with-count-aggregates - リレーションを読み込んで件数を数える代わりに withCount を使う
• eloquent-subquery-selects - サブクエリによる選択で余分なクエリを回避する
• eloquent-where-has-optimization - whereIn サブクエリで whereHas を最適化する

4. Redis によるキャッシュ（HIGH）

• cache-remember - 負荷の高いクエリには Cache::remember を使う
• cache-invalidation - モデルの変更時にキャッシュを無効化する
• cache-tags - グループ単位でキャッシュを無効化するにはキャッシュタグを使う
• cache-ttl - キャッシュデータに適切なTTL値を設定する

5. ページネーションと大規模データセット（HIGH）

• data-cursor-pagination - 大規模なデータセットにはカーソルページネーションを使う
• data-chunk-by-id - chunkById で大規模なデータセットを処理する
• data-cursor-iteration - メモリ効率の高い反復処理には遅延カーソルを使う
• data-avoid-unbounded - 大規模なテーブルに対して無制限のクエリを使わない

6. トランザクションとロック（HIGH）

• lock-short-transactions - トランザクションは短く、目的を絞ったものにする
• lock-deadlock-retry - デッドロック時の再試行ロジックを実装する
• lock-pessimistic-locking - 重要な更新には悲観的ロックを使う

7. マイグレーション（HIGH）

• migrate-zero-downtime - ダウンタイムが発生しないマイグレーションを作成する
• migrate-concurrent-indexes - 本番環境ではインデックスを並行作成する
• migrate-safe-column-additions - テーブルをロックせずに安全にカラムを追加する

8. クエリのデバッグ（MEDIUM）

• debug-explain-analyze - EXPLAIN ANALYZE を使ってクエリプランを把握する
• debug-laravel-debugbar - Laravel Debugbar を使ってクエリのボトルネックを特定する
• debug-slow-query-log - スロークエリログを有効にして監視する

9. 命名と構成（重要）

• naming-tables - テーブルの命名規則（複数形の snake_case、ピボットテーブルはアルファベット順）
• naming-columns - カラムの命名規則（外部キー、ブール値、タイムスタンプ、多態性）
• naming-relationships - リレーションシップメソッドの命名（単数形／複数形の一致）
• naming-migrations - マイグレーションとインデックスの命名規則

基本的なパターン

開発環境での遅延読み込みを防ぐ

<?php

namespace App\Providers;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Model::preventLazyLoading(!app()->isProduction());
    }
}

コストの高いクエリを Redis でキャッシュする

<?php

use Illuminate\Support\Facades\Cache;

// Cache a query result for 1 hour (3600 seconds)
$popularPosts = Cache::remember('posts:popular', 3600, fn () =>
    Post::query()
        ->withCount('comments')
        ->orderByDesc('comments_count')
        ->take(10)
        ->get()
);

大規模なデータセットにはカーソルページネーションを使う

<?php

// Cursor pagination — efficient for infinite scroll and large tables
$posts = Post::query()
    ->where('published_at', '<=', now())
    ->orderByDesc('published_at')
    ->cursorPaginate(15);

リレーションを読み込まずに集計数を取得する

<?php

// Instead of loading all posts just to count them
$users = User::withCount('posts')->get();

foreach ($users as $user) {
    echo "{$user->name} has {$user->posts_count} posts";
}

chunkById で大規模なデータセットを処理する

<?php

// Memory-efficient processing of large tables
User::query()
    ->where('last_login_at', '<', now()->subYear())
    ->chunkById(1000, function ($users) {
        foreach ($users as $user) {
            $user->update(['status' => 'inactive']);
        }
    });

データベーストランザクションを短く保つ

<?php

use Illuminate\Support\Facades\DB;

// Keep transactions short and focused
DB::transaction(function () {
    $order = Order::create([
        'user_id' => auth()->id(),
        'total' => $this->calculateTotal(),
    ]);

    $order->items()->createMany($this->cartItems());

    $order->user->decrement('credits', $order->total);
});

使用方法

詳細な説明とコード例については、個々のルールファイルを参照してください。

rules/query-eager-loading.md
rules/index-composite-indexes.md
rules/cache-remember.md
rules/_sections.md

各ルールファイルには以下が含まれます。

• メタデータ（タイトル、影響度、タグ）を含む YAML フロントマター
• 重要な理由の簡単な説明
• 説明付きの悪い例
• 説明付きの良い例
• Laravel 13 と PHP 8.3 に固有のコンテキストと参考情報

参考資料

• Laravel Eloquent
• Laravel Queries
• Laravel Cache
• Laravel Pagination
• Laravel Migrations
• Laravel Redis

コンパイル済みの完全版ドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md を参照してください。