Ошибка почти никогда не живёт в одной команде «обнулить счётчик». Обычно один процесс уже считает новый год, второй ещё использует старый часовой пояс, а третий держит закешированное значение sequence. Начните с двух конфликтующих документов: выпишите их тип, филиал, дату выдачи, часовой пояс и момент записи в UTC.

Если номер имеет юридическое или бухгалтерское значение, сначала согласуйте правила серии с владельцем процесса. Техническая схема обеспечивает уникальность и воспроизводимость, но не определяет, обязан ли ряд быть непрерывным: это требование зависит от документа и применимых правил.

Серия — это данные, а не ночная задача

Часть ключаПримерЗачем хранить
Тип документаinvoiceакты и счета могут иметь разные ряды
Бизнес-год2027отдельная последовательность каждого года
Филиал/организацияmskесли нумерация разделена организационно
Следующий номер42единственная изменяемая величина
Часовой поясEurope/Moscowодинаковая граница года у всех узлов

Новая строка `(invoice, 2027, msk)` сама начинает ряд нового года. Ничего глобально перезапускать в полночь не нужно. Если филиалы делят общую серию, филиал убирают из ключа; если у каждой организации свой ряд, добавляют стабильный идентификатор организации.

Год берётся из даты документа

Не используйте локальное `now()` приложения без явного правила. Пользователь может оформить документ задним числом, очередь — завершить его после полуночи, а сервер — работать в UTC. Выберите поле `issued_at`, преобразуйте его в утверждённый бизнес-часовой пояс и один раз получите `series_year`. Это значение сохраняется в документе и больше не пересчитывается из текущего времени.

series_year = year(issued_at AT TIME ZONE 'Europe/Moscow')
series_key  = (document_type, series_year, legal_entity_id)

UNIQUE (document_type, series_year, legal_entity_id, number)

Номер и документ фиксируются одной транзакцией

  1. Начать транзакцию и получить или создать строку нужной серии.
  2. Заблокировать строку счётчика `FOR UPDATE` либо выполнить атомарный `UPDATE ... RETURNING`.
  3. Получить номер и сразу вставить документ с тем же series key.
  4. Зафиксировать транзакцию; при ошибке откатить и счётчик, и документ.
  5. Вернуть клиенту уже сохранённый номер, а не предварительный прогноз.

На стороне базы оставьте уникальное ограничение. Оно не заменяет правильную транзакцию, но превращает скрытый дубль в видимую ошибку. Повтор API должен иметь idempotency key: иначе два одинаковых запроса смогут законно занять два разных номера.

Почему простой RESTART опасен

PostgreSQL sequence удобна для глобальных уникальных идентификаторов, но её значения не откатываются вместе с неуспешной транзакцией, поэтому возможны пропуски. `ALTER SEQUENCE ... RESTART` меняет текущее состояние и синхронизируется с конкурентными обращениями, однако сброс общей sequence не создаёт отдельные ряды по году и не исправляет неверный выбор года приложением.

  • Не вызывайте `setval(1)` из нескольких экземпляров приложения.
  • Не считайте `MAX(number)+1` без блокировки: два запроса увидят один максимум.
  • Не удаляйте старую строку счётчика — она объясняет историческую серию.
  • Не обещайте отсутствие пропусков, если используете обычную sequence.
  • Не меняйте уже выданный номер автоматически после смены часового пояса.

Пограничный тест проводится в четырёх сценариях

СценарийОжиданиеЧто ловим
31 декабря 23:59:59номер старой серииранний сброс
1 января 00:00:00первый номер новой серииневерный timezone
два параллельных запросаразные номерагонка
ошибка после выдачисогласованный rollback/retryпотерянный документ
документ задним числомсерия даты документазависимость от now

Уже возникшие дубли исправляют отдельно

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

Исправление готово, когда год вычисляется одинаково на всех узлах, параллельный тест не даёт дублей, а повтор одного запроса возвращает тот же документ. Для разбора достаточно схемы серии, двух обезличенных строк, часового пояса и trace транзакции; содержимое документов и персональные данные не нужны.

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