squawk-cli 1.6.0__py3-none-macosx_10_12_x86_64.whl → 2.0.0__py3-none-macosx_10_12_x86_64.whl

{squawk_cli-1.6.0.dist-info → squawk_cli-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squawk-cli
-Version: 1.6.0
+Version: 2.0.0
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
@@ -11,8 +11,7 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Summary: Linter for PostgreSQL migrations
 Keywords: postgres,postgresql,linter
-Author: Steve Dignam <steve@dignam.xyz>
-Author-email: Steve Dignam <steve@dignam.xyz>
+Author: Squawk Team & Contributors
 License: GPL-3.0
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
@@ -20,17 +19,15 @@ Project-URL: Source Code, https://github.com/sbdchd/squawk
 
 # 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
@@ -43,38 +40,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`
@@ -94,9 +123,6 @@ FLAGS:
     -h, --help
             Prints help information
 
-        --list-rules
-            List all available rules
-
     -V, --version
             Prints version information
 
@@ -108,8 +134,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
@@ -122,8 +148,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
@@ -154,6 +178,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.
@@ -204,11 +244,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>
@@ -218,8 +258,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/>
@@ -231,7 +272,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
@@ -252,7 +293,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.
 
@@ -260,37 +301,30 @@ 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!
 

squawk_cli-2.0.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+squawk_cli-2.0.0.dist-info/METADATA,sha256=SdjUfQKCoaw3Id-MQM-9qYO4YbrcvFuqRtWalfl0_i0,10411
+squawk_cli-2.0.0.dist-info/WHEEL,sha256=iynIFuruP98iAQ_vbgENee_L7CnfkfNjTMl4i53tE2Q,103
+squawk_cli-2.0.0.data/scripts/squawk,sha256=9K4hkLSpRwrqGmUy1ZEZZVpF5oE7xUSOF0ctIxADnd0,6916428
+squawk_cli-2.0.0.dist-info/RECORD,,

squawk_cli-1.6.0.dist-info/RECORD

@@ -1,4 +0,0 @@
-squawk_cli-1.6.0.dist-info/METADATA,sha256=HRi5ixTmllerjvbNYHaflWa0dmWrZs1PtaMtS-AQL6Q,8969
-squawk_cli-1.6.0.dist-info/WHEEL,sha256=iynIFuruP98iAQ_vbgENee_L7CnfkfNjTMl4i53tE2Q,103
-squawk_cli-1.6.0.data/scripts/squawk,sha256=fmdIWVGapk_rM4nxc6IPbo5t1mKcBhJKm8QH12qsk2Y,7779260
-squawk_cli-1.6.0.dist-info/RECORD,,