Интерфейс database/sql: pgx через StdLib

Адаптер живёт в подпакете stdlib того же модуля github.com/jackc/pgx/v5. Его функция init регистрирует драйвер под двумя именами — pgx и pgx/v5 — поэтому достаточно пустого импорта с подчёркиванием, и sql.Open("pgx", dsn) начинает работать с любым DSN из третьего урока: postgres://-строкой или keyword=value-формой. Секундная ошибка новичка: забыть пустой импорт — тогда sql.Open возвращает ошибку unknown driver «pgx» (forgotten import?), и текст прямо подсказывает диагноз. Если нужна тонкая настройка, которую не выразить строкой подключения, — pgx.ParseConfig даёт *pgx.ConnConfig, и её можно либо разыменовать и передать в stdlib.OpenDB напрямую, либо зарегистрировать через stdlib.RegisterConnConfig: функция вернёт служебную строку подключения, по которой sql.Open найдёт именно эту конфигурацию. Наконец, stdlib.GetDefaultDriver() отдаёт сам объект драйвера — путь для sql.OpenDB с собственным driver.Connector. Все четыре входа ведут к одному адаптеру; различается только то, кто владеет настройками соединений — строка DSN, конфиг или внешний pgxpool, о котором ниже.

stdlib.OpenDB(config pgx.ConnConfig) собирает sql.DB из полной конфигурации pgx — путь, когда настройки не лезут в DSN: кастомный Tracer из двадцать четвёртого урока, тонкая настройка TLS, свой Logger. Сюда же относятся параметры уровня коннекта вроде application_name и search_path — они живут в RuntimeParams той же конфигурации; хуки BeforeConnect и AfterConnect — собственность pgxpool: при OpenDBFromPool они остаются в пуле и продолжают срабатывать для каждого нового коннекта. Второй конструктор появился в v5.5 и решает деликатную задачу совместимости двух пулов: stdlib.OpenDBFromPool(pool pgxpool.Pool) делает sql.DB, чьи соединения — это коннекты вашего pgxpool. Без него два пула делили бы лимит max_connections базы, не зная друг о друге; с ним один pgxpool обслуживает и нативный код, и всё, что требует sql.DB. Механика честная: database/sql при каждом запросе Acquire-ит коннект из pgxpool и Release-ит после, поэтому стандартному пулу запрещают собственные idle-соединения — OpenDBFromPool сам выставляет SetMaxIdleConns(0), чтобы не выгрызать коннекты у pgxpool. Владение разделено: закрытие *sql.DB не закрывает пул — кто-то один в приложении должен вызвать pool.Close(), и обычно это код, который этот пул создал. Это же правило делает OpenDBFromPool главным мостом для постепенной миграции: новые методы пишутся на нативном pgx, старые продолжают ходить через интерфейс, и оба мира делят одну обслугу.

Термин «вы теряете скорость» в контексте stdlib вводит в заблуждение: драйвер — тот же самый, и весь нативный протокол с бинарной передачей значений работает под интерфейсом как есть. Проигрыш против нативного кода начинается на слое обёртки: database/sql конвертирует значения через интерфейсы и отражения, где pgx кладёт байты прямо в приёмники, — это не «разы», но и не ноль на горячем пути. Что правда живёт и здесь: режимы исполнения запросов. По умолчанию адаптер использует QueryExecModeCacheStatement — кэш prepared statements на каждую соединение; при pgbouncer в режиме transaction pooling режим переключают на QueryExecModeSimpleProtocol или Exec через конфиг, и это работает через stdlib так же, как через нативный pgx. Доступ к нативным типам из pgtype остаётся: pgtype.NewMap().SQLScanner(&target) оборачивает pgtype-приёмник в sql.Scanner для стандартного интерфейса — с ним массивы и NUMERIC сканируются и в *sql.DB. Наконец, ошибки на дороге: pgconn.PgError доходит и через database/sql — его вытаскивают из цепочки через errors.As, так что разбор SQLSTATE из шестнадцатого урока применим в обоих мирах. Забавная деталь свежих версий: с 5.7 pgx.ErrNoRows сам оборачивает sql.ErrNoRows, поэтому старые проверки на sql.ErrNoRows продолжают срабатывать и в нативном коде — мост между мирами проложен с обеих сторон. Потеря происходит не в скорости и не в типах, а в выразительности: пачки, NOTIFY, коллекторы и контексты в сигнатурах — интерфейс их просто не описывает.

Когда под интерфейсом понадобилась нативная операция — COPY, SendBatch, LISTEN, — database/sql предлагает штатный механизм для таких «выходов из абстракции»: (sql.Conn).Raw(). Схема из трёх шагов. Сначала db.Conn(ctx) арендует отдельное соединение из стандартного пула — его надо вернуть явно. Затем conn.Raw(func(driverConn any) error { ... }): внутри колбэка driverConn приводится к stdlib.Conn, и метод .Conn() отдаёт настоящий *pgx.Conn, на котором работает весь нативный API. Внутри колбэка запрещено держать ссылку на соединение после выхода — Raw декорирует соединение на время вызова, и использование после возврата — гонка, которую ревью должно ловить. После колбэка conn.Close() возвращает соединение пулу. Люк делает карту «stdlib как постоянный дом» несостоятельной: массовые операции всё равно пишутся нативно, а значит, половина команды всё равно должна владеть нативным API. Практический вывод, к которому я веду весь урок: Raw() — отличный инструмент миграции и редких исключений, но если нативных операций в проекте больше двух-трёх, честнее признать, что дом проекта — нативный pgx, а stdlib — гостиница для legacy.

Когда решение принято, переезд на нативный API предсказуем. Шаг первый — соединения: sql.DB заменяется на pgxpool.Pool из четвёртого урока, SetMaxOpenConns переезжает в MaxConns конфига пула. Шаг второй — грамматика вызовов: у всех методов появляется обязательный контекст, Exec и Query меняют подписи местами, а QueryRow теряет суффиксы Context. Шаг третий — ошибки и типы: sql.ErrNoRows становится pgx.ErrNoRows, sql.NullString — pgtype.Text из шестого урока, а для NUMERIC и UUID появляются честные типы — о них десятый. Шаг четвёртый — проверки: ошибки соединений теперь приходят с нативными типами, и errors.As на pgconn.PgError заменяет разбор через driver.ErrBadConn. Пятый шаг — самое приятное: ручные циклы схлопываются в CollectRows, а место под Batch и COPY освобождается само. Опыт команд, которые это проходили, совпадает: неделя на механику, остальное — на удаление обёрток, которые были нужны только из-за интерфейса. Держите оба мира на одном pgxpool через OpenDBFromPool, пока миграция идёт — тогда лимит соединений базы никогда не станет сюрпризом посреди релиза.