re:re:actable
Урок 053 минуты чтения

Что такое идемпотентность в SQL-запросах

На этой странице
Кратко

Идемпотентная операция при повторном выполнении даёт тот же результат, что и при первом. Это критично, потому что в распределённых системах повторы неизбежны: клиент повторил запрос после таймаута, очередь доставила сообщение дважды, воркер упал после записи, но до подтверждения. UPDATE users SET email = $1 WHERE id = $2 идемпотентен, а UPDATE accounts SET balance = balance - 100 или INSERT INTO payments … — нет. Идемпотентность обеспечивают уникальные ограничения на бизнес-ключ или ключ идемпотентности (Idempotency-Key от клиента, event_id из очереди) с INSERT … ON CONFLICT DO NOTHING, условные переходы состояний (WHERE status = 'pending'), запись «обработано» в той же транзакции, что и сам эффект, и IF NOT EXISTS в миграциях.

Вопрос

Что такое идемпотентность и как сделать SQL-операции идемпотентными?

Идемпотентно и нет

ОперацияИдемпотентна
UPDATE ... SET status = 'paid' WHERE id = $1Да
DELETE FROM sessions WHERE id = $1Да
UPDATE ... SET balance = balance - 100Нет
INSERT INTO orders (...) VALUES (...)Нет — второй заказ
UPDATE ... SET views = views + 1Нет

Ключ идемпотентности для API

CREATE TABLE payments (
  id              bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  idempotency_key uuid NOT NULL UNIQUE,
  order_id        bigint NOT NULL,
  amount          numeric(12, 2) NOT NULL,
  created_at      timestamptz NOT NULL DEFAULT now()
);
 
INSERT INTO payments (idempotency_key, order_id, amount)
VALUES ($1, $2, $3)
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id;
-- 0 строк → повтор: вернуть сохранённый результат первого запроса
POST /payments
Idempotency-Key: 6f1c...e2

Клиент генерирует ключ один раз на намерение пользователя и повторяет с ним запрос при сетевой ошибке.

Условный переход состояния

UPDATE orders
SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending'
RETURNING id;

Повторный вызов затронет 0 строк — оплата не применится дважды, побочные эффекты (письмо, начисление бонусов) выполняются, только если строка действительно изменилась.

Обработка событий из очереди

BEGIN;
INSERT INTO processed_events (event_id) VALUES ($1)
ON CONFLICT DO NOTHING
RETURNING event_id;          -- 0 строк → уже обработано → COMMIT и выход
 
UPDATE accounts SET balance = balance + $2 WHERE id = $3;
COMMIT;

Запись об обработке и сам эффект — в одной транзакции: если упадём после UPDATE, откатится и отметка, и событие обработается заново корректно.

Неидемпотентный инкремент → идемпотентная запись

-- ✗ при повторе просмотр посчитается дважды
UPDATE posts SET views = views + 1 WHERE id = $1;
 
-- ✓ уникальный факт, счётчик — производный
INSERT INTO post_views (post_id, visitor_id, day) VALUES ($1, $2, current_date)
ON CONFLICT DO NOTHING;

Идемпотентные миграции и скрипты

CREATE TABLE IF NOT EXISTS audit_log (...);
CREATE INDEX CONCURRENTLY IF NOT EXISTS orders_user_idx ON orders (user_id);
ALTER TABLE orders ADD COLUMN IF NOT EXISTS source text;
INSERT INTO roles (code) VALUES ('admin') ON CONFLICT (code) DO NOTHING;

Частые ошибки

  • Повтор запроса клиентом без ключа идемпотентности — двойное списание.
  • Отметка «обработано» в отдельной транзакции от эффекта.
  • Проверка «уже обработано?» через SELECT без уникального ограничения — гонка.
  • Хранить ключи идемпотентности вечно без TTL/очистки.

Что важно помнить

  • Повторы в сети и очередях неизбежны — операции должны их переживать.
  • Уникальный ключ + ON CONFLICT DO NOTHING — основной приём.
  • Эффект и отметка об обработке — в одной транзакции.

Мини-шпаргалка

  • UNIQUE (idempotency_key) + ON CONFLICT DO NOTHING.
  • UPDATE ... WHERE status = 'pending'.
  • processed_events(event_id PRIMARY KEY).
  • IF NOT EXISTS в DDL.

Документация

PostgreSQL: INSERT ON CONFLICT, Stripe: Idempotent requests.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам