Что такое UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** означает «вставить или обновить, если уже существует». PostgreSQL реализует это с помощью **`INSERT ... ON CONFLICT`** — вставить строку, но если это нарушит ограничение уникальности, вместо этого обновить существующую строку (или ничего не делать). Это атомарно решает распространённую задачу «вставить или обновить».

## Проблема, которую решает 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 — вставить или обновить

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

Если вставка конфликтует с ограничением уникальности `email`, Postgres обновляет существующую строку. **`EXCLUDED`** ссылается на значения, которые вы пытались вставить, и вы также можете ссылаться на существующую строку (`users.login_count`) — это позволяет реализовать логику типа увеличения счётчика.

## ON CONFLICT DO NOTHING — вставить или пропустить

```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` молча пропускает конфликтующие строки — полезно для «вставить, если отсутствует» без ошибок.

## Частый практический пример: счётчики и идемпотентные вставки

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

## Почему это важно

UPSERT (`INSERT ... ON CONFLICT`) — это важная и практичная функция PostgreSQL, которая чистым и **безопасным** способом решает очень распространённую задачу «вставить или обновить», поэтому её понимание полезно для работы с данными в реальных приложениях.

Нужда — вставить строку, которая может уже существовать (по уникальному ключу) — возникает постоянно (обновление записей, счётчики, идемпотентные вставки, синхронизация данных), а наивные альтернативы имеют проблемы: обычная INSERT падает с ошибкой, если строка существует, а подход проверить-потом-вставить (SELECT затем INSERT-или-UPDATE) содержит **race condition** (другая конкурирующая транзакция может вставить между вашей проверкой и вставкой, вызвав ошибки или потерю данных). `ON CONFLICT` решает это **атомарно в одном выражении** — устраняя race condition, что является его ключевым преимуществом для корректности в конкурирующих приложениях.

Понимание обеих форм — **`DO UPDATE`** (вставить или обновить, с `EXCLUDED`, ссылающимся на попытанные значения, и способностью ссылаться на существующую строку для логики типа увеличения счётчика) и **`DO NOTHING`** (вставить или молча пропустить) — охватывает распространённые паттерны (обновление записей, идемпотентные вставки, ведение счётчиков и агрегатов).

Поскольку вставить-или-обновить — частая операция, и делать это правильно и безопасно (атомарно, без race conditions) важно для целостности данных в конкурирующих приложениях, понимание UPSERT — что он решает, преимущество атомарности и отсутствия race conditions, и формы DO UPDATE/DO NOTHING — это ценное, часто применяемое знание PostgreSQL, которое предоставляет чистое, безопасное решение для распространённой нужды, которая иначе подвержена ошибкам, делая это практичной и важной функцией для реальных приложений.