Vai al contenuto principale
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.
Questa pagina si basa sull’implementazione di Laravel Framework 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. 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.
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. Per esempio, una connessione PostgreSQL produce un SQL come questo. I binding funzionano come in qualsiasi altra query del query builder.
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

Ultima modifica il 21 novembre 2026