Squawk — это инструмент статического анализа/линтинга SQL-файлов и миграций для PostgreSQL. Он предназначен для того, чтобы на этапе разработки или в CI проверить миграции и SQL-скрипты на наличие потенциально опасных операций, которые могут привести к блокировкам, простою или нарушению совместимости.
Основная идея: многие схемные изменения (добавление колонок с DEFAULT, переименование, удаление, создание индексов и т.д.) могут вести к длительным блокировкам, ожиданиям или неожиданным простоям. Squawk помогает автоматизировать проверку таких изменений.
Где находится Squawk
Проект Squawk — полностью open-source и доступен на GitHub
Исходный код, документация и примеры конфигураций находятся в репозитории. Там же можно найти релизы для разных систем, Docker-образы, а также ссылки на интеграции с GitHub Actions и примеры настроек.
Почему это актуально
В средах с высокой нагрузкой, большим количеством операций или мультиверсией приложения важно минимизировать риск отказов или простоев при миграциях схемы. Например:
- добавление колонки с NON NULL или DEFAULT может вызвать полное сканирование таблицы и блокировки;
- создание индекса без CONCURRENTLY может блокировать записи в таблицу;
- удаление или переименование таблицы/колонки может нарушать обратную совместимость приложения.
Инструменты вроде Squawk позволяют встроить "правила безопасности" в процесс миграций, чтобы предупреждать подобные проблемы ещё до выполнения на продуктиве.
Основные возможности
- Проверка .sql-миграций (и/или произвольных SQL-файлов) на набор правил («антипаттернов») схемных изменений.
- Настраиваемые правила: исключение по-файлам, по правилам, установка версии PostgreSQL.
- Интеграция с CI/CD и GitHub: например, как GitHub Action, который комментирует Pull Request с результатами проверки.
- Поддержка разных способов установки: npm, pip, Docker, двоичные сборки.
Установка и быстрый старт
Установка
Пример команд:
или через pip
или через Docker
Быстрая проверка
Допустим, у вас есть файл example-migration.sql:
ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
COMMIT;
Запуск:
Вывод может быть таким:
╭▸ example-migration.sql:2:24
│
2 │ ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
┰ help: Use `NOT VALID` with a later `VALIDATE CONSTRAINT` call.
warning[disallowed-unique-constraint]: Adding a `UNIQUE` constraint requires an `ACCESS EXCLUSIVE` lock which blocks reads and writes to the table while the index is built.
╭▸ example-migration.sql:2:28
│
2 │ ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│
┰ help: Create an index `CONCURRENTLY` and create the constraint using the index.
Found 2 issues in 1 file (checked 1 source file)
CLI-опции и конфиг
Среди опций:
- --config, -c <path> — указать файл конфигурации (.squawk.toml)
- --exclude-path <pattern> — исключать файлы
- --exclude <rule> — исключать конкретные правила
- --pg-version <version> — указать целевую версию PostgreSQL
- --assume-in-transaction / --no-assume-in-transaction — указать, предполагается ли, что файл миграции запускается внутри транзакции
Пример .squawk.toml:
excluded_rules = [
"require-concurrent-index-creation",
"require-concurrent-index-deletion",
]
assume_in_transaction = true
excluded_paths = [
"005_user_ids.sql",
"*user_ids.sql",
]
Интеграция в рабочий процесс
Pre-commit / Git workflow
Можно добавить Squawk как hook в .pre-commit-config.yaml, чтобы при коммите миграционных SQL-файлов автоматически запускалась проверка:
- repo: https://github.com/sbdchd/squawk
rev: v0.10.0
hooks:
- id: squawk
files: path/to/postgres/migrations/**/*.sql
CI/CD и Pull Request
Для интеграции на уровне GitHub можно использовать официальный Action:
name: Lint Migrations
on: pull_request
jobs:
lint_migrations:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: sbdchd/squawk-action@v2
with:
pattern: "migrations/*.sql"
version: "latest"
Таким образом каждый PR, который содержит SQL-миграции, будет автоматически проверен, и в комментариях появятся предупреждения, если будут найдены нарушения правил.
Правила (Rules) — важная часть
Squawk предоставляет множество встроенных правил, которые помогают выстроить "безопасную" схему миграций. Вот примеры:
- prefer-bigint-over-int — использовать bigint вместо int, чтобы не столкнуться с ограничением 32-битного int.
- prefer-identity — вместо serial использовать GENERATED BY DEFAULT AS IDENTITY — лучше для управления зависимостями схемы.
- disallowed-unique-constraint — запрет на добавление UNIQUE-констрейнта, который потребует ACCESS EXCLUSIVE блокировки.
- require-concurrent-index-creation — заставить использовать CREATE INDEX CONCURRENTLY чтобы избежать блокирования.
- adding-field-with-default, adding-not-nullable-field — добавление колонки с дефолтом или NOT NULL на больших таблицах часто вызывает полную блокировку.
Полный список правил и описание доступны на официальной документации.
Практические шаги внедрения
- Установите Squawk в среду разработки/CI (например, через Docker или npm).
- Добавьте проверку миграций на этапе pre-commit или в CI pipeline (GitHub, GitLab).
- Настройте .squawk.toml с правилами, релевантными вашему окружению (версия PostgreSQL, особенности вашей схемы).
- Обучите команду: объясните, какие предупреждения выводит Squawk, почему они важны. Если предупреждение, команда должна понимать, как его исправить (например: "используйте TEXT вместо VARCHAR(100)" или "создавайте индекс CONCURRENTLY").
- Внедрите процедуру обработки: если Squawk выдаёт критические предупреждения, миграцию либо откладывают, либо разбивают на безопасные шаги (expand → migrate → contract).
- Мониторьте: если после внедрения инструмент снижает количество инцидентов, это показатель эффективности.
Особенности и нюансы
- Squawk не заменяет тестирование на нагрузке или staging-окружение — он статически анализирует SQL, а не реально запускает миграцию под нагрузкой. Поэтому он дополнение, а не единственный защитный механизм.
- Некоторые миграции по-своему исключительные: например, создание индексов с CONCURRENTLY нельзя запускать внутри транзакции. Squawk может предупредить, но вам всё равно придётся понять и спланировать такие шаги.
- В проектах с историей и большими таблицами стоит уделить внимание “разделению миграций” - разбивать серьёзные изменения на несколько шагов, и Squawk помогает выявить потенциальные блокирующие операции.
FAQ
- Что именно проверяет Squawk?
Squawk анализирует SQL-файлы и миграции, чтобы обнаружить опасные изменения — например, создание индексов без CONCURRENTLY, добавление NOT NULL без дефолта, удаление колонок или ограничений, которые могут вызвать блокировку. - Можно ли использовать Squawk с другими СУБД, кроме PostgreSQL?
Нет, инструмент создан именно для PostgreSQL и использует особенности её синтаксиса и поведения блокировок. - Как встроить Squawk в CI/CD?
Вы можете добавить Squawk в pipeline GitHub Actions, GitLab или любой другой CI — он будет автоматически проверять SQL-файлы при каждом Pull Request или push. - Можно ли отключать отдельные правила?
Да, конфигурация .squawk.toml позволяет исключать определённые проверки, если они не актуальны для вашего проекта. - Поддерживается ли Windows?
Да, Squawk работает на Windows, macOS и Linux. Самый простой способ установки — через npm, pip или Docker.
Заключение
Squawk - это как заботливый "ревьюер", который всегда на страже вашей базы данных. Он не даст случайно заблокировать продакшен или внести миграцию, которая повредит пользователям.
Если вы работаете с PostgreSQL и регулярно обновляете схему - дайте Squawk место в вашем CI. Он быстро окупается, предотвращая ошибки, которые стоили бы часов отката и восстановления.
Добавьте его один раз - и пусть миграции станут не источником тревоги, а рутинным, безопасным этапом вашего деплоя.
О Базе знаний Serverspace
База знаний Serverspace - это удобный справочник для разработчиков, системных администраторов и DevOps-инженеров, где собраны пошаговые инструкции, обзоры инструментов и практические руководства по работе с современными технологиями.
Здесь вы найдете статьи о настройке CI/CD, контейнеризации, работе с облачными сервисами, базами данных, системами мониторинга и безопасности.
Наша цель - помочь инженерам автоматизировать рутину, ускорить развертывание инфраструктуры и сделать работу с серверами проще и безопаснее.