A cláusula RETURNING permite que instruções INSERT, UPDATE e DELETE retornem dados sobre as linhas que afetaram — mais comumente o ID gerado automaticamente após uma inserção, mas também qualquer coluna ou valores calculados. Isso economiza uma query separada e é um recurso conveniente do PostgreSQL.
-- 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
O uso mais comum: após inserir, você geralmente precisa da chave primária gerada (para usar em inserções relacionadas ou retornar ao cliente). RETURNING id a devolve diretamente — sem necessidade de uma query separada.
-- 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 com UPDATE (veja os novos valores) e DELETE (capture o que foi removido — útil para arquivamento ou confirmação).
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.
-- 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
A cláusula RETURNING é um recurso conveniente e frequentemente usado do PostgreSQL que é valioso para eficiência e correção ao modificar dados.
Seu uso mais comum e importante é obter o ID gerado automaticamente de volta de um INSERT — uma necessidade praticamente universal (você quase sempre quer a nova chave primária após inserir, para usar em operações relacionadas ou retornar à aplicação), e RETURNING id a fornece diretamente em uma única instrução.
Sem RETURNING, você precisaria de um SELECT separado para obter o ID gerado, o que significa uma viagem de ida e volta extra e uma condição de corrida potencial (o SELECT separado pode não recuperar confiàvelmente sua linha específica em cenários concorrentes), então RETURNING é mais eficiente e mais correto.
Além de inserções, RETURNING funciona com UPDATE (vendo os novos valores após uma atualização) e DELETE (capturando o que foi removido — útil para arquivamento, logging ou confirmação de exclusões).
Combinado com CTEs, ele permite padrões poderosos como inserir em tabelas relacionadas usando o ID retornado em uma única instrução.
Como obter valores gerados (especialmente IDs) após modificações de dados é uma necessidade constante, e como RETURNING fornece isso de forma eficiente e atômica (evitando queries extras e condições de corrida), compreender a cláusula RETURNING é conhecimento PostgreSQL valioso e frequentemente aplicado que torna o código de modificação de dados mais limpo, mais eficiente e mais correto — uma conveniência prática que é usada rotineiramente em aplicações reais trabalhando com Postgres, particularmente para a necessidade onipresente de recuperar IDs gerados após inserções.