メインコンテンツへスキップ
外部キー検査を妨げずに、対象行の更新競合を制御したい場合は、lockForNoKeyUpdate を使います。これはLaravel 13.xのQuery Builderに追加されたメソッドで、PostgreSQLでは FOR NO KEY UPDATE を生成します。
このページは Laravel Framework 13.xの実装 を元にしています。13.x ブランチに追加された機能が、利用中のリリースに含まれていることを確認してください。

lockForUpdateとの違い

Laravelの公式ドキュメントでは、sharedLock と lockForUpdate を使った悲観的ロックが説明されています。lockForNoKeyUpdate は、その中間にある別のロックモードを、Query Builderの共通APIから選択するためのメソッドです。 FOR NO KEY UPDATE は、すべての操作を妨げないロックという意味ではありません。通常の FOR UPDATE から変更する必要がある処理だけで使い、トランザクションの境界と、実際に利用するデータベースのロック仕様を確認してください。

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

悲観的ロックは、ロックの取得と更新を同じトランザクションに含めます。次の例では、ユーザー行を取得してから残高を更新するまで、対象行の競合を制御します。
DB::transaction のcallbackが正常に終わるとcommitされ、例外が投げられるとrollbackされます。公式ドキュメントが lockForUpdate について説明している通り、トランザクションで囲むことで、取得したデータが処理の完了まで変更されないようにします。 lockForNoKeyUpdate は select にロック句を追加するだけです。更新を自動的に実行したり、外部キー制約を無効にしたりするメソッドではありません。

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

Query Builderは、接続のGrammarにロック値を問い合わせてSQLを組み立てます。Laravel Framework 13.xの実装では、PostgreSQL専用Grammarだけが for no key update を返します。 たとえばPostgreSQL接続では、次のようなSQLになります。? のbindingは通常のQuery Builderと同じです。
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 が実行される可能性があります。

参照した一次情報

最終更新日 2026年11月21日