Getting started#

This guide sets up Rehearsal in an existing project. It creates a disposable database on your computer. Normal setup and rehearsal commands never connect to a hosted database.

Want to experiment first? Use the safe hands-on tutorial.

OS-specific setup files (optional)#

Separate setup folders are available for Windows / WSL 2, macOS and Linux. They are readable helpers, not native executables or bundled Node/Docker installers. Existing Node.js 24 or 26 is required. The default only checks an existing project; installation needs an explicit option and does not start a database. Review the shared behavior and release availability before choosing an install option. An exact core 1.0.2 install requires that version to be published; a checked-in helper is not proof of publication.

Windows: use a WSL 2 Linux workspace#

The Windows compatibility route is Linux execution inside WSL 2, not a native PowerShell/Command Prompt database runtime. Core 1.0.1 and extension 0.1.21 make that boundary explicit; native Windows version/help/discovery do not authorize runtime work.

Follow Microsoft's WSL installation guide to prepare a WSL 2 Linux distribution, such as Ubuntu 24.04. Do not use WSL 1.
Clone or open the project inside the distribution's Linux home directory, such as /home/your-name/projects/app. Do not keep the runtime project under /mnt/c, a Windows share or a Windows-mounted drive. Rehearsal does not relocate your files.
Install a supported Linux Node/npm and a Docker-compatible Linux engine in that environment. Docker Engine in WSL or an already configured Docker Desktop WSL integration are user-controlled setup choices; Rehearsal does not install or license Docker Desktop for you. In the Linux terminal, check:
bash
```
node -p "process.platform"
pwd
docker info --format '{{.OSType}}'
```
Both platform results must be linux, and pwd must be in the Linux filesystem.
For editor use, install Microsoft's WSL extension, then run code . from that Linux project directory. Confirm the VS Code window says WSL in its remote indicator, and install Rehearsal into WSL, not only the Windows-side extension host.
Continue below from that Linux terminal. Keep the existing baseline, approval and local-only checks; do not substitute a hosted database to make setup pass.

WSL is a compatibility preview. A real WSL PostgreSQL fixture and a native Remote-WSL editor walkthrough are different evidence; do not infer the latter from Linux unit tests. Supabase/Auth/Storage in WSL and other remote hosts remain unclaimed until their own checks pass. See the complete platform boundary.

1. Check the required tools#

You need Node.js 22, 24, or 26, npm, and a running Docker-compatible engine. Node.js 24 LTS is the recommended default:

bash

node --version
npm --version
docker info

node --version must begin with v22, v24, or v26. If docker info fails, start Docker Desktop, Colima, or your usual Docker engine.

Choose the extra requirement for your project:

Supabase: install Supabase CLI 2.117.0 and run supabase --version.
PostgreSQL: download the local database image once:
bash
```
docker pull postgres:17-alpine
```

Rehearsal will use that image with downloads disabled.

2. Install and open the guide#

Run these commands from the directory containing your project's package.json:

bash

npm install --save-dev @rehearsal-db/core
npx rehearsal

The guide first offers an optional update check. Not now makes no network request. Choose Check once or Check and remind me daily to contact npm's public registry; daily checks happen only when opening this guide, not in the background. A newer release offers its exact update command, Not now, Skip this release, and Disable reminders. Rehearsal exits before you run an update command; it never installs its own replacement. Review the release's compatibility notes and resulting dependency diff. Stable installations check stable releases only. Preview installations also check for a newer stable release and label it explicitly; switching remains your reviewed decision.

Use Check for updates in the guide to check manually or change that choice. Preferences stay in the owner-private ~/.cache/rehearsal/updates-v1.json, outside your project. Set REHEARSAL_UPDATE_CHECK=off to prevent checks and prompts for a session. JSON, CI and noninteractive commands never check. Offline checks do not block local work; custom artifact installations keep their own reviewed update process. Exact commands require matching npm manifest, lockfile and installed-origin records. Other package managers, unverified origins or a new compatibility series receive manual review guidance instead; release availability is not a compatibility guarantee. For an isolated test or a different preference location, set REHEARSAL_UPDATE_STATE_DIR to an absolute owner-private directory; this changes no registry endpoint or project files.

With npm, a normal application install creates rehearsal.config.mjs, the dedicated local runtime config, and the required .gitignore entries when Rehearsal can prove the application root. It never replaces an existing file. Review the generated config, especially:

the migration directory;
the application start and proof commands;
the local ports.

If a supported configuration already exists elsewhere—such as infrastructure/rehearsal/rehearsal.config.mjs—the installer reports that exact active path and does not generate a competing root file. Keep using it, or follow the explicit root relocation guide.

If lifecycle scripts were disabled, a global/cache install was used, or a workspace has more than one possible application, no project files are created automatically. Run npx rehearsal inside the intended application, choose Set the stage, select Supabase or PostgreSQL, and approve the same safe setup preview.

The proof command should check behavior changed by the migration. A test that only checks whether the home page loads is usually too weak.

If the sandbox needs Google or GitHub sign-in, uncomment supabase.authentication in rehearsal.config.mjs. Add the named credentials to .env.rehearsal-service.local, run chmod 600 .env.rehearsal-service.local, and register the local callback printed in the config. See Supabase authentication. Rehearsal keeps the values out of tracked files and generates the disposable provider configuration for you.

3. Prepare safe baseline inputs#

A baseline is the locked starting point restored before each rehearsal. Start with a small synthetic dataset. Do not use raw production data.

Rehearsal needs:

Input	What it contains
Records	Safe rows in NDJSON format: one JSON object per line
Migration ledger	The historical migrations represented by those rows
Sanitization policy	A decision for every included table and column
Storage manifest	Optional Supabase Storage files only

A record looks like this:

json

{ "table": "widgets", "row": { "id": 1, "name": "Synthetic Widget" } }

Put your safe records and ledger inside the project. Conventional names such as rehearsal/sanitized-data.ndjson and rehearsal/migration-ledger.json are discovered automatically. The guide inspects their structure but does not print row values.

Follow the guide's recommended actions:

Prepare the script creates a draft sanitization policy.
Review the script asks you to classify every table and column.
Create the baseline validates and activates the reviewed inputs.

Rehearsal will not activate a policy containing undecided fields.

The ledger must describe the exact historical SQL included in the baseline. Do not type years of migration history by hand for a real project. Generate it through reviewed project tooling. The tutorial contains a complete synthetic example, and Baselines explains the file formats.

4. Reach READY#

The guide displays four setup stages. Continue with its recommended action until all checks are complete and the project reports READY.

You can run the same check directly:

bash

npx rehearsal doctor

If it reports NOT READY, fix the listed item and run it again. Do not bypass a check or add a hosted connection string.

5. Run the rehearsal#

Choose Run a rehearsal. Rehearsal shows the exact candidate migrations and asks for confirmation before it changes the disposable runtime.

A successful run:

restores the baseline;
applies only the migrations you approved;
verifies the local database;
launches the ordinary application when readiness is configured;
runs the ordinary test command and declared positive/negative HTTP proofs;
stops only the application process it launched.

Your original baseline remains unchanged.

If a source owner later approves a production-shaped copy, use the separate workflow in Optional production-shaped preparation. Do not add source credentials to the normal config or runtime environment.

Once temporary source access is ready, npx rehearsal refresh previews the safe replacement workflow. It means “get a newly verified copy.” By contrast, reset means “discard local edits and restore the copy I already have.”

6. Use the sandbox and clean up#

Choose Open the sandbox app, or run:

bash

npx rehearsal open

Open the local URL printed by Rehearsal. The app stays available for hands-on testing until you press Ctrl+C. Only the app stops; your local database and Storage changes are kept. Run npx rehearsal open again to continue where you left off.

Use the guide for normal runtime tasks:

Verify checks the current runtime.
Reset discards runtime edits and restores the baseline.
Stop stops the runtime but keeps its local state.
Discard removes this project's disposable runtime and volume.

Press Ctrl+Z at any prompt to exit the entire guide. It will not leave a suspended process behind.

Command-line setup#

The guide is recommended for people. Scripts and CI can use explicit commands:

bash

npx rehearsal setup --target=postgresql --write
npx rehearsal doctor
npx rehearsal candidates
npx rehearsal run --confirm-candidates=PASTE_DIGEST_HERE

Replace postgresql with supabase when needed. See CLI commands for the complete reference and Troubleshooting when a check fails.

Running setup again is safe: existing configuration and runtime files are reported as unchanged. Rehearsal only adds missing ignore entries. It never refreshes an existing config during an upgrade. After upgrading, run npx rehearsal init to see important optional settings you have not enabled and compare your file with the installed release's current template.

If setup or an upgrade is interrupted#

Do not delete .rehearsal/ or your existing config. Start with:

bash

npx rehearsal doctor
npx rehearsal init

Use the reported problem to choose the smallest recovery:

Problem	Safe recovery
A generated runtime file is missing	Run `npx rehearsal setup --write`. Existing files stay unchanged; only missing files are created.
A port is already in use	Stop the conflicting local process or choose new dedicated ports, then rerun setup.
The config is malformed	Move it to a backup name, run `npx rehearsal setup --write`, then copy reviewed choices into the new file.
OAuth credentials are missing	Create the ignored file named by `supabase.authentication.environmentFile`, add only the declared keys, and run `chmod 600` on it. Ambient shell credentials are not used.
An npm upgrade fails	Keep the existing config, baseline, and lockfile. Restore dependencies with your package manager, then run `npx rehearsal init` before retrying.
Docker storage is low	Run `npx rehearsal cleanup` for an exact preview. Rehearsal never performs a global Docker prune or silently removes volumes.

setup --write and package installation never replace a config. If an existing file is invalid, Rehearsal fails closed and leaves it available for comparison.

Files Rehearsal creates#

rehearsal.config.mjs — reviewed project configuration
.rehearsal/ — ignored baselines, runtime files, and receipts
.rehearsal/runtime.env — generated local-only application variables
infrastructure/rehearsal/supabase/config.toml — Supabase-only local configuration

Keep .rehearsal/ out of source control, even when its data is synthetic.