Паттерн «с транзакцией»: функция-обёртка

Сигнатура: pgx.BeginFunc(ctx, db, fn) — где db это всё, у чего есть метод Begin(ctx) (pgx.Tx, error), а fn — func(tx pgx.Tx) error. На место db встаёт и pgxpool.Pool из четвёртого урока, и pgx.Conn, и сама транзакция — про последний случай ниже, он живее, чем кажется. Контракт BeginFunc короткий: открыть транзакцию, вызвать fn; вернула nil — Commit, вернула ошибку — Rollback, и именно её ошибку обёртка вернёт наверх. Обратите внимание, что ошибка запроса внутри fn обычно никуда специально не «отправляется» — вы сами возвращаете её из fn, и это делает поток ошибок прямым и читаемым: одна точка выхода, никаких флагов и состояний. Всё, что fn делает через tx.Exec и tx.Query, едет на коннект транзакции; пул внутрь не лезет — на этом построено живое место ниже. Отдельная деталь, которая сбивает с толку новичков: контекст в BeginFunc используется для управляющих команд BEGIN, COMMIT и ROLLBACK, но не ограничивает выполнение fn — если нужен дедлайн на всю операцию, его приносит сам ctx через WithTimeout, и о расстановке бюджетов говорит пятнадцатый урок. Пока — просто запомните: BeginFunc не добавляет таймаутов от себя.

Обёртка умещается в десять строк, и их стоит понимать, потому что контракт проще показать, чем описать. После Begin ставится defer tx.Rollback() — тот же приём из тринадцатого урока; далее fn вызывается. Если fn вернула ошибку, обёртка делает Rollback ещё раз явно и возвращает вашу ошибку без изменений — то, что fn хотела сказать наверх, не обёрнуто и не съедено. Если fn вернула nil, выполняется Commit, а отложенный Rollback после него вернёт ErrTxClosed, который обёртка распознаёт через errors.Is и молча игнорирует — тот самый безопасный defer. Практическое следствие: собственная ошибка Commit доходит до вызывающего как есть — обёртка не глотает её; фильтр errors.Is игнорирует только ErrTxClosed, а после Commit или явного отката транзакция уже закрыта, так что отложенный Rollback в живом коде возвращает именно его. Вторая коробочная версия — pgx.BeginTxFunc(ctx, db, options, fn): то же самое, но с pgx.TxOptions, где задаются уровень изоляции pgx.Serializable или pgx.RepeatableRead, режим доступа pgx.ReadOnly и откладываемость; она пригодится для отчётов, которым нужен согласованный срез данных, — базовый уровень read committed из тринадцатого урока остаётся выбором по умолчанию.

Коробочная BeginFunc покрывает восемь случаев из десяти, и начинать стоит с неё. Своя обёртка оправдывается, когда у каркаса появляется политика. Первое — время: дедлайн на транзакцию целиком, как в примере выше, — у BeginFunc для этого нет крючка, он честно берёт ваш контекст как есть. Второе — наблюдаемость: метрика «сколько транзакций откатилось», лог медленных операций, трассировка — всё это пишется один раз в WithTx и работает для всех операций автоматически. Третье — типовые отступления от атомарности: компенсирующие действия при откате, события для шины после коммита. Отдельный соблазн — ретраи: обёртка вроде место для повторной попытки, но повторять можно только операцию без внешних побочных эффектов, готовую к тому, что первая попытка откатилась целиком; колбэк с письмом внутри ретраить нельзя. Четвёртое — тесты: WithTx на интерфейсе позволяет подставить фейковый store без базы — тема двадцать третьего урока. Где проходит граница разумного: обёртка не должна знать про бизнес-логику — как только внутри появились условия «если такая-то таблица, то другой уровень изоляции», это уже не каркас, а новое место для багов. Правило то же, что у middleware: обёртка делает механику, функция — смысл. И да, хранить WithTx стоит рядом с пулом: методы структуры Store получают его «бесплатно», без передачи лишних аргументов.

Паттерн живёт или умирает на границе со слоем репозиториев. Первая наивная версия: методы репозитория принимают pgx.Tx — CreateOrder(ctx, tx, order). Работает, но связывает методы с транзакцией жёстко: тот же метод из кода без транзакции уже не вызвать, а в тестах придётся мокать весь pgx.Tx. Вторая версия — узкий интерфейс: type Querier interface { Exec(ctx, sql, args...) (...); Query(...); QueryRow(...) }. В pgx его реализуют и *pgxpool.Pool, и pgx.Tx — наборы методов у них совпадают намеренно, это проверено по исходникам. Репозиторий объявляет методы под Querier и не знает, приехал ли он с транзакцией: сервис при обычной операции передаёт пул, при составной — tx из BeginFunc. Бонус этой схемы — вложенность: у pgx.Tx есть и Begin, поэтому репозиторий, получивший tx, при нужде сам откроет savepoint, не ломая контракт. Нужен интерфейс из трёх методов или меньше? Сужайте под каждый репозиторий — вместо Querier с Exec может быть OrderWriter с одним InsertOrder; принцип тот же: функция просит ровно то, чем пользуется, и это остаётся честным при передаче транзакции. Спорная деталь, о которой спорят на ревью: передавать ли tx явно параметром или прятать в контекст. Явный параметр виден в сигнатуре и в трассировке; контекст короче, но превращает связь в невидимую — я за явный, пока команда не договорилась об обратном осознанно.

Внутри fn транзакция — тоже подходящее db для BeginFunc: pgx.BeginFunc(ctx, tx, fn2) сработает, но создаст не настоящую вторую транзакцию, а псевдо — через savepoint. Драйвер зовёт tx.Begin, который исполняет SAVEPOINT sp_N с растущим номером; Commit псевдотранзакции — это RELEASE SAVEPOINT, Rollback — ROLLBACK TO SAVEPOINT. Поведение для кода то же: ошибка внутреннего колбэка откатывает его часть и возвращается наверх, внешняя транзакция жива и может продолжиться. Это верно и для настоящей SQL-ошибки: после неё транзакция сидит в аварийном состоянии из тринадцатого урока, и снимает его именно ROLLBACK TO SAVEPOINT — в Postgres это единственный способ продолжить транзакцию после реального сбоя, не стирая уже годную работу; полный Rollback честнее, но стирает всё подряд. Классическое применение — батч независимых шагов: третий из пяти упал, откатили его, четыре остальных доехали; деталей больше, чем пользы, но как дешёвый частичный откат в групповых операциях savepoints честно работают. Есть и цена: каждый savepoint — лишняя поездка команды на сервер, и злоупотреблять вложенностью на горячем пути не стоит. Одна оговорка к истории с аварийным состоянием: продолжить можно только работу после отката к savepoint, а сама ошибка всё равно обязана доехать до вызывающего — молча проглотить её и делать вид, что ничего не случилось, — путь к данным, о которых никто не спрашивал.