Cláusula RETURNING en SQLite: INSERT, UPDATE y DELETE

Una forma de ver lo que acaba de pasar

Cuando ejecutas un INSERT, UPDATE o DELETE, SQLite te dice cuántas filas se vieron afectadas, pero no cuáles ni cómo quedaron sus valores finales. El truco de toda la vida es lanzar un SELECT justo después. Eso supone dos viajes de ida y vuelta, dos sentencias y una pequeña ventana de carrera en la que otra persona podría modificar la fila entre medias.

La cláusula RETURNING resuelve esto. La añades al final de una sentencia de escritura, indicas las columnas que quieres recuperar y SQLite te devuelve las filas afectadas como si acabaras de hacer un SELECT sobre ellas:

CREATE TABLE notes (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO notes (title) VALUES ('Primera nota')
RETURNING id, title, created_at;

Una sentencia, un viaje y obtienes de vuelta el id generado junto con el valor por defecto de created_at que la base de datos rellenó por ti.

La cláusula RETURNING se incorporó en SQLite 3.35.0 (marzo de 2021). Si tu sentencia te devuelve un error de sintaxis, revisa primero SELECT sqlite_version(); — las versiones antiguas no reconocen la palabra clave.

Obtener el ID generado tras un INSERT

El motivo más habitual para recurrir a RETURNING en SQLite es justamente ese: recuperar la clave primaria autogenerada justo después de insertar una fila:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email TEXT NOT NULL UNIQUE
);

INSERT INTO users (email) VALUES ('rosa@example.com')
RETURNING id;

Antes de la cláusula RETURNING, lo habitual era hacer el INSERT y luego llamar a last_insert_rowid() (o el equivalente de tu driver) sobre la misma conexión. Sigue funcionando, claro, pero depende del estado de la conexión —algo fácil de romper cuando entran en juego pools de conexiones o varios hilos. En cambio, RETURNING id es explícito, vive dentro de la propia sentencia y se comporta igual sin importar quién gestione la conexión.

Si tu tabla no declara una INTEGER PRIMARY KEY de forma explícita, aún puedes obtener el identificador implícito de la fila:

CREATE TABLE logs (event TEXT);

INSERT INTO logs (event) VALUES ('inicio')
RETURNING rowid, event;

Toda tabla común de SQLite tiene un rowid, y RETURNING te lo devuelve sin problema.

Varias columnas y expresiones

RETURNING admite lo mismo que la lista de columnas de un SELECT. Puedes enumerar columnas, usar *, armar expresiones y ponerles alias:

CREATE TABLE line_items (
    id INTEGER PRIMARY KEY,
    product TEXT NOT NULL,
    price REAL NOT NULL,
    quantity INTEGER NOT NULL
);

INSERT INTO line_items (product, price, quantity)
VALUES ('Cuaderno', 4.50, 3)
RETURNING id, product, price * quantity AS subtotal;

RETURNING * te resulta muy práctico cuando quieres obtener todo —incluidos los valores por defecto que rellena la base de datos— sin tener que nombrar cada columna:

CREATE TABLE events (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO events (name) VALUES ('inicio_sesion')
RETURNING *;

Verás el nuevo id, el name que pasaste y el timestamp que SQLite calculó.

RETURNING con UPDATE

En un UPDATE, la cláusula RETURNING te devuelve los valores ya actualizados, es decir, la fila tal como queda después de aplicar tus cambios:

CREATE TABLE accounts (
    id INTEGER PRIMARY KEY,
    name TEXT,
    balance INTEGER NOT NULL
);
INSERT INTO accounts (name, balance) VALUES ('Ada', 100), ('Boris', 50);

UPDATE accounts
SET balance = balance + 25
WHERE name = 'Ada'
RETURNING id, name, balance;

Recibes el nuevo saldo de Ada, que es 125, y no el anterior de 100. Por eso la cláusula RETURNING viene de maravilla para contadores atómicos y operaciones de débito/crédito: te ahorras tener que leer, calcular, escribir y volver a leer.

Si el WHERE coincide con varias filas, obtendrás una fila de respuesta por cada fila afectada:

CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL);
INSERT INTO products (name, price) VALUES ('A', 10), ('B', 20), ('C', 30);

UPDATE products
SET price = price * 1.1
RETURNING id, name, price;

Tres filas entran, tres filas salen. El orden no está garantizado: si necesitas un orden concreto, ordena el resultado en el cliente.

DELETE RETURNING en SQLite

En un DELETE, la cláusula RETURNING te devuelve las filas tal y como estaban justo antes de borrarlas. Viene genial para archivar datos, llevar un registro de auditoría o simplemente confirmar qué se eliminó:

CREATE TABLE sessions (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    expires_at TEXT NOT NULL
);
INSERT INTO sessions (user_id, expires_at) VALUES
    (1, '2024-01-01'), (2, '2024-01-02'), (3, '2026-01-01');

DELETE FROM sessions
WHERE expires_at < '2025-01-01'
RETURNING id, user_id, expires_at;

Recibes las dos sesiones expiradas con todos sus campos intactos, aunque ya no existan en la tabla. Si quieres moverlas a otro lugar, es el escenario ideal para una tabla de archivo: lees el resultado y lo insertas en otra tabla dentro de la misma transacción.

RETURNING con UPSERT en SQLite

La cláusula RETURNING también funciona con INSERT ... ON CONFLICT ... DO UPDATE. La fila devuelta refleja la rama que se ejecutó, ya sea la inserción nueva o la actualización por conflicto:

CREATE TABLE counters (
    name TEXT PRIMARY KEY,
    value INTEGER NOT NULL DEFAULT 0
);

INSERT INTO counters (name, value) VALUES ('visits', 1)
ON CONFLICT(name) DO UPDATE SET value = value + 1
RETURNING name, value;

Ejecuta esa sentencia dos veces. La primera vez inserta y devuelve ('visits', 1). La segunda vez se dispara el conflicto, el valor se incrementa y obtienes ('visits', 2). En ambos casos, una sola sentencia y una sola fila de salida: no hace falta preguntarse "¿se insertó o se actualizó?" antes de seguir.

Este es el patrón más limpio en SQLite para "dame el valor actual, creándolo si hace falta" sin necesidad de un ida y vuelta extra.

Algunas cosas que conviene saber

Hay un puñado de detalles que suelen pillar a la gente desprevenida:

• RETURNING siempre ve la fila después del cambio en INSERT y UPDATE, y antes del cambio en DELETE. No hay sintaxis para pedir el otro lado.
• El orden de las filas devueltas no está garantizado. Si te importa, añade un ORDER BY desde el cliente.
• No puedes meter RETURNING dentro de una subconsulta. Es una cláusula de nivel superior de la sentencia de escritura, no una expresión.
• RETURNING no devuelve los datos modificados por los triggers BEFORE — devuelve los valores que realmente se escribieron. Los triggers AFTER se ejecutan entre la escritura y el momento en que la fila se devuelve.
• Las columnas generadas y los valores DEFAULT aparecen en el resultado. Justamente por eso, RETURNING * es una forma rápida de ver qué rellenó la base de datos por ti.

Siguiente paso: importar datos desde CSV

RETURNING viene de perlas cuando escribes una fila o unas pocas a la vez y quieres ver el resultado al instante. Pero cuando tengas que cargar miles de filas desde un archivo, lo suyo es tirar de las herramientas de importación CSV de SQLite — y de eso hablamos en la siguiente página.