Uso de RETURNING para obtener datos después de insertar/actualizar

Hoy vamos a añadir otro truco mágico a nuestro arsenal: el comando RETURNING. Es una herramienta potente que te permite recibir de vuelta los datos que necesitas justo después de insertar, actualizar o borrar algo. Imagina que insertas una fila en una tabla y al instante recibes su identificador único. ¿Cómodo? ¡Por supuesto! ¡Vamos a aprender cómo se hace!

Después de ejecutar operaciones como INSERT, UPDATE o DELETE, a veces necesitas obtener enseguida los datos que se han tocado. Por ejemplo, tras insertar una nueva fila en una tabla, necesitas saber su clave primaria generada automáticamente (identificador único). En vez de hacer una consulta aparte para conseguir estos datos, puedes hacerlo directamente en la misma operación usando RETURNING.

Supón que añades un nuevo estudiante a la tabla students. Cada estudiante tiene un identificador único (por ejemplo, student_id) que se genera automáticamente. Después de añadir el registro, quieres usar ese identificador para registrar al estudiante en un curso. Sin RETURNING, tendrías que añadir primero al estudiante y luego hacer una consulta SELECT aparte para encontrar su identificador. ¡Con RETURNING lo haces todo de una!

Sintaxis del comando RETURNING

El comando RETURNING se añade al final de las operaciones INSERT, UPDATE y DELETE. Aquí tienes la sintaxis general:

-- Sintaxis de INSERT:
INSERT INTO tabla (column1, column2, ...)
VALUES (value1, value2, ...)
RETURNING columna;

-- Sintaxis de UPDATE:
UPDATE tabla
SET column1 = value1
WHERE condición
RETURNING columna;

-- Sintaxis de DELETE:
DELETE FROM tabla
WHERE condición
RETURNING columna;

RETURNING te permite indicar qué columnas de las filas modificadas quieres que te devuelva. Puede ser una columna concreta (por ejemplo, la clave primaria) o varias columnas a la vez.

Uso de RETURNING con INSERT

Vamos a ver un ejemplo con la tabla students:

CREATE TABLE students (
    student_id SERIAL PRIMARY KEY,
    first_name TEXT NOT NULL,
    last_name TEXT NOT NULL,
    email TEXT UNIQUE
);

Añadimos un nuevo estudiante y recibimos su identificador al instante:

INSERT INTO students (first_name, last_name, email)
VALUES ('Otto', 'Lin', 'otto.lin@example.com')
RETURNING student_id;

La consulta te devuelve el identificador del estudiante añadido:

Acabas de añadir al estudiante Otto Lin, y PostgreSQL te ha dicho al momento cuál es su student_id. ¿Cómodo? ¡Y tanto!

Ahora vamos a insertar y recibir varias columnas a la vez. Si necesitas no solo el student_id, sino también otros datos como el nombre y apellido del estudiante, puedes pedirlos con RETURNING:

INSERT INTO students (first_name, last_name, email)
VALUES ('Alex', 'Ming', 'alex.ming@example.com')
RETURNING student_id, first_name, last_name;

Resultado:

Uso de RETURNING con UPDATE

A veces, después de actualizar datos, quieres saber exactamente qué filas han cambiado. RETURNING lo hace fácil.

Imagina que el estudiante Otto Lin decide cambiar su email. Vamos a actualizar sus datos y recibir la información de la fila modificada:

UPDATE students
SET email = 'lin.new@example.com'
WHERE student_id = 1
RETURNING student_id, email;

Resultado:

Ahora sabes seguro que el email del estudiante con student_id = 1 se ha actualizado correctamente.

Uso de RETURNING con DELETE

Cuando borras registros de una tabla, a veces viene bien saber qué filas se han eliminado. Con RETURNING puedes obtener los datos de las filas borradas.

Por ejemplo, supón que el estudiante Peter Ming ha sido expulsado. Lo eliminamos de la tabla y recibimos la información de su eliminación:

DELETE FROM students
WHERE student_id = 2
RETURNING student_id, first_name, last_name;

Resultado:

Ahora tienes claro que fue Peter Ming quien se eliminó.

Consejos prácticos

Usa RETURNING siempre que necesites datos de las filas afectadas. Así evitas consultas extra a la base de datos.

Minimiza la cantidad de datos que devuelves. Si solo necesitas la clave primaria, pide solo esa columna.

En combinación con transacciones, RETURNING es aún más potente. Por ejemplo, puedes añadir datos en varias tablas relacionadas, pasando identificadores usando RETURNING.

Errores típicos al usar RETURNING

Muchos principiantes se olvidan de que RETURNING solo funciona con las filas que realmente se modifican. Por ejemplo, si una consulta UPDATE o DELETE no encuentra ninguna fila, RETURNING devuelve un resultado vacío. No te asustes, es normal. Solo asegúrate de que tu consulta es correcta, o maneja este caso en el código de tu aplicación.

Otro error común: intentar usar RETURNING con columnas que no existen. Asegúrate siempre de que todas las columnas que pides existen en tu tabla.

Ahora ya sabes cómo RETURNING puede simplificar mucho el trabajo con los datos. Es una de esas herramientas que vas a valorar un montón cuando crees aplicaciones reales. ¡A por nuevos horizontes!