Passer au contenu principal
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.
Cette page s’appuie sur l’implémentation de Laravel Framework 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. 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.
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. Par exemple, une connexion PostgreSQL produit un SQL comme celui-ci. Les bindings fonctionnent comme pour toute autre requête du query builder.
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

Dernière modification le 21 novembre 2026