Patchworks

Patchworks is a Rust desktop app for inspecting and diffing SQLite databases. It can open zero, one, or two database files, show schema and row-level changes, save snapshots, and generate SQL intended to transform the left database into the right database.

Current Scope

• Inspect SQLite tables and views in a native egui desktop UI
• Browse table rows with pagination and sortable columns
• Diff two databases at schema level and row level
• Save snapshots of a live database and compare against them later
• Preview SQL export in the UI, copy it to the clipboard, or save it to disk
• Preserve tracked indexes and triggers in generated SQL migrations
• Create a snapshot from the CLI with patchworks --snapshot <db>

Current limitations:

• Views are inspect-only in the current phase; they are not diffed or exported.
• Indexes and triggers are preserved in generated SQL, but they are not surfaced in dedicated UI panels yet.
• There is no headless CLI for diff, inspect, or SQL export yet.
• Snapshot state is stored under ~/.patchworks/.
• Very large exports and snapshot seeds still materialize substantial data in memory.
• Live / WAL-backed / actively changing databases are still best-effort.
• The crate is not published on crates.io yet.

Requirements

• Rust toolchain with cargo
• rustfmt
• clippy
• cargo-nextest for the preferred local test runner
• cargo-deny for dependency policy checks
• A desktop session if you want to launch the GUI

rusqlite is built with the bundled feature, so a system SQLite library is not required.

Verified Local Workflow

These commands were re-verified on 2026-03-20 in /Users/sawyer/github/patchworks:

cargo build
cargo test
cargo nextest run
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo bench --no-run
cargo deny check
cargo run -- --help

Benchmarks can then be executed locally with:

cargo bench

Launch and snapshot examples:

cargo run
cargo run -- app.db
cargo run -- left.db right.db
cargo run -- --snapshot app.db

Patchworks is not currently available via cargo install patchworks from crates.io.

For a local publishability check before release, run:

cargo package --allow-dirty

Snapshot Storage

Patchworks creates a local store in your home directory:

• Metadata database: ~/.patchworks/patchworks.db
• Snapshot database copies: ~/.patchworks/snapshots/<uuid>.sqlite

Behavior Notes

• Starting the app with two database paths computes a diff on launch.
• Diff requests now run in the background, so the UI stays responsive while large comparisons complete.
• Opening a right-side database from the toolbar loads it, but you still need to click Diff.
• Row diffs are only computed for tables that exist on both sides.
• Sorted pagination now adds a primary-key / rowid tie-breaker so duplicate sort values page deterministically.
• SQL export favors correctness over minimal migrations when a table schema changes.
• Generated SQL now drops and recreates tracked triggers after data changes so migration DML does not accidentally fire left-side trigger logic.

Repository Layout

• src/main.rs: CLI entrypoint and desktop startup
• src/app.rs: app coordinator and workspace actions
• src/db/: inspection, diff orchestration, snapshots, and shared types
• src/diff/: schema diff, row diff, and SQL export logic
• src/ui/: egui rendering layer
• tests/: integration tests and SQLite fixtures
• benches/: Criterion benchmarks for query and diff hot paths
• .github/workflows/ci.yml: GitHub Actions CI
• deny.toml: cargo-deny dependency policy
• BUILD.md: living build and handoff document for future passes

License

MIT. See LICENSE.