Новости
Обновление услуги LLM: управление API-ключами, моделями и расходами
DF
октября 12, 2025
Обновлено ноября 6, 2025

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

PostgreSQL

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, двоичные сборки.

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

Установка

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

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-опции и конфиг

Среди опций:

  • --config, -c <path> — указать файл конфигурации (.squawk.toml)
  • --exclude-path <pattern> — исключать файлы
  • --exclude <rule> — исключать конкретные правила
  • --pg-version <version> — указать целевую версию PostgreSQL
  • --assume-in-transaction / --no-assume-in-transaction — указать, предполагается ли, что файл миграции запускается внутри транзакции
    Пример .squawk.toml:
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 предоставляет множество встроенных правил, которые помогают выстроить "безопасную" схему миграций. Вот примеры:

  • 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 на больших таблицах часто вызывает полную блокировку.
    Полный список правил и описание доступны на официальной документации.

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

    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. Мониторьте: если после внедрения инструмент снижает количество инцидентов, это показатель эффективности.

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

    • Squawk не заменяет тестирование на нагрузке или staging-окружение — он статически анализирует SQL, а не реально запускает миграцию под нагрузкой. Поэтому он дополнение, а не единственный защитный механизм.
    • Некоторые миграции по-своему исключительные: например, создание индексов с CONCURRENTLY нельзя запускать внутри транзакции. Squawk может предупредить, но вам всё равно придётся понять и спланировать такие шаги.
    • В проектах с историей и большими таблицами стоит уделить внимание “разделению миграций” - разбивать серьёзные изменения на несколько шагов, и Squawk помогает выявить потенциальные блокирующие операции.
    Запустите проект за минуты с VPS в России — предустановленное ПО, высокая производительность и надёжная инфраструктура Serverspace - Арендовать VPS

    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, контейнеризации, работе с облачными сервисами, базами данных, системами мониторинга и безопасности.
    Наша цель - помочь инженерам автоматизировать рутину, ускорить развертывание инфраструктуры и сделать работу с серверами проще и безопаснее.

    Оценка:
    5 из 5
    Аverage rating : 5
    Оценок: 1
    191028 Санкт-Петербург Литейный пр., д. 26, Лит. А
    +7 (812) 403-06-99
    700 300
    ООО «ИТГЛОБАЛКОМ ЛАБС»
    700 300

    Вам также может быть интересно...