O que é UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** significa "inserir ou atualizar se já existe". PostgreSQL implementa isso com **`INSERT ... ON CONFLICT`** — insere uma linha, mas se violasse uma restrição única, ao invés disso atualiza a linha existente (ou não faz nada). Ele trata a necessidade comum de "inserir ou atualizar" atomicamente.

## O problema que UPSERT resolve

```text
You want to insert a row, but it might already exist (by a unique key):
  ❌ a plain INSERT fails with a unique-violation error if it exists
  ❌ check-then-insert (SELECT, then INSERT or UPDATE) has a RACE CONDITION
     (another transaction could insert between your check and insert)
→ ON CONFLICT does it atomically in ONE statement (no race condition)
```

## ON CONFLICT DO UPDATE — inserir ou atualizar

```sql
INSERT INTO users (email, name, login_count)
VALUES ('ann@x.com', 'Ann', 1)
ON CONFLICT (email)                  -- if a row with this email already exists...
DO UPDATE SET                        -- ...UPDATE it instead
  name = EXCLUDED.name,              -- EXCLUDED = the values you tried to insert
  login_count = users.login_count + 1;  -- can reference the existing row too
```

Se inserir entraria em conflito na restrição única `email`, Postgres atualiza a linha existente ao invés disso. **`EXCLUDED`** refere-se aos valores que você tentou inserir, e você também pode referenciar a linha existente (`users.login_count`) — permitindo lógica como incrementar um contador.

## ON CONFLICT DO NOTHING — inserir ou pular

```sql
INSERT INTO users (email, name) VALUES ('ann@x.com', 'Ann')
ON CONFLICT (email) DO NOTHING;      -- if it exists, just skip (no error)
```

`DO NOTHING` pula silenciosamente as linhas em conflito — útil para "inserir se não presente" sem erros.

## Um caso de uso real comum: contadores e inserts idempotentes

```sql
-- track page views — insert on first view, increment on subsequent
INSERT INTO page_views (page_id, views) VALUES (5, 1)
ON CONFLICT (page_id) DO UPDATE SET views = page_views.views + 1;
```

## Por que isso importa

UPSERT (`INSERT ... ON CONFLICT`) é um recurso PostgreSQL importante e praticamente valioso que resolve a necessidade muito comum de "inserir ou atualizar" de forma limpa e **segura**, portanto compreendê-lo é útil para operações de dados do mundo real.

A necessidade — inserir uma linha que pode já existir (por uma chave única) — surge constantemente (upserting registros, contadores, inserts idempotentes, sincronização de dados), e as alternativas ingênuas são problemáticas: um INSERT simples falha com um erro se a linha existe, e a abordagem check-then-insert (SELECT depois INSERT-or-UPDATE) tem uma **condição de corrida** (outra transação concorrente poderia inserir entre sua verificação e sua inserção, causando erros ou atualizações perdidas). `ON CONFLICT` resolve isso **atomicamente em uma única instrução** — eliminando a condição de corrida, que é seu benefício principal de correção para aplicações concorrentes.

Compreender ambas as formas — **`DO UPDATE`** (inserir ou atualizar, com `EXCLUDED` referenciando os valores tentados e a capacidade de referenciar a linha existente para lógica como incrementar contadores) e **`DO NOTHING`** (inserir ou pular silenciosamente) — cobre os padrões comuns (upserting registros, inserts idempotentes, manutenção de contadores/agregados).

Como inserir-ou-atualizar é uma operação frequente e fazê-lo corretamente e com segurança (atomicamente, sem condições de corrida) importa para a integridade de dados em aplicações concorrentes, compreender UPSERT — o que resolve, o benefício de atomicidade/condição de corrida, e as formas DO UPDATE/DO NOTHING — é conhecimento PostgreSQL valioso e frequentemente aplicado que fornece uma solução limpa e segura para uma necessidade comum que é de outra forma propensa a erros, tornando-o um recurso prático e importante para aplicações reais.