README.md

Diesel Guard 🐘💨

Linter for dangerous Postgres migration patterns in Diesel and SQLx. Prevents downtime caused by unsafe schema changes.

✓ Detects operations that lock tables or cause downtime
✓ Provides safe alternatives for each blocking operation
✓ Supports safety-assured blocks for verified operations
✓ Extensible with custom checks
✓ Works standalone or with any AI agent (Claude, Codex, Copilot, Gemini)

Why diesel-guard?

Uses PostgreSQL's own parser. diesel-guard embeds libpg_query — the C library compiled into Postgres itself. What diesel-guard flags is exactly what Postgres sees. If your SQL has a syntax error, diesel-guard reports that too.

Scriptable custom checks. Write project-specific rules in Rhai with full access to the SQL AST. No forking required.

Version-aware. Configure postgres_version to suppress checks that don't apply to your version (e.g., constant defaults are safe on PG 11+).

No database connection required. Works on SQL files directly — no running Postgres instance needed in CI.

Installation

Via Cargo:

cargo install diesel-guard

Via Homebrew:

brew install ayarotsky/tap/diesel-guard

Via shell script (macOS/Linux):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ayarotsky/diesel-guard/releases/latest/download/diesel-guard-installer.sh | sh

Via PowerShell (Windows):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/ayarotsky/diesel-guard/releases/latest/download/diesel-guard-installer.ps1 | iex"

Via Docker (Unix):

docker run --rm -v "$(pwd):/app" -w /app ayarotsky/diesel-guard check

Via Docker (Windows CMD):

docker run --rm -v "%cd%:/app" -w /app ayarotsky/diesel-guard check

Via Docker (Windows PowerShell):

docker run --rm -v "${PWD}:/app" -w /app ayarotsky/diesel-guard check

Via pre-commit:

repos:
  - repo: https://github.com/ayarotsky/diesel-guard
    rev: v0.8.0
    hooks:
      - id: diesel-guard

Quick Start

diesel-guard init   # creates diesel-guard.toml
diesel-guard check  # checks ./migrations/ by default

When it finds an unsafe migration:

❌ 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

Add to your GitHub Actions workflow:

- uses: actions/checkout@v6
- uses: ayarotsky/diesel-guard-action@v1

Pin the diesel-guard binary version for reproducible builds:

- uses: ayarotsky/diesel-guard-action@v1
  with:
    version: '0.10.0'

Use with AI agents

diesel-guard works with any AI agent that can run shell commands.

Point your agent at skills/diesel-guard/SKILL.md for full diesel-guard workflow coverage.

Agent discovery: diesel-guard check --format json returns structured findings, each with a ready-to-apply safe_alternative (exit 0 clean, 1 on errors). Use diesel-guard list-checks --format json for the full catalog of checks, and diesel-guard explain <CheckName> for any one.

See AI Agents for the full guide.

What It Detects

Built-in checks cover locking, rewrites, and schema safety. See the full list of checks.

Escape Hatch

When you've reviewed an operation and confirmed it's safe, wrap it in a safety-assured block to suppress the check:

-- safety-assured:start
ALTER TABLE users DROP COLUMN legacy_field;
-- safety-assured:end

To suppress only one known-safe check while keeping other checks active for the same migration, disable that check by name:

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

Further Reading

• Your Diesel Migrations Might Be Ticking Time Bombs
• Postgres Locks Explained
• Zero-downtime Postgres migrations: the hard parts
• Zero-downtime Postgres migrations: a little help
• Seven tips for dealing with Postgres locks
• Move fast and migrate things: how we automated migrations in Postgres
• PostgreSQL at scale: database schema changes without downtime
• PostgreSQL Explicit Locking
• Adding a Scripting Engine to a Rust CLI with Rhai

Credits

Inspired by strong_migrations by Andrew Kane.

License

MIT

---

If this looks useful, a star helps more developers find it ⭐