Cos'è UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** significa "inserisci, oppure aggiorna se esiste già". PostgreSQL implementa questo con **`INSERT ... ON CONFLICT`** — inserisce una riga, ma se violerebbe un vincolo di unicità, invece aggiorna la riga esistente (oppure non fa nulla). Gestisce l'esigenza comune di "inserisci-o-aggiorna" in modo atomico.

## Perché è importante

```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 — inserisci o aggiorna

```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 l'inserimento entrasse in conflitto con il vincolo di unicità di `email`, Postgres aggiorna la riga esistente. **`EXCLUDED`** si riferisce ai valori che hai tentato di inserire, e puoi fare riferimento anche alla riga esistente (`users.login_count`) — abilitando logica come incrementare un contatore.

## ON CONFLICT DO NOTHING — inserisci o salta

```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` salta silenziosamente le righe in conflitto — utile per "inserisci se non presente" senza errori.

## Un use case comune: contatori e inserimenti idempotenti

```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;
```

## Perché è importante

UPSERT (`INSERT ... ON CONFLICT`) è una funzionalità PostgreSQL importante e praticamente preziosa che risolve l'esigenza molto comune di "inserisci-o-aggiorna" in modo pulito e **sicuro**, quindi comprenderla è utile per operazioni di dati nel mondo reale.

L'esigenza — inserire una riga che potrebbe già esistere (per una chiave univoca) — sorge costantemente (upsert di record, contatori, inserimenti idempotenti, sincronizzazione di dati), e le alternative naive sono problematiche: un INSERT semplice fallisce con un errore se la riga esiste, e l'approccio check-then-insert (SELECT poi INSERT-o-UPDATE) ha una **race condition** (un'altra transazione concorrente potrebbe inserire tra il tuo controllo e il tuo inserimento, causando errori o perdita di aggiornamenti). `ON CONFLICT` risolve questo **atomicamente in un'unica istruzione** — eliminando la race condition, che è il suo beneficio chiave di correttezza per applicazioni concorrenti.

Comprendere entrambe le forme — **`DO UPDATE`** (inserisci o aggiorna, con `EXCLUDED` che fa riferimento ai valori tentati e la capacità di fare riferimento alla riga esistente per logica come incrementare contatori) e **`DO NOTHING`** (inserisci o salta silenziosamente) — copre i pattern comuni (upsert di record, inserimenti idempotenti, mantenimento di contatori/aggregati).

Poiché l'inserimento-o-aggiornamento è un'operazione frequente e farlo correttamente e in sicurezza (atomicamente, senza race condition) è importante per l'integrità dei dati in applicazioni concorrenti, comprendere UPSERT — cosa risolve, il beneficio di atomicità/race-condition, e le forme DO UPDATE/DO NOTHING — è una conoscenza PostgreSQL preziosa e frequentemente applicata che fornisce una soluzione pulita e sicura a un'esigenza comune che altrimenti è soggetta a errori, rendendola una funzionalità pratica e importante per applicazioni reali.