Ошибка 23505: конфликты уникальности

Конструкция вешается на INSERT: INSERT INTO users (email, name) VALUES ($1, $2) ON CONFLICT (email) DO NOTHING. Скобки после ON CONFLICT — цель конфликта: колонка или список колонок, по которым существует уникальный индекс. При встрече с дубликатом сервер молча пропускает строку, ошибки нет, RowsAffected в CommandTag равен нулю — так отличают вставку от пропуска без второго запроса. Механика экономит и код, и время: не нужен SELECT на проверку, не нужна транзакция на два запроса, не нужен ретрай — один Exec из пятого урока закрывает сценарий повторной отправки формы, повторной доставки задачи в очередь и перезапуска воркера на середине списка. Цель указывать необязательно: голое DO NOTHING глушит любой конфликт уникальности, и это удобно в скриптах и опасно в продакшене — новый констрейнт, о котором вы забыли, тоже будет заглушен, и баг осядет в данных без единой ошибки в логе. Существует и вариант по имени ограничения: ON CONFLICT ON CONSTRAINT users_email_key — имя берётся из Detail ошибки или из миграции. Главное свойство конструкции — атомарность: не существует окна между проверкой и вставкой, два параллельных запроса с одинаковым email дадут один INSERT и один пропуск, без гонки и без падений. Любой SELECT перед INSERT такой гарантии не даёт — об этом отдельное живое место ниже.

Режим DO UPDATE превращает INSERT в upsert: при конфликте вместо вставки выполняется UPDATE конфликтующей строки. Псевдотаблица EXCLUDED хранит предложенную к вставке строку — значения, которые вы передали аргументами: SET views = EXCLUDED.views + product_stats.views складывает новое значение со старым, SET name = EXCLUDED.name перезаписывает. Квалификация обязательна: без префикса имени таблицы поле views в правой части неоднозначно, и сервер ответит ошибкой про ambiguous column. У DO UPDATE есть необязательное WHERE: условие не сошлось — строка не обновится, RowsAffected будет нулём, RETURNING её не вернёт, и это штатная ситуация, а не ошибка. Апсерт атомарен и при конкурентности: два параллельных upsert одной строки выстроятся в очередь на блокировку строки, второй дождётся и выполнится поверх первого; потерянных обновлений нет. Опасность обратного рода: два upsert, которые в одном запросе трогают строку A, а в другом — строку B и vice versa, могут встретиться лбами и получить 40P01 deadlock — класс 40 из шестнадцатого урока, лечится единым порядком строк во всех апсертах и ретраем транзакции. Справедливости ради: с пятнадцатой версии у Postgres есть и отдельная команда MERGE, решающая смежные задачи условного слияния; pgx ей не мешает — это просто SQL-текст в том же Exec, и вся анатомия ошибок отсюда переносится на неё без изменений.

Там, где on conflict не подходит — например, конфликт сообщает пользователю о занятом email, — код 23505 ловится и переводится на язык клиента. Схема из шестнадцатого урока: errors.As распаковывает PgError, ветка по pgerrcode.UniqueViolation, дальше — маппинг ConstraintName на понятный ответ: users_email_key значит «email занят», поле формы подсвечивается, HTTP-статус 409 Conflict. Имя констрейнта хардкодить можно, но осторожно: переименование в миграции сломает маппинг молча, поэтому реестр имён держите рядом с миграциями или сверяйте тестом на реальной базе. Пользователю Detail не отдаётся: строка Key (email)=(a@b.example) already exists. содержит значение, которое прилетело от клиента, — отражать ввод обратно в ответе значит кормить XSS и утечки. Правило распространяется на всю структуру: Message содержит имена таблиц, Hint — серверные советы, и всё это внутренняя кухня, которую клиенту знать не нужно. Формулировка своя, поле своё, код статуса по семантике: 409 для конфликта ресурса, 422 для проблем валидации. Один нюанс: на один INSERT с двумя уникальными индексами могут падать два разных 23505 — различать их по ConstraintName, а не только по коду, иначе занятый email и занятый телефон получат одинаковый ответ.

Цель в ON CONFLICT должна опираться на существующий уникальный индекс: напишете ON CONFLICT (email) там, где индекса по email нет, — сервер ответит 42P10 с текстом про отсутствующий matching constraint, и это ошибка разработки, а не данных. Частичный уникальный индекс — например, UNIQUE (email) WHERE deleted_at IS NULL — требует совпадающего WHERE в цели конфликта, иначе арбитр не найдётся. Таблица с двумя уникальными индексами создаёт главную развилку: DO NOTHING без цели заглушит оба, и телефонный дубликат пройдёт молча там, где вы ждали только почтовый. Правило: в бизнес-кодах цель пишется явно, безцельный DO NOTHING остаётся для служебных сценариев идемпотентности, где любой повтор допустим. Ловля кода 23505 при этом всегда различает констрейнты по ConstraintName — реестр из прошлого блока растёт вместе со схемой. И не забывайте про первичный ключ: upsert по id трогает PK-индекс так же, как email-констрейнт, — на одной таблице спокойно живут три цели конфликта для трёх разных сценариев. Составные цели тоже легальны: ON CONFLICT (tenant_id, slug) опирается на составной уникальный индекс целиком и часто правильнее цели по одной колонке, когда уникальность гарантируется только парой значений.

DO UPDATE берёт блокировку конфликтующей строки, и это следствие важно при нагрузке. Два горутины апсертят одну строку — вторая ждёт первую, задержка в миллисекунды, данные корректны. Десять тысяч горутин апсертят одну и ту же строку — очередь на блокировку станет бутылочным горлышком, и время ответа вырастет независимо от железа: для сверхгорячих счётчиков буферизуйте инкременты в приложении и сбрасывайте пачкой реже. Перекрёстный порядок — упомянутый deadlock — проверяется код-ревью: все транзакции, трогающие несколько строк upsert-ом, обязаны идти в одном порядке сортировки. WHERE в DO UPDATE добавляет ещё один слой: обновление только при устаревших данных, SET views = EXCLUDED.views WHERE product_stats.views < EXCLUDED.views, — конкурирующие записи перестают затирать свежие, а пропущенные строки честно показываются нулём RowsAffected. Числа для калибровки: очередь на блокировке стоит миллисекунды при десятках горутин, секунды — при тысячах, и граница, где буферизация становится обязательной, обычно наступает раньше, чем кажется при чтении кода. Всё это продолжение мысли шестнадцатого урока: серверная ошибка — не приговор, а переговоры с базой на языке кодов.