> ## 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-TW/advanced/index.md)
- [进阶主题](https://kawax.biz/zh-CN/advanced/index.md)
- [Queue Job 的執行控制](https://kawax.biz/zh-TW/advanced/queue-job-control.md)
- [輔助函式](https://kawax.biz/zh-TW/helpers.md)
- [Laravel AI SDK](https://kawax.biz/zh-TW/ai-sdk.md)


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