Menu

RETURNING en PostgreSQL para INSERT, UPDATE y DELETE

RETURNING hace que INSERT, UPDATE, DELETE y MERGE devuelvan las filas que cambiaron: ids generados, valores nuevos, filas borradas y qué acción de MERGE se ejecutó.

Esta página incluye editores ejecutables: edita, ejecuta y ve el resultado al instante.

RETURNING hace que una sentencia que modifica datos devuelva filas, como un SELECT. Añádela al final de un INSERT, UPDATE, DELETE o (desde PostgreSQL 17) MERGE, seguida de las columnas o expresiones que quieras: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.

Las dos filas nuevas vuelven con los ids que generó PostgreSQL y el plan relleno con su valor por defecto, sin una segunda consulta.

Obtener el id de una fila insertada

RETURNING id es la forma estándar de obtener una clave generada. Informa de la fila tal como se guardó, así que funciona con columnas identity, serial, valores por defecto UUID y valores puestos por un trigger BEFORE. Un VALUES de varias filas o un INSERT ... SELECT devuelve una fila por cada fila insertada.

Los drivers lo leen como el resultado de cualquier consulta: cursor.fetchone() en Python con psycopg, result.rows en Node.js con pg. RETURNING * está bien mientras exploras; en el código de una aplicación, enumera las columnas para que el resultado no cambie cuando cambie la tabla.

Ver qué cambió un UPDATE

En un UPDATE, RETURNING muestra las filas después del cambio, y solo las que cumplieron el WHERE:

Vuelven dos filas, Book a 16.5 y Lamp a 33. Pen no se tocó, así que no está en el resultado.

En PostgreSQL 17, RETURNING solo ve los valores nuevos. PostgreSQL 18 añade old y new (RETURNING old.price, new.price). En la 17, une la tabla con una copia bloqueada de sí misma:

Cada fila vuelve con su precio de antes y de después: 10 y 15, 20 y 25.

Devolver las filas que borró un DELETE

DELETE ... RETURNING te da las filas que eliminó, para un registro, para deshacer o para una cola de trabajos en la que un worker borra un trabajo y recibe sus datos. Dentro de una consulta WITH, las filas devueltas alimentan la siguiente sentencia, lo que mueve filas entre tablas en una sola sentencia:

Las tareas 1 y 3 salen de tasks y llegan a done_tasks. Es una sola sentencia, así que ninguna otra sesión las ve en las dos tablas ni en ninguna.

Saber qué acción ejecutó MERGE

Desde PostgreSQL 17, MERGE acepta RETURNING, y la función merge_action() devuelve INSERT, UPDATE o DELETE para cada fila:

A-100 se actualizó a 7 y C-300 se insertó con 4. Para insertar o actualizar por clave con escrituras concurrentes, mejor usa un upsert con ON CONFLICT, que también admite RETURNING.

Qué puede contener RETURNING

Todo lo que admite la lista de un SELECT: columnas, *, expresiones, llamadas a funciones y alias (RETURNING price * qty AS total), salvo agregados. Para contar o sumar las filas devueltas, envuelve la sentencia en una consulta WITH y agrega en el SELECT exterior.

Las filas omitidas por ON CONFLICT DO NOTHING, o por un trigger BEFORE que devolvió NULL, no se devuelven.

Preguntas frecuentes

¿Cómo obtengo el id de la fila que acabo de insertar en PostgreSQL?

Añade RETURNING id al INSERT. Devuelve el valor generado de cada fila insertada en el mismo viaje al servidor, lo que es más seguro que SELECT max(id) y funciona con columnas identity, serial y valores por defecto como gen_random_uuid().

¿RETURNING es más rápido que un SELECT aparte?

Normalmente, sí. Ahorra una segunda sentencia y un segundo viaje al servidor, y devuelve exactamente las filas que tocó la sentencia, sin margen para que otra sesión las cambie entre medias.

¿MySQL soporta RETURNING?

MySQL no tiene cláusula RETURNING; en su lugar lees LAST_INSERT_ID() después de un insert. SQLite soporta RETURNING desde la versión 3.35.

Ilustración de los lenguajes de programación de Coddy

Aprende a programar con Coddy

Comenzar