Menu

RETURNING no PostgreSQL para INSERT, UPDATE e DELETE

RETURNING faz INSERT, UPDATE, DELETE e MERGE devolverem as linhas que alteraram: ids gerados, valores novos, linhas apagadas e qual ação do MERGE foi executada.

Esta página tem editores executáveis. Edite, execute e veja a saída na hora.

RETURNING faz um comando que altera dados devolver linhas, como um SELECT. Coloque no final de um INSERT, UPDATE, DELETE ou (desde o PostgreSQL 17) MERGE, seguido das colunas ou expressões que você quer: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.

As duas linhas novas voltam com os ids que o PostgreSQL gerou e o plan preenchido pelo valor padrão, sem uma segunda consulta.

Pegar o id de uma linha inserida

RETURNING id é o jeito padrão de pegar uma chave gerada. Ele mostra a linha como ela foi gravada, então funciona com colunas identity, serial, valores padrão UUID e valores definidos por um trigger BEFORE. Um VALUES com várias linhas ou um INSERT ... SELECT devolve uma linha para cada linha inserida.

Os drivers leem o resultado como o de qualquer consulta: cursor.fetchone() em Python com psycopg, result.rows em Node.js com pg. RETURNING * serve enquanto você explora; no código da aplicação, liste as colunas para o resultado continuar estável quando a tabela mudar.

Ver o que um UPDATE alterou

Num UPDATE, RETURNING mostra as linhas depois da alteração, e só as que bateram com o WHERE:

Voltam duas linhas, Book por 16.5 e Lamp por 33. Pen não foi alterado, então não aparece no resultado.

No PostgreSQL 17, RETURNING só enxerga os valores novos. O PostgreSQL 18 adiciona old e new (RETURNING old.price, new.price). Na 17, faça um join da tabela com uma cópia travada dela mesma:

Cada linha volta com o preço de antes e de depois: 10 e 15, 20 e 25.

Devolver as linhas que um DELETE removeu

DELETE ... RETURNING devolve as linhas removidas, para log, para desfazer ou para uma fila de jobs em que um worker apaga um job e recebe os dados dele. Dentro de uma consulta WITH, as linhas devolvidas alimentam o próximo comando, o que move linhas entre tabelas num único comando:

As tarefas 1 e 3 saem de tasks e chegam em done_tasks. É um único comando, então nenhuma outra sessão as vê nas duas tabelas ou em nenhuma.

Descobrir qual ação o MERGE executou

Desde o PostgreSQL 17, o MERGE aceita RETURNING, e a função merge_action() retorna INSERT, UPDATE ou DELETE para cada linha:

A-100 foi atualizado para 7 e C-300 foi inserido com 4. Para inserir ou atualizar por chave com escritas concorrentes, prefira um upsert com ON CONFLICT, que também aceita RETURNING.

O que o RETURNING pode conter

Tudo que a lista de um SELECT aceita: colunas, *, expressões, chamadas de função e aliases (RETURNING price * qty AS total), exceto agregações. Para contar ou somar as linhas devolvidas, coloque o comando numa consulta WITH e agregue no SELECT de fora.

Linhas ignoradas por ON CONFLICT DO NOTHING, ou por um trigger BEFORE que retornou NULL, não são devolvidas.

Perguntas frequentes

Como pegar o id da linha que acabei de inserir no PostgreSQL?

Adicione RETURNING id ao INSERT. Ele devolve o valor gerado de cada linha inserida na mesma ida ao servidor, o que é mais seguro que SELECT max(id) e funciona com colunas identity, serial e valores padrão como gen_random_uuid().

RETURNING é mais rápido que um SELECT separado?

Geralmente, sim. Ele economiza um segundo comando e uma segunda ida ao servidor, e devolve exatamente as linhas que o comando alterou, sem chance de outra sessão mudá-las no meio do caminho.

O MySQL suporta RETURNING?

O MySQL não tem a cláusula RETURNING; em vez disso, você lê LAST_INSERT_ID() depois de um insert. O SQLite suporta RETURNING desde a versão 3.35.

Ilustração das linguagens de programação do Coddy

Aprenda a programar com o Coddy

Começar