Set up Local and your project

1. Install Local and a container runtime

Get the archive for your platform from the Sequelarius Local page, verify its SHA-256 checksum, and unpack both the CLI and local engine. Run the executables from that directory or add it to PATH.

Local also needs a container runtime:

• Linux: Docker; verified configurations may use Podman.
• Windows: Docker Desktop; WSL2 is required for the Btrfs path, not for copy snapshots.
• macOS: Podman with copy snapshots.

sqlrs --help

See the installation matrix for the current archive and runtime status.

2. Create a workspace

Run these commands from the root of the repository that should own the database:

sqlrs init local --snapshot auto
sqlrs status

Continue when the engine reports status: ok, the profile and mode are local, and workspace points to the current project. The endpoint and additional platform checks vary by machine.

The .sqlrs/ directory marks the workspace boundary. Recipe inputs must stay inside it, and the CLI protects against accidentally creating a nested workspace.

Keep the local workspace out of Git

sqlrs discover --gitignore to inspect the current ignore rules and print any missing entries. Discovery suggests a command but does not edit .gitignore itself. :::

3. Record the minimum configuration

Inspect .sqlrs/config.yaml. An explicit database image plus automatic snapshot selection is a predictable starting point:

dbms:
  image: postgres:16
snapshot:
  backend: auto

A one-off --image flag takes precedence over the workspace setting. With auto, Local selects an available snapshot method and falls back to copy when necessary. Forcing Btrfs or OverlayFS can make initialization fail when the platform does not meet that backend’s requirements.

4. Verify the installation

sqlrs prepare:psql --image postgres:16 -- -c "create table if not exists smoke_check(id int); insert into smoke_check values (1);" run:psql -- -t -A -c "select count(*) from smoke_check;"

The final output should be 1. In this composite command, run receives the instance from prepare, executes the query, and removes the temporary instance when it finishes. Arguments after each -- belong to the corresponding psql stage.

Next: choose a prepare source for a real project.