Практическое руководство по использованию Atlas для декларативных миграций схемы и интеграции в CI/CD. Выполните от начала до конца за ~60–90 минут на машине с 4 ГБ ОЗУ.
Что вы изучите
Как описывать схему базы данных декларативно с Atlas CLI 1.8.0 (релиз 2026).
Как получить diff между текущей БД и репозиторием и применить изменения (git-driven workflow).
Как настроить CI для проверки миграций через GitHub Actions runner (ubuntu-22.04) и обеспечить безопасный apply в CD.
Сравнение с Flyway и golang-migrate по подходу GitOps и управлению схемой.
Пакет типовых ошибок и инструкции по их исправлению в рабочих скриптах и в системах ревью.
Минимум: 2 vCPU, 4 ГБ ОЗУ для локальной проверки; рекомендуем 4 vCPU, 8 ГБ для параллельных CI job-ов.
Порты: PostgreSQL 5432, HTTP-интерфейсы CI — стандартные.
Что такое Atlas?
0
Статья была полезной?
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…
Atlas — инструмент от Ariga для управления схемой базы данных декларативно и миграциями в режиме GitOps. Atlas 1.8.0 (релиз 2026) сочетает в себе синтез схемы в формате HCL/YAML, diff-механизм и apply-операции, ориентированные на reproducible workflow. Он поддерживает PostgreSQL, MySQL и SQLite и оптимизирован для интеграции в CI/CD и pull request-ревью.
Схема работы Atlas: репозиторий -> diff -> apply
Шаг 1: declarative schema
Цель шага — описать базовую схему декларативно в репозитории и синхронизировать с локальной БД. Требуемое время: 10–15 минут. Команды ниже показаны для atlas CLI 1.8.0 (релиз 2026).
Команда: инициализация проекта и создание файла schema.hcl
Объяснение: файл schema.hcl описывает окружение dev и схему app с таблицей users. Atlas хранит структуру в виде HCL, что удобно для ревью и diff в git.
Ошибка: could not connect to postgres: dial tcp 127.0.0.1:5432: connect: connection refused
Фикс: убедитесь, что контейнер PostgreSQL запущен:
docker run -d --name pg-test -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15
(ожидание старта ~3-6 с)
Примечание по времени: запуск контейнера PostgreSQL обычно занимает 3–10 секунд на SSD; если база поднимается медленно, подождите 5–15 секунд перед выполнением команды inspect.
Фрагмент schema.hcl в редакторе
Шаг 2: diff и apply
Цель шага — сгенерировать diff между declarative schema и реальной БД, создать миграцию и применить её. Время: 15–25 минут включая ревью миграции.
Команда: сгенерировать diff и создать миграцию
# создать миграцию из текущих изменений в schema.hcl
docker run --rm -v $(pwd):/work -w /work ariga/atlas:1.8.0 atlas migrate diff --dir file://migrations -e dev --format sql -o migration.sql
Объяснение: команда создаёт SQL-файл в каталоге migrations с конкретными шагами DDL. Путь file://migrations — локальный каталог в репозитории, который попадёт в git и будет ревьються.
Ошибка: migration is already applied
Фикс: проверьте таблицу миграций (по умолчанию atlas_schema_revisions). Если миграция частично применена, выполните откат вручную или создайте новую миграцию с откатом.
Ошибка: permission denied for schema public
Фикс: проверьте пользователя подключения в URL: предоставьте CREATE привилегии для роли, используемой Atlas, или используйте роль с достаточными правами.
Шаг 3: CI
Цель шага — интегрировать проверку diffs и тестовый apply в CI. Время: 20–30 минут на настройку GitHub Actions workflow и тестирование в CI.
Подход: в PR запускать job, которая поднимает ephemeral PostgreSQL контейнер, запускает atlas migrate diff и проверяет, что новые SQL-миграции соответствуют ожиданиям (no drift). Если diff обнаружен — job должен провалиться и потребовать обновления миграций.
Объяснение: job поднимает PostgreSQL, монтирует репозиторий и выполняет diff. Если diff возвращает содержимое, значит схема в коде и БД не совпадают — CI провалит сборку.
Ожидаемый вывод CI при успехе:
No drift
Ожидаемый вывод при обнаружении расхождения:
DRIFT FOUND
Error: Process completed with exit code 1.
Типичные ошибки и фиксы в CI:
Ошибка: pg_isready health check timeouts
Фикс: увеличьте --health-retries или добавьте задержку перед запуском atlas (sleep 5-15). На тяжёлых runner-ах запуск Postgres может занимать 10-20 с.
Ошибка: каталога migrations нет в build-артефакте
Фикс: проверьте, что migrations заинклюдены в репозитории и не игнорируются .gitignore.
CD интеграция
Цель — показать безопасный путь применения миграций в production через CD pipeline. Время: 15–30 минут для примера и конфигурации шага deploy.
Практика: разделите CI (проверка) и CD (применение). CD-runner должен иметь ограниченные права и работать по цепочке утверждений: PR -> main -> manual approval -> deploy.
Объяснение: URL к production хранится в секретах CI (GitHub Secrets). Перед apply должен сработать manual approval (environment protection rules) и проверка, что migrations в main совпадают с ожидаемыми.
Типичная ошибка и решение:
Ошибка: secrets.PROD_DATABASE_URL отсутствует
Фикс: добавьте секрет в репозиторий или организации и протестируйте в staging перед production.
Ошибка: apply зависает при блокировке DDL
Фикс: используйте транзакции и тестируйте сценарии блокировок в staging, применяйте миграции в maintenance window с мониторингом.
Рекомендуется включать в CD step логирование выполнения миграций и систему отката (backup/pg_dump) перед apply для production: время создания дампа ~10–60 с в зависимости от объема данных.
Чем лучше Flyway?
Atlas и Flyway решают задачу миграций, но подходы различаются. Flyway (стабильная ветка 9.x, релизы 2023–2025) ориентирован на миграции как серию SQL-скриптов, выполняемых последовательно. Atlas фокусируется на декларативной схеме и генерации миграций через diff, что снижает вероятность human-error при создании DDL.
Declarative vs Imperative: Atlas хранит схему (HCL/DDL) и генерирует миграции; Flyway полагается на вручную написанные SQL-скрипты.
GitOps: Atlas позволяет синхронизировать «source of truth» с репозиторием схемы; в Flyway GitOps возможен, но требует дисциплины по генерации и поддержке версий скриптов.
Usability: при крупных изменениях схема-ориентированный подход Atlas упрощает анализ и ревью; Flyway проще для микрозменений и сценариев CI с простыми SQL-скриптами.
Когда выбирать Flyway: если команда уже имеет десятки ручных версий SQL и нужна минимальная инфраструктура — Flyway быстрее встраивается. Когда выбирать Atlas: если вы хотите GitOps workflow, генерацию миграций и более предсказуемый diff-process.
А golang-migrate?
golang-migrate (релизы активны 2020–2025) — минималистичный инструмент для запуска SQL миграций, часто используется в приложениях на Go. Он компактен и удобен для включения в приложение, но не предоставляет декларативного представления схемы и генерации diff.
Преимущество golang-migrate: простота, встроение в CI и контейнеризацию, легковесность (~1–2 MB бинарника при сборке).
Ограничение: отсутствие механизма для декларативного описания схемы и автоматической генерации миграций; все изменения пишутся вручную как up/down SQL.
Комбинации: возможен гибрид — использовать Atlas для генерации миграций и golang-migrate или Flyway для применения миграций в рантайме, но это добавляет сложность.
Частые вопросы
Как хранить schema.hcl в репозитории?
Храните schema.hcl в корне репозитория в каталоге db/schema или infrastructure/db. Зафиксируйте правило: любые изменения схемы должны сопровождаться генерацией миграции через atlas migrate diff и созданием Pull Request. Так обеспечивается единый источник правды и независимая проверка в CI. Файлы HCL удобны для машинного парсинга и для визуального ревью. Включите форматы и линтеры в pre-commit, чтобы избежать форматных шумов.
Что делать с ручными SQL-патчами, которые уже в production?
Если в production есть ручные изменения, начните с инвентаризации: используйте atlas schema inspect, чтобы снять текущую схему и сохранить её в репозитории как baseline. Создайте миграцию, приводящую репозиторий к состоянию production (baseline migration), и пометьте её как applied. В CI добавьте проверки, чтобы новые миграции не противоречили baseline. Такой подход требует планирования и тестов в staging перед конвертацией в GitOps workflow.
Почему diff иногда показывает мелкие изменения, связанные с whitespace или порядком столбцов?
Diff основан на структурной модели схемы. Atlas стремится к детерминированному выходу, но различия в DDL (например, неявные значения по умолчанию или порядок столбцов) могут приводить к шуму. Решения: нормализуйте схему перед diff (используйте atlas schema inspect --format hcl для стандартизации), настройте процесс ревью, чтобы фильтровать незначимые изменения, и тестируйте генерацию миграций в локальных environment перед PR.
Где хранить миграции: в одном репозитории или рядом с кодом приложения?
Можно хранить миграции рядом с кодом приложения (mono-repo) или в отдельном репозитории-инфраструктуре. Mono-repo даёт простую координацию изменений и atomic commits (код + миграция), но может усложнить права доступа. Отдельный репозиторий удобен для централизованного контроля и общего процесса CD. Решение зависит от команды: если deploy приложения и миграции синхронны, храните их рядом; если команды ролей разные, рассмотрите выделенный repo для миграций и schema.hcl.
Сколько времени занимает rollback миграции в production?
Время отката зависит от объёма данных и характера изменения. Простое удаление индекса — ~1–3 секунды; откат DROP COLUMN с миграцией данных может занимать минуты или часы. Всегда планируйте backup: pg_dump/pg_basebackup перед применением миграций. Для крупных таблиц используйте стратегию zero-downtime: создание новой колонки, фоновые миграции для копирования данных и переключение приложений. Тестируйте откат в staging, чтобы измерить реальные времена и подготовить план rollforward/rollback.
Дополнительные материалы и примеры конфигураций доступны в других руководствах на сайте: DevOps и Database.
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…