Work across Git revisions

There are two separate questions:

• sqlrs diff compares the paths and content hashes of prepare input files.
• plan --ref or prepare --ref reads inputs from a selected commit or tag.

Compare migration inputs

sqlrs diff --from-ref origin/main --to-ref HEAD plan:psql -- -f db/prepare.sql

The command collects related files independently in each revision, including psql \i and \ir includes, then reports added, changed, and removed inputs. Liquibase follows changelog relations:

sqlrs diff --from-ref v1.2.0 --to-ref HEAD prepare:lb -- update --changelog-file db/changelog.xml

This is not a schema diff

live database schemas. It does not compare job plans, prepare request data, alias files, composite prepare/run commands, or run:*. Use it to review file inputs; validate migration behavior with an instance and tests. :::

Prepare from a tag or commit

sqlrs plan --ref v1.2.0 test-db
sqlrs prepare --ref v1.2.0 test-db

By default, Local creates a temporary detached worktree and removes it after the command. This preserves normal file behavior, including symbolic links. If the recipe does not depend on links, files can be read directly from Git objects:

sqlrs prepare --ref v1.2.0 --ref-mode blob test-db

Record the inputs used by a check

--provenance-path writes a JSON artifact containing the command, selected Git revision, input hashes, cache decision, and plan or prepare result. Normal command output is unchanged.

sqlrs plan --ref v1.2.0 --provenance-path artifacts/v1.2.0-plan.json test-db

The artifact excludes DSNs and tokens. Store it with CI results when you need a reviewable record of the files used by a check.

Pull-request checklist

1. Run diff from the merge base or target branch to HEAD.
2. Review unexpected additions, removals, and included files.
3. Run plan --ref for the old and new revisions.
4. Create an instance from the new revision and run integration tests.
5. Test upgrades of an existing database separately; diff does not model that transition.

The referenced branch, tag, or commit must exist locally, and the primary input must exist on both sides of a diff. --ref supports one stage, not a composite prepare/run command. A retained worktree created with --ref-keep-worktree must be removed manually after diagnosis.

Next: use the troubleshooting map.