Что такое идемпотентность в 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.