Saltar al contenido principal
Cuando necesites controlar los conflictos de actualización sobre las filas objetivo sin bloquear las comprobaciones de claves foráneas, usa lockForNoKeyUpdate. Este método se añadió al query builder de Laravel 13.x y genera FOR NO KEY UPDATE en PostgreSQL.
Esta página se basa en la implementación de Laravel Framework 13.x. Confirma que la funcionalidad añadida en la rama 13.x está incluida en la versión que utilizas.

Diferencias con lockForUpdate

La documentación oficial de Laravel describe el bloqueo pesimista con sharedLock y lockForUpdate. lockForNoKeyUpdate añade otro modo de bloqueo que puede seleccionarse mediante la API común del query builder. FOR NO KEY UPDATE no significa que todas las operaciones puedan avanzar sin bloquearse. Úsalo solo cuando el bloqueo de actualización más débil sea apropiado, y verifica los límites de la transacción y el comportamiento de bloqueo de la base de datos que usas realmente.

Úsalo dentro de una transacción

Adquiere el bloqueo pesimista y realiza la actualización en la misma transacción. En el siguiente ejemplo, la fila del usuario permanece bloqueada mientras se prepara y escribe la actualización del saldo.
Tal como recomienda la documentación oficial para lockForUpdate, envolver la operación en una transacción mantiene protegidos los datos obtenidos hasta que la operación termina. DB::transaction confirma cuando el callback retorna normalmente y revierte cuando el callback lanza una excepción. lockForNoKeyUpdate solo añade una cláusula de bloqueo a la consulta select. No realiza ninguna actualización automáticamente ni desactiva las restricciones de claves foráneas.

SQL generado por base de datos

El query builder solicita el valor de bloqueo a la gramática de la conexión. En la implementación de Laravel Framework 13.x, solo la gramática de PostgreSQL devuelve for no key update. Por ejemplo, una conexión PostgreSQL produce un SQL como este. Los bindings funcionan igual que en cualquier otra consulta del query builder.
Llamar a lockForNoKeyUpdate en una conexión que no es PostgreSQL no falla por sí mismo. Sin embargo, no tiene el mismo significado que FOR NO KEY UPDATE de PostgreSQL: MySQL y SQL Server lo compilan a su equivalente del bloqueo de actualización normal, mientras que SQLite no emite ninguna cláusula de bloqueo.

Procesamiento interno del framework

El método delega la elección del bloqueo a la gramática de la conexión en lugar de ramificar por controlador de base de datos dentro del query builder.
  1. Builder::lockForNoKeyUpdate() llama a grammar->getNoKeyUpdateLock().
  2. La clase base Grammar devuelve true, que representa la alternativa del bloqueo de actualización normal.
  3. PostgresGrammar devuelve la cadena for no key update.
  4. compileLock mantiene los valores de tipo cadena tal cual; cada gramática decide cómo compilar la alternativa booleana.
Así, el código de la aplicación no necesita incluir SQL específico de cada base de datos. Al mismo tiempo, el significado del bloqueo varía según la base de datos, por lo que el código que admite varios controladores no debe asumir el comportamiento específico de PostgreSQL.

Migrar desde bloqueos pesimistas existentes

Al sustituir una llamada existente a lockForUpdate, no cambies solo el nombre del método. Verifica todo lo siguiente:
  • La operación realmente necesita un bloqueo que no bloquee las comprobaciones de claves foráneas.
  • La conexión de producción usa PostgreSQL.
  • Recurrir a un bloqueo de actualización normal es aceptable en MySQL o SQL Server.
  • La adquisición del bloqueo, la actualización y el commit ocurren en una sola transacción.
  • El orden en que se adquieren los bloqueos existentes sobre varias filas sigue siendo coherente.
Si un paquete usa esta API, exige una versión de Laravel que incluya el método o diseña una alternativa explícita para versiones anteriores. Una simple comprobación con method_exists puede ocultar un cambio de significado: un usuario puede esperar el comportamiento de PostgreSQL mientras otro controlador ejecuta un bloqueo FOR UPDATE normal.

Fuentes primarias consultadas

Última modificación el 21 de noviembre de 2026