squawk

Postgres迁移的linter

快速开始 | 规则文档 | github action | DIY GitHub集成

为什么？

预防由数据库迁移引起的意外停机时间，并鼓励围绕Postgres模式和SQL的最佳实践。

此外，这似乎是一个很好的项目，可以花更多的时间使用 Rust。

安装

npm install -g squawk-cli

# or via PYPI
pip install squawk-cli

# or install binaries directly via the releases page
https://github.com/sbdchd/squawk/releases

用法

❯ 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 | );

  note: Changing the size of a varchar field requires an ACCESS EXCLUSIVE lock.
  help: Use a text field with a check constraint.

example.sql:9:2: warning: require-concurrent-index-creation

   9 |
  10 | CREATE INDEX "field_name_idx" ON "table_name" ("field_name");

  note: Creating an index blocks writes.
  note: Create the index CONCURRENTLY.

example.sql:11:2: warning: disallowed-unique-constraint

  11 |
  12 | ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);

  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.

squawk --help

squawk
Find problems in your SQL

USAGE:
    squawk [FLAGS] [OPTIONS] [path]... [SUBCOMMAND]

FLAGS:
        --assume-in-transaction
            Assume that a transaction will wrap each SQL file when run by a migration tool

            Use --no-assume-in-transaction to override this setting in any config file that exists
    -h, --help
            Prints help information

        --list-rules
            List all available rules

    -V, --version
            Prints version information

        --verbose
            Enable debug logging output


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]

        --exclude-path <excluded-path>...
            Paths to exclude

            For example: --exclude-path=005_user_ids.sql --exclude-path=009_account_emails.sql

            --exclude-path='*user_ids.sql'

    -e, --exclude <rule>...
            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

            For example: --pg-version=13.0
        --reporter <reporter>
            Style of error reporting [possible values: Tty, Gcc, Json]

        --stdin-filepath <filepath>
            Path to use in reporting for stdin


ARGS:
    <path>...
            Paths to search


SUBCOMMANDS:
    help                Prints this message or the help of the given subcommand(s)
    upload-to-github    Comment on a PR with Squawk's results

规则

可以通过 --exclude 标志禁用单个规则

squawk --exclude=adding-field-with-default,disallowed-unique-constraint example.sql

配置文件

规则也可以通过配置文件禁用。

默认情况下，Squawk 将从当前目录向上遍历以查找 .squawk.toml 配置文件。您可以使用 -c 或 --config 标志指定自定义路径。

squawk --config=~/.squawk.toml example.sql

--exclude 标志始终优先于配置文件。

示例 .squawk.toml

excluded_rules = [
    "require-concurrent-index-creation",
    "require-concurrent-index-deletion",
]

有关每个规则及其示例和理由的文档，请参阅 Squawk 网站。

机器人设置

Squawk 作为一个 CLI 工具，但也可以使用 upload-to-github 子命令在 GitHub Pull Requests 上创建评论。

以下是 squawk 使用 repo 中的 example.sql 创建的示例评论

https://github.com/sbdchd/squawk/pull/14#issuecomment-647009446

有关更多信息，请参阅 “GitHub Integration” 文档。

pre-commit 钩子

使用 pre-commit 将 Squawk 集成到 Git 工作流中。将以下内容添加到您项目的 .pre-commit-config.yaml 中

repos:
  - repo: https://github.com/sbdchd/squawk
    rev: v0.10.0
    hooks:
     - id: squawk
       files: path/to/postres/migrations/written/in/sql

注意 files 参数，因为它指定了要 lint 的文件位置。

先有技术

• https://github.com/erik/squabble

相关工具

• https://github.com/yandex/zero-downtime-migrations
• https://github.com/tbicr/django-pg-zero-downtime-migrations
• https://github.com/3YOURMIND/django-migration-linter
• https://github.com/ankane/strong_migrations
• https://github.com/AdmTal/PostgreSQL-Query-Lock-Explainer
• https://github.com/stripe/pg-schema-diff
• https://github.com/kristiandupont/schemalint

相关博客文章 / SE 帖子 / PG 文档

• https://www.braintreepayments.com/blog/safe-operations-for-high-volume-postgresql/
• https://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/
• https://www.citusdata.com/blog/2018/02/22/seven-tips-for-dealing-with-postgres-locks/
• https://realpython.com/create-django-index-without-downtime/#non-atomic-migrations
• https://dba.stackexchange.com/questions/158499/postgres-how-is-set-not-null-more-efficient-than-check-constraint
• https://postgresql.ac.cn/docs/10/sql-altertable.html#SQL-ALTERTABLE-NOTES
• https://postgresql.ac.cn/docs/current/explicit-locking.html
• 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

开发

cargo install
cargo run
./s/test
./s/lint
./s/fmt

... 或使用 nix

$ nix develop
[nix-shell]$ cargo run
[nix-shell]$ cargo insta review
[nix-shell]$ ./s/test
[nix-shell]$ ./s/lint
[nix-shell]$ ./s/fmt

添加新规则

当添加新规则时，s/new-rule 脚本将为您的规则在 Rust 和文档站点中创建存根。

s/new-rule 'prefer big serial'

发布新版本

1. 更新 CHANGELOG.md 和 cli 中的 Cargo.toml 中的版本，确保锁定文件已更新，并更新 package.json 并提交更改

   # update version in Cargo.toml files and package.json to 4.5.3
   s/update-version 4.5.3
   

2. 在 GitHub 上创建新版本 - CI 将自动附加二进制文件

3. 等待构建工件附加到版本。

4. 登录到 npm 并发布新版本。

   npm login
   npm publish
   

Algolia

您可以在 爬虫网站 上找到 squawkhq.com 的 Algolia 索引。Algolia 每天在 5:30 (UTC) 重新索引网站。

工作原理

Squawk 将对 libpg_query-sys 的调用包装在安全接口中，并将 JSON 解析为更易于工作的结构。libpg_query-sys 使用 bindgen 绑定到 libpg_query，它本身使用一些 C 代码将 Postgres 的 SQL 解析器包装起来，并将解析的 AST 输出到 JSON 字符串中。

Squawk 然后在解析的 AST 上运行规则函数，收集并格式化输出规则违规。