> ## 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`은 문자열 값을 그대로 사용하며, boolean 대체를 어떻게 컴파일할지는 각 grammar가 결정합니다.

덕분에 애플리케이션 코드에 데이터베이스별 SQL을 넣지 않아도 됩니다. 동시에 잠금의 의미가 데이터베이스마다 달라지므로, 여러 드라이버를 지원하는 코드는 PostgreSQL 고유의 동작을 전제로 해서는 안 됩니다.

## 기존 비관적 잠금에서 마이그레이션하기

기존 `lockForUpdate` 호출을 대체할 때는 메서드 이름만 바꾸지 마세요. 다음을 모두 확인하세요.

* 해당 작업에 정말로 외래 키 검사를 막지 않는 잠금이 필요한가.
* 프로덕션 연결이 PostgreSQL을 사용하는가.
* MySQL이나 SQL Server에서 일반 업데이트 잠금으로 대체되어도 괜찮은가.
* 잠금 획득, 업데이트, 커밋이 하나의 트랜잭션 안에서 이루어지는가.
* 여러 행에 대한 기존 잠금의 획득 순서가 일관되게 유지되는가.

패키지에서 이 API를 사용한다면 메서드가 포함된 Laravel 버전을 요구하거나, 이전 버전을 위한 명시적인 대체 처리를 설계하세요. `method_exists` 확인만으로는 의미의 변화가 가려질 수 있습니다. 사용자는 PostgreSQL의 동작을 기대하는데, 다른 드라이버에서는 일반 `FOR UPDATE` 잠금이 실행될 수 있습니다.

## 참고한 1차 자료

* [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/ko/advanced/index.md)
- [進階主題](https://kawax.biz/zh-TW/advanced/index.md)
- [데이터베이스 마이그레이션](https://kawax.biz/ko/migrations.md)
- [패키지의 동적 관계 등록](https://kawax.biz/ko/advanced/package-dynamic-relations.md)
- [进阶主题](https://kawax.biz/zh-CN/advanced/index.md)


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