Choose a prepare source

Start with the project’s source of truth, not with sqlrs. A prepare command should reproduce the schema and required seed data that the project normally needs before work begins.

Schema workflow	Prepare input	Command
SQL files or psql scripts	The primary SQL file and its \i or \ir includes	prepare:psql
Liquibase	The root changelog and all included changelogs	prepare:lb
Flyway, an ORM, or a custom tool	Deterministic SQL exported by that same tool and version	prepare:psql
Manual changes to a shared database	Convert them to versioned SQL or a changelog first	Do not automate the manual process as-is

Use the raw command form while you are validating inputs. Once it works, store it as a short alias next to the project.

Raw SQL and psql

sqlrs plan:psql -- -f db/prepare.sql
sqlrs prepare:psql -- -f db/prepare.sql

Use plan:psql first to inspect the ordered tasks and input files without creating an instance. A state_execute task reports whether it can reuse a cached state. Raw-command paths are resolved from the current directory and must stay inside the workspace.

Unlike plan, a successful prepare creates a mutable instance and prints DSN=postgres://…. Pass the value after DSN= to a database client or application.

Liquibase

sqlrs plan:lb -- update --changelog-file db/changelog.xml
sqlrs prepare:lb -- update --changelog-file db/changelog.xml

Liquibase must be installed on the host. If it is not discovered automatically, configure liquibase.exec in .sqlrs/config.yaml. The root changelog and all included files must remain inside the workspace.

Other migration tools

Local does not directly execute Flyway, ORM commands, or arbitrary migration tools during prepare. Running one after prepare changes only that instance; the cached state does not gain those changes.

A reliable bridge is to:

1. generate complete SQL with the same tool and version the project uses;
2. confirm that identical inputs produce identical SQL and keep the result in the workspace;
3. pass the file to prepare:psql;
4. update it with migrations and check drift in CI.

Store the recipe as an alias

sqlrs alias create test-db prepare:psql -- -f db/prepare.sql
sqlrs prepare test-db

Check and list aliases

Use sqlrs alias check to validate aliases.

Use sqlrs alias ls to list the aliases in the current workspace.

This creates test-db.prep.s9s.yaml. An alias is a versioned recipe, not a database. Paths inside an alias resolve relative to the alias file, which keeps the recipe usable from other directories and in CI.

Separate stable and changing data

from per-run test data. The advisory sqlrs discover --prepare-shaping check can flag suspiciously mixed directories by filename, but it does not understand file relationships or rewrite a recipe.

Next: inspect the project with discovery.