Menu

RETURNING PostgreSQL : récupérer l'id après un INSERT

RETURNING fait renvoyer à INSERT, UPDATE, DELETE et MERGE les lignes qu'ils ont modifiées : id générés, nouvelles valeurs, lignes supprimées et action exécutée par MERGE.

Cette page contient des éditeurs exécutables. Modifiez, exécutez et voyez la sortie instantanément.

RETURNING fait renvoyer des lignes à une requête qui modifie des données, comme le ferait un SELECT. Ajoutez-la à la fin d'un INSERT, d'un UPDATE, d'un DELETE ou (depuis PostgreSQL 17) d'un MERGE, suivie des colonnes ou expressions voulues : INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.

Les deux nouvelles lignes reviennent avec les id générés par PostgreSQL et la colonne plan remplie par sa valeur par défaut, sans deuxième requête.

Récupérer l'id d'une ligne insérée

RETURNING id est la façon standard de récupérer une clé générée. La clause décrit la ligne telle qu'elle a été stockée, donc elle fonctionne avec les colonnes identity, serial, les UUID par défaut et les valeurs posées par un trigger BEFORE. Un VALUES à plusieurs lignes ou un INSERT ... SELECT renvoie une ligne par ligne insérée.

Les drivers la lisent comme n'importe quel résultat de requête : cursor.fetchone() en Python avec psycopg, result.rows en Node.js avec pg. RETURNING * convient pour explorer ; dans le code de l'application, listez les colonnes pour que le résultat reste stable quand la table change.

Voir ce qu'un UPDATE a modifié

Sur un UPDATE, RETURNING montre les lignes après la modification, et seulement celles qui correspondent au WHERE :

Deux lignes reviennent, Book à 16.5 et Lamp à 33. Pen n'a pas été touché, il n'apparaît donc pas dans le résultat.

Dans PostgreSQL 17, RETURNING ne voit que les nouvelles valeurs. PostgreSQL 18 ajoute old et new (RETURNING old.price, new.price). Sur la 17, joignez la table à une copie verrouillée d'elle-même :

Chaque ligne revient avec son prix avant et après : 10 et 15, 20 et 25.

Renvoyer les lignes supprimées par un DELETE

DELETE ... RETURNING vous donne les lignes supprimées, pour un journal, pour pouvoir annuler, ou pour une file de tâches où un worker supprime une tâche et récupère ses données. Dans une requête WITH, les lignes renvoyées alimentent l'instruction suivante, ce qui déplace des lignes d'une table à l'autre en une seule instruction :

Les tâches 1 et 3 quittent tasks et arrivent dans done_tasks. C'est une seule instruction, donc aucune autre session ne les voit dans les deux tables ou dans aucune.

Savoir quelle action MERGE a exécutée

Depuis PostgreSQL 17, MERGE accepte RETURNING, et la fonction merge_action() renvoie INSERT, UPDATE ou DELETE pour chaque ligne :

A-100 a été mis à jour à 7 et C-300 a été inséré avec 4. Pour insérer ou mettre à jour par clé avec des écritures concurrentes, préférez un upsert avec ON CONFLICT, qui prend aussi en charge RETURNING.

Ce que RETURNING peut contenir

Tout ce qu'une liste de SELECT peut contenir : colonnes, *, expressions, appels de fonction et alias (RETURNING price * qty AS total), sauf les agrégats. Pour compter ou additionner les lignes renvoyées, placez l'instruction dans une requête WITH et agrégez dans le SELECT externe.

Les lignes ignorées par ON CONFLICT DO NOTHING, ou par un trigger BEFORE qui a renvoyé NULL, ne sont pas renvoyées.

Questions fréquentes

Comment récupérer l'id de la ligne que je viens d'insérer dans PostgreSQL ?

Ajoutez RETURNING id à l'INSERT. La clause renvoie la valeur générée pour chaque ligne insérée dans le même aller-retour, ce qui est plus sûr que SELECT max(id) et fonctionne avec les colonnes identity, serial et les valeurs par défaut comme gen_random_uuid().

RETURNING est-il plus rapide qu'un SELECT séparé ?

En général, oui. Vous économisez une deuxième requête et un deuxième aller-retour vers le serveur, et vous obtenez exactement les lignes touchées par la requête, sans laisser à une autre session le temps de les modifier entre les deux.

MySQL prend-il en charge RETURNING ?

MySQL n'a pas de clause RETURNING ; on lit LAST_INSERT_ID() après une insertion à la place. SQLite prend en charge RETURNING depuis la version 3.35.

Illustration des langages de programmation de Coddy

Apprendre à coder avec Coddy

Commencer