Skip to main content

An extensible linter for SQL

Project description

build status Documentation Status PyPI version

Catch unsafe SQL migrations.

$ squabble sql/migration.sql
sql/migration.sql:4:46 ERROR: column "uh_oh" has a disallowed constraint [1004]
ALTER TABLE big_table ADD COLUMN uh_oh integer DEFAULT 0;
# Use --explain to get more information on a lint violation
$ squabble --explain 1004
     When adding a column to an existing table, certain constraints can have
     unintentional side effects, like locking the table or introducing
     performance issues.

Squabble can also be integrated with your editor to catch errors in SQL files.

$ echo 'SELECT * FROM WHERE x = y;' | squabble --reporter=plain
stdin:1:15 CRITICAL: syntax error at or near "WHERE"

Currently, most of the rules have been focused on Postgres and its quirks. However, squabble can parse any ANSI SQL and new rules that are specific to other databases are appreciated!


$ pip3 install squabble
$ squabble --help

If you’d like to install from source:

$ git clone && cd squabble
$ python3 -m venv ve && source ve/bin/activate
$ python install
$ squabble --help


To see a list of rules, try

$ squabble --list-rules

Then, to show more verbose information about a rule (such as rationale and configuration options)

$ squabble --show-rule AddColumnsDisallowConstraints

Once a configuration file is in place, it can be passed explicitly on the command line, or automatically looked up.

$ squabble -c path/to/config ...

If not explicitly given on the command line, squabble will look for a file named .squabblerc in the following places (in order):

  • ./.squabblerc

  • (git_repo_root)/.squabblerc

  • ~/.squabblerc

Per-File Configuration

Configuration can also be applied at the file level by using SQL line comments in the form -- enable:RuleName or -- disable:RuleName.

For example, to disable RuleA and enable RuleB just for one file, this could be done:

-- disable:RuleA
-- enable:RuleB config=value array=1,2,3
SELECT email FROM users WHERE ...;

Example Configuration

  "reporter": "color",

  "plugins": [

  "rules": {
    "AddColumnsDisallowConstraints": {
      "disallowed": ["DEFAULT", "FOREIGN", "NOT NULL"]

Prior Art

squabble is of course not the first tool in this space. If it doesn’t fit your needs, consider one of these tools:

  • sqlcheck - regular expression based (rather than parsing), focuses more on SELECT statements than migrations.

  • sqlint - checks that the syntax of a file is valid. Uses the same parsing library as squabble.

  • sqlfluff - focused more on style and formatting, seems to still be a work in progress.


This project would not be possible without:

  • libpg_query - Postgres query parser

  • pglast - Python bindings to libpg_query

  • Postgres - …obviously

The logo image used in the documentation is created by Gianni - Dolce Merda from the Noun Project.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

squabble-1.3.2.tar.gz (30.4 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page