> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# lockForNoKeyUpdateで外部キー検査を妨げない行ロック

> Laravel 13.xのQuery Builderに追加されたlockForNoKeyUpdateを、PostgreSQLの行ロックとデータベースごとのフォールバックまでソースコードから解説します。

外部キー検査を妨げずに、対象行の更新競合を制御したい場合は、`lockForNoKeyUpdate` を使います。これはLaravel 13.xのQuery Builderに追加されたメソッドで、PostgreSQLでは `FOR NO KEY UPDATE` を生成します。

> [!NOTE]
>
> このページは [Laravel Framework 13.xの実装](https://github.com/laravel/framework/tree/13.x) を元にしています。`13.x` ブランチに追加された機能が、利用中のリリースに含まれていることを確認してください。

## `lockForUpdate`との違い

Laravelの公式ドキュメントでは、`sharedLock` と `lockForUpdate` を使った悲観的ロックが説明されています。`lockForNoKeyUpdate` は、その中間にある別のロックモードを、Query Builderの共通APIから選択するためのメソッドです。

| Query Builderのメソッド | PostgreSQLで生成されるロック | 用途の目安 |
| - | - | - |
| `sharedLock()` | `FOR SHARE` | 共有ロックで読み取る |
| `lockForNoKeyUpdate()` | `FOR NO KEY UPDATE` | 外部キー検査を妨げない更新ロック |
| `lockForUpdate()` | `FOR UPDATE` | 更新対象を強くロックする |

`FOR NO KEY UPDATE` は、すべての操作を妨げないロックという意味ではありません。通常の `FOR UPDATE` から変更する必要がある処理だけで使い、トランザクションの境界と、実際に利用するデータベースのロック仕様を確認してください。

## トランザクション内で使う

悲観的ロックは、ロックの取得と更新を同じトランザクションに含めます。次の例では、ユーザー行を取得してから残高を更新するまで、対象行の競合を制御します。

```php theme={null}
<?php

use Illuminate\Support\Facades\DB;

DB::transaction(function () use ($userId): void {
    $user = DB::table('users')
        ->where('id', $userId)
        ->lockForNoKeyUpdate()
        ->first();

    if ($user === null) {
        return;
    }

    DB::table('users')
        ->where('id', $user->id)
        ->update([
            'balance' => $user->balance + 100,
        ]);
});
```

`DB::transaction` のcallbackが正常に終わるとcommitされ、例外が投げられるとrollbackされます。公式ドキュメントが `lockForUpdate` について説明している通り、トランザクションで囲むことで、取得したデータが処理の完了まで変更されないようにします。

`lockForNoKeyUpdate` は `select` にロック句を追加するだけです。更新を自動的に実行したり、外部キー制約を無効にしたりするメソッドではありません。

## データベースごとの生成結果

Query Builderは、接続のGrammarにロック値を問い合わせてSQLを組み立てます。Laravel Framework 13.xの実装では、PostgreSQL専用Grammarだけが `for no key update` を返します。

| データベース | 生成されるロック句 | 実装上の扱い |
| - | - | - |
| PostgreSQL | `for no key update` | `FOR NO KEY UPDATE` を使用 |
| MySQL | `for update` | 通常の更新ロックへフォールバック |
| SQL Server | `with(rowlock,updlock,holdlock)` | `lockForUpdate` と同じヒントへフォールバック |
| SQLite | ロック句なし | `SQLiteGrammar` はロック句を出力しない |
| その他・カスタムGrammar | Grammarの実装による | 基底Grammarは通常の更新ロックを表す `true` を返す |

たとえばPostgreSQL接続では、次のようなSQLになります。`?` のbindingは通常のQuery Builderと同じです。

```php theme={null}
$query = DB::connection('pgsql')
    ->table('users')
    ->where('id', $userId)
    ->lockForNoKeyUpdate();

$sql = $query->toSql();
// select * from "users" where "id" = ? for no key update
```

PostgreSQL以外で `lockForNoKeyUpdate` を呼び出しても、メソッド呼び出し自体がエラーになるわけではありません。ただし、PostgreSQLの `FOR NO KEY UPDATE` と同じ意味にはなりません。MySQLやSQL Serverでは通常の更新ロック相当へ変換され、SQLiteではロック句が出力されません。

## Framework内部の処理

このメソッドはデータベースごとにQuery Builderを分岐させるのではなく、Grammarへロック値の解決を委譲します。

1. `Builder::lockForNoKeyUpdate()` が `grammar->getNoKeyUpdateLock()` を呼び出す。
2. 共通の `Grammar` は `true` を返す。これは通常の更新ロックへのフォールバックを表す。
3. `PostgresGrammar` は文字列 `for no key update` を返す。
4. Grammarの `compileLock` が文字列をそのまま扱い、booleanのフォールバックを各Grammarの実装に委譲する。

この設計により、アプリケーションコードは接続ごとのSQL方言を直接扱わずに済みます。一方で、ロックの意味がデータベースによって変わるため、複数のドライバーをサポートする処理では、PostgreSQL固有の動作を前提にしないでください。

## 既存の悲観的ロックから移行する

既存の `lockForUpdate` を置き換える場合は、メソッド名だけを変更せず、次の点を確認します。

* 本当に外部キー検査を妨げないロックが必要か
* 本番環境の接続ドライバーがPostgreSQLか
* MySQLやSQL Serverでは通常の更新ロックへのフォールバックで問題ないか
* ロックの取得から更新・commitまでが同じトランザクションに含まれているか
* 既存の複数行ロックと取得順序が変わらないか

パッケージでこのAPIを使う場合、Laravelのバージョン制約にメソッドが存在するリリースを含めるか、古いバージョン向けの明示的なフォールバックを設計します。`method_exists` だけで切り替えると、利用者がPostgreSQL固有の動作を期待しているのに、別のドライバーで通常の `FOR UPDATE` が実行される可能性があります。

## 参照した一次情報

* [Laravel公式データベースドキュメント: Pessimistic Locking](https://github.com/laravel/docs/blob/13.x/queries.md#pessimistic-locking)
* [`Builder::lockForNoKeyUpdate` の実装](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Builder.php)
* [`Grammar::getNoKeyUpdateLock` の実装](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/Grammar.php)
* [`PostgresGrammar::getNoKeyUpdateLock` の実装](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/PostgresGrammar.php)
* [`SQLiteGrammar::compileLock` の実装](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php)
* [ドライバーごとのSQLを検証する公式テスト](https://github.com/laravel/framework/blob/13.x/tests/Database/DatabaseQueryBuilderTest.php)
* [Laravel Frameworkへの追加コミット](https://github.com/laravel/framework/commit/e60670a48433716006d965ea826daeda42142b59)


## Related topics

- [応用トピック](https://kawax.biz/jp/advanced/index.md)
- [データベースマイグレーション](https://kawax.biz/jp/migrations.md)
- [パッケージの動的リレーション登録](https://kawax.biz/jp/advanced/package-dynamic-relations.md)
- [データベーストランザクションの実行時間を監視する](https://kawax.biz/jp/advanced/transaction-duration-monitoring.md)
- [ヘルパー関数](https://kawax.biz/jp/helpers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.