Diesel Guard 🐘💨

Linter for dangerous Postgres migration patterns in Diesel and SQLx.

✓ Detects operations that lock tables or cause downtime
✓ Provides safe alternatives for each blocking operation
✓ Works with both Diesel and SQLx migration frameworks
✓ Supports safety-assured blocks for verified operations
✓ Extensible with custom checks

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.

Quick Start

cargo install diesel-guard
diesel-guard init          # creates diesel-guard.toml
diesel-guard check migrations/

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: ayarotsky/diesel-guard-action@v1

What It Detects

24 built-in checks across locking, rewrites, and schema safety:

Plus custom checks via Rhai scripting.

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

Further Reading

• Your Diesel Migrations Might Be Ticking Time Bombs

Credits

Inspired by strong_migrations by Andrew Kane.

License

MIT

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