Menu

PostgreSQL RETURNING bei INSERT, UPDATE und DELETE

Mit RETURNING geben INSERT, UPDATE, DELETE und MERGE die Zeilen zurück, die sie geändert haben: generierte IDs, neue Werte, gelöschte Zeilen und welche MERGE-Aktion lief.

Diese Seite enthält ausführbare Editoren. Bearbeiten, ausführen und Ausgabe sofort sehen.

Mit RETURNING liefert eine Anweisung, die Daten ändert, Zeilen zurück, wie ein SELECT. Häng es ans Ende eines INSERT, UPDATE, DELETE oder (seit PostgreSQL 17) MERGE, gefolgt von den gewünschten Spalten oder Ausdrücken: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.

Beide neuen Zeilen kommen mit den IDs zurück, die PostgreSQL erzeugt hat, und mit plan aus dem Default, ganz ohne zweite Abfrage.

Die ID einer eingefügten Zeile bekommen

RETURNING id ist der Standardweg, um einen generierten Schlüssel zu bekommen. Es meldet die Zeile so, wie sie gespeichert wurde, und funktioniert deshalb mit Identity-Spalten, serial, UUID-Defaults und Werten, die ein BEFORE Trigger gesetzt hat. Ein VALUES mit mehreren Zeilen oder ein INSERT ... SELECT liefert eine Zeile pro eingefügter Zeile.

Treiber lesen das wie jedes Abfrageergebnis: cursor.fetchone() in Python mit psycopg, result.rows in Node.js mit pg. RETURNING * ist zum Ausprobieren in Ordnung; im Anwendungscode zählst du die Spalten auf, damit das Ergebnis stabil bleibt, wenn sich die Tabelle ändert.

Sehen, was ein UPDATE geändert hat

Bei einem UPDATE zeigt RETURNING die Zeilen nach der Änderung, und nur die Zeilen, die zum WHERE gepasst haben:

Zwei Zeilen kommen zurück, Book mit 16.5 und Lamp mit 33. Pen wurde nicht angefasst und ist deshalb nicht im Ergebnis.

In PostgreSQL 17 sieht RETURNING nur die neuen Werte. PostgreSQL 18 ergänzt old und new (RETURNING old.price, new.price). Unter 17 joinst du die Tabelle mit einer gesperrten Kopie ihrer selbst:

Jede Zeile kommt mit ihrem Preis vorher und nachher zurück: 10 und 15, 20 und 25.

Die Zeilen zurückgeben, die ein DELETE entfernt hat

DELETE ... RETURNING liefert dir die entfernten Zeilen, zum Protokollieren, für ein Undo oder für eine Job-Queue, in der ein Worker einen Job löscht und dabei seine Daten bekommt. Innerhalb einer WITH Abfrage speisen die zurückgegebenen Zeilen die nächste Anweisung. So verschiebst du Zeilen in einer einzigen Anweisung zwischen Tabellen:

Die Tasks 1 und 3 verlassen tasks und landen in done_tasks. Es ist eine einzige Anweisung, keine andere Sitzung sieht sie also in beiden Tabellen oder in keiner.

Herausfinden, welche Aktion MERGE ausgeführt hat

Seit PostgreSQL 17 akzeptiert MERGE ein RETURNING, und die Funktion merge_action() liefert für jede Zeile INSERT, UPDATE oder DELETE:

A-100 wurde auf 7 aktualisiert und C-300 mit 4 eingefügt. Für ein Einfügen oder Aktualisieren per Schlüssel bei gleichzeitigen Schreibzugriffen nimmst du besser einen Upsert mit ON CONFLICT, der ebenfalls RETURNING unterstützt.

Was RETURNING enthalten kann

Alles, was eine SELECT Liste enthalten kann: Spalten, *, Ausdrücke, Funktionsaufrufe und Aliase (RETURNING price * qty AS total), außer Aggregaten. Um die zurückgegebenen Zeilen zu zählen oder zu summieren, packst du die Anweisung in eine WITH Abfrage und aggregierst im äußeren SELECT.

Zeilen, die ON CONFLICT DO NOTHING oder ein BEFORE Trigger mit Rückgabe NULL übersprungen hat, werden nicht zurückgegeben.

Häufig gestellte Fragen

Wie bekomme ich in PostgreSQL die ID der gerade eingefügten Zeile?

Häng RETURNING id an das INSERT. Das liefert den generierten Wert für jede eingefügte Zeile im selben Roundtrip, ist sicherer als SELECT max(id) und funktioniert mit Identity-Spalten, serial und Defaults wie gen_random_uuid().

Ist RETURNING schneller als ein separates SELECT?

Meist ja. Es spart eine zweite Anweisung und einen zweiten Roundtrip zum Server, und es liefert genau die Zeilen, die die Anweisung berührt hat, ohne Zeitfenster, in dem eine andere Sitzung sie dazwischen ändern könnte.

Unterstützt MySQL RETURNING?

MySQL hat keine RETURNING Klausel; dort liest du nach einem Insert stattdessen LAST_INSERT_ID(). SQLite unterstützt RETURNING seit Version 3.35.

Illustration der Programmiersprachen bei Coddy

Lerne mit Coddy zu programmieren

Los geht's