Транзакции: QueriesWithTx

Запрос «sqlc транзакции» почти всегда означает одно и то же недоумение: методы Queries есть, а ключевого слова BEGIN среди них нет. Разложим сцену по слоям. Сгенерированный q := db.New(pool) держит в поле db интерфейс DBTX, под который подходит и пул, и одиночное соединение. Каждый вызов q.CompleteTodo или q.CreateSpending — самостоятельный оператор: он выполняется в режиме автокоммита, то есть база оборачивает его в собственное неявное BEGIN ... COMMIT и фиксирует сразу. Два соседних вызова — две независимые сделки, и между ними есть окно, куда влезает что угодно: чужой запрос, сбой сети, рестарт приложения, отмена контекста. Требование «или оба изменения, или ни одного» на таком слое не выражается — это и есть момент, когда нужны транзакции.

Вторая причина тоньше и про соединения. Пул держит несколько соединений и раздаёт их по запросу; два вызова одного и того же q вовсе не обязаны поехать на одном — и BEGIN, открытый на одном соединении, не накроет оператор на другом. Транзакция в Go — это выделенное соединение с состоянием: database/sql отдаёт его в виде *sql.Tx после Begin или BeginTx, pgx — в виде pgx.Tx. У этого выделенного соединения своя судьба: всё, что через него проходит, коммитится или откатывается одной кнопкой, а чужие клиенты его не трогают.

Запрос «withtx sqlc» ищет именно мостик между двумя мирами — пулом и выделенным соединением. Сгенерированные Queries умеют работать с любым DBTX, а *sql.Tx и pgx.Tx реализуют DBTX целиком: у них есть все те же Exec- и Query-методы. Значит, копия Queries с tx в поле db вызывает те же методы с теми же сигнатурами — но внутри одной транзакции на одном соединении. Ровно это и делает WithTx. Шестой урок дал привычку «несколько записей — одна транзакция»; сегодня — механика по буквам, включая строку, которая не скомпилируется.

Точную генерацию сверим с шаблонами генератора — папка internal/codegen/golang/templates в репозитории sqlc, версия 1.27. Для pgx/v5 db.go содержит четыре сущности: интерфейс DBTX из трёх методов (Exec, Query, QueryRow — плюс CopyFrom и SendBatch, если ваши запросы их используют), конструктор New(db DBTX), структуру Queries с единственным полем db и метод WithTx. Никакого второго хранилища, никаких флагов транзакции: WithTx строит новую структуру Queries, у которой то же самое поле db теперь ссылается на транзакцию.

Три факта об этой генерации стоит запомнить наизусть. Первый: WithTx не отправляет в базу ни одного оператора — BEGIN к моменту вызова уже выполнен Begin-ом, и методу нечего делать в сети; поэтому у него нет и ошибки. Он возвращает ровно одно значение — Queries. Если где-то в вашем коде осталась строка вида qtx, err := queries.WithTx(tx), она не скомпилируется: справа одно значение, слева две переменные, и компилятор ответит assignment mismatch. Ошибку отдаёт Begin — к моменту WithTx транзакция уже открыта. Второй факт: копия независима. Оригинальный q продолжает работать с пулом — после WithTx у вас в руках два объекта, pool-версия и tx-версия, и это разные пути данных. Третий факт: WithTx — метод Queries, а не функция пакета, вызывается как queries.WithTx(tx).

В database/sql-флейворе генерация идентична с точностью до типа аргумента: WithTx(tx sql.Tx) Queries, а DBTX описан четырьмя методами с суффиксом Context. Занятная деталь: New(tx) компилируется так же — конструктор принимает любой DBTX, и транзакция в него влезает. WithTx всё равно полезнее: при подготовленных выражениях он переносит stmt-поля, о которых New знать не знает, — этому посвящён отдельный раздел ниже.

Канонический порядок паттерна withTx жёсткий, и каждое место в нём обосновано. Шаг первый — Begin: у pgx pool.Begin(ctx), у database/sql db.BeginTx(ctx, nil) или короткое db.Begin(ctx); оператор вынимает соединение из пула и открывает транзакцию. Это единственная точка входа с ошибкой — проверяем её первой строкой. Шаг второй — defer tx.Rollback(ctx), поставленный сразу после Begin: отложенный откат сторожит все выходы — каждый return с ошибкой, ранний выход, панику. Отложенные функции выполняются при раскрутке стека даже в случае паники, поэтому изменения откатятся, а паника продолжит всплытие к recover или до верха программы. Шаг третий — qtx := queries.WithTx(tx): дальше всё только через tx-копию. Шаг четвёртый — вызовы qtx, где каждая ошибка означает return err. Шаг пятый — return tx.Commit(ctx): единственная и явная точка фиксации, ошибку которой проверяют — здесь база говорит «зафиксировать не вышло».

Две детали делают паттерн честным. Первая: Rollback после Commit вернёт ошибку — database/sql ответит sql.ErrTxDone с дословным текстом «sql: transaction has already been committed or rolled back», pgx — ошибкой, для которой errors.Is(err, pgx.ErrTxClosed) истинно. В defer эту ошибку игнорируют: это ожидаемая дорога, а не авария. Вторая: Commit в defer писать нельзя — анти-паттерн по обеим осям. Ошибка коммита потеряется, ведь defer ничего не возвращает, а при ошибке внутри транзакции Commit сделает бессмысленную попытку зафиксировать прерванную работу: в Postgres транзакция после сбоя оператора считается прерванной, и pgx честно ответит ErrTxCommitRollback — «коммит на самом деле сделал откат». Плюс мелочь, которая путает: у *sql.Tx методы Rollback и Commit живут без контекста — контекст израсходован BeginTx; у pgx контекст есть у всех.

Скелет из пяти шагов повторяется в проекте столько раз, сколько есть атомарных сценариев, и рано или поздно кто-то напишет его без defer. Решение — хелпер withTx: рамка, внутри которой boilerplate живёт ровно один раз. Сигнатура проста: функция принимает контекст, источник соединений и замыкание fn func(q *db.Queries) error; сама открывает транзакцию, ставит отложенный откат, строит tx-копию Queries, передаёт её в замыкание и — если замыкание вернуло nil — коммитит. Ошибка внутри замыкания означает откат, nil — фиксацию; других режимов нет.

Из такой формы следуют три дисциплины. Первая: забыть откат или потерять коммит невозможно — они прописаны в одном месте, и новые сценарии не копируют boilerplate, а вызывают хелпер. Вторая: замыкание видит только tx-версию Queries и не решает, коммитить ли по ходу дела — решение «атомарно или не атомарно» принимает вызывающий код, выбирая между q и withTx. Третья: внутри замыкания не открывают вторую транзакцию — почему, следующий раздел покажет на дедлоке.

В pgx-мире есть и встроенный аналог — pgx.BeginFunc: функция принимает контекст, что-то умеющее Begin (пул или соединение) и замыкание от pgx.Tx; сама делает Begin, коммит при nil и откат при ошибке, а отложенный отладочный Rollback фильтрует по ErrTxClosed — ровно та дисциплина, которую мы разбирали. database/sql встроенного хелпера не имеет: пишут свой withTx, благо это десять строк. Обе версии хелпера — в блоке кода ниже; они не знают ни одного конкретного запроса и потому переживают любые изменения слоя данных.

Флаг emit_interface из второго урока просит у генератора ещё один файл — querier.go — и в транзакционной теме у него вторая, более тонкая роль. Сгенерированный интерфейс собирается из методов запросов: по форме на каждый оператор — :one даёт метод с возвратом (Row, error), :many — ([]Row, error), :exec — error, :execrows — (int64, error). В конце файла стоит строка var _ Querier = (*Queries)(nil) — компиляционная проверка, что структура Queries реализует интерфейс целиком: забудете один метод в тестовом фейке — компилятор укажет раньше, чем CI.

Главное для сегодняшней темы — чего в интерфейсе НЕТ. Querier — это только методы запросов: New, DBTX и WithTx в него не входят, потому что это не запросы, а рамка. Из этого следует практическое правило маршрутизации. Функции вниз по стеку — business-логика, обработчики — объявляйте как принимающие ctx и Querier: им всё равно, приехал аргумент с пула или из транзакции, и тесты подставляют фейк (вторая роль той же опции из второго урока). А функция, которая ПЛАНИРУЕТ транзакцию, обязана принимать конкретную *Queries или пул: у интерфейса нет WithTx, и это осознанный дизайн — сервисный метод, способный втихую открыть транзакцию внутри себя, — плохой контракт. Хелпер withTx строит рамку и отдаёт tx-копию; функции ниже принимают Querier и даже не знают, что работают внутри транзакции.

Отсюда же простой тест на подозрительную сигнатуру: если функция объявлена func(ctx, q Querier) и внутри пытается открыть транзакцию — она не скомпилируется, и это хорошо: открытие транзакции — решение уровня хелпера, а не каждой функции наугад.

Имя PrepareTx из плана курса не приедет из генератора: sqlc не создаёт метода PrepareTx — и это лучший повод рассказать, как подготовленные выражения уживаются с транзакциями по-настоящему. Начало истории — в database/sql. По умолчанию каждый ExecContext и QueryContext отправляет текст запроса на сервер заново: парсинг и планирование повторяются при каждом вызове, кэша prepared statements у database/sql нет — подготовленное *sql.Stmt привязано к соединению, а пул это соединение меняет при каждом запросе.

Опция emit_prepared_queries: true — та самая, которую второй урок держал выключенной, — меняет генерацию: sqlc пишет функцию Prepare(ctx, db DBTX) (Queries, error), метод Close() и поля sql.Stmt по одному на каждый запрос; вызовы идут через внутренние queryRow, query и exec, которые используют подготовленные выражения. Где здесь транзакции? Внутри WithTx: копия получает не только tx, но и stmt-поля, а каждый вызов проходит через ветку, где подготовленное выражение перепривязывается к транзакции методом q.tx.StmtContext(ctx, stmt). Вот почему отдельного PrepareTx не существует — пара Prepare и WithTx покрывает сценарий целиком: подготовили один раз на пуле, перепривязали в каждой транзакции. StmtContext здесь несущая конструкция: *sql.Stmt подготовлен на соединении из пула, транзакция живёт на своём соединении, и без перепривязки выражение из пула нельзя выполнить внутри tx.

У pgx всё иначе: драйвер имеет неявный кэш подготовленных выражений из коробки — документация sqlc прямо говорит, что с pgx/v5 дополнительная конфигурация не нужна, и опция emit_prepared_queries к pgx-флейвору не применяется вовсе. Есть и техническое ограничение: опция несовместима с emit_methods_with_db_argument — sqlc откажется генерировать такую конфигурацию. Проверить, что ваши запросы вообще поддаются подготовке, можно без включения опции — sqlc vet с правилом sqlc/db-prepare прогоняет каждый запрос через Prepare на живой базе и роняет проверку на первом неудобном запросе.

Правило звучит коротко: одна транзакция на весь путь вызовов. Анти-паттерн выглядит так: функция A открывает withTx и внутри вызывает функцию B, которая тоже открывает withTx. Вторая Begin просит у пула ещё одно соединение — а первое-то занято транзакцией A. При пуле из одного-двух соединений программа взаимоблокирует сама себя: A ждёт завершения B, B ждёт свободное соединение. Даже при щедром пуле атомарность разваливается: два коммита — два независимых события, и сбой между ними оставляет половину работы. Внутри транзакции вторую не открывают — её либо не открывают, либо передают вниз tx-версию.

Правильная форма — раздача аргументом. Функция вниз по стеку принимает q — tx-версию Queries: chargeTodo(ctx, q, id). Она не знает и не хочет знать, в транзакции ли едет: снаружи её вызывают и с pool-версией (каждый оператор сам по себе), и внутри withTx (всё атомарно). Так функции передают не соединение, а Queries — и сигнатура честно показывает, что функция ходит в базу.

Смешивание q и qtx внутри одной транзакции — тихий убийца корректности. Вызов queries.GetTodo посреди withTx едет через пул: возможно, на другом соединении, в автокоммите, и незакоммиченных изменений вашей транзакции он не видит — read-your-writes ломается без единой ошибки. А вызов queries.UpdateSomething в середине транзакции — независимая сделка в стороне от вашего атомарного сценария. Дисциплина одна: внутри рамки — только qtx.

Две придаточные темы. pgx умеет псевдовложенность: tx.Begin(ctx) на живой транзакции отдаёт вложенную транзакцию через SAVEPOINT — pgx сам ведёт счёт точек сохранения; database/sql предлагает только ручные SAVEPOINT и ROLLBACK TO текстом. И помните про длину: транзакция живёт, пока вы её держите, — сетевые вызовы, отправка писем и ожидание ввода внутри рамки растягивают блокировки и истощают пул; работа вне базы выносится за withTx.

Критерии стоят того, чтобы держать их перед глазами на ревью. Нужна транзакция, когда выполняется хотя бы одно из трёх. Первое — две и более записи атомарно: деньги и журнал, перевод между счетами, каскадное закрытие задачи вместе с её подзадачами. Второе — согласованное прочитать-изменить-записать: прочитать счётчик и записать инкремент — это два оператора, и без рамки между ними влезет чужой инкремент; один оператор с возвратом id решал похожую гонку внутри самого себя, но два оператора без транзакции не сцепить. Третье — частичный результат хуже ошибки: биллинг, аудит, миграции данных, где половина применённого изменения хуже отложенной работы.

Не нужны транзакции, когда оператор один: INSERT либо вставит строку, либо нет — атомарность оператора база гарантирует и без рамки, и оборачивание одиночного вызова в withTx добавляет поездки BEGIN и COMMIT без выгоды. Не нужны они и для чтений, которые показывают пользователю список: пусть даже данные чуть устареют — ничего не сломается. Отдельная категория — диалоговые транзакции, открытые в ожидании пользовательского ввода: соединение занято, блокировки растут, соседние запросы queue-ятся; пользователь ушёл на обед — пул исчерпан.

И последнее уточнение: транзакция — инструмент корректности, а не скорости. Она не ускоряет ничего, а длинная транзакция замедляет всех вокруг. Если внутри рамки нужен захват строки — SELECT ... FOR UPDATE в аннотированном запросе сработает как обычно, sqlc не мешает писать это в SQL; но выбор уровня изоляции — уже следующий виток глубины, и для трекера дефолтного READ COMMITTED хватает почти всегда: меняйте TxOptions осознанно, когда объяснили себе, какую именно аномалию вы лечите.

QueriesWithTx разобран по буквам: копия Queries с tx в поле db, одно возвращаемое значение вместо двух, defer-сторож сразу после Begin, единственный проверяемый Commit, хелпер с замыканием и pgx.BeginFunc, Querier без WithTx и PrepareTx как пара Prepare и WithTx со StmtContext внутри. Трекер научился закрывать задачу и списывать деньги одной судьбой — и знает границы: одна транзакция на путь вызовов, никаких рамок вокруг сети.

Следующая остановка — двенадцатый урок «Джойны и вложенные структуры»: много-колоночные выборки и сканирование в структуры, JOIN в аннотированных запросах и что делает генератор с Row-типами на несколько таблиц. Спойлер из практики: часть сценариев, ради которых вчера открывали транзакцию, завтра читается одним запросом с соединением таблиц. Если понадобится освежить карту коллекций — она в десятом уроке, nullable-мир обёрток и указателей — в девятом; план остальных тем — на странице курса sqlc.