☰
06.11.2025

Squawk - линтер для PostgreSQL миграций и SQL: как избежать блокировок и ошибок в базе данных

Squawk — это инструмент статического анализа/линтинга SQL-файлов и миграций для PostgreSQL. Он предназначен для того, чтобы на этапе разработки или в CI проверить миграции и SQL-скрипты на наличие потенциально опасных операций, которые могут привести к блокировкам, простою или нарушению совместимости.
Основная идея: многие схемные изменения (добавление колонок с DEFAULT, переименование, удаление, создание индексов и т.д.) могут вести к длительным блокировкам, ожиданиям или неожиданным простоям. Squawk помогает автоматизировать проверку таких изменений.

Где находится Squawk

Проект Squawk — полностью open-source и доступен на GitHub
Исходный код, документация и примеры конфигураций находятся в репозитории. Там же можно найти релизы для разных систем, Docker-образы, а также ссылки на интеграции с GitHub Actions и примеры настроек.

Почему это актуально

В средах с высокой нагрузкой, большим количеством операций или мультиверсией приложения важно минимизировать риск отказов или простоев при миграциях схемы. Например:

Основные возможности

Установка и быстрый старт

Установка

Пример команд:

npm install -g squawk-cli

или через pip

pip install squawk-cli

или через Docker

docker run --rm -v $(pwd):/data ghcr.io/sbdchd/squawk:latest *.sql

Быстрая проверка

Допустим, у вас есть файл example-migration.sql:

BEGIN;
ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
COMMIT;

Запуск:

squawk example-migration.sql

Вывод может быть таким:

warning[constraint-missing-not-valid]: By default new constraints require a table scan and block writes to the table while that scan occurs.
╭▸ 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-опции и конфиг

Среди опций:

pg_version = "11.0"
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-файлов автоматически запускалась проверка:

repos:
- 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:

# .github/workflows/lint-migrations.yml
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 предоставляет множество встроенных правил, которые помогают выстроить "безопасную" схему миграций. Вот примеры:

Практические шаги внедрения

  1. Установите Squawk в среду разработки/CI (например, через Docker или npm).
  2. Добавьте проверку миграций на этапе pre-commit или в CI pipeline (GitHub, GitLab).
  3. Настройте .squawk.toml с правилами, релевантными вашему окружению (версия PostgreSQL, особенности вашей схемы).
  4. Обучите команду: объясните, какие предупреждения выводит Squawk, почему они важны. Если предупреждение, команда должна понимать, как его исправить (например: "используйте TEXT вместо VARCHAR(100)" или "создавайте индекс CONCURRENTLY").
  5. Внедрите процедуру обработки: если Squawk выдаёт критические предупреждения, миграцию либо откладывают, либо разбивают на безопасные шаги (expand → migrate → contract).
  6. Мониторьте: если после внедрения инструмент снижает количество инцидентов, это показатель эффективности.

Особенности и нюансы

Запустите проект за минуты с VPS в России — предустановленное ПО, высокая производительность и надёжная инфраструктура Serverspace - Арендовать VPS

FAQ

Заключение

Squawk - это как заботливый "ревьюер", который всегда на страже вашей базы данных. Он не даст случайно заблокировать продакшен или внести миграцию, которая повредит пользователям.
Если вы работаете с PostgreSQL и регулярно обновляете схему - дайте Squawk место в вашем CI. Он быстро окупается, предотвращая ошибки, которые стоили бы часов отката и восстановления.

Добавьте его один раз - и пусть миграции станут не источником тревоги, а рутинным, безопасным этапом вашего деплоя.

О Базе знаний Serverspace

База знаний Serverspace - это удобный справочник для разработчиков, системных администраторов и DevOps-инженеров, где собраны пошаговые инструкции, обзоры инструментов и практические руководства по работе с современными технологиями.
Здесь вы найдете статьи о настройке CI/CD, контейнеризации, работе с облачными сервисами, базами данных, системами мониторинга и безопасности.
Наша цель - помочь инженерам автоматизировать рутину, ускорить развертывание инфраструктуры и сделать работу с серверами проще и безопаснее.