05.11.2025

Squawk - linter para migrações PostgreSQL e SQL: como evitar bloqueios e erros no banco de dados

Squawk — é uma ferramenta de análise estática (linter) para arquivos SQL e migrações do PostgreSQL. Ela foi projetada para verificar, durante o desenvolvimento ou no pipeline de CI, migrações e scripts SQL em busca de operações potencialmente perigosas que possam causar bloqueios, tempo de inatividade ou problemas de compatibilidade.
A ideia central é simples: muitas alterações de esquema (como adicionar colunas com DEFAULT, renomear, excluir ou criar índices) podem levar a bloqueios longos ou paralisações inesperadas. O Squawk ajuda a automatizar a verificação dessas mudanças.

Onde encontrar o Squawk

O projeto Squawk é totalmente open-source e está disponível no GitHub. O código-fonte, a documentação e os exemplos de configuração estão disponíveis no repositório. Lá você também encontrará versões para diferentes sistemas, imagens Docker, além de integrações com GitHub Actions e exemplos de configuração.

Por que isso é importante

Em ambientes com alta carga, múltiplas versões de aplicativos ou grande volume de transações, é fundamental minimizar o risco de falhas durante migrações de esquema. Por exemplo:

Adicionar uma coluna com NOT NULL ou DEFAULT pode causar uma varredura completa da tabela e bloqueios.
Criar um índice sem CONCURRENTLY pode bloquear gravações na tabela.
Excluir ou renomear uma tabela/coluna pode quebrar a compatibilidade retroativa do aplicativo. Ferramentas como o Squawk ajudam a incorporar “regras de segurança” no processo de migração, prevenindo esses problemas antes que cheguem ao ambiente de produção.

Principais recursos

Verificação de migrações .sql (ou arquivos SQL arbitrários) com base em regras de “antipadrões” de alterações de esquema.
Regras configuráveis: exclusão por arquivos, por regras e definição da versão do PostgreSQL.
Integração com CI/CD e GitHub — por exemplo, como uma GitHub Action que comenta o Pull Request com os resultados da verificação.
Várias opções de instalação: npm, pip, Docker ou binários prontos.

Instalação e início rápido

Instalação

Exemplos de comando:

npm install -g squawk-cli

ou via pip

pip install squawk-cli

ou com Docker

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

Verificação rápida

Suponha que você tenha um arquivo example-migration.sql:

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

Execução:

squawk example-migration.sql

Saída possível:

warning[constraint-missing-not-valid]: By default new constraints require a table scan and block writes to the table while that scan occurs.
...
Found 2 issues in 1 file (checked 1 source file)

Opções CLI e configuração

Entre as opções estão:

--config, -c <path> — especificar o arquivo de configuração (.squawk.toml)
--exclude-path <pattern> — excluir arquivos
--exclude <rule> — excluir regras específicas
--pg-version <version> — definir a versão do PostgreSQL
--assume-in-transaction / --no-assume-in-transaction — indicar se a migração é executada dentro de uma transação

Exemplo de .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",
]

Integração ao fluxo de trabalho

Pre-commit / Git workflow

Adicione o Squawk como hook no arquivo .pre-commit-config.yaml:

repos: - repo: https://github.com/sbdchd/squawk rev: v0.10.0 hooks: - id: squawk files: path/to/postgres/migrations/**/*.sql

CI/CD e Pull Request

Você pode usar a GitHub Action oficial:

# .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"

Regras (Rules)

O Squawk inclui várias regras integradas que ajudam a manter migrações seguras, como:

prefer-bigint-over-int — use bigint em vez de int.
prefer-identity — prefira GENERATED BY DEFAULT AS IDENTITY em vez de serial.
disallowed-unique-constraint — impede UNIQUE que causa bloqueios de tabela.
require-concurrent-index-creation — exige CREATE INDEX CONCURRENTLY.
adding-field-with-default — alerta sobre colunas com DEFAULT ou NOT NULL em tabelas grandes.

FAQ

O que o Squawk verifica? Ele analisa arquivos SQL e migrações, identificando alterações arriscadas que podem causar bloqueios, como criação de índices sem CONCURRENTLY ou remoção de colunas.
Posso usar com outro banco além do PostgreSQL? Não, o Squawk é feito exclusivamente para o PostgreSQL.
Funciona em Windows? Sim, ele funciona no Windows, macOS e Linux — com instalação via npm, pip ou Docker.

Conclusão

Squawk é como um revisor cuidadoso, sempre de olho na integridade do seu banco de dados. Ele ajuda a evitar migrações perigosas e bloqueios inesperados, tornando seus deploys mais seguros e previsíveis. Se você trabalha com PostgreSQL e realiza migrações com frequência — adote o Squawk no seu pipeline. Ele se paga rapidamente, evitando horas de rollback e recuperação.

Sobre a Base de Conhecimento Serverspace

A Base de Conhecimento Serverspace é um guia prático para desenvolvedores, administradores de sistemas e engenheiros DevOps. Aqui você encontra tutoriais passo a passo, revisões de ferramentas e guias práticos sobre CI/CD, contêineres, bancos de dados, segurança e automação de infraestrutura. Nosso objetivo é ajudar profissionais a simplificar processos, reduzir o tempo de configuração e tornar o trabalho com servidores mais seguro e eficiente.