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

# Bloqueos de fila que no impiden las comprobaciones de claves foráneas con lockForNoKeyUpdate

> Aprende a partir del código fuente cómo funciona lockForNoKeyUpdate de Laravel 13.x, incluido el modo de bloqueo de fila de PostgreSQL y la alternativa que usan las gramáticas de otras bases de datos.

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.

> [!NOTE]
>
> Esta página se basa en la [implementación de Laravel Framework 13.x](https://github.com/laravel/framework/tree/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.

| Método del query builder | Bloqueo generado por PostgreSQL | Uso típico |
| - | - | - |
| `sharedLock()` | `FOR SHARE` | Leer con un bloqueo compartido |
| `lockForNoKeyUpdate()` | `FOR NO KEY UPDATE` | Bloqueo de actualización que no bloquea las comprobaciones de claves foráneas |
| `lockForUpdate()` | `FOR UPDATE` | Bloqueo más fuerte para las filas que se van a actualizar |

`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.

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

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`.

| Base de datos | Cláusula de bloqueo generada | Comportamiento de la implementación |
| - | - | - |
| PostgreSQL | `for no key update` | Usa `FOR NO KEY UPDATE` |
| MySQL | `for update` | Recurre al bloqueo de actualización normal |
| SQL Server | `with(rowlock,updlock,holdlock)` | Recurre a las mismas pistas que `lockForUpdate` |
| SQLite | Sin cláusula de bloqueo | `SQLiteGrammar` no emite ninguna cláusula de bloqueo |
| Otras gramáticas o personalizadas | Depende de la gramática | La gramática base devuelve `true`, que representa el bloqueo de actualización normal |

Por ejemplo, una conexión PostgreSQL produce un SQL como este. Los bindings funcionan igual que en cualquier otra consulta del 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
```

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

* [Documentación oficial de bases de datos de Laravel: Pessimistic Locking](https://github.com/laravel/docs/blob/13.x/queries.md#pessimistic-locking)
* [Implementación de `Builder::lockForNoKeyUpdate`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Builder.php)
* [Implementación de `Grammar::getNoKeyUpdateLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/Grammar.php)
* [Implementación de `PostgresGrammar::getNoKeyUpdateLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/PostgresGrammar.php)
* [Implementación de `SQLiteGrammar::compileLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php)
* [Pruebas oficiales del SQL generado por cada controlador](https://github.com/laravel/framework/blob/13.x/tests/Database/DatabaseQueryBuilderTest.php)
* [Commit que añadió la funcionalidad a Laravel Framework](https://github.com/laravel/framework/commit/e60670a48433716006d965ea826daeda42142b59)


## Related topics

- [Migraciones de base de datos](https://kawax.biz/es/migrations.md)
- [Fusión y caché de la configuración de paquetes](https://kawax.biz/es/advanced/package-config-merging.md)
- [Temas avanzados](https://kawax.biz/es/advanced/index.md)
- [Atributos contextuales y resolución de dependencias en paquetes](https://kawax.biz/es/advanced/package-contextual-attributes.md)
- [Drivers de sesión personalizados en paquetes](https://kawax.biz/es/advanced/package-session-drivers.md)


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