Batch: сотни запросов за один рейс

Очередь строится без сети: Queue только запоминает SQL и аргументы и возвращает QueuedQuery — указатель на постановку. SendBatch отправляет всё скопом и отдаёт BatchResults, дальше контракты совпадают с обычными вызовами: br.Exec() читает результат следующей команды, как обычный Exec — CommandTag и ошибку; br.Query() открывает курсор следующего SELECT со знакомым циклом rows.Next из пятого урока; br.QueryRow() даёт Row со Scan и ErrNoRows. Единственное правило — порядок: первый вызов читает результат первой постановки, второй — второй, и перепрыгнуть нельзя. Пачка живёт на одном коннекте: у pgx.Conn соединение занято с момента SendBatch до Close — документация формулирует это буквально, ридер обязан быть закрыт до следующего использования коннекта. Пул в pool.SendBatch берёт коннект из стока, а возвращает ровно в Close — в исходниках pgxpool Release вызывается именно там. Отсюда рефлекс: defer br.Close() пишется сразу после SendBatch, и между ними не должно быть ни одного return. Переиспользовать Batch нельзя: комментарий в исходниках гласит, что пачка отправляется один раз — новая операция собирает новый объект. Len перед отправкой — дешёвая проверка, что цикл поставил столько команд, сколько ожидалось: пустая пачка уедет и вернёт пустой набор, а лишний Exec на исчерпанной очереди вернёт ошибку no more results in batch — увидим её в интерактиве ниже.

Документация SendBatch формулирует жёстко: все запросы пачки выполняются в неявной транзакции, если вы сами не послали команды управления транзакциями. Практическое следствие: сбой посреди пачки откатывает уже выполненные команды и рвёт остаток — четвёртый INSERT упал, значит первые три не фиксируются, а пятый и дальше вернут ошибку. Пачка по умолчанию — атомарный блок: либо всё, либо ничего, как транзакция из тринадцатого урока, только без явных BEGIN и COMMIT. Нужен частичный успех — режьте операцию на несколько независимых пачек по бизнес-группам: упавшая группа не тянет остальные и повторяется отдельно. Формулировка «если не послали команды управления» — это не формальность: BEGIN и COMMIT можно положить в очередь обычными элементами пачки, и границы сместятся, но такой стиль быстро становится нечитаемым — явная tx.SendBatch из четырнадцатого урока честнее. Ошибка в середине — обычная PgError из шестнадцатого урока: br.Exec() вернёт её на соответствующем месте очереди, 23505 от дубликата валит пачку целиком, а все последующие чтения возвращают ту же ошибку — конвейер уже оборван. Отсюда правило идемпотентности: пачку после сбоя можно отправить заново целиком, неявный откат гарантирует, что дубликатов внутри не останется. Тонкость для продакшена: журналировать стоит только факт провала группы и её размер — собирать «сколько успело» бессмысленно, успело ноль.

BatchResults.Close читает все непрочитанные результаты, выполняет зарегистрированные колбэки, завершает операцию и освобождает коннект — на уровне пула это буквальный Release. Забытый Close означает коннект, который не вернулся в сток: при MaxConns из четвёртого урока достаточно нескольких утечек в минуту, чтобы сервис замер на Acquire без единой ошибки в логе — просто медленно, потом наглухо. Рецепт двумя строками: defer br.Close() сразу после SendBatch, повторный вызов безопасен — исходники гарантируют, что второй Close вернёт ту же ошибку без побочных эффектов. Сам Close возвращает агрегированную ошибку пачки: если нечитанные результаты содержали сбой, вы узнаете здесь — в сценариях с неполным чтением ошибку Close стоит логировать отдельно, она последняя, кто видел проблему. Вторая грань — параллельность: пачка выполняется на одном коннекте последовательно, распараллелить её внутренности между соединениями нельзя; масштабирование достигается несколькими SendBatch из разных горутин, каждая со своей пачкой, и потолок задаёт размер пула. Диагностика свободна: pool.Stat() в срезе метрик показывает занятые и ожидающие Acquire — ступенька вниз на графике свободных коннектов сразу указывает на утечку ридеров. Третья грань — память: очередь живёт в приложении до отправки, миллион Queue с аргументами съедает сотни мегабайт, поэтому большие объёмы режьте на пачки по несколько тысяч команд или переходите на COPY.

Дефолтный режим выполнения pgx — QueryExecModeCacheStatement: перед выполнением пачки новые запросы готовятся все сразу, одним конвейером описаний. Документация предупреждает о следствии прямо: если в одной пачке сначала CREATE TABLE, а потом INSERT в неё, вставка может упасть — на момент подготовки стейтмента таблицы ещё нет, хотя CREATE формально уже выполнен. Ловушка расставляет границы: DDL в пачку не кладётся — схема меняется отдельной поездкой через Exec, как в пятом уроке, а пачка работает только с данными. Вторая тонкость: постановка выполняется в дефолтном режиме коннекта, поэтому поведение пачки зависит от QueryExecMode — на простом протоколе пачка склеивается в одну строку через точку с запятой, и правила игры другие; тесты обязаны гоняться на том же режиме, что и продакшен, иначе проверяется чужой драйвер. Аргументы каждой постановки едут через расширенный протокол отдельно, значит правила типизации из восьмого урока действуют на каждую команду в отдельности — nil против пустой строки и прочие сюрпризы не растворяются в массовой отправке. Сверхдлинный SQL внутри Queue — сигнал, что логика живёт не там: пачка экономит дорогу, а не чинит кривой план.

Граница проходит по однородности и объёму. Пачка — про разнородность: вставить справочник, обновить счётчики, посчитать итоги — всё за одну поездку и с разными типами результатов. COPY — про объём: тысячи однотипных INSERT в одну таблицу через пачку всё равно готовят стейтмент на каждую постановку и тащат каждый результат, а COPY гонит бинарный поток строк без SQL вообще — механизм следующего урока. Между ними лежит ступенька мульти-VALUES: INSERT ... VALUES (...), (...) собирает много строк в один запрос, но упирается в потолок расширенного протокола — 65535 параметров на оператор, значит максимум строк в пачке равен 65535, делённому на число колонок; для широких таблиц потолок низкий, а длинные VALUES тяжки для планировщика. Ориентиры: единицы команд — обычный Exec, десятки-сотни — batch, тысячи — уже вопрос, десятки тысяч — точно COPY; финальное слово за замером на вашей базе. Атомарность тоже различается: пачка откатывается целиком при сбое, COPY — тоже, но конфликты уникальности он разрешать не умеет вовсе. Следующий урок покажет бенчмарк на глазах: одна и та же загрузка через цикл и через CopyFrom, цифры рядом.