{"id":13626171,"url":"https://github.com/sbdchd/squawk","last_synced_at":"2026-02-28T23:04:30.069Z","repository":{"id":37793353,"uuid":"270156402","full_name":"sbdchd/squawk","owner":"sbdchd","description":"🐘 linter for PostgreSQL, focused on migrations","archived":false,"fork":false,"pushed_at":"2025-04-03T03:30:59.000Z","size":7817,"stargazers_count":713,"open_issues_count":45,"forks_count":43,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-13T06:14:09.257Z","etag":null,"topics":["linter","postgres","postgresql","rust","sql"],"latest_commit_sha":null,"homepage":"https://squawkhq.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbdchd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-07T01:28:56.000Z","updated_at":"2025-04-12T14:26:46.000Z","dependencies_parsed_at":"2023-12-13T02:29:57.619Z","dependency_job_id":"50e8cf60-518d-4901-89e9-ebd1756678c7","html_url":"https://github.com/sbdchd/squawk","commit_stats":{"total_commits":271,"total_committers":29,"mean_commits":9.344827586206897,"dds":0.5904059040590406,"last_synced_commit":"0917fe45fc68bfe0863bfe73551a122143d6e433"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbdchd%2Fsquawk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbdchd%2Fsquawk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbdchd%2Fsquawk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbdchd%2Fsquawk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbdchd","download_url":"https://codeload.github.com/sbdchd/squawk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670435,"owners_count":21142904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linter","postgres","postgresql","rust","sql"],"created_at":"2024-08-01T21:02:11.781Z","updated_at":"2026-02-26T07:55:46.626Z","avatar_url":"https://github.com/sbdchd.png","language":"Rust","readme":"# squawk [![npm](https://img.shields.io/npm/v/squawk-cli)](https://www.npmjs.com/package/squawk-cli)\n\n\u003e Linter for Postgres migrations \u0026 SQL\n\n[Quick Start](https://squawkhq.com/docs/) | [Playground](https://play.squawkhq.com) | [Rules Documentation](https://squawkhq.com/docs/rules) | [GitHub Action](https://github.com/sbdchd/squawk-action) | [DIY GitHub Integration](https://squawkhq.com/docs/github_app)\n\n## Why?\n\nPrevent unexpected downtime caused by database migrations and encourage best\npractices around Postgres schemas and SQL.\n\n## Install\n\n```shell\nnpm install -g squawk-cli\n\n# or via PYPI\npip install squawk-cli\n\n# or install binaries directly via the releases page\nhttps://github.com/sbdchd/squawk/releases\n```\n\n### Or via Docker\n\nYou can also run Squawk using Docker. The official image is available on GitHub Container Registry.\n\n```shell\n# Assuming you want to check sql files in the current directory\ndocker run --rm -v $(pwd):/data ghcr.io/sbdchd/squawk:latest *.sql\n```\n\n### Or via the Playground\n\nUse the WASM powered playground to check your SQL locally in the browser!\n\n\u003chttps://play.squawkhq.com\u003e\n\n### Or via VSCode\n\n\u003chttps://marketplace.visualstudio.com/items?itemName=sbdchd.squawk\u003e\n\n## Usage\n\n```shell\n❯ squawk example.sql\nwarning[prefer-bigint-over-int]: Using 32-bit integer fields can result in hitting the max `int` limit.\n  ╭▸ example.sql:6:10\n  │\n6 │     \"id\" serial NOT NULL PRIMARY KEY,\n  │          ━━━━━━\n  │\n  ├ help: Use 64-bit integer values instead to prevent hitting this limit.\n  ╭╴\n6 │     \"id\" bigserial NOT NULL PRIMARY KEY,\n  ╰╴         +++\nwarning[prefer-identity]: Serial types make schema, dependency, and permission management difficult.\n  ╭▸ example.sql:6:10\n  │\n6 │     \"id\" serial NOT NULL PRIMARY KEY,\n  │          ━━━━━━\n  │\n  ├ help: Use an `IDENTITY` column instead.\n  ╭╴\n6 -     \"id\" serial NOT NULL PRIMARY KEY,\n6 +     \"id\" integer generated by default as identity NOT NULL PRIMARY KEY,\n  ╰╴\nwarning[prefer-text-field]: Changing the size of a `varchar` field requires an `ACCESS EXCLUSIVE` lock, that will prevent all reads and writes to the table.\n  ╭▸ example.sql:7:13\n  │\n7 │     \"alpha\" varchar(100) NOT NULL\n  │             ━━━━━━━━━━━━\n  │\n  ├ help: Use a `TEXT` field with a `CHECK` constraint.\n  ╭╴\n7 -     \"alpha\" varchar(100) NOT NULL\n7 +     \"alpha\" text NOT NULL\n  ╰╴\nwarning[require-concurrent-index-creation]: During normal index creation, table updates are blocked, but reads are still allowed.\n   ╭▸ example.sql:10:1\n   │\n10 │ CREATE INDEX \"field_name_idx\" ON \"table_name\" (\"field_name\");\n   │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   │\n   ├ help: Use `concurrently` to avoid blocking writes.\n   ╭╴\n10 │ CREATE INDEX concurrently \"field_name_idx\" ON \"table_name\" (\"field_name\");\n   ╰╴             ++++++++++++\nwarning[constraint-missing-not-valid]: By default new constraints require a table scan and block writes to the table while that scan occurs.\n   ╭▸ example.sql:12:24\n   │\n12 │ ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);\n   │                        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   │\n   ╰ help: Use `NOT VALID` with a later `VALIDATE CONSTRAINT` call.\nwarning[disallowed-unique-constraint]: Adding a `UNIQUE` constraint requires an `ACCESS EXCLUSIVE` lock which blocks reads and writes to the table while the index is built.\n   ╭▸ example.sql:12:28\n   │\n12 │ ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);\n   │                            ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   │\n   ╰ help: Create an index `CONCURRENTLY` and create the constraint using the index.\n\nFind detailed examples and solutions for each rule at https://squawkhq.com/docs/rules\nFound 6 issues in 1 file (checked 1 source file)\n```\n\n### `squawk --help`\n\n```\nsquawk\nFind problems in your SQL\n\nUSAGE:\n    squawk [FLAGS] [OPTIONS] [path]... [SUBCOMMAND]\n\nFLAGS:\n        --assume-in-transaction\n            Assume that a transaction will wrap each SQL file when run by a migration tool\n\n            Use --no-assume-in-transaction to override this setting in any config file that exists\n    -h, --help\n            Prints help information\n\n    -V, --version\n            Prints version information\n\n        --verbose\n            Enable debug logging output\n\n\nOPTIONS:\n    -c, --config \u003cconfig-path\u003e\n            Path to the squawk config file (.squawk.toml)\n\n        --debug \u003cformat\u003e\n            Output debug info [possible values: Lex, Parse]\n\n        --exclude-path \u003cexcluded-path\u003e...\n            Paths to exclude\n\n            For example: --exclude-path=005_user_ids.sql --exclude-path=009_account_emails.sql\n\n            --exclude-path='*user_ids.sql'\n\n    -e, --exclude \u003crule\u003e...\n            Exclude specific warnings\n\n            For example: --exclude=require-concurrent-index-creation,ban-drop-database\n\n        --pg-version \u003cpg-version\u003e\n            Specify postgres version\n\n            For example: --pg-version=13.0\n        --reporter \u003creporter\u003e\n            Style of error reporting [possible values: Tty, Gcc, Json]\n\n        --stdin-filepath \u003cfilepath\u003e\n            Path to use in reporting for stdin\n\n\nARGS:\n    \u003cpath\u003e...\n            Paths to search\n\n\nSUBCOMMANDS:\n    help                Prints this message or the help of the given subcommand(s)\n    upload-to-github    Comment on a PR with Squawk's results\n```\n\n## Rules\n\nIndividual rules can be disabled via the `--exclude` flag\n\n```shell\nsquawk --exclude=adding-field-with-default,disallowed-unique-constraint example.sql\n```\n\n### Disabling rules via comments\n\nRule violations can be ignored via the `squawk-ignore` comment:\n\n```sql\n-- squawk-ignore ban-drop-column\nalter table t drop column c cascade;\n```\n\nYou can also ignore multiple rules by making a comma seperated list:\n\n```sql\n-- squawk-ignore ban-drop-column, renaming-column,ban-drop-database\nalter table t drop column c cascade;\n```\n\nTo ignore a rule for the entire file, use `squawk-ignore-file`:\n\n```sql\n-- squawk-ignore-file ban-drop-column\nalter table t drop column c cascade;\n-- also ignored!\nalter table t drop column d cascade;\n```\n\nOr leave off the rule names to ignore all rules for the file\n\n```sql\n-- squawk-ignore-file\nalter table t drop column c cascade;\ncreate table t (a int);\n```\n\n### Configuration file\n\nRules can also be disabled with a configuration file.\n\nBy default, Squawk will traverse up from the current directory to find a `.squawk.toml` configuration file. You may specify a custom path with the `-c` or `--config` flag.\n\n```shell\nsquawk --config=~/.squawk.toml example.sql\n```\n\nThe `--exclude` flag will always be prioritized over the configuration file.\n\n**Example `.squawk.toml`**\n\n```toml\nexcluded_rules = [\n    \"require-concurrent-index-creation\",\n    \"require-concurrent-index-deletion\",\n]\n```\n\nSee the [Squawk website](https://squawkhq.com/docs/rules) for documentation on each rule with examples and reasoning.\n\n## Bot Setup\n\nSquawk works as a CLI tool but can also create comments on GitHub Pull\nRequests using the `upload-to-github` subcommand.\n\nHere's an example comment created by `squawk` using the `example.sql` in the repo:\n\n\u003chttps://github.com/sbdchd/squawk/pull/14#issuecomment-647009446\u003e\n\nSee the [\"GitHub Integration\" docs](https://squawkhq.com/docs/github_app) for more information.\n\n## `pre-commit` hook\n\nIntegrate Squawk into Git workflow with [pre-commit](https://pre-commit.com/). Add the following\nto your project's `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n  - repo: https://github.com/sbdchd/squawk\n    rev: 2.42.0\n    hooks:\n      - id: squawk\n        files: path/to/postgres/migrations/written/in/sql\n```\n\nNote the `files` parameter as it specifies the location of the files to be linted.\n\n## Prior Art / Related\n\n- \u003chttps://github.com/erik/squabble\u003e\n- \u003chttps://github.com/yandex/zero-downtime-migrations\u003e\n- \u003chttps://github.com/tbicr/django-pg-zero-downtime-migrations\u003e\n- \u003chttps://github.com/3YOURMIND/django-migration-linter\u003e\n- \u003chttps://github.com/ankane/strong_migrations\u003e\n- \u003chttps://github.com/AdmTal/PostgreSQL-Query-Lock-Explainer\u003e\n- \u003chttps://github.com/stripe/pg-schema-diff\u003e\n- \u003chttps://github.com/kristiandupont/schemalint\u003e\n- \u003chttps://github.com/supabase-community/postgres-language-server\u003e\n- \u003chttps://github.com/premium-minds/sonar-postgres-plugin\u003e\n- \u003chttps://engineering.fb.com/2022/11/30/data-infrastructure/static-analysis-sql-queries/\u003e\n- \u003chttps://github.com/xNaCly/sqleibniz\u003e\n- \u003chttps://github.com/sqlfluff/sqlfluff\u003e\n- \u003chttps://atlasgo.io/lint/analyzers\u003e\n- \u003chttps://github.com/tobymao/sqlglot\u003e\n- \u003chttps://github.com/paupino/pg_parse\u003e\n- \u003chttps://github.com/sql-formatter-org/sql-formatter\u003e\n- \u003chttps://github.com/darold/pgFormatter\u003e\n- \u003chttps://github.com/sqls-server/sqls\u003e\n- \u003chttps://github.com/joe-re/sql-language-server\u003e\n- \u003chttps://github.com/nene/sql-parser-cst\u003e\n  - \u003chttps://github.com/nene/prettier-plugin-sql-cst\u003e\n- \u003chttps://www.sqlstyle.guide\u003e\n- \u003chttps://github.com/ivank/potygen\u003e\n\n## Related Blog Posts / SE Posts / PG Docs\n\n- \u003chttps://www.braintreepayments.com/blog/safe-operations-for-high-volume-postgresql/\u003e\n- \u003chttps://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/\u003e\n- \u003chttps://www.citusdata.com/blog/2018/02/22/seven-tips-for-dealing-with-postgres-locks/\u003e\n- \u003chttps://realpython.com/create-django-index-without-downtime/#non-atomic-migrations\u003e\n- \u003chttps://dba.stackexchange.com/questions/158499/postgres-how-is-set-not-null-more-efficient-than-check-constraint\u003e\n- \u003chttps://www.postgresql.org/docs/10/sql-altertable.html#SQL-ALTERTABLE-NOTES\u003e\n- \u003chttps://www.postgresql.org/docs/current/explicit-locking.html\u003e\n- \u003chttps://benchling.engineering/move-fast-and-migrate-things-how-we-automated-migrations-in-postgres-d60aba0fc3d4\u003e\n- \u003chttps://medium.com/paypal-tech/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680\u003e\n\n## Dev\n\n```shell\ncargo install\ncargo run\n./s/test\n./s/lint\n./s/fmt\n```\n\n... or with nix:\n\n```\n$ nix develop\n[nix-shell]$ cargo run\n[nix-shell]$ cargo insta review\n[nix-shell]$ ./s/test\n[nix-shell]$ ./s/lint\n[nix-shell]$ ./s/fmt\n```\n\n### Adding a New Rule\n\nWhen adding a new rule, running `cargo xtask new-rule` will create stubs for your rule in the Rust crate and in Documentation site.\n\n```bash\ncargo xtask new-rule 'prefer big serial'\n```\n\n### Releasing a New Version\n\n1. Run `s/update-version`\n\n   ```bash\n   # update version in squawk/Cargo.toml, package.json, flake.nix to 4.5.3\n   s/update-version 4.5.3\n   ```\n\n2. Update the `CHANGELOG.md`\n\n   Include a description of any fixes / additions. Make sure to include the PR numbers and credit the authors.\n\n3. Create a new release on GitHub\n\n   Use the text and version from the `CHANGELOG.md`\n\n### Algolia\n\nThe squawkhq.com Algolia index can be found on [the crawler website](https://crawler.algolia.com/admin/crawlers/9bf0dffb-bc5a-4d46-9b8d-2f1197285213/overview). Algolia reindexes the site every day at 5:30 (UTC).\n\n## How it Works\n\nSquawk uses its parser (based on rust-analyzer's parser) to create a CST. The\nlinters then use an AST layered on top of the CST to navigate and record\nwarnings, which are then pretty printed!\n","funding_links":[],"categories":["PLpgSQL","Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbdchd%2Fsquawk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbdchd%2Fsquawk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbdchd%2Fsquawk/lists"}