RETURNING sprawia, że polecenie zmieniające dane zwraca wiersze, tak jak SELECT. Dodaj je na końcu INSERT, UPDATE, DELETE albo (od PostgreSQL 17) MERGE, a po nim kolumny lub wyrażenia, które chcesz dostać: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.
Oba nowe wiersze wracają z identyfikatorami wygenerowanymi przez PostgreSQL i z plan wypełnionym wartością domyślną, bez drugiego zapytania.
Identyfikator wstawionego wiersza
RETURNING id to standardowy sposób na pobranie wygenerowanego klucza. Pokazuje wiersz tak, jak został zapisany, więc działa z kolumnami identity, serial, domyślnymi UUID i wartościami ustawionymi przez wyzwalacz BEFORE. VALUES z wieloma wierszami albo INSERT ... SELECT zwraca jeden wiersz na każdy wstawiony.
Sterowniki czytają to jak każdy wynik zapytania: cursor.fetchone() w Pythonie z psycopg, result.rows w Node.js z pg. RETURNING * wystarczy podczas eksperymentów; w kodzie aplikacji wypisz kolumny, żeby wynik był stabilny, gdy tabela się zmieni.
Co zmienił UPDATE
Przy UPDATE RETURNING pokazuje wiersze po zmianie i tylko te, które pasowały do WHERE:
Wracają dwa wiersze, Book z 16.5 i Lamp z 33. Pen nie został zmieniony, więc nie ma go w wyniku.
W PostgreSQL 17 RETURNING widzi tylko nowe wartości. PostgreSQL 18 dodaje old i new (RETURNING old.price, new.price). W wersji 17 złącz tabelę z zablokowaną kopią samej siebie:
Każdy wiersz wraca z ceną przed i po zmianie: 10 i 15, 20 i 25.
Wiersze usunięte przez DELETE
DELETE ... RETURNING zwraca usunięte wiersze, do logowania, cofania zmian albo kolejki zadań, w której worker usuwa zadanie i dostaje jego dane. Wewnątrz zapytania WITH zwrócone wiersze zasilają następne polecenie, co pozwala przenieść wiersze między tabelami jednym poleceniem:
Zadania 1 i 3 opuszczają tasks i trafiają do done_tasks. To jedno polecenie, więc żadna inna sesja nie zobaczy ich w obu tabelach ani w żadnej.
Która akcja MERGE się wykonała
Od PostgreSQL 17 MERGE przyjmuje RETURNING, a funkcja merge_action() zwraca dla każdego wiersza INSERT, UPDATE albo DELETE:
A-100 zostało zaktualizowane do 7, a C-300 wstawione z 4. Do wstawienia albo aktualizacji po kluczu przy współbieżnych zapisach lepiej użyć upsert z ON CONFLICT, który też obsługuje RETURNING.
Co może zawierać RETURNING
Wszystko, co lista SELECT: kolumny, *, wyrażenia, wywołania funkcji i aliasy (RETURNING price * qty AS total), z wyjątkiem agregatów. Żeby policzyć albo zsumować zwrócone wiersze, opakuj polecenie w zapytanie WITH i agreguj w zewnętrznym SELECT.
Wiersze pominięte przez ON CONFLICT DO NOTHING albo przez wyzwalacz BEFORE, który zwrócił NULL, nie są zwracane.
Najczęściej zadawane pytania
Jak pobrać id właśnie wstawionego wiersza w PostgreSQL?
Dodaj RETURNING id do INSERT. Zwraca wygenerowaną wartość dla każdego wstawionego wiersza w tym samym zapytaniu do serwera, co jest bezpieczniejsze niż SELECT max(id) i działa z kolumnami identity, serial i wartościami domyślnymi, takimi jak gen_random_uuid().
Czy RETURNING jest szybsze niż osobny SELECT?
Zwykle tak. Oszczędza drugie polecenie i drugą wymianę z serwerem, a zwraca dokładnie te wiersze, których dotknęło polecenie, bez okna, w którym inna sesja mogłaby je w międzyczasie zmienić.
Czy MySQL obsługuje RETURNING?
MySQL nie ma klauzuli RETURNING; zamiast tego po wstawieniu odczytujesz LAST_INSERT_ID(). SQLite obsługuje RETURNING od wersji 3.35.