Интеграция с CI

Начните с инвентаризации того, что может поехать в main незаметно. Поменять запрос и забыть sqlc generate — верхний пункт списка: пакет собирается, компилятор доволен, потому что генерат в репозитории по-прежнему старый и самодостаточный; расхождение проявится позже, у коллеги, который потянет ветку и получит метод, отсутствующий в его генерате, или у ревьюера, читающего один SQL, а в diff видящего другой. Второй пункт — новая версия sqlc у кого-то в команде: без пина генерация тихо меняет формат, и diff в ревью пестрит шумом. Третий — конфиг и схема разъехались: новая миграция добавлена, queries не переписаны, и только генерация знает, что пакет уменьшился. Все три случая объединяет одно: ни один не ломает сборку на машине виновника, и потому ручная дисциплина против них не работает.

Задача sqlc ci — перевести эти проверки из памяти людей в конвейер. Сгенерированный код детерминирован: один конфиг, одна схема, одна версия sqlc дают байт в байт одинаковый пакет, — и на этой детерминированности стоит вся механика. CI знает ровно три факта: содержимое репозитория, конфиг и пиннутую версию генератора. Этого достаточно, чтобы за секунды ответить на главный вопрос «соответствует ли коммит тому, что выдал бы его конфиг» — и уронить сборку, если нет. Всё остальное в этом уроке — оформление этого вопроса в yaml и дополнение его тестами из двадцать первого урока, которым CI даёт постоянную площадку с докером и настоящей базой.

Команда sqlc diff делает ровно одно: запускает генерацию так же, как sqlc generate, но не пишет файлы, а сравнивает результат с тем, что лежит на диске, — и завершается с ненулевым кодом, если нашлась разница. Это вся семантика, и в ней вся ценность: проверка не требует ни докера, ни базы, ни сети — только файлов репозитория и бинарника sqlc. Прогон занимает секунды даже на большом конфиге, поэтому diff ставят первым job-ом: он дешевле всего и падает раньше всего. Отдельные записи списка sql проверяются разом: три движка из двадцатого урока — три пакета, один прогон.

Пара уточнений, которые экономят вечер отладки. diff сравнивает сгенерированные файлы, а не git-состояние: если генерат вообще не коммитится (выбор из двадцатого урока против дефолта), проверять не с чем — сравнение всегда упадёт или всегда пройдёт в зависимости от реализации; коммит генерата и diff идут парой. Альтернативный паттерн, который вы встретите в чужих конвейерах, — sqlc generate в CI-копии и git diff --exit-code: то же сравнение руками. Штатный diff делает это чище и без правки рабочего дерева. За пределами этого урока остаётся пара команд для больших команд: sqlc push и sqlc verify из sqlc Cloud — схема и запросы загружаются в облако, и каждая новая версия проверяется на регрессии против истории; удобно при строжайших требованиях, но требует аккаунта, а базовая гигиена живёт в локальном diff. Ещё дальше — sqlc vet, статические правила для запросов: их разбор — тема следующего урока.

Соберите конвейер из трёх job-ов, каждый — про свою полосу из пирамиды тестов. Первый sqlc-diff: checkout, установка sqlc с пином, sqlc diff — дрейф ловится за секунды на каждом push и pull request. Второй unit: go test -short — домен на фейках, контракты на sqlmock, sqlite в памяти по канону девятнадцатого урока; по договорённости двадцать первого урока этот набор не требует докера и проходит на любом раннере. Третий integration: сервис-контейнер PostgreSQL прямо в job-е, миграции из шестнадцатого урока, TEST_DATABASE_URL в окружении — и полный набор против настоящего диалекта.

Пара слов про механику Actions, чтобы yaml читался как проза. actions/checkout выгружает репозиторий, actions/setup-go ставит Go и кеширует модули — кеш экономит минуты на каждом прогоне. Job-ы по умолчанию идут параллельно: diff не ждёт тестов, что и нужно — падение проверки генерации должно быть видно сразу. Секция services поднимает контейнер рядом с job-ом и следит за его здоровьем через health-cmd: шаги не начнутся, пока pg_isready не ответит. Секреты и пароли в тестовой базе — не секреты: контейнер живёт минуты, но DSN всё равно уезжает в env шага, а не в код. Такой пайплайн — типовой ответ на запрос sqlc github actions, и его можно копировать в проект как есть, поменяв путь к миграциям и версию Go.

Первый способ — go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.27.0: сборка из исходников на раннере. Минус — время: холодная компиляция занимает минуты, но setup-go кеширует модули, и повторные прогоны сходятся к десяткам секунд; плюс — версия задана прямо в yaml, ничего вне git не существует. Второй способ — готовый бинарник с релизов GitHub: один curl-распаковка в /usr/local/bin, секунды вместо минут; цену платите строкой с URL конкретного релиза, которую придётся обновлять руками. Третий — docker-образ sqlc/sqlc: docker run с примонтированным репозиторием; естественно там, где раннер и так живёт в докере.

Какой бы способ вы ни выбрали, версия фиксируется явно — это не рекомендация, а условие корректности всей проверки. Генерация детерминирована для одной версии: две разные версии sqlc могут разложить пробелы, комментарии или порядок полей по-разному, и diff начнёт падать «на пустом месте» — не потому, что генерат устарел, а потому, что раннер думает другим генератором. Пин закрывает и обратную сторону: новая версия sqlc с ломающими изменениями не подорвёт конвейер внезапно — вы поднимаете пин осознанно, читаете changelog, прогоняете diff и тесты, и коммит обновлённого генерата попадает в ревью как обычное изменение. Готовые сторонние actions для установки sqlc существуют, но два явных шага из канона делают то же самое без зависимости от чужого мейнтейнера.

Проверка diff в CI закрывает вопрос «поймали ли», но стоит объяснить и «почему так». Существует альтернативная модель: генерат не коммитится, CI сам запускает sqlc generate и подкладывает результат в артефакт сборки. Она выглядит чище в git и разбивается о быт: разработчик без установленного sqlc не собирает проект локально; ревьюер не видит в PR, как изменились структуры и методы; откат релиза — не revert-коммит, а повторная генерация, требующая точной версии инструмента. Поэтому дефолт из двадцатого урока остаётся: генерат в git, diff в CI как охрана этой договорённости.

Когда дрейф всё же случился (а он случится хотя бы один раз, чтобы вы полюбили job sqlc-diff), починка тривиальна и одинакова всегда: pull свежей main, sqlc generate, посмотреть diff в ревью — не подгонять ли его под чей-то незакоммиченный эксперимент — и коммит. Автоматизировать этот коммит ботом (генерировать в CI и пушить в ветку) можно, но взвесьте: автоматический push в ревью — источник гонок и сюрпризов, а экономия — одна команда, которую никто не забудет после первого красного конвейера. Для монорепозиториев добавляется штрих: paths-фильтры в триггере, чтобы sqlc-diff гонялся только когда изменились sqlc.yaml, db/ или внутренние пакеты; но держите его обязательным для любых изменений слоя данных — фильтр экономит секунды, дрейф стоит доверия.

Разложите конвейер по ролям — и порядок шагов станет очевидным, а не магией. Job sqlc-diff не касается живых баз вообще: генератору нужен только DDL из db/migrations как файлы — проверка схемы и запросов компилятором sqlc. Job unit тоже: sqlite-контур создаёт базу сам. Единственный job, где база настоящая, — integration, и внутри него порядок жёсткий: контейнер поднялся и ответил pg_isready, миграции накатились тем же инструментом, что и на прод (golang-migrate из шестнадцатого урока), затем тесты. Пропуск миграций — любимая ошибка: тесты падают с «relation does not exist» и уводят отладку в сторону sqlc, который ни при чём.

Отдельный вопрос — миграции при деплое: конвейер проверки и конвейер выката — разные сущности. CI отвечает на «правильно ли написано», CD-шаг отвечает на «успешно ли накатится»: миграции перед выкаткой новой версии приложения, в порядке, который шестнадцатый урок разбирал на примере schema_migrations. В маленьких проектах шаг migrate up живёт прямо в деплой-job-е CI, в больших — в отдельном пайплайне релиза; для урока важно одно: тестовая база integration-job-а и продовая база не связаны, и успех тестов ничего не накатывает на прод. И последний штрих порядка: держите diff первым, unit вторым, integration третьим — не потому, что Actions этого требуют (job-ы параллельны), а потому, что так логи читаются сверху вниз от дешёвых проверок к дорогим.

Остановитесь и посмотрите, что получилось. Дрейф генерата пойман job-ом sqlc-diff за секунды и без базы. Пирамида тестов из двадцать первого урока получила постоянную площадку: быстрые наборы на каждый push, полный Postgres-набор с миграциями — на pull request. Пин версии делает всю проверку воспроизводимой, а чеклист — её обслуживаемой. Конвейер отвечает на вопрос «правильно ли собран слой данных»: конфиг соответствует коммиту, запросы соответствуют схеме, поведение соответствует тестам.

Остаётся вопрос глубже: сами запросы могут быть правильными по синтаксису и всё равно плохими — сканировать всю таблицу без индекса, забывать WHERE, дублировать условия, возвращать лишние колонки. Ловить это руками в ревью можно, но sqlc умеет проверять запросы по правилам: команда sqlc vet исполняет декларированные в конфиге проверки — от «в каждом запросе есть WHERE» до прогона EXPLAIN против настоящей базы и ловли full scan-ов на этапе пуша. Следующий урок посвящён sqlc vet: правилам, EXPLAIN-проверкам и тому, как встроить статический анализ SQL в тот же конвейер, который вы только что собрали. Проверка генерации сказала «код свежий» — vet скажет «код хороший».