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-cliou via pip
pip install squawk-cliou com Docker
docker run --rm -v $(pwd):/data ghcr.io/sbdchd/squawk:latest *.sqlVerificaçã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.sqlSaí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/**/*.sqlCI/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.
