05.11.2025

Squawk - a linter for PostgreSQL migrations and SQL: how to avoid deadlocks and errors in the database

Squawk is a static analysis / linting tool for PostgreSQL SQL files and schema migrations. It is designed to check migrations and SQL scripts during development or in CI pipelines for potentially dangerous operations that could lead to locks, downtime, or compatibility issues.
The core idea: many schema changes — adding columns with DEFAULT values, renaming, dropping columns, creating indexes, etc. — can cause long table locks or unexpected outages. Squawk automates the detection of such risky changes.

Where Squawk is Located

The Squawk project is fully open-source and available on GitHub. The repository includes the source code, documentation, configuration examples, releases for different systems, Docker images, and integrations such as GitHub Actions.

Why This Matters

In high-load environments, with mission-critical databases or multiple application versions running at once, it is important to minimize migration risks. For example:

Adding a column with NOT NULL or DEFAULT may trigger a full table scan and write locks.
Creating an index without CONCURRENTLY may block inserts and updates.
Dropping or renaming tables/columns may break backward compatibility. Tools like Squawk embed “safety rules” into the migration process, catching issues before they hit production.

Key Features

Analysis of .sql migration files (or arbitrary SQL) using rules to detect schema change anti-patterns.
Configurable rules: per file, per rule, PostgreSQL version control.
CI/CD and GitHub integration — e.g. a GitHub Action posting comments directly to Pull Requests.
Multiple installation options: npm, pip, Docker, prebuilt binaries.

Installation & Quick Start

Installation

Example commands:

npm install -g squawk-cli

Or via pip:

pip install squawk-cli

Or via Docker:

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

Quick Check

Assume you have an example-migration.sql:

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

Run:

squawk example-migration.sql

Possible output:

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)

CLI Options & Config

Main flags include:

--config, -c <path> — specify .squawk.toml
--exclude-path <pattern> — exclude particular files
--exclude <rule> — disable specific rules
--pg-version <version> — set target PostgreSQL version
--assume-in-transaction / --no-assume-in-transaction — whether migrations run inside a transaction

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

Workflow Integration

Pre-Commit / Git Workflow

Add Squawk as a hook in .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 & Pull Requests

Example 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"

Rules — Core Element

Some examples of built-in rules:

prefer-bigint-over-int — avoid hitting 32-bit integer limits.
prefer-identity — use GENERATED ... AS IDENTITY instead of serial.
disallowed-unique-constraint — UNIQUE may require ACCESS EXCLUSIVE locks.
require-concurrent-index-creation — enforce CREATE INDEX CONCURRENTLY.
adding-field-with-default / adding-not-nullable-field — warns about blocking operations on large tables.

FAQ

What does Squawk check? It detects unsafe schema changes — blocking constraint creation, adding NOT NULL columns, index creation without CONCURRENTLY, column drops, etc.
Does it support other databases? No, Squawk is built specifically for PostgreSQL.
Does it work on Windows? Yes — supported on Windows, macOS, and Linux via npm, pip, or Docker.

Conclusion

Squawk acts like a careful reviewer standing guard over your database. It prevents risky migrations from reaching production, avoiding downtime and emergency rollbacks. If you work with PostgreSQL and frequently deploy schema changes — give Squawk a place in your CI. It quickly pays for itself by preventing incidents. Add it once — and let migrations become a safe, predictable part of deployment.

About the Serverspace Knowledge Base

The Serverspace Knowledge Base is a comprehensive and practical resource created for developers, system administrators, and DevOps engineers who work with modern cloud infrastructures. It serves as a hub of expertise where you can find detailed, step-by-step tutorials, configuration examples, and best practices for managing scalable systems.

From setting up CI/CD pipelines and automating infrastructure deployment to configuring databases, monitoring performance, and ensuring system security — the Knowledge Base covers the entire lifecycle of cloud application management. Each article is written by technical experts and is designed to be clear, actionable, and directly applicable to real-world tasks.

Whether you're exploring containerization with Docker and Kubernetes, fine-tuning PostgreSQL performance, or learning to use modern DevOps tools like Terraform and Ansible, Serverspace provides structured, easy-to-follow guidance. Our goal is to help engineers simplify routine operations, optimize workflows, and minimize downtime through automation and reliable infrastructure design.

The Knowledge Base grows continuously, reflecting new technologies and industry trends. It’s not just a documentation hub - it’s a living learning platform that empowers teams to build, deploy, and maintain applications with confidence and efficiency.