> ## 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` 并不意味着所有操作都能无阻塞地进行。只有在较弱的更新锁合适时才使用它，并确认你实际使用的数据库的事务边界和锁行为。

## 在事务中使用

在同一个事务中获取悲观锁并执行更新。在下面的示例中，准备并写入余额更新期间，用户行始终处于锁定状态。

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

正如官方文档对 `lockForUpdate` 的建议，将操作包裹在事务中，可以让获取的数据在操作完成之前一直受到保护。`DB::transaction` 在回调正常返回时提交，在回调抛出异常时回滚。

`lockForNoKeyUpdate` 只是给 `select` 查询添加锁子句。它不会自动执行更新，也不会禁用外键约束。

## 各数据库的生成结果

Query Builder 会向连接的 grammar 请求锁的值。在 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。绑定参数的处理与其他 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. `compileLock` 原样使用字符串值；布尔回退如何编译由各个 grammar 决定。

这样，应用代码无需嵌入特定数据库的 SQL。同时，锁的含义会因数据库而异，因此支持多种驱动的代码不能假定 PostgreSQL 特有的行为。

## 从现有悲观锁迁移

替换现有的 `lockForUpdate` 调用时，不要只修改方法名。请确认以下所有事项：

* 该操作确实需要不阻塞外键检查的锁。
* 生产环境的连接使用 PostgreSQL。
* 在 MySQL 或 SQL Server 上回退为普通更新锁是可以接受的。
* 获取锁、更新和提交在同一个事务中完成。
* 对多行获取现有锁的顺序保持一致。

如果包使用了这个 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/zh-CN/advanced/index.md)
- [進階主題](https://kawax.biz/zh-TW/advanced/index.md)
- [包的自定义缓存存储与契约](https://kawax.biz/zh-CN/advanced/package-cache-drivers.md)
- [数据库迁移](https://kawax.biz/zh-CN/migrations.md)
- [实现自定义认证 Guard](https://kawax.biz/zh-CN/advanced/custom-auth-guard.md)


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