---
id: squawk-cli
version: "2.62.0"
license: Apache-2.0 OR MIT
license_treatment: permissive
maintenance: active
---

# squawk-cli — Linter for PostgreSQL migrations

License: permissive · Maintenance: active · Downloads: 520.5K/mo

## 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 above — 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

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

- License: Apache-2.0 OR MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 520.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

postgres migration linter, sql linting tool, postgresql schema checker, database migration validator, sql best practices checker, postgres downtime prevention, migration safety analyzer, postgres-migrations, sql-linting, schema-safety

[View on SkillFed](https://skillfed.io/packages/squawk-cli) · [View on PyPI](https://pypi.org/project/squawk-cli/)