squawk-cli 1.6.0 → 2.0.0

package/README.md

@@ -1,16 +1,14 @@
 # squawk [![npm](https://img.shields.io/npm/v/squawk-cli)](https://www.npmjs.com/package/squawk-cli)
 
-> linter for Postgres migrations
+> Linter for Postgres migrations & SQL
 
-[quick start](https://squawkhq.com/docs/) | [rules documentation](https://squawkhq.com/docs/rules) | [github action](https://github.com/sbdchd/squawk-action) | [diy github integration](https://squawkhq.com/docs/github_app)
+[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)
 
 ## Why?
 
 Prevent unexpected downtime caused by database migrations and encourage best
 practices around Postgres schemas and SQL.
 
-Also it seemed like a nice project to spend more time with Rust.
-
 ## Install
 
 ```shell
@@ -23,38 +21,70 @@ pip install squawk-cli
 https://github.com/sbdchd/squawk/releases
 ```
 
-## Usage
-
-```shell
-❯ squawk example.sql
-example.sql:2:1: warning: prefer-text-field
-
-   2 | --
-   3 | -- Create model Bar
-   4 | --
-   5 | CREATE TABLE "core_bar" (
-   6 |     "id" serial NOT NULL PRIMARY KEY,
-   7 |     "alpha" varchar(100) NOT NULL
-   8 | );
+### Or via Docker
 
-  note: Changing the size of a varchar field requires an ACCESS EXCLUSIVE lock.
-  help: Use a text field with a check constraint.
+You can also run Squawk using Docker. The official image is available on GitHub Container Registry.
 
-example.sql:9:2: warning: require-concurrent-index-creation
+```shell
+# Assuming you want to check sql files in the current directory
+docker run --rm -v $(pwd):/data ghcr.io/sbdchd/squawk:latest *.sql
+```
 
-   9 |
-  10 | CREATE INDEX "field_name_idx" ON "table_name" ("field_name");
+### Or via the Playground
 
-  note: Creating an index blocks writes.
-  note: Create the index CONCURRENTLY.
+Use the WASM powered playground to check your SQL locally in the browser!
 
-example.sql:11:2: warning: disallowed-unique-constraint
+<https://play.squawkhq.com>
 
-  11 |
-  12 | ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
+## Usage
 
-  note: Adding a UNIQUE constraint requires an ACCESS EXCLUSIVE lock which blocks reads.
-  help: Create an index CONCURRENTLY and create the constraint using the index.
+```shell
+❯ squawk example.sql
+warning[prefer-bigint-over-int]: Using 32-bit integer fields can result in hitting the max `int` limit.
+ --> example.sql:6:10
+  |
+6 |     "id" serial NOT NULL PRIMARY KEY,
+  |          ^^^^^^
+  |
+  = help: Use 64-bit integer values instead to prevent hitting this limit.
+warning[prefer-identity]: Serial types make schema, dependency, and permission management difficult.
+ --> example.sql:6:10
+  |
+6 |     "id" serial NOT NULL PRIMARY KEY,
+  |          ^^^^^^
+  |
+  = help: Use Identity columns instead.
+warning[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.
+ --> example.sql:7:13
+  |
+7 |     "alpha" varchar(100) NOT NULL
+  |             ^^^^^^^^^^^^
+  |
+  = help: Use a `TEXT` field with a `CHECK` constraint.
+warning[require-concurrent-index-creation]: During normal index creation, table updates are blocked, but reads are still allowed.
+  --> example.sql:10:1
+   |
+10 | CREATE INDEX "field_name_idx" ON "table_name" ("field_name");
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: Use `CONCURRENTLY` to avoid blocking writes.
+warning[constraint-missing-not-valid]: By default new constraints require a table scan and block writes to the table while that scan occurs.
+  --> example.sql:12:24
+   |
+12 | ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
+   |                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: Use `NOT VALID` with a later `VALIDATE CONSTRAINT` call.
+warning[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.
+  --> example.sql:12:28
+   |
+12 | ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
+   |                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: Create an index `CONCURRENTLY` and create the constraint using the index.
+
+Find detailed examples and solutions for each rule at https://squawkhq.com/docs/rules
+Found 7 issues in 1 file (checked 1 source file)
 ```
 
 ### `squawk --help`
@@ -74,9 +104,6 @@ FLAGS:
     -h, --help
             Prints help information
 
-        --list-rules
-            List all available rules
-
     -V, --version
             Prints version information
 
@@ -88,8 +115,8 @@ OPTIONS:
     -c, --config <config-path>
             Path to the squawk config file (.squawk.toml)
 
-        --dump-ast <ast-format>
-            Output AST in JSON [possible values: Raw, Parsed, Debug]
+        --debug <format>
+            Output debug info [possible values: Lex, Parse]
 
         --exclude-path <excluded-path>...
             Paths to exclude
@@ -102,8 +129,6 @@ OPTIONS:
             Exclude specific warnings
 
             For example: --exclude=require-concurrent-index-creation,ban-drop-database
-        --explain <rule>
-            Provide documentation on the given rule
 
         --pg-version <pg-version>
             Specify postgres version
@@ -134,6 +159,22 @@ Individual rules can be disabled via the `--exclude` flag
 squawk --exclude=adding-field-with-default,disallowed-unique-constraint example.sql
 ```
 
+### Disabling rules via comments
+
+Rule violations can be ignored via the `squawk-ignore` comment:
+
+```sql
+-- squawk-ignore ban-drop-column
+alter table t drop column c cascade;
+```
+
+You can also ignore multiple rules by making a comma seperated list:
+
+```sql
+-- squawk-ignore ban-drop-column, renaming-column,ban-drop-database
+alter table t drop column c cascade;
+```
+
 ### Configuration file
 
 Rules can also be disabled with a configuration file.
@@ -184,11 +225,11 @@ repos:
 
 Note the `files` parameter as it specifies the location of the files to be linted.
 
-## prior art
+## Prior Art
 
 - <https://github.com/erik/squabble>
 
-### related tools
+### Related Tools
 
 - <https://github.com/yandex/zero-downtime-migrations>
 - <https://github.com/tbicr/django-pg-zero-downtime-migrations>
@@ -198,8 +239,9 @@ Note the `files` parameter as it specifies the location of the files to be linte
 - <https://github.com/stripe/pg-schema-diff>
 - <https://github.com/kristiandupont/schemalint>
 - <https://github.com/supabase-community/postgres-language-server>
+- <https://github.com/premium-minds/sonar-postgres-plugin>
 
-## related blog posts / SE Posts / PG Docs
+## Related Blog Posts / SE Posts / PG Docs
 
 - <https://www.braintreepayments.com/blog/safe-operations-for-high-volume-postgresql/>
 - <https://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/>
@@ -211,7 +253,7 @@ Note the `files` parameter as it specifies the location of the files to be linte
 - <https://benchling.engineering/move-fast-and-migrate-things-how-we-automated-migrations-in-postgres-d60aba0fc3d4>
 - <https://medium.com/paypal-tech/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680>
 
-## dev
+## Dev
 
 ```shell
 cargo install
@@ -232,7 +274,7 @@ $ nix develop
 [nix-shell]$ ./s/fmt
 ```
 
-### adding a new rule
+### Adding a New Rule
 
 When adding a new rule, the `s/new-rule` script will create stubs for your rule in Rust and in Documentation site.
 
@@ -240,36 +282,29 @@ When adding a new rule, the `s/new-rule` script will create stubs for your rule
 s/new-rule 'prefer big serial'
 ```
 
-### releasing a new version
+### Releasing a New Version
+
+1. Update the `CHANGELOG.md`
+
+   Include a description of any fixes / additions. Make sure to include the PR numbers and credit the authors.
 
-1. update the CHANGELOG.md and bump version in the cli `Cargo.toml`, ensure the
-   lock file is updated, and update `package.json` and commit the changes
+2. Run `s/update-version`
 
    ```bash
-   # update version in Cargo.toml files and package.json to 4.5.3
+   # update version in cli/Cargo.toml, package.json, flake.nix to 4.5.3
    s/update-version 4.5.3
    ```
 
-2. create a new release on github - CI will attach the binaries automatically
-3. wait for build artifacts to be attached to release.
-4. login to `npm` and publish new version.
+3. Create a new release on GitHub
 
-   ```bash
-   npm login
-   npm publish
-   ```
+   Use the text and version from the `CHANGELOG.md`
 
-### algolia
+### Algolia
 
 The 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).
 
-## how it works
-
-squawk wraps calls to [libpg_query-sys](https://github.com/tdbgamer/libpg_query-sys) in a safe
-interface and parses the JSON into easier to work with structures.
-libpg_query-sys in turn uses [bindgen](https://rust-lang.github.io/rust-bindgen/) to bind to
-[libpg_query](https://github.com/lfittl/libpg_query), which itself wraps Postgres' SQL
-parser in a bit of C code that outputs the parsed AST into a JSON string.
+## How it Works
 
-Squawk then runs the rule functions over the parsed AST, gathers and pretty
-prints the rule violations.
+Squawk uses its parser (based on rust-analyzer's parser) to create a CST. The
+linters then use an AST layered on top of the CST to navigate and record
+warnings, which are then pretty printed!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squawk-cli",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "linter for PostgreSQL, focused on migrations",
   "repository": "git@github.com:sbdchd/squawk.git",
   "author": "Steve Dignam <steve@dignam.xyz>",