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

# Row locks without blocking foreign key checks with lockForNoKeyUpdate

> Learn how Laravel 13.x's lockForNoKeyUpdate works, including PostgreSQL's row-lock mode and the fallback used by other database grammars.

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.

> [!NOTE]
>
> This page is based on the [Laravel Framework 13.x implementation](https://github.com/laravel/framework/tree/13.x). 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.

| Query builder method | Lock generated by PostgreSQL | Typical use |
| - | - | - |
| `sharedLock()` | `FOR SHARE` | Read with a shared lock |
| `lockForNoKeyUpdate()` | `FOR NO KEY UPDATE` | Update locking without blocking foreign key checks |
| `lockForUpdate()` | `FOR UPDATE` | Stronger locking for rows being updated |

`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.

```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,
        ]);
});
```

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`.

| Database | Generated lock clause | Implementation behavior |
| - | - | - |
| PostgreSQL | `for no key update` | Uses `FOR NO KEY UPDATE` |
| MySQL | `for update` | Falls back to the regular update lock |
| SQL Server | `with(rowlock,updlock,holdlock)` | Falls back to the same hints as `lockForUpdate` |
| SQLite | No lock clause | `SQLiteGrammar` emits no lock clause |
| Other or custom grammars | Depends on the grammar | The base grammar returns `true`, representing the regular update lock |

For example, a PostgreSQL connection produces SQL like this. Bindings work as they do with any other query builder query.

```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
```

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

* [Laravel official database documentation: Pessimistic Locking](https://github.com/laravel/docs/blob/13.x/queries.md#pessimistic-locking)
* [`Builder::lockForNoKeyUpdate` implementation](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Builder.php)
* [`Grammar::getNoKeyUpdateLock` implementation](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/Grammar.php)
* [`PostgresGrammar::getNoKeyUpdateLock` implementation](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/PostgresGrammar.php)
* [`SQLiteGrammar::compileLock` implementation](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php)
* [Official tests for the SQL generated by each driver](https://github.com/laravel/framework/blob/13.x/tests/Database/DatabaseQueryBuilderTest.php)
* [Commit adding the feature to Laravel Framework](https://github.com/laravel/framework/commit/e60670a48433716006d965ea826daeda42142b59)


## Related topics

- [Advanced Topics](https://kawax.biz/en/advanced/index.md)
- [Database migrations](https://kawax.biz/en/migrations.md)
- [Package translation overrides and updates](https://kawax.biz/en/advanced/package-translations.md)
- [Package morph maps and stored data compatibility](https://kawax.biz/en/advanced/package-morph-maps.md)
- [October 2026 Laravel updates](https://kawax.biz/en/blog/changelog/202610.md)


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