ON CONFLICT no PostgreSQL: o que o DO NOTHING esconde e como saber o que o upsert fez
Testamos o upsert no PostgreSQL 18.4: o RETURNING vazio, a sequência que pula números, os dois erros clássicos e o RETURNING com OLD e NEW da versão 18.

O INSERT ... ON CONFLICT resolve em um comando o “insere se não existe, atualiza se existe”, sem o SELECT antes. É dos recursos mais usados do PostgreSQL, e quatro comportamentos dele surpreendem quem chega esperando um INSERT comum.
Testamos todos no PostgreSQL 18.4, numa tabela temporária de estoque com um sku único. Os números abaixo são da saída do psql.
O upsert básico
INSERT INTO estoque (sku, qtd) VALUES ('CAM-P', 3)
ON CONFLICT (sku) DO UPDATE SET qtd = estoque.qtd + EXCLUDED.qtd
RETURNING id, sku, qtd;O EXCLUDED é a linha que você tentou inserir; o nome da tabela é a que já estava lá. No teste, o estoque de 10 passou a 13. A documentação garante que o DO UPDATE tem resultado atômico, inserção ou atualização, mesmo com muita concorrência, que é justamente o que o SELECT seguido de INSERT não garante.
1. O DO NOTHING devolve vazio, sem erro
O RETURNING devolve as linhas inseridas ou atualizadas. Quando o DO NOTHING não faz nada, não há linha, e o resultado é vazio, com o psql mostrando INSERT 0 0. O código que esperava o id de volta recebe zero linhas e, se não conferir, segue com um id nulo.
Para ter o id nos dois casos, um padrão que funcionou no teste:
WITH novo AS (
INSERT INTO estoque (sku, qtd) VALUES ('CAM-P', 10)
ON CONFLICT (sku) DO NOTHING RETURNING id
)
SELECT id FROM novo
UNION ALL
SELECT id FROM estoque WHERE sku = 'CAM-P'
LIMIT 1;Na primeira execução, o id veio do novo; na segunda, da tabela. Um aviso honesto: com várias transações gravando o mesmo sku ao mesmo tempo, há uma janela em que as duas partes voltam vazias, porque o SELECT enxerga a tabela como ela estava no começo do comando. Não reproduzimos esse caso, que pede duas sessões e uma tabela de verdade. Se ele importa no seu sistema, trate o resultado vazio repetindo a consulta.
2. A sequência anda mesmo quando nada entra
Inserimos o primeiro item (id 1), tentamos o mesmo sku três vezes e inserimos um item novo. Ele recebeu o id 6. Cada tentativa consumiu um número da sequência, inclusive as que deram em nada. No fim do teste, a tabela tinha 4 linhas e o maior id era 13.
A documentação das sequências explica: para não bloquear as outras transações, o número tirado pelo nextval não volta para a fila. Buracos são normais. O problema é usar o id como contagem ou como número de nota fiscal, que precisa ser seguido.

3. Inserido ou atualizado? Três jeitos
O truque do xmax. Muito citado: RETURNING (xmax = 0) AS inserido. No teste, deu t para a linha nova e f para a atualizada. Funciona, mas usa um detalhe interno do armazenamento, e não uma interface documentada.
O RETURNING com OLD e NEW, do PostgreSQL 18. As notas da versão 18 trazem o OLD e o NEW no RETURNING do INSERT, do UPDATE, do DELETE e do MERGE. Na linha recém-inserida, o old vem nulo:
... RETURNING new.sku, old.qtd AS antes, new.qtd AS depois, (old.id IS NULL) AS inserido;
sku | antes | depois | inserido
CAM-P | 10 | 13 | f
CAM-M | (nulo) | 5 | tÉ o jeito que recomendamos de agora em diante: documentado, e ainda devolve o valor anterior, que serve para log e auditoria.
O MERGE com merge_action(). Desde o PostgreSQL 17, o MERGE aceita RETURNING, e a função merge_action() diz o que aconteceu em cada linha: no teste, UPDATE para o item existente e INSERT para o novo, o que faz dele o caminho natural quando a entrada vem de outra tabela, como numa importação já carregada no banco.
4. Os dois erros que todo mundo encontra
A mesma chave duas vezes no mesmo comando. Um INSERT com ('CAM-X', 1), ('CAM-X', 2) e DO UPDATE falhou com “ON CONFLICT DO UPDATE command cannot affect row a second time”. Aparece em importação de planilha com linha repetida. A saída é tirar as repetidas antes, com DISTINCT ON (sku), escolhendo pela ordem qual delas vale; no teste, ficou a de quantidade 2.
O ON CONFLICT numa coluna sem índice único. Na coluna qtd, o erro foi “não há nenhuma restrição de unicidade ou de exclusão que corresponda à especificação ON CONFLICT”. O ON CONFLICT só funciona sobre um índice único ou uma restrição de exclusão que o PostgreSQL consiga reconhecer pelas colunas, e numa chave composta o índice precisa ter exatamente as colunas citadas no ON CONFLICT.
Um último detalhe: o WHERE do DO UPDATE
O DO UPDATE aceita um WHERE, útil para só atualizar quando algo mudou. Quando o WHERE não bate, o comportamento é o mesmo do DO NOTHING: nenhuma linha no RETURNING, e o código que usa o WHERE precisa tratar o resultado vazio como no item 1.
Fontes: Documentação do PostgreSQL: INSERT, Documentação do PostgreSQL: sequências, Documentação do PostgreSQL: MERGE, Notas do PostgreSQL 18
Produzido com auxílio de IA e revisado pela redação.
Comentários (0)
Ainda não há comentários. Comece a conversa.




Deixe seu comentário