Содержание
- Что такое идемпотентность
- Где ломается без идемпотентности
- Принцип работы идемпотентной загрузки
- Upsert по естественному ключу
- Перезапись партиции
- Ключ идемпотентности в API
- Идемпотентность и exactly-once
- Подводные камни
- Когда нужна идемпотентность, а когда нет
- Повторный запуск загрузки в PostgreSQL на практике
- Повторная загрузка партиции тремя способами
- Ключ идемпотентности для POST /payments
- Заключение
- Референсные ссылки
Идемпотентность (idempotency) это свойство операции, при котором её повторный запуск не меняет итог. Сколько раз ни выполни идемпотентную операцию, состояние системы окажется таким же, как после первого успешного выполнения. В инженерии данных от этого свойства зависит, переживёт ли конвейер обычный ретрай. Задача, которую планировщик перезапустил после сбоя, не должна удваивать строки в витрине, а запрос на оплату, повторённый клиентом по таймауту, не должен списать деньги второй раз.
Что такое идемпотентность
Термин пришёл из алгебры. Функция идемпотентна, если f(f(x)) = f(x), то есть повторное применение к собственному результату ничего не меняет. Модуль числа идемпотентен, присваивание x = 5 тоже, а инкремент x = x + 1 нет, потому что каждый вызов сдвигает значение.
В HTTP идемпотентность закреплена в спецификации семантики протокола RFC 9110, которую выпускает IETF (Internet Engineering Task Force, организация, стандартизирующая интернет-протоколы). Методы GET, HEAD, OPTIONS, TRACE, PUT и DELETE там считаются идемпотентными, а POST нет. Метод PATCH описан отдельно, в RFC 5789, и идемпотентным тоже не считается. Повторный PUT кладёт по адресу тот же ресурс, повторный POST создаёт ещё один заказ.
В данных формулировка практичнее. Документация Apache Airflow требует, чтобы задача давала одинаковый результат при каждом перезапуске, и сравнивает задачи с транзакциями базы данных. Важная оговорка касается того, что именно должно совпадать. Идемпотентен итог, а не каждое промежуточное действие. Повторная загрузка может заново прочитать файл, переписать строки и сгенерировать журнал изменений, и это допустимо, пока таблица после неё та же самая.
Где ломается без идемпотентности
Повторы в распределённой системе неизбежны. Сеть может оборваться после того, как сервер выполнил операцию, но до того, как ответ дошёл до клиента. Клиент не знает, прошла операция или нет, и единственный безопасный для него ход это повторить. Поэтому доставка с повтором до подтверждения, режим «хотя бы один раз» (at-least-once), встречается в брокерах и планировщиках сплошь и рядом. Airflow тоже повторяет упавшую задачу, если у неё задано число попыток, и позволяет инженеру перезапустить любую задачу руками.
В демо к этой статье наивная загрузка пяти заказов упала после третьей строки, а ретрай дописал все пять заново. В таблице оказалось 8 строк вместо 5, сумма выросла с 6715.75 до 9256.25, а ручной перезапуск довёл её до 15972.00. При этом count(DISTINCT order_id) все три раза показывал 5, и проверка уникальности по ключу дублей бы не заметила.
Чтобы повтор стал безопасным, операции нужны три составляющие.
- Ключ операции. Идентификатор, по которому повтор узнаётся как повтор, например order_id, дата партиции или UUID в заголовке запроса.
- Арбитр уникальности. Механизм, который атомарно решает, видели этот ключ или нет, обычно первичный ключ или уникальный индекс.
- Сохранённый результат. Уже записанная строка или сохранённый ответ, который повтор получает вместо нового выполнения.
Без любой из трёх частей защита от дублей держится на везении.
Принцип работы идемпотентной загрузки
На практике встречаются три приёма. Два из них относятся к загрузке таблиц, третий к API.
Upsert по естественному ключу
Upsert (от update и insert) вставляет строку, если её нет, и обновляет, если она уже есть. В PostgreSQL это команда INSERT … ON CONFLICT, и документация INSERT в PostgreSQL гарантирует атомарный исход «вставка или обновление» даже при высокой конкуренции. Арбитром служит уникальный индекс или ограничение, вариант DO NOTHING пропускает конфликтующую строку, а DO UPDATE обновляет существующую, и новые значения доступны через псевдотаблицу excluded. Приём требует естественного ключа, который не меняется от запуска к запуску. Суррогатный автоинкремент для этого не годится, потому что каждый повтор получает новое значение.
Перезапись партиции
Второй приём удаляет всё, что относится к загружаемому интервалу, и пишет интервал заново. В PostgreSQL это DELETE и INSERT в одной транзакции, в Apache Spark и Apache Hive, движках SQL поверх озера данных, это INSERT OVERWRITE по партиции. Если задача упала посередине, транзакция откатывается и в таблице не остаётся обрывка. Airflow советует строить задачи так же. Задача читает и пишет конкретную партицию по data_interval_start, началу интервала данных, который Airflow передаёт каждому запуску DAG, а не «последние данные», и не использовать now() в критичной логике. Тогда перезапуск задачи за 1 ноября через неделю даст тот же результат, что и в ночь на 2 ноября.
Ключ идемпотентности в API
Для неидемпотентных по природе запросов вроде POST IETF готовит отдельный заголовок Idempotency-Key. Черновик draft-ietf-httpapi-idempotency-key-header в версии 08 обновлён 22 октября 2026 года и пока остаётся Internet-Draft, а не RFC. Клиент генерирует ключ, черновик рекомендует UUID, и шлёт его с каждой попыткой одной и той же операции. Сервер хранит ключ, отпечаток тела запроса (fingerprint) и готовый ответ.
Первый запрос с новым ключом обрабатывается штатно. Повтор после завершения получает ответ, согласованный с исходным, а повтор во время обработки получает 409 Conflict. Тот же ключ с другим телом запроса отклоняется кодом 422, отсутствие обязательного ключа кодом 400. Как тот же принцип выглядит в задачах конвейера, разобрано в статье об атомарности и идемпотентности задач Airflow.
Идемпотентность и exactly-once
Идемпотентность часто путают с семантикой «ровно один раз» (exactly-once), хотя это ответы на разные вопросы. Семантики доставки описывают, сколько раз сообщение дойдёт до получателя. Идемпотентность описывает, что произойдёт, если оно дойдёт дважды.
| Свойство | Что гарантирует | Чем обеспечивается | Чем платим |
|---|---|---|---|
| At-most-once | Не больше одной доставки, потери возможны | Отказ от повторов | Потерянные данные |
| At-least-once | Доставка без потерь, дубли возможны | Повторы до подтверждения | Дубли у получателя |
| Exactly-once | Эффект ровно одной обработки | Повторы плюс дедупликация или транзакции на стороне системы | Работает только внутри границ одной системы |
| Идемпотентность | Повтор не меняет итог | Ключ операции, арбитр уникальности, сохранённый результат | Хранилище ключей и проверка на пути записи |
Как следствие, exactly-once в прикладном смысле обычно собирается из двух частей, доставки at-least-once и идемпотентного получателя. Гарантии брокера заканчиваются на его границе. Если консьюмер пишет в PostgreSQL или вызывает платёжный API, дубли на этой стороне отсекает уже идемпотентность самой записи.
Подводные камни
Прогон демо, документация PostgreSQL и Airflow и черновик IETF показывают несколько мест, где идемпотентность ломается незаметно.
- Время и случайность. Функция now() или случайный UUID внутри загрузки дают разный результат на каждом повторе, поэтому дата партиции берётся из параметров запуска.
- Побочные эффекты. Upsert без условия WHERE … IS DISTINCT FROM на повторе затронул все 5 строк. Итог тот же, но каждая строка переписана новой версией, а значит лишние записи в журнале упреждающей записи (Write-Ahead Log, WAL), сработавшие триггеры и 5 событий UPDATE в захвате изменений (Change Data Capture, CDC).
- Дубли внутри одной пачки. Одна команда ON CONFLICT DO UPDATE не может обновить строку дважды, и PostgreSQL отвечает ошибкой CardinalityViolation. Входную пачку нужно дедуплицировать заранее.
- Зависший ключ. Если операция упала после того, как ключ занят, запись остаётся в статусе processing, и все повторы получают 409. Нужен срок жизни ключа или сброс зависших записей, черновик IETF оставляет этот срок на политику ресурса.
- Ответ повтора не побайтный. Демо хранит ответ в jsonb, а jsonb не сохраняет порядок ключей, поэтому ответ 200 отличается от исходного 201 порядком полей. Побайтное совпадение даёт хранение в text или json, оба типа сохраняют входной текст как есть.
Четыре ловушки из пяти проявляются только на повторе, поэтому одиночный прогон задачи их не покажет.
Когда нужна идемпотентность, а когда нет
Идемпотентность нужна любой операции, которую кто-то может повторить. Это пакетные задачи под планировщиком, консьюмеры очередей, обработчики вебхуков, API создания заказов и платежей, скрипты миграций. Если ретрай настроен хотя бы где-то по цепочке, повтор однажды случится, и вопрос только в том, увидите вы дубли сразу или через месяц в отчёте.
Отдельно заботиться о ней не нужно для операций чтения и для разовых аналитических запросов, которые ничего не пишут. Кроме того, у идемпотентности есть цена. Таблица ключей растёт, уникальный индекс замедляет вставку, а upsert берёт блокировку на строку. Для журнала событий, где у каждого события уже есть собственный уникальный идентификатор, достаточно уникального ограничения по нему, без отдельной таблицы ключей. Проектировать конвейеры, которые спокойно переживают ретраи и догрузку истории за прошлые даты (backfill), учат на курсе по Apache Airflow для инженеров данных.
Повторный запуск загрузки в PostgreSQL на практике
По традиции весь код используемый в статье выкладываем на наш GitHub репозиторий
Стенд собран из PostgreSQL 18.6 в Docker, Python 3.12 и драйвера psycopg 3.3.7. Контейнер описан в файле docker-compose.yml.
# postgres 18.6 в Docker, стенд для статьи про идемпотентность
services:
postgres:
image: postgres:18.6
container_name: idempotency-postgres
mem_limit: 1g
environment:
POSTGRES_USER: demo
POSTGRES_PASSWORD: demo
POSTGRES_DB: idem
ports:
- "127.0.0.1:55432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U demo -d idem"]
interval: 2s
timeout: 3s
retries: 30
Команды запуска взяты из README.md репозитория.
# postgres 18.6 + psycopg 3.3.7, команды из README.md, прогнано на стенде 2026-11-03 # поднять Postgres и дождаться healthcheck docker compose up -d --wait # окружение Python с закреплённой версией драйвера python3 -m venv .venv && .venv/bin/pip install "psycopg[binary]==3.3.7" # два демо по очереди .venv/bin/python partition_reload.py .venv/bin/python idempotency_key_store.py # убрать контейнер вместе с данными docker compose down -v
Повторная загрузка партиции тремя способами
Скрипт partition_reload.py грузит пять заказов за 2026-11-01 в три таблицы. Первая попытка падает после третьей строки, вторая играет роль ретрая, третья ручного перезапуска.
# postgres 18.6 + psycopg 3.3.7, прогнано на стенде 2026-11-03
"""Повторная загрузка одной партиции тремя способами.
Задача грузит продажи за день. Первая попытка падает на середине, планировщик
делает ретрай, потом задачу ещё раз перезапускают руками. Смотрим, что остаётся
в целевой таблице при наивном INSERT, при перезаписи партиции и при upsert.
"""
import os
import psycopg
DSN = os.environ.get("PG_DSN", "postgresql://demo:demo@127.0.0.1:55432/idem")
DAY = "2026-11-01"
# Источник: пять заказов за день. order_id это естественный ключ строки.
BATCH = [
(101, DAY, 1200.00),
(102, DAY, 350.50),
(103, DAY, 990.00),
(104, DAY, 75.25),
(105, DAY, 4100.00),
]
class TaskCrash(Exception):
"""Имитация падения задачи посреди загрузки."""
def setup(conn):
with conn.cursor() as cur:
for name in ("sales_naive", "sales_overwrite", "sales_upsert"):
cur.execute(f"DROP TABLE IF EXISTS {name}")
# первичный ключ есть только у таблицы для upsert: он и будет арбитром
pk = "PRIMARY KEY" if name == "sales_upsert" else ""
cur.execute(
f"CREATE TABLE {name} (order_id int {pk}, sale_date date, amount numeric(12,2))"
)
conn.commit()
def load_naive(conn, crash_after=None):
"""INSERT строка за строкой с автокоммитом, как пишет наивный скрипт."""
with conn.cursor() as cur:
for i, row in enumerate(BATCH, 1):
cur.execute("INSERT INTO sales_naive VALUES (%s, %s, %s)", row)
conn.commit()
if crash_after and i == crash_after:
raise TaskCrash(f"упали после {i} строк")
def load_overwrite(conn, crash_after=None):
"""Перезапись партиции: DELETE за день и INSERT в одной транзакции."""
try:
with conn.cursor() as cur:
cur.execute("DELETE FROM sales_overwrite WHERE sale_date = %s", (DAY,))
for i, row in enumerate(BATCH, 1):
cur.execute("INSERT INTO sales_overwrite VALUES (%s, %s, %s)", row)
if crash_after and i == crash_after:
raise TaskCrash(f"упали после {i} строк")
conn.commit()
except TaskCrash:
conn.rollback() # транзакция не дошла до COMMIT, в таблице ничего не осталось
raise
def load_upsert(conn, only_changed=True):
"""INSERT ... ON CONFLICT по первичному ключу. Возвращает число затронутых строк."""
sql = """
INSERT INTO sales_upsert AS t (order_id, sale_date, amount)
VALUES (%s, %s, %s)
ON CONFLICT (order_id) DO UPDATE
SET sale_date = excluded.sale_date, amount = excluded.amount
"""
if only_changed:
# без этого условия повтор переписывает каждую строку, хоть и теми же значениями
sql += " WHERE (t.sale_date, t.amount) IS DISTINCT FROM (excluded.sale_date, excluded.amount)"
touched = 0
with conn.cursor() as cur:
for row in BATCH:
cur.execute(sql, row)
touched += cur.rowcount
conn.commit()
return touched
def state(conn, table):
with conn.cursor() as cur:
cur.execute(f"SELECT count(*), count(DISTINCT order_id), coalesce(sum(amount), 0) FROM {table}")
rows, uniq, total = cur.fetchone()
return f"строк={rows} уникальных order_id={uniq} сумма={total}"
def run_attempts(conn, name, attempt):
"""Попытка 1 падает после 3 строк, попытка 2 это ретрай, попытка 3 ручной перезапуск."""
print(f"\n--- {name} ---")
for n, crash in ((1, 3), (2, None), (3, None)):
try:
attempt(conn, crash)
note = "успех"
except TaskCrash as e:
note = str(e)
print(f"попытка {n}: {note:<20} {state(conn, name)}")
def main():
with psycopg.connect(DSN) as conn:
print("server_version:", conn.info.parameter_status("server_version"))
print("psycopg:", psycopg.__version__)
setup(conn)
run_attempts(conn, "sales_naive", load_naive)
run_attempts(conn, "sales_overwrite", load_overwrite)
# upsert работает построчно по ключу, поэтому падение на середине ему не страшно,
# повтор просто дописывает недостающее и не трогает уже загруженное
print("\n--- sales_upsert ---")
for n, only_changed in ((1, True), (2, True), (3, False)):
touched = load_upsert(conn, only_changed)
mode = "WHERE IS DISTINCT FROM" if only_changed else "без WHERE"
print(f"попытка {n} ({mode}): затронуто строк={touched} {state(conn, 'sales_upsert')}")
# граница upsert: одна команда не может обновить одну строку дважды
print("\n--- дубль ключа внутри одной пачки ---")
try:
with conn.cursor() as cur:
cur.execute(
"""INSERT INTO sales_upsert VALUES (106, %s, 10), (106, %s, 20)
ON CONFLICT (order_id) DO UPDATE SET amount = excluded.amount""",
(DAY, DAY),
)
conn.commit()
except psycopg.Error as e:
conn.rollback()
print(f"{type(e).__name__}: {e.diag.message_primary}")
print(f"hint: {e.diag.message_hint}")
if __name__ == "__main__":
main()
Вывод прогона на стенде.
server_version: 18.6 (Debian 18.6-1.pgdg13+2) psycopg: 3.3.7 --- sales_naive --- попытка 1: упали после 3 строк строк=3 уникальных order_id=3 сумма=2540.50 попытка 2: успех строк=8 уникальных order_id=5 сумма=9256.25 попытка 3: успех строк=13 уникальных order_id=5 сумма=15972.00 --- sales_overwrite --- попытка 1: упали после 3 строк строк=0 уникальных order_id=0 сумма=0 попытка 2: успех строк=5 уникальных order_id=5 сумма=6715.75 попытка 3: успех строк=5 уникальных order_id=5 сумма=6715.75 --- sales_upsert --- попытка 1 (WHERE IS DISTINCT FROM): затронуто строк=5 строк=5 уникальных order_id=5 сумма=6715.75 попытка 2 (WHERE IS DISTINCT FROM): затронуто строк=0 строк=5 уникальных order_id=5 сумма=6715.75 попытка 3 (без WHERE): затронуто строк=5 строк=5 уникальных order_id=5 сумма=6715.75 --- дубль ключа внутри одной пачки --- CardinalityViolation: ON CONFLICT DO UPDATE command cannot affect row a second time hint: Ensure that no rows proposed for insertion within the same command have duplicate constrained values.
Наивный INSERT портит данные уже на автоматическом ретрае, до всякого ручного вмешательства. Перезапись партиции после падения оставляет пустую таблицу, а не три строки, потому что транзакция откатилась целиком, и дальше каждый запуск даёт ровно 5 строк на 6715.75. Upsert с условием на второй попытке не затронул ни одной строки, а без условия переписал все пять, хотя итог в таблице одинаковый.
Ключ идемпотентности для POST /payments
Скрипт idempotency_key_store.py реализует обработчик платежа с таблицей ключей. Ключ занимается отдельной вставкой с ON CONFLICT DO NOTHING, чтобы параллельный повтор сразу его увидел, а платёж и сохранённый ответ пишутся одной транзакцией.
# postgres 18.6 + psycopg 3.3.7, прогнано на стенде 2026-11-03; коды ответов по draft-ietf-httpapi-idempotency-key-header-08
"""Хранилище ключей идемпотентности для обработчика POST /payments.
Клиент шлёт ключ в заголовке Idempotency-Key. Сервер запоминает ключ, отпечаток
тела запроса и готовый ответ. Повтор с тем же ключом получает сохранённый ответ,
а платёж второй раз не создаётся.
"""
import hashlib
import json
import os
import threading
import time
import uuid
import psycopg
from psycopg.types.json import Jsonb
DSN = os.environ.get("PG_DSN", "postgresql://demo:demo@127.0.0.1:55432/idem")
WORK_SECONDS = 1.0 # сколько «идёт» списание у платёжного шлюза
def setup():
with psycopg.connect(DSN) as conn:
conn.execute("DROP TABLE IF EXISTS payments, idempotency_keys")
conn.execute(
"""CREATE TABLE payments (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
account text, amount numeric(12,2))"""
)
conn.execute(
"""CREATE TABLE idempotency_keys (
key text PRIMARY KEY, -- арбитр: второй такой же ключ не вставится
fingerprint text NOT NULL, -- sha256 тела запроса
status text NOT NULL, -- processing | done
response jsonb,
created_at timestamptz NOT NULL DEFAULT now())"""
)
def fingerprint(payload):
return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()[:16]
def create_payment(conn, payload):
"""Сама неидемпотентная операция: каждый вызов даёт новую строку."""
time.sleep(WORK_SECONDS)
row = conn.execute(
"INSERT INTO payments (account, amount) VALUES (%s, %s) RETURNING id",
(payload["account"], payload["amount"]),
).fetchone()
return {"payment_id": row[0], "status": "charged"}
def handle(key, payload):
"""Обработчик POST /payments. Возвращает (код HTTP, тело ответа)."""
if key is None:
return 400, {"error": "Idempotency-Key обязателен"}
fp = fingerprint(payload)
with psycopg.connect(DSN, autocommit=True) as conn:
# шаг 1: занять ключ. Отдельный коммит, чтобы параллельный запрос сразу его увидел
claimed = conn.execute(
"""INSERT INTO idempotency_keys (key, fingerprint, status)
VALUES (%s, %s, 'processing')
ON CONFLICT (key) DO NOTHING RETURNING key""",
(key, fp),
).fetchone()
if claimed is None:
# ключ уже есть: решаем по сохранённой записи
saved_fp, status, response = conn.execute(
"SELECT fingerprint, status, response FROM idempotency_keys WHERE key = %s",
(key,),
).fetchone()
if saved_fp != fp:
return 422, {"error": "ключ уже использован с другим телом запроса"}
if status == "processing":
return 409, {"error": "запрос с этим ключом ещё обрабатывается"}
return 200, response # повтор: отдаём тот же ответ, ничего не делаем
# шаг 2: ключ наш, выполняем операцию и сохраняем ответ одной транзакцией
with conn.transaction():
response = create_payment(conn, payload)
conn.execute(
"UPDATE idempotency_keys SET status = 'done', response = %s WHERE key = %s",
(Jsonb(response), key),
)
return 201, response
def handle_without_keys(payload):
"""Тот же обработчик без хранилища ключей, для сравнения."""
with psycopg.connect(DSN, autocommit=True) as conn:
return 201, create_payment(conn, payload)
def count_payments():
with psycopg.connect(DSN) as conn:
return conn.execute("SELECT count(*), coalesce(sum(amount), 0) FROM payments").fetchone()
def show(label, result):
code, body = result
print(f"{label:<46} -> {code} {json.dumps(body, ensure_ascii=False)}")
def main():
setup()
payload = {"account": "ACC-42", "amount": 1500}
print("--- без ключа идемпотентности: клиент не дождался ответа и повторил ---")
show("POST #1", handle_without_keys(payload))
show("POST #2 (ретрай)", handle_without_keys(payload))
print("платежей, сумма:", count_payments())
setup()
key = str(uuid.uuid4()) # клиент генерирует ключ один раз на операцию
print(f"\n--- с ключом {key[:8]}...: тот же сценарий плюс гонка ---")
# первый запрос и его ретрай уходят почти одновременно
results = {}
t1 = threading.Thread(target=lambda: results.__setitem__("first", handle(key, payload)))
t1.start()
time.sleep(0.2)
show("POST #2 пока #1 ещё в работе", handle(key, payload))
t1.join()
show("POST #1", results["first"])
show("POST #3 после завершения", handle(key, payload))
show("POST #4 тот же ключ, amount=9999", handle(key, {**payload, "amount": 9999}))
show("POST #5 без заголовка", handle(None, payload))
print("платежей, сумма:", count_payments())
if __name__ == "__main__":
main()
Вывод прогона на стенде, UUID ключа у каждого запуска свой.
--- без ключа идемпотентности: клиент не дождался ответа и повторил ---
POST #1 -> 201 {"payment_id": 1, "status": "charged"}
POST #2 (ретрай) -> 201 {"payment_id": 2, "status": "charged"}
платежей, сумма: (2, Decimal('3000.00'))
--- с ключом 7ce1d9b7...: тот же сценарий плюс гонка ---
POST #2 пока #1 ещё в работе -> 409 {"error": "запрос с этим ключом ещё обрабатывается"}
POST #1 -> 201 {"payment_id": 1, "status": "charged"}
POST #3 после завершения -> 200 {"status": "charged", "payment_id": 1}
POST #4 тот же ключ, amount=9999 -> 422 {"error": "ключ уже использован с другим телом запроса"}
POST #5 без заголовка -> 400 {"error": "Idempotency-Key обязателен"}
платежей, сумма: (1, Decimal('1500.00'))
Без ключа ретрай создал второй платёж, и клиент заплатил 3000.00 вместо 1500.00. С ключом платёж один, повтор во время обработки получил 409, а повтор после неё тот же payment_id с кодом 200. Порядок полей в ответе 200 другой, потому что ответ лежит в jsonb. В демо намеренно не обработан случай, когда create_payment падает, и ключ навсегда остаётся в processing. В рабочем коде для этого нужен срок жизни ключа.
Заключение
Идемпотентность превращает ретрай из угрозы в рутину. В данных она достигается upsert по естественному ключу или атомарной перезаписью партиции, в API ключом Idempotency-Key с таблицей сохранённых ответов. Прогон показал, что наивный INSERT ломается уже на первом автоматическом повторе и что дубли при этом не видны по count(DISTINCT). Поэтому проверять задачу стоит самым простым способом, а именно запустить её дважды и сравнить таблицу.


