Contents
SchemaBot
SchemaBot is a schema diff and migration validation tool for PostgreSQL. We use it in CI to detect pg_search schema changes and check that migration fragments include the required SQL statements.
Quickstart
Run these commands from the repository root. Building requires Rust, a C compiler, and libclang. On Ubuntu, install the build dependencies with:
sudo apt install clang libclang-dev lld
- Generate a suggested migration between two SQL schema files:
cargo run -p schemabot --locked -- diff base.sql head.sql > diff.sql
- Check that migration fragments contain the required statements:
cargo run -p schemabot --locked -- check base.sql head.sql migration.sql
check prints suggested SQL and manual-change diagnostics before validating fragments. It accepts multiple fragment paths and allows additional statements. Fragment paths may be omitted when there is no schema change. Review the SQL generated by diff before applying it; changes requiring a manual migration are listed on stderr and exit with status 2. Parse, I/O, and validation errors exit with status 1. Supported suggestions are still written to stdout.
An explicit CREATE OR REPLACE for a function, procedure, view, or supported aggregate covers both its matching definition and its suggested DROP. A plain CREATE still requires the DROP statement. This checks structural coverage; review must confirm that PostgreSQL permits replacing the object with the new definition.
check recomputes the diff from the base and head schemas, including objects requiring manual migration even when the suggested SQL is empty. It requires an ALTER TYPE or DROP TYPE targeting each affected type, in addition to the generated statements. Qualified and unqualified names can match; two explicitly qualified names must use the same schema. This checks object coverage; review is still needed to confirm the migration implements the change. Other unsupported object changes require extending SchemaBot.
Development
Run the tests with:
cargo test -p schemabot --locked