Connect an existing test suite

Do not rewrite a project’s test system around sqlrs. Make its database connection an external setting, create a reproducible instance, and pass the DSN through the same environment mechanism the project already uses.

1. Move the connection into the environment

The application or test bootstrap should read a variable such as DATABASE_URL. Do not commit a returned DSN: the instance is temporary and the address belongs only to that local run.

2. Create an instance from a stored recipe

In this example, test-db is the prepare alias created in the previous chapter. A normal prepare waits for the instance and prints DSN=postgres://…. Remove the DSN= prefix before passing it to the application.

PowerShell

$dsnLine = sqlrs prepare test-db
$env:DATABASE_URL = $dsnLine -replace '^DSN=', ''
pnpm test

POSIX shell

export DATABASE_URL="$(sqlrs prepare test-db | sed 's/^DSN=//')"
pnpm test

Replace pnpm test with the project’s existing command: an application, JUnit, pytest, Go tests, or any other process that accepts a DSN. For parallel tests, choose isolation explicitly: one instance per process, or careful cleanup and transactions in a shared instance.

3. Remove the instance

sqlrs ls --instances
sqlrs rm INSTANCE_ID_PREFIX

An unambiguous hexadecimal prefix of at least eight characters is enough. The default ls table shows 12 characters, so its INSTANCE_ID is usually ready to copy.

4. Keep schema setup out of each test

• Let the prepare recipe own the schema and stable reference data.
• Let a test create only the data for its scenario.
• Let tests mutate an instance while the prepared state remains unchanged.
• Repeating the same prepare can reuse the prepared state.

For a check expressed entirely as psql, use a composite command:

sqlrs prepare test-db run:psql -- -f tests/db-smoke.sql

The instance is removed after run. The built-in run modes cover psql and pgbench; there is no general Local run mode for an arbitrary host command. Pass the DSN to an application or ordinary test runner directly, as shown above.

Adopt the workflow gradually

1. Start with one slow integration test and one prepare alias.
2. Remove schema creation from the test while keeping scenario data and assertions.
3. Put a short verification command in the project README or build system.
4. Once the local loop is stable, reproduce it in CI with a supported container runtime.
5. Measure prepare, instance startup, and the tests separately.

The cache does not clean test data

itself. Tests sharing one mutable instance may still affect each other’s data. :::

Next: add a migration-input check to a pull request.