Ce este UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** înseamnă "insera, sau actualiza dacă deja există." PostgreSQL implementează aceasta cu **`INSERT ... ON CONFLICT`** — insera un rând, dar dacă ar încălca o constrângere de unicitate, actualizează în schimb rândul existent (sau nu face nimic). Gestionează nevoie comună "insert-or-update" în mod atomic.

## Problema pe care o rezolvă UPSERT

```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 — insera sau actualiza

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

Dacă inserarea ar intra în conflict pe constrângerea unică `email`, Postgres actualizează rândul existent în schimb. **`EXCLUDED`** se referă la valorile pe care ai încercat să le inserezi, și poți referi și rândul existent (`users.login_count`) — permițând logică precum incrementarea unui contor.

## ON CONFLICT DO NOTHING — insera sau omite

```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` omite tacit rândurile în conflict — util pentru "insera dacă nu e prezent" fără erori.

## Un caz de utilizare comun: contoare și inserări idempotente

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

## De ce conteaza

UPSERT (`INSERT ... ON CONFLICT`) este o caracteristică importantă și practic-valoroasă a PostgreSQL care rezolvă nevoia foarte comună "insert-or-update" curat și **sigur**, deci înțelegerea ei este utilă pentru operații de date din lumea reală.

Nevoia — inserarea unui rând care ar putea deja exista (după o cheie unică) — apare constant (upserting records, contoare, inserări idempotente, sincronizarea datelor), iar alternativele naïve sunt problematice: un INSERT simplu eșuează cu o eroare dacă rândul există, și abordarea check-then-insert (SELECT apoi INSERT-or-UPDATE) are o **condiție de curse** (o altă tranzacție concurentă ar putea insera între verificarea și inserarea ta, cauzând erori sau pierderi de actualizări). `ON CONFLICT` rezolvă aceasta **atomic într-o singură declarație** — eliminând condiția de curse, care este beneficiul cheie de corectitudine pentru aplicații concurente.

Înțelegerea ambelor forme — **`DO UPDATE`** (insera sau actualiza, cu `EXCLUDED` referindu-se la valorile încercate și abilitatea de a referi rândul existent pentru logică precum incrementarea contorilor) și **`DO NOTHING`** (insera sau omite tacit) — acoperă modelele comune (upserting records, inserări idempotente, menținere contoare/agregate).

Deoarece insert-or-update este o operație frecventă și a o face corect și sigur (atomic, fără condiții de curse) conteaza pentru integritatea datelor în aplicații concurente, înțelegerea UPSERT — ceea ce rezolvă, beneficiul atomicității/condiției de curse, și formele DO UPDATE/DO NOTHING — este cunoaștere PostgreSQL valoroasă, frecvent aplicată, care oferă o soluție curată și sigură unei nevoi comune care este altfel predispusă la erori, ceea ce o face o caracteristică practică și importantă pentru aplicații reale.