`SELECT MAX(number) + 1` работает только пока запросы идут по одному. Две транзакции читают один максимум, вычисляют одинаковое следующее значение и обе пытаются сохранить его. Проверка «такого номера ещё нет» в приложении имеет ту же гонку. Последнюю линию защиты должен держать UNIQUE constraint в базе.
Перед исправлением ответьте на один вопрос: допустимы ли пропуски. Для технического уникального номера PostgreSQL sequence проста и безопасна при конкуренции, но выданное значение не возвращается после rollback. Если бизнес требует нумерацию без дыр, понадобится сериализованный счётчик и более дорогая блокировка в момент окончательного проведения документа.
Воспроизведите гонку до изменения схемы
- Откройте две независимые транзакции на тестовой базе.
- В обеих прочитайте текущий MAX для одного года или организации.
- Поставьте паузу после чтения и выполните оба INSERT.
- Зафиксируйте, какая транзакция прошла и есть ли ограничение, остановившее вторую.
- Повторите тест через реальный 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.