Parfois, il est intéressant d'obtenir des données de lignes modifiées pendant qu'elles sont manipulées. Les commandes INSERT, UPDATE et DELETE 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 *;
   

Si des triggers (Chapitre 39) 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.