La cláusula RETURNING permite que las sentencias INSERT, UPDATE y DELETE devuelvan datos sobre las filas que afectaron — más comúnmente el ID generado automáticamente después de una inserción, pero también cualquier columna o valor calculado. Ahorra una consulta separada y es una característica conveniente de PostgreSQL.
RETURNING después de INSERT (obtener el ID generado)
-- get the auto-generated id back from the insert (no separate SELECT needed)
INSERT INTO users (name, email) VALUES ('Ann', '[email protected]')
RETURNING id; -- returns the new id
-- return multiple columns or all of them
INSERT INTO users (name) VALUES ('Bob')
RETURNING id, name, created_at; -- including DB-generated values
INSERT INTO users (name) VALUES ('Carol') RETURNING *; -- the whole row
El uso más común: después de insertar, normalmente necesitas la clave primaria generada (para usar en inserciones relacionadas o devolver al cliente). RETURNING id la devuelve directamente — sin necesidad de una consulta separada.
RETURNING con UPDATE y DELETE
-- see what was updated
UPDATE products SET price = price * 1.1 WHERE category = 'books'
RETURNING id, name, price; -- the NEW values after the update
-- capture deleted rows (e.g. for archiving/logging)
DELETE FROM sessions WHERE expired = true
RETURNING id, user_id; -- which rows were deleted
RETURNING funciona en UPDATE (ver los nuevos valores) y DELETE (capturar lo que se eliminó — útil para archivado o confirmación).
Por qué es importante: eficiencia y atomicidad
Without RETURNING:
INSERT ...; then a separate SELECT to get the id → TWO round-trips, and a potential
race (the SELECT might not reliably get YOUR row).
With RETURNING:
one statement returns the affected data atomically → fewer round-trips, no race.
Un patrón combinado: insertar en tablas relacionadas
-- use a CTE with RETURNING to insert and use the id in the same statement
WITH new_user AS (
INSERT INTO users (name) VALUES ('Ann') RETURNING id
)
INSERT INTO profiles (user_id, bio)
SELECT id, 'Hello' FROM new_user; -- use the returned id directly
Por qué es importante
La cláusula RETURNING es una característica conveniente y frecuentemente utilizada de PostgreSQL que es valiosa para la eficiencia y la corrección al modificar datos.
Su uso más común e importante es obtener el ID generado automáticamente de un INSERT — una necesidad casi universal (casi siempre quieres la nueva clave primaria después de insertar, para usarla en operaciones relacionadas o devolver a la aplicación), y RETURNING id la proporciona directamente en una sola sentencia.
Sin RETURNING, necesitarías un SELECT separado para obtener el ID generado, lo que significa un viaje de ida y vuelta adicional y una posible condición de carrera (el SELECT separado podría no recuperar confiablemente tu fila específica en escenarios concurrentes), así que RETURNING es tanto más eficiente como más correcto.
Más allá de inserciones, RETURNING funciona con UPDATE (viendo los nuevos valores después de una actualización) y DELETE (capturando lo que se eliminó — útil para archivado, registro o confirmación de eliminaciones).
Combinado con CTEs, habilita patrones poderosos como insertar en tablas relacionadas usando el ID devuelto en una sola sentencia.
Ya que obtener valores generados (especialmente IDs) después de modificaciones de datos es una necesidad constante, y ya que RETURNING proporciona esto eficientemente y atómicamente (evitando consultas extra y condiciones de carrera), entender la cláusula RETURNING es conocimiento valioso y frecuentemente aplicado de PostgreSQL que hace que el código de modificación de datos sea más limpio, más eficiente y más correcto — una conveniencia práctica que se utiliza rutinariamente en aplicaciones reales que trabajan con Postgres, particularmente para la necesidad ubicua de recuperar IDs generados después de inserciones.