Inserção com atualização do registro existente
O upsert é uma gravação que insere um registro novo ou atualiza um registro existente conforme uma correspondência definida. O nome reúne update e insert. A sintaxe varia entre bancos e interfaces, por isso é preciso saber como cada implementação identifica o registro que será atualizado.
No PostgreSQL, o comando INSERT ... ON CONFLICT DO UPDATE usa um conflito de unicidade para escolher a atualização. Quando a inserção tenta repetir uma chave que deveria ser única, o banco executa a alteração especificada em DO UPDATE sobre a linha existente.
Atualizar a descrição de um código
Neste exemplo didático, a tabela produtos tem uma chave primária em codigo e uma coluna de texto chamada descricao. O comando envia o código 42 com uma nova descrição:
INSERT INTO produtos (codigo, descricao)VALUES (42, 'Teclado USB')ON CONFLICT (codigo)DO UPDATE SET descricao = EXCLUDED.descricaoRETURNING codigo, descricao;Se o código 42 ainda não existir, o banco insere a linha. Caso exista, a cláusula SET atualiza sua descrição com o valor proposto pela inserção, disponível em EXCLUDED.descricao. A cláusula RETURNING devolve o código e a descrição da linha inserida ou atualizada para você conferir o resultado.
O conflito tratado tem um alvo específico
Esse comando exige uma restrição de unicidade compatível com codigo. Sem ela, o PostgreSQL não consegue usar a coluna como alvo do conflito. Uma violação diferente, como a ausência de um campo obrigatório, ainda pode causar erro: o upsert não transforma qualquer falha de inserção em atualização.
O PostgreSQL executa essa alternativa entre inserir e atualizar de forma atômica, inclusive com gravações concorrentes, desde que não ocorra outro erro. Isso evita separar a consulta de existência da gravação, mas você ainda precisa definir quais colunas podem mudar e conceder as permissões exigidas pelo comando.
Dúvidas frequentes
Perguntas frequentes sobre upsert
- Upsert substitui a linha inteira?
- As colunas alteradas dependem da implementação. No PostgreSQL, a cláusula DO UPDATE SET especifica o que será atualizado na linha existente. Uma coluna omitida dessa cláusula não é substituída por ela.
- Qual chave o PostgreSQL usa para identificar o conflito?
- O comando precisa indicar o alvo de ON CONFLICT DO UPDATE, por colunas de um índice único compatível ou pelo nome de uma restrição de unicidade. A chave primária pode cumprir essa função.
- A permissão de inserir é suficiente?
- O comando com DO UPDATE também exige UPDATE nas colunas alteradas. As colunas lidas pelo comando exigem SELECT, inclusive as usadas para identificar o conflito ou devolver o resultado.
Para continuar
Recursos relacionados
Documentação
PostgreSQL: INSERT e ON CONFLICT
Detalha ON CONFLICT, a referência EXCLUDED e as permissões necessárias para inserir ou atualizar uma linha.
Abrir recursoSite de referência
Dev Side Studio: desenvolvimento colaborativo
No Desenvolvimento Colaborativo da Dev Side, você pode acompanhar a revisão de uma gravação e testar como o banco trata um código que já existe.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao revisar uma gravação criada com agentes, você precisa testar o cadastro de um código novo e a atualização de um código existente para conferir quais campos mudam.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.