`SELECT MAX(number) + 1` работает только пока запросы идут по одному. Две транзакции читают один максимум, вычисляют одинаковое следующее значение и обе пытаются сохранить его. Проверка «такого номера ещё нет» в приложении имеет ту же гонку. Последнюю линию защиты должен держать UNIQUE constraint в базе.

Перед исправлением ответьте на один вопрос: допустимы ли пропуски. Для технического уникального номера PostgreSQL sequence проста и безопасна при конкуренции, но выданное значение не возвращается после rollback. Если бизнес требует нумерацию без дыр, понадобится сериализованный счётчик и более дорогая блокировка в момент окончательного проведения документа.

Воспроизведите гонку до изменения схемы

  1. Откройте две независимые транзакции на тестовой базе.
  2. В обеих прочитайте текущий MAX для одного года или организации.
  3. Поставьте паузу после чтения и выполните оба INSERT.
  4. Зафиксируйте, какая транзакция прошла и есть ли ограничение, остановившее вторую.
  5. Повторите тест через реальный API с барьером перед сохранением.

Если оба INSERT проходят, данные уже не защищены. Если второй получает unique violation, инвариант сохранён, но приложение должно превратить конфликт в контролируемый повтор или понятный ответ. Не удаляйте дубли автоматически до выяснения ссылок: номер мог попасть в печатный файл или внешнюю систему.

Вариант с sequence: быстро и конкурентно

CREATE SEQUENCE contract_number_seq;

ALTER TABLE contracts
  ADD CONSTRAINT contracts_number_unique UNIQUE (number);

INSERT INTO contracts (number, customer_id, status)
VALUES (nextval('contract_number_seq'), :customer_id, 'draft');

PostgreSQL выполняет `nextval` атомарно: параллельные сессии получают разные значения. Это не означает нумерацию без пропусков. Значение не возвращается после отката, а кеш sequence и аварийное завершение тоже могут оставлять дыры. Не обещайте пользователю gapless-последовательность, если выбрана sequence.

Если номер зависит от года или компании

ТребованиеСхема уникальностиМеханизм выдачи
Один поток номеров для всехUNIQUE (number)Одна sequence
Нумерация начинается заново каждый годUNIQUE (year, number)Счётчик на строку year либо отдельная политика
Свой поток для каждой компанииUNIQUE (company_id, number)Счётчик на строку company_id
Год и компания вместеUNIQUE (company_id, year, number)Строка счётчика на пару ключей
Номер назначается при проведенииUNIQUE по финальным документамВыдача в транзакции смены статуса

Не склеивайте составной ключ в строку без ограничения на исходные колонки. Формат `2026-000123` удобен для отображения, но год и порядковый номер лучше хранить отдельно и защищать составным UNIQUE. Строковое представление формируется детерминированно после успешной выдачи номера.

Gapless-счётчик требует честной блокировки

Для строгой последовательности храните текущий номер в отдельной строке для нужного диапазона. Транзакция блокирует эту строку `SELECT ... FOR UPDATE`, увеличивает значение, создаёт финальный документ и commit. Все конкурентные выдачи этого диапазона выстраиваются в очередь. Чем длиннее транзакция, тем больше задержка.

Не держите блокировку во время генерации PDF, сетевого вызова или ожидания пользователя. Сначала атомарно проведите документ и выдайте номер, затем отправляйте событие через outbox. Если внешняя отправка не состоялась, номер остаётся связан с проведённым документом, а доставка повторяется отдельно.

UNIQUE-ошибка должна быть частью сценария

  • Ловите конкретный код нарушения уникальности, а не любую ошибку базы.
  • Повторяйте всю транзакцию, если номер вычисляется внутри неё.
  • Ограничьте число повторов и добавьте jitter для нагрузки.
  • Идемпотентный ключ запроса не позволяет пользователю создать два договора повторным кликом.
  • Мониторинг считает unique conflicts: их рост показывает скрытую гонку или неверный диапазон.

После миграции запустите параллельный тест с десятками одновременных запросов на тестовом диапазоне. Успех — нет дублей, каждый API-запрос имеет один итоговый документ, а повторы не создают новые строки. Для gapless-варианта дополнительно проверьте rollback между увеличением счётчика и INSERT.

Проверенные источники