Diagnose common Local problems

Start with four read-only or advisory commands:

sqlrs status --cache
sqlrs ls --all --cache-details
sqlrs alias check
sqlrs discover

They report runtime readiness, states, instances, and jobs; validate aliases; and print project suggestions. None applies migrations to a database.

Workspace is not found

Run the command inside the intended repository. If .sqlrs/ does not exist, go to the project root and initialize it:

sqlrs init local --snapshot auto

Do not use --force for a nested workspace until you know which project should own its paths and aliases.

The engine or container runtime is unavailable

Confirm that the runtime documented for your platform is installed and running, then use sqlrs status. If the configuration forces an unavailable snapshot backend, restore automatic selection with sqlrs config set snapshot.backend "auto" or temporarily select copy.

An SQL file is rejected or missing

Every input must stay inside the workspace. A raw-command path is relative to the current directory; a path inside an alias is relative to that alias file. Check included files and filename casing on Linux.

An alias is not found

sqlrs alias ls --from cwd --depth recursive
sqlrs alias check test-db

An alias reference is an exact logical path from the current directory without the file suffix. The CLI does not search the whole repository for a matching basename. A prepare recipe ends in .prep.s9s.yaml.

Liquibase does not start

Check that Liquibase is available on the host and inspect liquibase.exec in .sqlrs/config.yaml. Liquibase arguments belong after --; the changelog and every included file must stay inside the workspace.

Prepare does not reuse the expected state

sqlrs cache explain prepare test-db
sqlrs ls --states --cache-details

cache explain does not prepare a state or create an instance. It reports hit with reason exact_state_match, or miss with no_matching_state, plus the resolved image, normalized arguments, and input hashes. It does not yet identify the exact differing field, so compare those values directly rather than inferring cache behavior from elapsed time.

Tests cannot connect with the DSN

Confirm that the test process receives DATABASE_URL and does not override the address or port. Try the DSN with a separate client. Do not pass -h, -p, -U, or -d to run:psql; sqlrs injects the connection.

Diff fails on a ref or file

Run inside a Git repository, resolve both refs with Git first, and confirm that the primary -f file or changelog exists in both revisions. If the project uses symbolic links, try the default worktree mode before blob.

Before opening an issue

Reduce the problem to one workspace and command. Include the version from sqlrs --help, OS, container runtime, a safe configuration excerpt, and output with DSNs and secrets removed. Then open an issue.

At the end of the beginner’s path, a project should have one workspace, one verified prepare alias, a small database check, its existing tests connected through a DSN, and a Git diff for migration inputs. Add further scenarios one at a time and inspect cache decisions explicitly.