DEV Community: Alex Yarotsky

Adding a Scripting Engine to a Rust CLI with Rhai

Alex Yarotsky — Wed, 01 Apr 2026 01:29:04 +0000

diesel-guard is a linter for Postgres migrations. It catches operations that lock tables or cause downtime before they reach production. It ships with 28 built-in checks, but over time, users started asking for custom checks:

"Our DBA requires all indexes to follow the naming convention idx_<table>_<column>. Can I enforce that?"

"Our team convention is that every new table must have an updated_at column. Can diesel-guard catch tables that don't?"

Each request is completely reasonable. But each one is unique enough that it did not make sense to add a built-in check for it. So telling users "open a PR" for a one-off team convention felt like the wrong answer.

The solution was to let users write the rule themselves, as a script, loaded at runtime, without recompiling. This post covers how I did it with Rhai.

Why Rhai

Rhai is an embedded scripting language written in Rust. You drop it into your project as you would any other crate, and scripts run within your process at runtime.

I came across this talk about it, found it interesting enough to give it a shot.

It turned out to work well for this use case. Add it to your Cargo.toml with two features:

rhai = { version = "1", features = ["serde", "sync"] }

sync makes the Rhai engine Send + Sync, which is required to store it behind a trait object. serde lets you serialize any Rust struct into a value that scripts can navigate. Both matter here, and you will see why shortly.

If you are evaluating Rhai for something performance-sensitive, the HN thread has a good discussion of the trade-offs.

The Architecture: One Trait, One Registry

Every check in diesel-guard, built-in or custom, implements the same trait:

use rhai::{AST, Dynamic, Engine};
use std::sync::Arc;

pub trait Check: Send + Sync {
    fn name(&self) -> &'static str;
    fn check(&self, node: &NodeEnum, config: &Config, ctx: &MigrationContext) -> Vec<Violation>;
}

NodeEnum is a pg_query protobuf enum with one variant per SQL statement type (IndexStmt, AlterTableStmt, CreateStmt, and so on). The Registry holds a Vec<Box<dyn Check>> and calls every check against every parsed statement.

Custom Rhai checks implement the same trait through CustomCheck:

pub struct CustomCheck {
    name: &'static str,
    engine: Arc<Engine>,
    ast: AST,
}

At check time, the registry has no way to tell whether it is calling a built-in Rust check or a Rhai script. They look the same from the outside.

To give you a sense of what this enables, here is the naming convention check from the intro. The whole thing is ten lines of Rhai:

let stmt = node.IndexStmt;
if stmt == () { return; }

let name = stmt.idxname;
if name == "" { return; }
if name.starts_with("idx_") { return; }

#{
    operation: "Index naming violation: " + name,
    problem: "Index '" + name + "' does not follow naming convention. Names must start with 'idx_'.",
    safe_alternative: "Rename: CREATE INDEX idx_" + name + " ON ...;"
}

Drop that file in a directory, point custom_checks_dir at it in diesel-guard.toml, and the check runs alongside every built-in check. How that works is what the rest of this post explains.

Bridging Typed Rust and Dynamic Scripts

This is the part that surprised me with how little code it actually needed.

pg_query gives us deeply nested protobuf types: Rust enums with dozens of variants, each with its own struct fields. Rhai scripts cannot import Rust types. The bridge is rhai::serde::to_dynamic(). Enable Rhai's serde feature, and it serializes any Serialize type into a Dynamic value that scripts can navigate like a regular map.

fn check(&self, node: &NodeEnum, config: &Config, ctx: &MigrationContext) -> Vec<Violation> {
    let dynamic_node = rhai::serde::to_dynamic(node)?;
    let dynamic_config = rhai::serde::to_dynamic(config)?;
    let dynamic_ctx = rhai::serde::to_dynamic(ctx).unwrap();

    let mut scope = rhai::Scope::new();
    scope.push("node", dynamic_node);
    scope.push("config", dynamic_config);
    scope.push("ctx", dynamic_ctx);

    self.engine.eval_ast_with_scope::<Dynamic>(&mut scope, &self.ast)
}

On the script side, protobuf enum variants become map keys and struct fields become nested map keys. A NodeEnum::IndexStmt(stmt) becomes:

{ "IndexStmt": { "concurrent": false, "idxname": "idx_users_email", ... } }

So the guard pattern in scripts looks like this:

let stmt = node.IndexStmt;
if stmt == () { return; }  // wrong node type, skip

When the node is an IndexStmt, node.IndexStmt returns the inner map. When it is anything else, it returns (), and the script exits early.

To see exactly what a statement produces, there is a built-in subcommand:

diesel-guard dump-ast --sql "CREATE INDEX idx_users_email ON users(email);"

[
  {
    "IndexStmt": {
      "concurrent": false,
      "idxname": "idx_users_email",
      "index_params": [
        { "node": { "IndexElem": { "name": "email" } } }
      ],
      "relation": { "relname": "users" },
      ...
    }
  }
]

The output strips the RawStmt and Node wrappers. What you see is what the script receives as node.

Sandboxing: Resource Limits Are Enough

Scripts run inside a sandboxed engine with four limits:

fn create_engine() -> Engine {
    let mut engine = Engine::new();
    engine.set_max_operations(100_000);  // halt infinite loops
    engine.set_max_string_size(10_000);  // prevent memory leaks
    engine.set_max_array_size(1_000);
    engine.set_max_map_size(1_000);
    engine.register_static_module("pg", create_pg_constants_module().into());
    engine
}

When max_operations is hit, Rhai returns an ErrorTerminated. We catch that and treat it as "no violation", so the linter continues normally:

Err(e) => {
    let err_str = e.to_string();
    if !err_str.contains("ErrorTerminated") {
        eprintln!("Warning: custom check '{}': runtime error: {e}", self.name);
    }
    vec![]
}

For a CLI tool checking local files written by your own team, this is sufficient. You are not running untrusted scripts from the internet.

Each invocation gets a fresh Scope, so no state leaks between migrations or between scripts.

A Stable Script API with the `pg::` Module

pg_query protobuf enums are Rust types. Scripts cannot import them. If you want a script to check whether a statement is dropping an index versus dropping a table, it needs to compare stmt.remove_type against something, but that something is an integer that lives in a Rust enum.

The fix is to expose the values scripts need as a static module, registered on the engine at startup:

fn create_pg_constants_module() -> rhai::Module {
    use pg_query::protobuf::{AlterTableType, ConstrType, DropBehavior, ObjectType};

    let mut m = rhai::Module::new();
    m.set_var("OBJECT_INDEX", ObjectType::ObjectIndex as i64);
    m.set_var("OBJECT_TABLE", ObjectType::ObjectTable as i64);
    m.set_var("AT_ADD_COLUMN", AlterTableType::AtAddColumn as i64);
    m.set_var("AT_DROP_COLUMN", AlterTableType::AtDropColumn as i64);
    m.set_var("CONSTR_PRIMARY", ConstrType::ConstrPrimary as i64);
    // ...
    m
}

Scripts access them as pg::OBJECT_INDEX, pg::AT_DROP_COLUMN, and so on. If pg_query ever changes an enum value, there is one place to update it.

Return Protocol: Three Valid Shapes

Scripts return one of three things:

() for no violation
A map #{ operation: "...", problem: "...", safe_alternative: "..." } for one violation
An array of those maps for multiple violations

Validation is strict. A script with a typo in a key gets a helpful error violation rather than a silent failure:

SCRIPT ERROR: my_check
Custom check returned an invalid map: 'safe_alternative' is missing
Fix the custom check script to return all three required string keys.

Compilation errors at load time are non-fatal. The function signature makes this explicit:

pub fn load_custom_checks(
    dir: &Utf8Path,
    config: &Config,
) -> (Vec<Box<dyn Check>>, Vec<ScriptError>)

Broken scripts produce warnings to stderr. Valid scripts still load and run.

A Complete Script

Here is require_concurrent_index.rhai, one of the examples included in the repo. It covers node access, context usage, conditional messages, and both the single and multi-violation return shapes:

// Require CONCURRENTLY on CREATE INDEX.
// Also flags CONCURRENTLY inside a transaction (PostgreSQL will error at runtime).
// Inspect: diesel-guard dump-ast --sql "CREATE INDEX idx ON t(id);"

let stmt = node.IndexStmt;
if stmt == () { return; }

if !stmt.concurrent {
    let idx_name = if stmt.idxname != "" { stmt.idxname } else { "(unnamed)" };
    return #{
        operation: "INDEX without CONCURRENTLY: " + idx_name,
        problem: "Creating index '" + idx_name + "' without CONCURRENTLY blocks writes on the table.",
        safe_alternative: "Use CREATE INDEX CONCURRENTLY:\n  CREATE INDEX CONCURRENTLY " + idx_name + " ON ...;"
    };
}

// CONCURRENTLY cannot run inside a transaction block
if ctx.run_in_transaction {
    let idx_name = if stmt.idxname != "" { stmt.idxname } else { "(unnamed)" };
    let hint = if ctx.no_transaction_hint != "" {
        ctx.no_transaction_hint
    } else {
        "Run this migration outside a transaction block."
    };
    #{
        operation: "INDEX CONCURRENTLY inside a transaction: " + idx_name,
        problem: "CREATE INDEX CONCURRENTLY cannot run inside a transaction block. PostgreSQL will raise an error at runtime.",
        safe_alternative: hint
    }
}

A few things worth noticing. ctx.run_in_transaction is a bool passed from the migration runner, useful for catching CONCURRENTLY inside a transaction block, which Postgres rejects at runtime. ctx.no_transaction_hint carries framework-specific instructions for how to opt out of transactions in Diesel versus SQLx. Scripts can return early with an explicit return #{ ... } or let the last expression be the return value. Integers auto-coerce to strings in concatenation.

If this was useful and you work with Postgres, a star on diesel-guard goes a long way. It helps other teams find the tool before a migration causes an outage.

Your Diesel Migrations Might Be Ticking Time Bombs

Alex Yarotsky — Tue, 16 Dec 2025 14:03:45 +0000

Handshake deployed what looked like a routine migration during their regular multi-daily release cycle:

ALTER TABLE table_name
  ADD CONSTRAINT fk_user_id
  FOREIGN KEY (user_id) REFERENCES users(id);

60 seconds later, their entire site was down.

The problem? Adding a foreign key constraint requires an ACCESS EXCLUSIVE lock on the referenced table. Postgres grants locks first-come, first-served. A long-running query on the users table was holding an ACCESS SHARE lock, so the migration queued up waiting for it. But here's the kicker: since ACCESS EXCLUSIVE conflicts with everything, all the regular SELECT queries that came after started queuing behind the migration. The lock queue grew. The site stopped responding. They had to abort the migration to bring the site back up.

GoCardless hit a similar issue. They were recreating foreign key constraints on renamed tables. The tables were empty, so it seemed safe. But adding the constraints required locks on the parent tables, which were heavily used. API timeouts across the board for 15 seconds.

Both incidents came from database migrations that looked completely normal. Both ran fine in staging. Both only showed their true colors in production.

The Postgres Lock Problem

Postgres uses different lock levels to keep your data consistent. The worst one is ACCESS EXCLUSIVE. When something holds this lock, nothing else can touch that table. Not SELECT, not INSERT, nothing.

A bunch of common migration operations take ACCESS EXCLUSIVE locks:

Creating Indexes

CREATE INDEX idx_users_email ON users(email);

This takes a SHARE lock, which blocks all writes (INSERT, UPDATE, DELETE) while the index builds. On a table with millions of rows, this can take minutes.

Adding NOT NULL

ALTER TABLE users ALTER COLUMN email SET NOT NULL;

Postgres has to verify every single row has a non-null value. ACCESS EXCLUSIVE lock the entire time.

Changing Column Types

ALTER TABLE products ALTER COLUMN price TYPE NUMERIC(10,2);

Complete table rewrite. Every row converted to the new type. ACCESS EXCLUSIVE lock throughout.

The Lock Queue Makes It Worse

Here's what makes this really nasty: Postgres's lock queue is first-come, first-served. If a migration is waiting for a lock, all subsequent queries queue behind it, even if they don't conflict with the original lock holder.

So this happens:

Long-running query holds ACCESS SHARE lock on users table.
Migration tries to get ACCESS EXCLUSIVE lock, queues up.
New SELECT query comes in, would normally be fine with ACCESS SHARE.
But since migration is waiting, this SELECT goes to the back of the queue.
Another SELECT comes in, also queued.
Your application starts timing out.

The migration hasn't even started yet, and you're already down.

Why This is Hard to Catch

These migrations look fine. They work great in development where you have 100 test records. They run instantly in staging with 10,000 rows. Then in production with 5 million rows, they lock the table for minutes.

You don't find out until it's running against real data with real traffic.

Enter diesel-guard

diesel-guard was built to catch these problems before they hit production. It's a static analysis tool that scans your Diesel migration files for dangerous operations.

It 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.

Install it:

cargo install diesel-guard

Run it:

diesel-guard check migrations/

When it finds something risky:

❌ Unsafe migration detected in migrations/2024_01_01_add_fk/up.sql

❌ ADD COLUMN with DEFAULT

Problem:
  Adding column 'status' with DEFAULT on table 'orders' requires a full
  table rewrite on PostgreSQL < 11, which acquires an ACCESS EXCLUSIVE
  lock. On large tables, this can take significant time and block all
  operations.

Safe alternative:
  1. Add the column without a default:
     ALTER TABLE orders ADD COLUMN status TEXT;

  2. Backfill data in batches (outside migration):
     UPDATE orders SET status = 'pending' WHERE status IS NULL;

  3. Add default for new rows only:
     ALTER TABLE orders ALTER COLUMN status SET DEFAULT 'pending';

  Note: For Postgres 11+, this is safe if the default is a constant.

You get:

What's dangerous about it
What lock it takes
Step-by-step fix with SQL

Safe Alternatives for Common Operations

Creating Indexes

Instead of:

CREATE INDEX idx_orders_created_at ON orders(created_at);

Do this:

CREATE INDEX CONCURRENTLY idx_orders_created_at ON orders(created_at);

CONCURRENTLY means writes can continue while the index builds. You need to add a metadata.toml:

# migrations/2024_01_01_add_order_index/metadata.toml
run_in_transaction = false

Adding NOT NULL

Instead of:

ALTER TABLE users ALTER COLUMN email SET NOT NULL;

Do this:

-- Add CHECK constraint without validating existing rows
ALTER TABLE users
  ADD CONSTRAINT users_email_not_null_check
  CHECK (email IS NOT NULL) NOT VALID;

-- Validate separately (lighter lock)
ALTER TABLE users VALIDATE CONSTRAINT users_email_not_null_check;

-- Add NOT NULL (fast since we validated)
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

-- Clean up
ALTER TABLE users DROP CONSTRAINT users_email_not_null_check;

The VALIDATE step uses SHARE UPDATE EXCLUSIVE, which allows reads and writes to continue.

Adding UNIQUE Constraints

Instead of:

ALTER TABLE users ADD CONSTRAINT users_email_key UNIQUE (email);

Do this:

-- Build index concurrently
CREATE UNIQUE INDEX CONCURRENTLY users_email_idx ON users(email);

-- Add constraint using existing index (instant)
ALTER TABLE users
  ADD CONSTRAINT users_email_key
  UNIQUE USING INDEX users_email_idx;

Adding Foreign Keys

This is what bit Handshake. Instead of:

ALTER TABLE posts
  ADD CONSTRAINT posts_user_id_fkey
  FOREIGN KEY (user_id) REFERENCES users(id);

Do this:

-- Add constraint without validating existing rows
ALTER TABLE posts
  ADD CONSTRAINT posts_user_id_fkey
  FOREIGN KEY (user_id) REFERENCES users(id)
  NOT VALID;

-- Validate separately (lighter lock)
ALTER TABLE posts VALIDATE CONSTRAINT posts_user_id_fkey;

NOT VALID means it doesn't scan existing rows. VALIDATE happens separately with a lighter lock.

Setting Timeouts

One thing both Handshake and GoCardless learned: set lock_timeout in your migrations.

-- At the top of your migration
SET lock_timeout = '2s';

ALTER TABLE users ADD COLUMN email TEXT;

If the migration can't get a lock within 2 seconds, it fails instead of queuing indefinitely. Your app stays up, and you can retry during lower traffic.

When You Know It's Safe

Sometimes you know a migration is safe (tiny table, maintenance window, etc.):

-- safety-assured:start
-- Safe because: table has 50 rows, deploying during maintenance window
ALTER TABLE countries ADD COLUMN flag_emoji TEXT DEFAULT '🏳️';
-- safety-assured:end

diesel-guard will skip anything in these blocks.

Configuration

Put a diesel-guard.toml in your project:

# Skip checking migrations before this date
start_after = "2024_01_01_000000"

# Check down.sql too
check_down = true

# Disable specific checks if needed
disable_checks = ["CreateExtensionCheck"]

CI/CD Integration

Add to GitHub Actions:

name: Check Migrations
on: [pull_request]

jobs:
  check-migrations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ayarotsky/diesel-guard@v0.3.0

Now dangerous migrations get caught in PR review, not production.

What It Checks

diesel-guard currently detects 24 different issues:

Check	Risk
ADD COLUMN with DEFAULT	Table rewrite on Postgres < 11 (ACCESS EXCLUSIVE)
ADD INDEX without CONCURRENTLY	Blocks writes (SHARE lock)
ADD NOT NULL constraint	Full table scan (ACCESS EXCLUSIVE)
ADD PRIMARY KEY	Blocks all operations during index creation
ADD UNIQUE constraint	ACCESS EXCLUSIVE during index build
ALTER COLUMN TYPE	Table rewrite (ACCESS EXCLUSIVE)
ADD COLUMN with SERIAL	Table rewrite to populate sequence
ADD COLUMN with GENERATED STORED	Table rewrite to compute expressions
DROP COLUMN	ACCESS EXCLUSIVE lock
DROP INDEX without CONCURRENTLY	ACCESS EXCLUSIVE lock
DROP PRIMARY KEY	Breaks FK relationships
DROP TABLE	Irreversible, ACCESS EXCLUSIVE
DROP DATABASE	Irreversible
REINDEX without CONCURRENTLY	ACCESS EXCLUSIVE lock
RENAME COLUMN	Breaks running app references immediately
RENAME TABLE	Breaks running app references, ACCESS EXCLUSIVE
TRUNCATE TABLE	ACCESS EXCLUSIVE, cannot be batched
ADD COLUMN with JSON	Breaks DISTINCT/GROUP BY
ADD COLUMN with CHAR	Storage waste, comparison bugs
ADD COLUMN with TIMESTAMP	DST/timezone hazards
PRIMARY KEY with INT/SMALLINT	ID exhaustion risk
CREATE EXTENSION	Requires superuser
CONSTRAINT without name	Auto-names break future migrations
CREATE INDEX with 4+ columns	Ineffective, high storage overhead

Plus custom checks via Rhai scripting.

Why This Matters for Rust

The Rust ecosystem has great tooling. clippy lints your code. cargo audit catches security problems. But we didn't have anything for database migrations.

I've seen too many production incidents from migrations. The fix is usually obvious in hindsight, but you only find out when it's causing downtime.

diesel-guard brings the fix forward to development time.

Should You Use This?

Maybe you're thinking "my tables are small."

Tables grow. The users table with 100 rows today might have a million rows next year. The migration that's instant now might take minutes then.

Building safe migrations from the start is way easier than fixing them during an incident. And diesel-guard takes a couple seconds to run.

Wrapping Up

Database migrations can be tricky. Operations that look perfectly safe can cause serious production issues. The gap between how they behave in staging versus production can be huge, and often you only find out when it's too late.

Static analysis can catch these problems early. Whether you use diesel-guard or build your own checks, having something review your migrations before they reach production is worth it. The patterns are well-documented and you just need tooling to enforce them.

Building safety into your database migration workflow pays off.

DEV Community: Alex Yarotsky

Adding a Scripting Engine to a Rust CLI with Rhai

Why Rhai

The Architecture: One Trait, One Registry

Bridging Typed Rust and Dynamic Scripts

Sandboxing: Resource Limits Are Enough

A Stable Script API with the pg:: Module

Return Protocol: Three Valid Shapes

A Complete Script

Your Diesel Migrations Might Be Ticking Time Bombs

The Postgres Lock Problem

Creating Indexes

Adding NOT NULL

Changing Column Types

The Lock Queue Makes It Worse

Why This is Hard to Catch

Enter diesel-guard

Safe Alternatives for Common Operations

Creating Indexes

Adding NOT NULL

Adding UNIQUE Constraints

Adding Foreign Keys

Setting Timeouts

When You Know It's Safe

Configuration

CI/CD Integration

What It Checks

Why This Matters for Rust

Should You Use This?

Wrapping Up

A Stable Script API with the `pg::` Module