ayarotsky/diesel-guard
GitHub: ayarotsky/diesel-guard
一款针对 Diesel 和 SQLx 迁移的 PostgreSQL 静态检查工具，用于在不连接数据库的前提下检测并阻止会导致停机的危险 schema 变更操作。
Stars: 116 | Forks: 11
# Diesel Guard 🐘💨
 [](https://crates.io/crates/diesel-guard) [](https://ayarotsky.github.io/diesel-guard/) [](LICENSE) [](https://codecov.io/github/ayarotsky/diesel-guard)
**用于检查 Diesel 和 SQLx 中危险的 Postgres 迁移模式的 Linter。防止因不安全的 schema 更改而导致停机。**
✓ 检测锁定表或导致停机的操作
✓ 为每个拦截的操作提供安全的替代方案
✓ 同时兼容 Diesel 和 SQLx 迁移框架
✓ 支持为已验证的操作使用安全声明确保块
✓ 可通过自定义检查进行扩展
## 为什么使用 diesel-guard？ **使用 PostgreSQL 自带的解析器。** diesel-guard 内嵌了 libpg_query —— 这是一个 C 语言库， 它也被编译进了 Postgres 本身。diesel-guard 标记的内容正是 Postgres 所看到的内容。 如果你的 SQL 存在语法错误，diesel-guard 也会将其报告出来。 **可编写脚本的自定义检查。** 使用 Rhai 编写项目特定的规则，并可以完全访问 SQL AST。无需 fork 代码库。 **版本感知。** 配置 `postgres_version` 可以忽略不适用于你当前版本的检查 （例如，常量默认值在 PG 11+ 上是安全的）。 **无需连接数据库。** 直接作用于 SQL 文件 —— 在 CI 环境中无需运行 Postgres 实例。 ## 安装说明 通过 Cargo： ``` cargo install diesel-guard ``` 通过 Homebrew： ``` brew install ayarotsky/tap/diesel-guard ``` 通过 shell 脚本 (macOS/Linux)： ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ayarotsky/diesel-guard/releases/latest/download/diesel-guard-installer.sh | sh ``` 通过 PowerShell (Windows)： ``` powershell -ExecutionPolicy Bypass -c "irm https://github.com/ayarotsky/diesel-guard/releases/latest/download/diesel-guard-installer.ps1 | iex" ``` 通过 Docker (Unix)： ``` docker run --rm -v "$(pwd):/app" -w /app ayarotsky/diesel-guard check ``` 通过 Docker (Windows CMD)： ``` docker run --rm -v "%cd%:/app" -w /app ayarotsky/diesel-guard check ``` 通过 Docker (Windows PowerShell)： ``` docker run --rm -v "${PWD}:/app" -w /app ayarotsky/diesel-guard check ``` 通过 pre-commit： ``` repos: - repo: https://github.com/ayarotsky/diesel-guard rev: v0.8.0 hooks: - id: diesel-guard ``` ## 快速开始 ``` diesel-guard init # creates diesel-guard.toml diesel-guard check # checks ./migrations/ by default ``` 当发现不安全的迁移时： ``` ❌ Unsafe migration detected in migrations/20240101_add_admin/up.sql ❌ ADD COLUMN with DEFAULT Problem: Adding column 'admin' with DEFAULT on table 'users' requires a full table rewrite on Postgres < 11, acquiring an ACCESS EXCLUSIVE lock. Safe alternative: 1. Add the column without a default: ALTER TABLE users ADD COLUMN admin BOOLEAN; 2. Backfill data in batches (outside migration): UPDATE users SET admin = false WHERE admin IS NULL; 3. Add default for new rows only: ALTER TABLE users ALTER COLUMN admin SET DEFAULT false; ``` ## CI/CD 添加到你的 GitHub Actions 工作流中： ``` - uses: actions/checkout@v6 - uses: ayarotsky/diesel-guard-action@v1 ``` 固定 diesel-guard 二进制文件版本以实现可重现的构建： ``` - uses: ayarotsky/diesel-guard-action@v1 with: version: '0.10.0' ``` ## 检测内容 内置检查涵盖了锁定、重写和 schema 安全性。请参阅[完整检查列表](https://ayarotsky.github.io/diesel-guard/checks/overview.html)。 ## 逃生舱口 当你审查了一个操作并确认其安全后，可以将其包裹在安全声明确保块中以忽略该检查： ``` -- safety-assured:start ALTER TABLE users DROP COLUMN legacy_field; -- safety-assured:end ``` 如果只想忽略某一个已知安全的检查，同时保留对同一迁移的其他检查，可以通过名称禁用该检查： ``` -- diesel-guard:disable AddColumnCheck ALTER TABLE users ADD COLUMN admin BOOLEAN DEFAULT FALSE; -- Disable multiple checks with a comma-separated list: -- diesel-guard:disable AddColumnCheck, IdempotencyAlterCheck ALTER TABLE users ADD COLUMN admin BOOLEAN DEFAULT FALSE; ``` ## 延伸阅读 - [你的 Diesel 迁移可能是定时炸弹](https://dev.to/ayarotsky/your-diesel-migrations-might-be-ticking-time-bombs-30g7) - [Postgres 锁详解](https://postgreslocksexplained.com/) - [零停机 Postgres 迁移：难点解析](https://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/) - [零停机 Postgres 迁移：一点小帮助](https://gocardless.com/blog/zero-downtime-postgres-migrations-a-little-help/) - [处理 Postgres 锁的七个技巧](https://www.citusdata.com/blog/2018/02/22/seven-tips-for-dealing-with-postgres-locks/) - [快速行动与迁移事物：我们如何在 Postgres 中自动化迁移](https://benchling.engineering/move-fast-and-migrate-things-how-we-automated-migrations-in-postgres-d60aba0fc3d4) - [大规模 PostgreSQL：无停机的数据库 schema 更改](https://medium.com/paypal-tech/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680) - [PostgreSQL 显式锁定](https://www.postgresql.org/docs/current/explicit-locking.html) - [使用 Rhai 为 Rust CLI 添加脚本引擎](https://dev.to/ayarotsky/adding-a-scripting-engine-to-a-rust-cli-with-rhai-56g1) ## 许可证 [MIT](LICENSE) 如果这个工具对你有帮助，点个 Star 可以帮助更多开发者发现它 ⭐
✓ 为每个拦截的操作提供安全的替代方案
✓ 同时兼容 Diesel 和 SQLx 迁移框架
✓ 支持为已验证的操作使用安全声明确保块
✓ 可通过自定义检查进行扩展
## 为什么使用 diesel-guard？ **使用 PostgreSQL 自带的解析器。** diesel-guard 内嵌了 libpg_query —— 这是一个 C 语言库， 它也被编译进了 Postgres 本身。diesel-guard 标记的内容正是 Postgres 所看到的内容。 如果你的 SQL 存在语法错误，diesel-guard 也会将其报告出来。 **可编写脚本的自定义检查。** 使用 Rhai 编写项目特定的规则，并可以完全访问 SQL AST。无需 fork 代码库。 **版本感知。** 配置 `postgres_version` 可以忽略不适用于你当前版本的检查 （例如，常量默认值在 PG 11+ 上是安全的）。 **无需连接数据库。** 直接作用于 SQL 文件 —— 在 CI 环境中无需运行 Postgres 实例。 ## 安装说明 通过 Cargo： ``` cargo install diesel-guard ``` 通过 Homebrew： ``` brew install ayarotsky/tap/diesel-guard ``` 通过 shell 脚本 (macOS/Linux)： ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ayarotsky/diesel-guard/releases/latest/download/diesel-guard-installer.sh | sh ``` 通过 PowerShell (Windows)： ``` powershell -ExecutionPolicy Bypass -c "irm https://github.com/ayarotsky/diesel-guard/releases/latest/download/diesel-guard-installer.ps1 | iex" ``` 通过 Docker (Unix)： ``` docker run --rm -v "$(pwd):/app" -w /app ayarotsky/diesel-guard check ``` 通过 Docker (Windows CMD)： ``` docker run --rm -v "%cd%:/app" -w /app ayarotsky/diesel-guard check ``` 通过 Docker (Windows PowerShell)： ``` docker run --rm -v "${PWD}:/app" -w /app ayarotsky/diesel-guard check ``` 通过 pre-commit： ``` repos: - repo: https://github.com/ayarotsky/diesel-guard rev: v0.8.0 hooks: - id: diesel-guard ``` ## 快速开始 ``` diesel-guard init # creates diesel-guard.toml diesel-guard check # checks ./migrations/ by default ``` 当发现不安全的迁移时： ``` ❌ Unsafe migration detected in migrations/20240101_add_admin/up.sql ❌ ADD COLUMN with DEFAULT Problem: Adding column 'admin' with DEFAULT on table 'users' requires a full table rewrite on Postgres < 11, acquiring an ACCESS EXCLUSIVE lock. Safe alternative: 1. Add the column without a default: ALTER TABLE users ADD COLUMN admin BOOLEAN; 2. Backfill data in batches (outside migration): UPDATE users SET admin = false WHERE admin IS NULL; 3. Add default for new rows only: ALTER TABLE users ALTER COLUMN admin SET DEFAULT false; ``` ## CI/CD 添加到你的 GitHub Actions 工作流中： ``` - uses: actions/checkout@v6 - uses: ayarotsky/diesel-guard-action@v1 ``` 固定 diesel-guard 二进制文件版本以实现可重现的构建： ``` - uses: ayarotsky/diesel-guard-action@v1 with: version: '0.10.0' ``` ## 检测内容 内置检查涵盖了锁定、重写和 schema 安全性。请参阅[完整检查列表](https://ayarotsky.github.io/diesel-guard/checks/overview.html)。 ## 逃生舱口 当你审查了一个操作并确认其安全后，可以将其包裹在安全声明确保块中以忽略该检查： ``` -- safety-assured:start ALTER TABLE users DROP COLUMN legacy_field; -- safety-assured:end ``` 如果只想忽略某一个已知安全的检查，同时保留对同一迁移的其他检查，可以通过名称禁用该检查： ``` -- diesel-guard:disable AddColumnCheck ALTER TABLE users ADD COLUMN admin BOOLEAN DEFAULT FALSE; -- Disable multiple checks with a comma-separated list: -- diesel-guard:disable AddColumnCheck, IdempotencyAlterCheck ALTER TABLE users ADD COLUMN admin BOOLEAN DEFAULT FALSE; ``` ## 延伸阅读 - [你的 Diesel 迁移可能是定时炸弹](https://dev.to/ayarotsky/your-diesel-migrations-might-be-ticking-time-bombs-30g7) - [Postgres 锁详解](https://postgreslocksexplained.com/) - [零停机 Postgres 迁移：难点解析](https://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/) - [零停机 Postgres 迁移：一点小帮助](https://gocardless.com/blog/zero-downtime-postgres-migrations-a-little-help/) - [处理 Postgres 锁的七个技巧](https://www.citusdata.com/blog/2018/02/22/seven-tips-for-dealing-with-postgres-locks/) - [快速行动与迁移事物：我们如何在 Postgres 中自动化迁移](https://benchling.engineering/move-fast-and-migrate-things-how-we-automated-migrations-in-postgres-d60aba0fc3d4) - [大规模 PostgreSQL：无停机的数据库 schema 更改](https://medium.com/paypal-tech/postgresql-at-scale-database-schema-changes-without-downtime-20d3749ed680) - [PostgreSQL 显式锁定](https://www.postgresql.org/docs/current/explicit-locking.html) - [使用 Rhai 为 Rust CLI 添加脚本引擎](https://dev.to/ayarotsky/adding-a-scripting-engine-to-a-rust-cli-with-rhai-56g1) ## 许可证 [MIT](LICENSE) 如果这个工具对你有帮助，点个 Star 可以帮助更多开发者发现它 ⭐
标签：LNA, PostgreSQL, Rust, SOC Prime, 可视化界面, 开发工具, 数据库迁移, 测试用例, 网络流量审计, 请求拦截, 通知系统