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

# Lock di riga che non bloccano i controlli delle chiavi esterne con lockForNoKeyUpdate

> Scopri dal codice sorgente come funziona lockForNoKeyUpdate di Laravel 13.x, inclusa la modalità di lock di riga di PostgreSQL e il ripiego usato dalle grammatiche degli altri database.

Quando devi controllare i conflitti di aggiornamento sulle righe interessate senza bloccare i controlli delle chiavi esterne, usa `lockForNoKeyUpdate`. Questo metodo è stato aggiunto al query builder di Laravel 13.x e genera `FOR NO KEY UPDATE` su PostgreSQL.

> [!NOTE]
>
> Questa pagina si basa sull'[implementazione di Laravel Framework 13.x](https://github.com/laravel/framework/tree/13.x). Verifica che la funzionalità aggiunta al branch `13.x` sia inclusa nella release che stai usando.

## Differenze rispetto a `lockForUpdate`

La documentazione ufficiale di Laravel descrive il lock pessimistico con `sharedLock` e `lockForUpdate`. `lockForNoKeyUpdate` aggiunge un'altra modalità di lock selezionabile tramite l'API comune del query builder.

| Metodo del query builder | Lock generato da PostgreSQL | Uso tipico |
| - | - | - |
| `sharedLock()` | `FOR SHARE` | Lettura con lock condiviso |
| `lockForNoKeyUpdate()` | `FOR NO KEY UPDATE` | Lock di aggiornamento che non blocca i controlli delle chiavi esterne |
| `lockForUpdate()` | `FOR UPDATE` | Lock più forte per le righe da aggiornare |

`FOR NO KEY UPDATE` non significa che ogni operazione possa procedere senza blocchi. Usalo solo quando il lock di aggiornamento più debole è appropriato e verifica i confini della transazione e il comportamento di lock del database che usi realmente.

## Usarlo all'interno di una transazione

Acquisisci il lock pessimistico ed esegui l'aggiornamento nella stessa transazione. Nell'esempio seguente, la riga dell'utente resta bloccata mentre l'aggiornamento del saldo viene preparato e scritto.

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

Come raccomanda la documentazione ufficiale per `lockForUpdate`, racchiudere l'operazione in una transazione mantiene protetti i dati recuperati fino al completamento dell'operazione. `DB::transaction` esegue il commit quando la callback ritorna normalmente e il rollback quando la callback lancia un'eccezione.

`lockForNoKeyUpdate` aggiunge solo una clausola di lock alla query `select`. Non esegue alcun aggiornamento automaticamente né disattiva i vincoli di chiave esterna.

## SQL generato per database

Il query builder chiede il valore del lock alla grammatica della connessione. Nell'implementazione di Laravel Framework 13.x, solo la grammatica di PostgreSQL restituisce `for no key update`.

| Database | Clausola di lock generata | Comportamento dell'implementazione |
| - | - | - |
| PostgreSQL | `for no key update` | Usa `FOR NO KEY UPDATE` |
| MySQL | `for update` | Ripiega sul normale lock di aggiornamento |
| SQL Server | `with(rowlock,updlock,holdlock)` | Ripiega sugli stessi hint di `lockForUpdate` |
| SQLite | Nessuna clausola di lock | `SQLiteGrammar` non emette alcuna clausola di lock |
| Altre grammatiche o personalizzate | Dipende dalla grammatica | La grammatica di base restituisce `true`, che rappresenta il normale lock di aggiornamento |

Per esempio, una connessione PostgreSQL produce un SQL come questo. I binding funzionano come in qualsiasi altra query 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
```

Chiamare `lockForNoKeyUpdate` su una connessione diversa da PostgreSQL non fallisce di per sé. Tuttavia non ha lo stesso significato di `FOR NO KEY UPDATE` di PostgreSQL: MySQL e SQL Server lo compilano nel loro equivalente del normale lock di aggiornamento, mentre SQLite non emette alcuna clausola di lock.

## Elaborazione interna del framework

Il metodo delega la scelta del lock alla grammatica della connessione invece di diramarsi in base al driver del database nel query builder.

1. `Builder::lockForNoKeyUpdate()` chiama `grammar->getNoKeyUpdateLock()`.
2. La classe base `Grammar` restituisce `true`, che rappresenta il ripiego sul normale lock di aggiornamento.
3. `PostgresGrammar` restituisce la stringa `for no key update`.
4. `compileLock` mantiene invariati i valori stringa; ogni grammatica decide come compilare il ripiego booleano.

In questo modo il codice applicativo non deve incorporare SQL specifico per ogni database. Allo stesso tempo, il significato del lock varia a seconda del database, quindi il codice che supporta più driver non deve presupporre il comportamento specifico di PostgreSQL.

## Migrare dai lock pessimistici esistenti

Quando sostituisci una chiamata esistente a `lockForUpdate`, non cambiare solo il nome del metodo. Verifica tutti i punti seguenti:

* L'operazione ha davvero bisogno di un lock che non blocchi i controlli delle chiavi esterne.
* La connessione di produzione usa PostgreSQL.
* Ripiegare su un normale lock di aggiornamento è accettabile su MySQL o SQL Server.
* L'acquisizione del lock, l'aggiornamento e il commit avvengono in un'unica transazione.
* L'ordine in cui vengono acquisiti i lock esistenti su più righe resta coerente.

Se un package usa questa API, richiedi una versione di Laravel che includa il metodo oppure progetta un ripiego esplicito per le versioni precedenti. Un semplice controllo con `method_exists` può nascondere un cambiamento di significato: un utente potrebbe aspettarsi il comportamento di PostgreSQL mentre un altro driver esegue un normale lock `FOR UPDATE`.

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel sul database: Pessimistic Locking](https://github.com/laravel/docs/blob/13.x/queries.md#pessimistic-locking)
* [Implementazione di `Builder::lockForNoKeyUpdate`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Builder.php)
* [Implementazione di `Grammar::getNoKeyUpdateLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/Grammar.php)
* [Implementazione di `PostgresGrammar::getNoKeyUpdateLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/PostgresGrammar.php)
* [Implementazione di `SQLiteGrammar::compileLock`](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php)
* [Test ufficiali dell'SQL generato da ciascun driver](https://github.com/laravel/framework/blob/13.x/tests/Database/DatabaseQueryBuilderTest.php)
* [Commit che ha aggiunto la funzionalità a Laravel Framework](https://github.com/laravel/framework/commit/e60670a48433716006d965ea826daeda42142b59)


## Related topics

- [Argomenti avanzati](https://kawax.biz/it/advanced/index.md)
- [Driver di sessione personalizzati nei pacchetti](https://kawax.biz/it/advanced/package-session-drivers.md)
- [Attributi contestuali e risoluzione delle dipendenze nei pacchetti](https://kawax.biz/it/advanced/package-contextual-attributes.md)
- [Migration del database](https://kawax.biz/it/migrations.md)
- [Aggiornamenti Laravel di settembre 2026](https://kawax.biz/it/blog/changelog/202609.md)


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