squawk-cli

What it is and what it does

Squawk is a linter that parses PostgreSQL SQL and migration files to identify patterns that commonly cause production issues: unsafe index creation, lock-prone constraint additions, serial-type pitfalls, and schema changes that block reads or writes. It runs as a CLI tool and outputs warnings with inline suggestions and remediation examples.

The tool supports multiple reporting formats (TTY, JSON, GitLab, GCC), rule exclusion via CLI flags or `.squawk.toml` config files, and inline SQL comments to suppress specific checks. It integrates with pre-commit hooks, GitHub Actions, and VSCode, making it suitable for catching migration problems before they reach production.

Use it for:

• Review migration files in CI/CD to catch blocking operations (e.g., UNIQUE constraints, index creation) before deployment.
• Enforce team standards on column types (e.g., prefer bigint over serial, text over varchar with length limits).
• Suppress known-safe violations per-file or per-rule via comments or config, reducing noise in large legacy codebases.
• Local pre-commit hook to validate SQL syntax and schema safety before pushing to version control.
• Generate structured JSON reports for custom tooling or dashboards that track migration risk over time.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Linter that analyzes PostgreSQL migrations and SQL statements to detect patterns that risk downtime, lock contention, or schema problems, and suggests corrections.

Yes. Squawk is actively maintained, has no known vulnerabilities, and fills a specific niche—preventing downtime from unsafe Postgres migrations. The permissive dual license and multi-platform binaries lower adoption friction. Install if your team runs Postgres migrations and wants automated guardrails; skip if you do not use Postgres or migrations are rare.

Install

squawk-cli on PyPI

pip install squawk-cli

uv add squawk-cli

poetry add squawk-cli

Installing squawk-cli

Before you install

Medium install friction due to compiled Rust binaries, but pre-built wheels exist for common platforms (macOS x86_64/arm64, Linux x86_64/aarch64, Windows). Last release 8 days ago; active maintenance with 1153 GitHub stars.

License in practice

Dual-licensed under Apache-2.0 OR MIT (permissive). You may choose either license; no restrictions on commercial or private use.

Quickstart

pip install squawk-cli
squawk example.sql
# or check stdin: squawk --stdin-filepath=migration.sql < migration.sql

Requires Python >=3.8. Pre-built binaries available for macOS (Intel/ARM), Linux (x86_64/aarch64), and Windows; source builds require Rust.

Verify before relying

• How many built-in rules are available and what is their coverage of common migration anti-patterns.
• Performance on large SQL files or migration batches.
• Integration maturity with CI/CD systems beyond GitHub Actions.

Package facts

Evidence: squawk_cli-2.62.0-py3-none-macosx_10_12_x86_64.whl; squawk_cli-2.62.0-py3-none-macosx_11_0_arm64.whl; squawk_cli-2.62.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; squawk_cli-2.62.0-py3-none-manylinux_2_28_x86_64.whl; squawk_cli-2.62.0-py3-none-win32.whl; squawk_cli-2.62.0-py3-none-win_amd64.whl

Keywords: postgres, postgresql, linter

Tags

More Quality Assurance packages