https://github.com/erik/squabble
An extensible linter for SQL queries and migrations.
https://github.com/erik/squabble
linter postgres sql static-analysis
Last synced: about 1 month ago
JSON representation
An extensible linter for SQL queries and migrations.
- Host: GitHub
- URL: https://github.com/erik/squabble
- Owner: erik
- License: gpl-3.0
- Created: 2018-12-21T09:00:27.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-10-29T20:35:00.000Z (over 4 years ago)
- Last Synced: 2024-04-26T03:20:47.033Z (about 1 year ago)
- Topics: linter, postgres, sql, static-analysis
- Language: Python
- Homepage: https://squabble.readthedocs.org
- Size: 184 KB
- Stars: 64
- Watchers: 3
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
- awesome-github-repos - erik/squabble - An extensible linter for SQL queries and migrations. (Python)
README
squabble
========
|build-status| |docs| |pypi|
Catch unsafe SQL migrations.
.. code:: console
$ 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
ConstraintNotAllowed
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.
.. code:: console
$ 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!
Installation
------------
.. code-block:: console
$ pip3 install squabble
$ squabble --help
.. note::
Squabble is only supported on Python 3.5+
If you’d like to install from source:
.. code-block:: console
$ git clone https://github.com/erik/squabble.git && cd squabble
$ python3 -m venv ve && source ve/bin/activate
$ python setup.py install
$ squabble --help
Configuration
-------------
To see a list of rules, try
.. code-block:: console
$ squabble --list-rules
Then, to show more verbose information about a rule (such as rationale
and configuration options)
.. code-block:: console
$ squabble --show-rule AddColumnDisallowConstraints
Once a configuration file is in place, it can be passed explicitly on
the command line, or automatically looked up.
.. code-block:: console
$ 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 ``-- squabble-enable:RuleName`` or ``-- squabble-disable:RuleName``.
For example, to disable ``RuleA`` and enable ``RuleB`` just for one file,
this could be done:
.. code-block:: sql
-- squabble-disable:RuleA
-- squabble-enable:RuleB config=value array=1,2,3
SELECT email FROM users WHERE ...;
To prevent squabble from running on a file, use ``-- squabble-disable``. Note
that this will also disable syntax checking. Note that this flag will take
precedence over any other configuration set either on the command line or in
the rest of the file.
Example Configuration
~~~~~~~~~~~~~~~~~~~~~
.. code-block:: json
{
"reporter": "color",
"plugins": [
"/some/directory/with/custom/rules"
],
"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.
Acknowledgments
---------------
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.
.. |build-status| image:: https://img.shields.io/travis/erik/squabble.svg?style=flat
:alt: build status
:target: https://travis-ci.org/erik/squabble
.. |docs| image:: https://readthedocs.org/projects/squabble/badge/?version=stable
:alt: Documentation Status
:target: https://squabble.readthedocs.io/en/stable/?badge=stable
.. |pypi| image:: https://img.shields.io/pypi/v/squabble.svg
:alt: PyPI version
:target: https://pypi.org/project/squabble