pgschema - это инструмент командной строки (CLI) для работы со схемами баз данных PostgreSQL в декларативном стиле, аналогичном подходу Terraform.
Он позволяет описывать желаемое состояние схемы базы данных в виде кода и автоматически применять изменения, чтобы привести существующую базу к этому состоянию.
Инструмент упрощает управление миграциями, устраняя необходимость вручную писать SQL-скрипты и отслеживать версии изменений.
pgschema самостоятельно анализирует разницу между текущей и целевой схемой, генерирует план изменений и применяет его в безопасной транзакции.
Для чего используется pgschema
pgschema помогает:
- автоматизировать процесс обновления схем PostgreSQL;
- внедрить подход "Database as Code";
- интегрировать управление схемами в CI/CD-процессы;
- контролировать изменения в схемах через Git (pull request, review, откат);
- упростить сопровождение мультиарендных (multi-tenant) баз данных.
Установка
- Загрузите бинарный файл из официального репозитория GitHub.
- Распакуйте архив и добавьте бинарный файл в PATH.
- Проверьте установку командой:
pgschema --version
На Windows инструмент можно запустить через WSL.
Основные команды
1. Снятие дампа схемы
PGPASSWORD=pass pgschema dump \
--host localhost \
--db mydb \
--user postgres \
--schema public > schema.sqlКоманда сохраняет текущее состояние схемы в файл schema.sql.
Этот файл можно редактировать вручную — добавлять таблицы, поля, индексы и т.д.
2. Планирование изменений
PGPASSWORD=pass pgschema plan \
--host localhost \
--db mydb \
--user postgres \
--schema public \
--file schema.sql \
--output-human stdout \
--output-json plan.jsonИнструмент сравнивает текущее состояние базы с файлом схемы и выводит план изменений:
Plan: 1 to modify.
Summary by type:
tables: 1 to modify
Tables:
~ users
+ age (column)3. Применение изменений
PGPASSWORD=pass pgschema apply \
--host localhost \
--db mydb \
--user postgres \
--schema public \
--plan plan.json \
--auto-approvepgschema применит план и выполнит все необходимые DDL-запросы (например, ALTER TABLE).
Преимущества
- Декларативный подход - не нужно вручную писать миграции, просто редактируйте желаемое состояние.
- Без таблицы версий - инструмент сам анализирует различия между базой и схемой.
- Поддержка CI/CD и GitOps - схемы можно хранить в репозитории, генерировать план изменений при pull request.
- Транзакционность - все изменения выполняются в одной транзакции, что снижает риск ошибок.
- Поддержка мультиарендных схем - можно управлять несколькими схемами или клиентами.
Недостатки
- Нет официальной поддержки Windows - требуется WSL или контейнер.
- Нет классического rollback - инструмент не хранит историю миграций, поэтому отмена изменений производится вручную.
- Необходим контроль дисциплины - файл схемы должен всегда соответствовать фактическому состоянию базы.
- Ограничена совместимость - поддерживаются PostgreSQL 14–17.
Вывод
pgschema - это современный инструмент, идеально подходящий для DevOps-инженеров и администраторов баз данных, которые внедряют подход Infrastructure as Code и стремятся автоматизировать управление схемами PostgreSQL.
Он помогает упростить процесс версионирования и обновления схем, обеспечивая прозрачность, воспроизводимость и контроль изменений на всех этапах CI/CD.
На практике стоит использовать pgschema для:
- Автоматизации миграций схем при развёртывании новых окружений;
- Проверки согласованности структуры баз данных между тестовыми и продакшен-серверами;
- Хранения схем в Git для облегчённого ревью и отката изменений;
- Интеграции с пайплайнами Jenkins, GitLab CI или GitHub Actions для полной инфраструктурной автоматизации.
Для команд, работающих с PostgreSQL в облачных средах или контейнеризированных проектах, pgschema может стать надёжной альтернативой инструментам вроде Flyway и Liquibase, обеспечивая более простой и декларативный подход к управлению схемами.
FAQ
- Что делать, если схема изменилась вручную?
pgschema при следующем запуске определит различия и предложит обновить базу или файл схемы. Рекомендуется избегать ручных изменений. - Можно ли использовать инструмент для нескольких баз данных?
Да. pgschema поддерживает работу с несколькими схемами и базами - достаточно указать разные подключения и файлы. - Безопасно ли применять изменения в продакшене?
Да, если вы используете plan перед apply и внимательно просматриваете список DDL-операций. Всегда рекомендуется предварительно тестировать в staging-среде. - Можно ли использовать pgschema в CI/CD?
Да. Его легко встроить в pipeline:
шаг 1 - генерация плана (pgschema plan);
шаг 2 - проверка плана;
шаг 3 - применение (pgschema apply --auto-approve).