sqlc и спектр обёрток: типизированный SQL-кодоген, билдеры запросов и честные компромиссы ORM

Спектр, честно

Прежде чем тянуться к ORM или сырому SQL, спроси себя: чем ты на самом деле торгуешь — читаемостью на ревью, гибкостью динамических запросов, типобезопасностью или объёмом рутины? Каждый слой данных в Go сидит где-то на спектре из четырёх точек, и у каждой точки есть реальная цена — нечестный ход только один: делать вид, что у вашей её нет.

Сырой database/sql — максимум контроля и максимум рутины: каждый запрос повторяет церемонию Query/defer Close/Next/Scan/Err из начала юнита, а позиционный Scan — постоянная угроза при рефакторинге: переставьте две колонки одного типа в SELECT — и name ляжет в email без единой ошибки. Билдеры запросов (стандарт — squirrel) собирают SQL из Go-значений: верный инструмент для по-настоящему динамических запросов — двенадцать опциональных фильтров в админке, — но запрос теперь существует только в рантайме, и до выполнения его никто не проверяет. Полные ORM (GORM) максимизируют эргономику: связи, хуки, миграции-из-структур. Цена — семантическая дистанция: правило нулевых значений из крючка, магия порядка сохранений, N+1-запросы, материализующиеся из невинного обращения к полю, — и ревью, на котором никто не видит SQL, который реально выполнится. sqlc застолбил четвёртую точку: вы пишете настоящие SQL-файлы, а кодогенерация выдаёт типизированные Go-функции. SQL виден; рутина сгенерирована; проверка происходит до того, как код уедет в прод.

Механика sqlc: SQL на входе, типизированный Go на выходе

Когда Scan-цели пишешь вручную — ты несёшь ответственность за маппинг вечно: одна переставленная колонка, и баг тихий. sqlc забирает эту ответственность у тебя. Запросы пишутся в .sql-файле, каждый — с именем и аннотацией кардинальности:

-- name: GetUser :one
SELECT id, email, active FROM users WHERE id = $1;

-- name: ListOrgUsers :many
SELECT id, email FROM users
WHERE org_id = $1 AND active
ORDER BY created_at DESC
LIMIT $2;

-- name: DeactivateUsers :exec
UPDATE users SET active = false, updated_at = now() WHERE id = ANY($1::bigint[]);

sqlc generate парсит их вместе со схемой и выдаёт типизированный Go:

// Сгенерировано. Порядком Scan и маппингом полей владеет генератор —
// класс багов с перестановкой колонок исчез: Scan больше не пишет человек.
func (q *Queries) GetUser(ctx context.Context, id int64) (GetUserRow, error)
func (q *Queries) ListOrgUsers(ctx context.Context, arg ListOrgUsersParams) ([]ListOrgUsersRow, error)
func (q *Queries) DeactivateUsers(ctx context.Context, ids []int64) error

Проверка происходит на этапе генерации: сослались на несуществующую колонку, передали string туда, где схема говорит bigint, вернули четыре колонки в структуру из трёх полей — sqlc generate падает, в CI, до ревью. :one компилируется в QueryRow (ноль строк по-прежнему всплывает как sql.ErrNoRows на месте вызова — sqlc не прячет семантику слоя ниже); :many — в полный цикл Query/Close/Err, написанный правильно каждый раз; :exec — в ExecContext. Сгенерированный интерфейс Querier — часть, которую команды недооценивают: это тестовый шов, который не пришлось проектировать. Тесты хендлеров берут рукописный фейк; настоящая база нужна только слою репозитория.

Две точки интеграции держат систему честной в масштабе. Транзакции: сгенерированный код работает на чём угодно, что удовлетворяет его интерфейсу DBTX, поэтому WithTx переиспользует хелпер из прошлого урока без изменений —

q := store.New(db) // *Queries, привязанный к пулу

err := withTx(ctx, db, nil, func(tx *sql.Tx) error {
	qtx := q.WithTx(tx) // те же сгенерированные методы, теперь поверх пришпиленного соединения
	if err := qtx.DeactivateUsers(ctx, ids); err != nil {
		return err
	}
	return qtx.InsertAuditEvent(ctx, auditParams)
})

Миграции: схемой sqlc не владеет — ею владеет инструмент миграций (golang-migrate или goose: нумерованные SQL-файлы, применяемые по порядку и записываемые в таблицу версий). sqlc читает те же файлы миграций, чтобы узнать схему, и это замыкает контур дрейфа: переименуйте колонку в миграции, перезапустите sqlc generate — и компилятор выдаст полный список мест вызова, которые надо поправить. То же переименование с рукописным Scan-кодом компилируется спокойно и тихо портит данные.

Там, где sqlc останавливается, он останавливается резко: на каждую аннотацию генерируется один статический стейтмент, поэтому поисковый эндпоинт с двенадцатью опциональными фильтрами не может быть одним sqlc-запросом. Цепочки трюков с coalesce($1, col) технически работают и надёжно производят одновременно нечитаемый SQL и непригодные планы. Это территория билдера — squirrel за тем же интерфейсом репозитория — или рукописного WHERE поверх белого списка колонок. Зрелый слой данных — композиция, а не монокультура.

Аргумент масштаба команды

Сильнейший довод за SQL-first — не типобезопасность, а ревью. Со sqlc дифф в пулл-реквесте — это и есть запрос: ревьюер может его прочитать, вставить в EXPLAIN ANALYZE и заметить отсутствующий индекс или случайный cross join до мерджа. С ORM-DSL ревьюер мысленно компилирует цепочку методов в SQL и надеется, что его ментальная модель совпадает с версией библиотеки, — крючок показывает, как выглядит несовпадение. То же свойство окупается в три часа ночи: pg_stat_statements показывает медленный запрос, и со sqlc его буквальный текст ищется грепом и приводит к одному именованному, аннотированному запросу. И граница остаётся честной в обратную сторону: отчётные запросы с оконными функциями, рекурсивными CTE и переписываниями под EXPLAIN остаются сырым SQL по своей природе — и sqlc охотно генерирует типы для большинства из них, потому что он никогда не требовал от SQL простоты, только статичности.