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

# Verrous de ligne qui ne bloquent pas les vérifications de clés étrangères avec lockForNoKeyUpdate

> Découvrez à partir du code source le fonctionnement de lockForNoKeyUpdate dans Laravel 13.x, y compris le mode de verrouillage de ligne de PostgreSQL et le repli utilisé par les grammaires des autres bases de données.

Lorsque vous devez contrôler les conflits de mise à jour sur les lignes ciblées sans bloquer les vérifications de clés étrangères, utilisez `lockForNoKeyUpdate`. Cette méthode a été ajoutée au query builder de Laravel 13.x et génère `FOR NO KEY UPDATE` avec PostgreSQL.

> [!NOTE]
>
> Cette page s'appuie sur l'[implémentation de Laravel Framework 13.x](https://github.com/laravel/framework/tree/13.x). Vérifiez que la fonctionnalité ajoutée à la branche `13.x` est incluse dans la version que vous utilisez.

## Différences avec `lockForUpdate`

La documentation officielle de Laravel décrit le verrouillage pessimiste avec `sharedLock` et `lockForUpdate`. `lockForNoKeyUpdate` ajoute un autre mode de verrouillage, sélectionnable via l'API commune du query builder.

| Méthode du query builder | Verrou généré par PostgreSQL | Usage typique |
| - | - | - |
| `sharedLock()` | `FOR SHARE` | Lire avec un verrou partagé |
| `lockForNoKeyUpdate()` | `FOR NO KEY UPDATE` | Verrou de mise à jour qui ne bloque pas les vérifications de clés étrangères |
| `lockForUpdate()` | `FOR UPDATE` | Verrou plus fort pour les lignes à mettre à jour |

`FOR NO KEY UPDATE` ne signifie pas que toutes les opérations peuvent se poursuivre sans blocage. Utilisez-le uniquement lorsque le verrou de mise à jour plus faible est approprié, et vérifiez les limites de transaction et le comportement de verrouillage de la base de données que vous utilisez réellement.

## L'utiliser dans une transaction

Acquérez le verrou pessimiste et effectuez la mise à jour dans la même transaction. Dans l'exemple suivant, la ligne de l'utilisateur reste verrouillée pendant la préparation et l'écriture de la mise à jour du solde.

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

Comme le recommande la documentation officielle pour `lockForUpdate`, encapsuler l'opération dans une transaction protège les données récupérées jusqu'à la fin de l'opération. `DB::transaction` valide lorsque le callback se termine normalement et annule lorsque le callback lève une exception.

`lockForNoKeyUpdate` ajoute seulement une clause de verrouillage à la requête `select`. Elle n'effectue aucune mise à jour automatiquement et ne désactive pas les contraintes de clés étrangères.

## SQL généré selon la base de données

Le query builder demande la valeur de verrouillage à la grammaire de la connexion. Dans l'implémentation de Laravel Framework 13.x, seule la grammaire PostgreSQL renvoie `for no key update`.

| Base de données | Clause de verrouillage générée | Comportement de l'implémentation |
| - | - | - |
| PostgreSQL | `for no key update` | Utilise `FOR NO KEY UPDATE` |
| MySQL | `for update` | Se replie sur le verrou de mise à jour classique |
| SQL Server | `with(rowlock,updlock,holdlock)` | Se replie sur les mêmes indications que `lockForUpdate` |
| SQLite | Aucune clause de verrouillage | `SQLiteGrammar` n'émet aucune clause de verrouillage |
| Autres grammaires ou grammaires personnalisées | Dépend de la grammaire | La grammaire de base renvoie `true`, qui représente le verrou de mise à jour classique |

Par exemple, une connexion PostgreSQL produit un SQL comme celui-ci. Les bindings fonctionnent comme pour toute autre requête du 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
```

Appeler `lockForNoKeyUpdate` sur une connexion autre que PostgreSQL n'échoue pas en soi. Cependant, cela n'a pas le même sens que `FOR NO KEY UPDATE` de PostgreSQL : MySQL et SQL Server le compilent en leur équivalent du verrou de mise à jour classique, tandis que SQLite n'émet aucune clause de verrouillage.

## Traitement interne du framework

La méthode délègue le choix du verrou à la grammaire de la connexion au lieu de brancher selon le pilote de base de données dans le query builder.

1. `Builder::lockForNoKeyUpdate()` appelle `grammar->getNoKeyUpdateLock()`.
2. La classe de base `Grammar` renvoie `true`, qui représente le repli sur le verrou de mise à jour classique.
3. `PostgresGrammar` renvoie la chaîne `for no key update`.
4. `compileLock` conserve les valeurs de type chaîne telles quelles ; chaque grammaire décide comment compiler le repli booléen.

Le code applicatif n'a ainsi pas besoin d'embarquer du SQL propre à chaque base de données. En revanche, le sens du verrou varie selon la base de données, donc un code qui prend en charge plusieurs pilotes ne doit pas supposer le comportement propre à PostgreSQL.

## Migrer depuis des verrous pessimistes existants

Lorsque vous remplacez un appel existant à `lockForUpdate`, ne changez pas seulement le nom de la méthode. Vérifiez tous les points suivants :

* L'opération a réellement besoin d'un verrou qui ne bloque pas les vérifications de clés étrangères.
* La connexion de production utilise PostgreSQL.
* Le repli sur un verrou de mise à jour classique est acceptable avec MySQL ou SQL Server.
* L'acquisition du verrou, la mise à jour et le commit se déroulent dans une seule transaction.
* L'ordre d'acquisition des verrous existants sur plusieurs lignes reste cohérent.

Si un package utilise cette API, exigez une version de Laravel qui inclut la méthode ou concevez un repli explicite pour les versions antérieures. Une simple vérification avec `method_exists` peut masquer un changement de sens : un utilisateur peut s'attendre au comportement de PostgreSQL alors qu'un autre pilote exécute un verrou `FOR UPDATE` classique.

## Sources primaires consultées

* [Documentation officielle de Laravel sur les bases de données : Pessimistic Locking](https://github.com/laravel/docs/blob/13.x/queries.md#pessimistic-locking)
* [Implémentation de `Builder::lockForNoKeyUpdate`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Builder.php)
* [Implémentation de `Grammar::getNoKeyUpdateLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/Grammar.php)
* [Implémentation de `PostgresGrammar::getNoKeyUpdateLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/PostgresGrammar.php)
* [Implémentation de `SQLiteGrammar::compileLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php)
* [Tests officiels du SQL généré par chaque pilote](https://github.com/laravel/framework/blob/13.x/tests/Database/DatabaseQueryBuilderTest.php)
* [Commit ayant ajouté la fonctionnalité à Laravel Framework](https://github.com/laravel/framework/commit/e60670a48433716006d965ea826daeda42142b59)


## Related topics

- [Migrations de base de données](https://kawax.biz/fr/migrations.md)
- [Sujets avancés](https://kawax.biz/fr/advanced/index.md)
- [Canaux de notification personnalisés dans un package et vérification de l'envoi](https://kawax.biz/fr/advanced/package-notification-channels.md)
- [Enregistrement de règles de validation sous forme de chaîne pour les packages](https://kawax.biz/fr/advanced/package-validation-extensions.md)
- [Au cœur du driver de broadcasting Mercure](https://kawax.biz/fr/advanced/mercure-broadcasting.md)


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