Parfois, il est intéressant d'obtenir des données de lignes modifiées pendant qu'elles sont manipulées. Les commandes INSERT, UPDATE, DELETE et MERGE ont toutes une clause RETURNING optionnelle qui le permet. L'utilisation de la clause RETURNING évite l'exécution d'une requête supplémentaire pour coller les données, et est particulièrement intéressante quand il serait difficile d'identifier autrement les lignes modifiées.

Le contenu autorisé d'une clause RETURNING est identique à celui de la liste de sortie d'une commande SELECT (voir Section 7.3). Elle peut contenir les noms des colonnes de la table cible ou des expressions utilisant ces colonnes. Un raccourci habituel est RETURNING *, qui sélectionne toutes les colonnes de la table cible, dans l'ordre de définition.

Avec un INSERT, les données disponibles à RETURNING sont la ligne qui a été insérée. Ceci n'est pas utile pour les insertions simples, car cela ne fera que répéter les données fournies par le client, mais cela peut devenir très utile si la commande se base sur les valeurs calculées par défaut. Par exemple, lors de l'utilisation d'une colonne serial fournissant des identifiants uniques, RETURNING peut renvoyer l'identifiant affecté à une nouvelle ligne :

CREATE TABLE utilisateurs (prenom text, nom text, id serial primary key);

INSERT INTO utilisateurs (prenom, nom) VALUES ('Joe', 'Cool') RETURNING id;
   

La clause RETURNING est aussi très utile avec un INSERT ... SELECT

Dans un UPDATE, les données disponibles pour la clause RETURNING correspondent au nouveau contenu de la ligne modifiée. Par exemple :

UPDATE produits SET prix = prix * 1.10
  WHERE prix <= 99.99
  RETURNING nom, prix AS nouveau_prix;
   

Dans un DELETE, les données disponibles pour la clause RETURNING correspondent au contenu de la ligne supprimée. Par exemple :

DELETE FROM produits
  WHERE date_perime = 'today'
  RETURNING *;
   

Dans un MERGE, les données disponibles pour la clause RETURNING est le contenu de la ligne cible ainsi que le contenu de la ligne cible insérée, mise à jour ou supprimée. Comme il est souvent commun que la source et la cible aient un grand nombre de colonnes en commun, indiquer RETURNING * peut ajouter un grand nombre de colonnes dupliquées, donc il est souvent plus utile de le qualifier pour qu'il ne renvoie que la ligne source ou cible. Par exemple :

MERGE INTO products p USING new_products n ON p.product_no = n.product_no
  WHEN NOT MATCHED THEN INSERT VALUES (n.product_no, n.name, n.price)
  WHEN MATCHED THEN UPDATE SET name = n.name, price = n.price
  RETURNING p.*;

Si des triggers (Chapitre 37) sont définis sur la table cible, les données disponibles pour la clause RETURNING correspondent à la ligne modifiée par les triggers. De ce fait, une utilisation courante de la clause RETURNING est d'inspecter les colonnes calculées par les triggers.