Czym jest UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** oznacza "wstaw lub zaktualizuj, jeśli już istnieje". PostgreSQL realizuje to za pomocą **`INSERT ... ON CONFLICT`** — wstaw wiersz, ale jeśli naruszałby on ograniczenie unikalności, zamiast tego zaktualizuj istniejący wiersz (albo nie rób nic). Obsługuje to atomowo powszechną potrzebę typu "wstaw lub zaktualizuj".

## Problem, który rozwiązuje 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 — wstaw lub zaktualizuj

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

Jeśli wstawienie spowodowałoby konflikt z ograniczeniem unikalności `email`, Postgres zaktualizuje zamiast tego istniejący wiersz. **`EXCLUDED`** odnosi się do wartości, które próbowano wstawić, a możesz też odwołać się do istniejącego wiersza (`users.login_count`) — co umożliwia logikę taką jak inkrementacja licznika.

## ON CONFLICT DO NOTHING — wstaw lub pomiń

```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` po cichu pomija wiersze powodujące konflikt — przydatne, gdy chcemy "wstawić, jeśli nie istnieje" bez błędów.

## Częste zastosowanie w praktyce: liczniki i idempotentne wstawienia

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

## Dlaczego to ważne

UPSERT (`INSERT ... ON CONFLICT`) to istotna, praktycznie wartościowa funkcja PostgreSQL, która czysto i **bezpiecznie** rozwiązuje bardzo częstą potrzebę typu "wstaw lub zaktualizuj", więc jej zrozumienie jest przydatne w rzeczywistych operacjach na danych.

Potrzeba — wstawienie wiersza, który może już istnieć (według klucza unikalnego) — pojawia się nieustannie (upsertowanie rekordów, liczniki, idempotentne wstawienia, synchronizacja danych), a naiwne alternatywy są problematyczne: zwykły INSERT kończy się błędem, jeśli wiersz istnieje, a podejście typu sprawdź-potem-wstaw (SELECT, a następnie INSERT lub UPDATE) ma **sytuację wyścigu** (inna współbieżna transakcja mogłaby wstawić wiersz między twoim sprawdzeniem a wstawieniem, powodując błędy lub utracone aktualizacje). `ON CONFLICT` rozwiązuje to **atomowo w pojedynczej instrukcji** — eliminując sytuację wyścigu, co jest jego kluczową zaletą pod względem poprawności w aplikacjach współbieżnych.

Zrozumienie obu form — **`DO UPDATE`** (wstaw lub zaktualizuj, gdzie `EXCLUDED` odnosi się do próbowanych wartości oraz z możliwością odwołania się do istniejącego wiersza dla logiki takiej jak inkrementacja liczników) i **`DO NOTHING`** (wstaw lub po cichu pomiń) — obejmuje powszechne wzorce (upsertowanie rekordów, idempotentne wstawienia, utrzymywanie liczników/agregatów).

Ponieważ wstawianie-lub-aktualizacja to częsta operacja, a wykonanie jej poprawnie i bezpiecznie (atomowo, bez sytuacji wyścigu) ma znaczenie dla integralności danych w aplikacjach współbieżnych, zrozumienie UPSERT — co rozwiązuje, korzyść w zakresie atomowości/sytuacji wyścigu oraz formy DO UPDATE/DO NOTHING — to wartościowa, często stosowana wiedza o PostgreSQL, która zapewnia czyste, bezpieczne rozwiązanie powszechnej potrzeby, w przeciwnym razie podatnej na błędy, czyniąc z niej praktyczną, istotną funkcję dla rzeczywistych aplikacji.