Diesel Guard

diesel-guard

diesel-guard is a CLI that lints Diesel and SQLx Postgres migrations using PostgreSQL's own parser (libpg_query). It flags operations that take dangerous locks or rewrite tables, and prints a safe alternative for each one. It needs no database connection — it reads .sql files directly. Use it to vet a migration before it ships, to fix a reported violation, or to add project-specific rules.

Core workflow: run → interpret → fix

1. Run the linter:

   diesel-guard check                 # checks ./migrations/ by default
   diesel-guard check path/to/up.sql  # a single file
   cat up.sql | diesel-guard check -  # stdin
   diesel-guard check migrations/ --format json   # text (default) | json | github

2. Interpret the result. Exit code is the contract:

   • 0 — clean, or only warnings (warnings never block).
   • 1 — at least one error-level violation, or a fatal error (e.g. invalid diesel-guard.toml, unparsable SQL, or a bad invocation). Read stderr to tell the two apart.

   Each violation has three fields: operation (what was flagged), problem (why it's dangerous), and safe_alternative (what to do instead). In JSON each also carries check_name, line, and severity.

3. Fix by applying the printed safe_alternative, then re-run to confirm 0 (see below).

Fixing violations

Apply the safe_alternative printed for the violation, then re-run until the exit code is 0. Prefer fixing the migration over suppressing the check.

Get the full reasoning and exact rewrite for any check by name — including the most common ones (AddColumnCheck, AddIndexCheck, AddNotNullCheck) — from the tool itself:

diesel-guard explain <CheckName>

Treat that output and the violation's own safe_alternative as the source of truth; do not recite fixes from memory.

Escape hatches (only when the operation is genuinely verified safe)

• Suppress a range — wrap statements (no nesting):

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

• Disable named checks for the whole file (comma-separated):

  -- diesel-guard:disable AddColumnCheck, DropColumnCheck

• Diesel per-migration — in that migration's metadata.toml:

  run_in_transaction = false        # allows CONCURRENTLY operations
  disable_checks = ["AddColumnCheck"]

• SQLx per-migration — make the migration non-transactional (required for CONCURRENTLY) by putting this as the first line of the file:

  -- no-transaction

Configuring diesel-guard.toml

Run diesel-guard init to scaffold the file (use --force to overwrite). Keys:

• framework (required) — "diesel" or "sqlx". Case-sensitive.
• start_after — skip migrations older than this timestamp. Diesel accepts YYYYMMDDHHMMSS, YYYY_MM_DD_HHMMSS, and YYYY-MM-DD-HHMMSS; SQLx accepts plain numeric versions like 42 and separator-formatted 14-digit timestamp filters. Good for retrofitting.
• check_down (default false) — also check rollback/down migrations.
• disable_checks — blacklist of check names to skip.
• enable_checks — whitelist; only these run. Mutually exclusive with disable_checks.
• warn_checks — demote these checks to warnings (reported, but exit stays 0).
• custom_checks_dir — directory of .rhai custom checks.
• postgres_version — target major version (e.g. 16); silences checks that are safe from that version onward.

Discovering checks (the source of truth)

The tool serves the live, config-aware list — do not hardcode it:

diesel-guard list-checks                 # every check: NAME, TYPE, SEVERITY, ENABLED
diesel-guard list-checks --format json
diesel-guard explain AddIndexCheck       # full description + safe alternative for one check

Migration layouts

• Diesel — one directory per migration containing up.sql (and optional down.sql, metadata.toml). check scans up.sql recursively.
• SQLx — flat files: <version>_<name>.up.sql / .down.sql, or single-file <version>_<name>.sql.

Writing custom checks

Write project-specific rules in Rhai with full access to the parsed SQL AST — no forking required.

Setup

Point custom_checks_dir at a directory of .rhai files in diesel-guard.toml:

custom_checks_dir = "checks"

Every .rhai file in that directory becomes a check. They load in alphabetical order. A check's name is its filename stem (require_concurrent_index.rhai → require_concurrent_index), so it can be listed by list-checks, disabled via disable_checks/enable_checks, and explained via explain. Compilation errors are non-fatal — they become warnings on stderr and the other checks still run. Safety-assured blocks and -- diesel-guard:disable apply to custom checks too.

Inspect the AST with dump-ast

Before writing a check, see exactly what node a statement produces:

diesel-guard dump-ast --sql "CREATE INDEX idx ON t(id);"
diesel-guard dump-ast --file migrations/.../up.sql

The output strips the outer RawStmt/Node wrappers and starts at the concrete node type (e.g. {"IndexStmt": {...}}) — that is precisely the shape your script receives as node.