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.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 returnsfor no key update.
For example, a PostgreSQL connection produces SQL like this. Bindings work as they do with any other query builder query.
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.Builder::lockForNoKeyUpdate()callsgrammar->getNoKeyUpdateLock().- The base
Grammarreturnstrue, which represents the regular update-lock fallback. PostgresGrammarreturns the stringfor no key update.compileLockkeeps string values as-is; each grammar decides how to compile the boolean fallback.
Migrating from existing pessimistic locks
When replacing an existinglockForUpdate 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.
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
- Laravel official database documentation: Pessimistic Locking
Builder::lockForNoKeyUpdateimplementationGrammar::getNoKeyUpdateLockimplementationPostgresGrammar::getNoKeyUpdateLockimplementationSQLiteGrammar::compileLockimplementation- Official tests for the SQL generated by each driver
- Commit adding the feature to Laravel Framework