RETURNING fa restituire righe a un'istruzione che modifica i dati, come una SELECT. Aggiungila in fondo a un INSERT, UPDATE, DELETE o (da PostgreSQL 17) MERGE, seguita dalle colonne o espressioni che ti servono: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.
Tornano indietro entrambe le nuove righe, con gli id generati da PostgreSQL e plan riempito dal suo valore predefinito, senza una seconda query.
Ottenere l'id di una riga inserita
RETURNING id è il modo standard per ottenere una chiave generata. Riporta la riga così come è stata salvata, quindi funziona con le colonne identity, con serial, con i valori predefiniti UUID e con i valori impostati da un trigger BEFORE. Un VALUES con più righe o un INSERT ... SELECT restituisce una riga per ogni riga inserita.
I driver lo leggono come qualsiasi risultato di una query: cursor.fetchone() in Python con psycopg, result.rows in Node.js con pg. RETURNING * va bene mentre esplori; nel codice dell'applicazione elenca le colonne, così il risultato resta stabile quando la tabella cambia.
Vedere cosa ha cambiato un UPDATE
Su un UPDATE, RETURNING mostra le righe dopo la modifica, e solo quelle che corrispondono al WHERE:
Tornano due righe, Book a 16.5 e Lamp a 33. La Pen non è stata toccata, quindi non compare nel risultato.
In PostgreSQL 17, RETURNING vede solo i valori nuovi. PostgreSQL 18 aggiunge old e new (RETURNING old.price, new.price). Sulla 17, unisci la tabella con una sua copia bloccata:
Ogni riga torna con il prezzo di prima e di dopo: 10 e 15, 20 e 25.
Restituire le righe rimosse da un DELETE
DELETE ... RETURNING ti restituisce le righe che ha rimosso, per i log, per annullare un'operazione o per una coda di job in cui un worker elimina un job e ne riceve i dati. Dentro una query WITH, le righe restituite alimentano l'istruzione successiva, e così sposti righe tra tabelle con una sola istruzione:
I task 1 e 3 escono da tasks e arrivano in done_tasks. È una sola istruzione, quindi nessun'altra sessione li vede in entrambe le tabelle o in nessuna delle due.
Scoprire quale azione ha eseguito MERGE
Da PostgreSQL 17, MERGE accetta RETURNING, e la funzione merge_action() restituisce INSERT, UPDATE o DELETE per ogni riga:
A-100 è stato aggiornato a 7 e C-300 è stato inserito con 4. Per un inserimento o aggiornamento per chiave con scritture concorrenti, preferisci un upsert con ON CONFLICT, che supporta anche RETURNING.
Cosa può contenere RETURNING
Tutto ciò che può contenere la lista di una SELECT: colonne, *, espressioni, chiamate di funzione e alias (RETURNING price * qty AS total), tranne le funzioni di aggregazione. Per contare o sommare le righe restituite, metti l'istruzione in una query WITH e aggrega nella SELECT esterna.
Le righe saltate da ON CONFLICT DO NOTHING, o da un trigger BEFORE che ha restituito NULL, non vengono restituite.
Domande frequenti
Come ottengo in PostgreSQL l'id della riga che ho appena inserito?
Aggiungi RETURNING id all'INSERT. Restituisce il valore generato per ogni riga inserita nello stesso viaggio al server, il che è più sicuro di SELECT max(id) e funziona per le colonne identity, per serial e per valori predefiniti come gen_random_uuid().
RETURNING è più veloce di una SELECT separata?
Di solito sì. Risparmia una seconda istruzione e un secondo viaggio al server, e restituisce esattamente le righe toccate dall'istruzione, senza lasciare a un'altra sessione il tempo di modificarle nel mezzo.
MySQL supporta RETURNING?
MySQL non ha una clausola RETURNING; dopo un insert leggi invece LAST_INSERT_ID(). SQLite supporta RETURNING dalla versione 3.35.