Skip to main content
When you need to coordinate updates without blocking foreign key checks, use lockForNoKeyUpdate. This method was added to Laravel 13.x’s query builder and generates FOR NO KEY UPDATE for PostgreSQL.
This page is based on the Laravel Framework 13.x implementation. Confirm that the 13.x feature is included in the release you are running.

How it differs from lockForUpdate

Laravel’s official documentation describes pessimistic locking with sharedLock and lockForUpdate. lockForNoKeyUpdate adds another lock mode that can be selected through the query builder’s common API. FOR NO KEY UPDATE does not mean that every operation can proceed without blocking. Use it only when the weaker update lock is appropriate, and verify the transaction boundaries and locking behavior of the database you actually use.

Use it inside a transaction

Put pessimistic lock acquisition and the update in the same transaction. In the following example, the user row is locked while the balance update is prepared and written.
As the official documentation recommends for lockForUpdate, wrapping the operation in a transaction keeps the retrieved data protected until the operation completes. DB::transaction commits when its callback returns normally and rolls back when the callback throws. lockForNoKeyUpdate only adds a lock clause to the select query. It does not perform an update automatically or disable foreign key constraints.

Generated SQL by database

The query builder asks the connection’s grammar for the lock value. In the Laravel Framework 13.x implementation, only the PostgreSQL grammar returns for no key update. For example, a PostgreSQL connection produces SQL like this. Bindings work as they do with any other query builder query.
Calling lockForNoKeyUpdate on a non-PostgreSQL connection does not itself fail. However, it does not have the same meaning as PostgreSQL’s FOR NO KEY UPDATE: MySQL and SQL Server compile it to their regular update-lock equivalent, while SQLite emits no lock clause.

How the framework resolves the lock

The method delegates lock selection to the connection grammar instead of branching on database drivers in the query builder.
  1. Builder::lockForNoKeyUpdate() calls grammar->getNoKeyUpdateLock().
  2. The base Grammar returns true, which represents the regular update-lock fallback.
  3. PostgresGrammar returns the string for no key update.
  4. compileLock keeps string values as-is; each grammar decides how to compile the boolean fallback.
This lets application code avoid embedding database-specific SQL. It also means that the lock’s meaning varies by database, so code that supports multiple drivers must not assume PostgreSQL-specific behavior.

Migrating from existing pessimistic locks

When replacing an existing lockForUpdate call, do not change only the method name. Verify all of the following:
  • The operation really needs a lock that does not block foreign key checks.
  • The production connection uses PostgreSQL.
  • Falling back to a regular update lock is acceptable on MySQL or SQL Server.
  • Lock acquisition, the update, and the commit happen in one transaction.
  • The order in which existing multi-row locks are acquired remains consistent.
If a package uses this API, either require a Laravel version that includes the method or design an explicit fallback for older versions. A method_exists check alone can hide a semantic change: a user may expect PostgreSQL behavior while another driver executes a regular FOR UPDATE lock.

Primary sources

Last modified on November 21, 2026