Dev-Database Validation

The --dev-image flag lets you validate schema changes against an ephemeral database before applying them to production. This catches runtime errors early by running the generated migration SQL against a real database instance.

How It Works

When --dev-image is provided, the CLI:

1. Pulls the specified Docker image (if not already cached locally)
2. Creates and starts a temporary container
3. Waits for the database to accept connections
4. Applies the current source schema to the dev database
5. Runs the migration SQL against the dev database
6. Reports any runtime errors
7. Shuts down and removes the container

The dev database is completely isolated and ephemeral, so nothing persists after validation completes.

Usage

migrata diff \
  --from ./schemas/current \
  --to ./schemas/target \
  --dev-image postgres:16-alpine

Validation runs after the plan is generated but before any changes are applied to the target. If errors are found, they are displayed and the apply step is skipped.

Default Configuration

The dev database uses these defaults for PostgreSQL:

Setting	Default
Database	migrata_dev
Username	postgres
Password	postgres
Host	127.0.0.1
Port	Auto-assigned by Docker
Startup timeout	30 seconds

Requirements

• Docker Desktop or a compatible Docker daemon must be running
• The Docker image must support the same database dialect as your target (PostgreSQL is currently supported)
• Network access to pull the image from the registry

Skipping Validation

If Docker is not available or you want to skip validation, simply omit the --dev-image flag. Validation is entirely optional.

Error Handling

If Docker is not running or unreachable, the CLI shows a message like:

Docker is not available or running.
Make sure Docker Desktop is running, then try again.
To skip validation, remove the `--dev-image` flag.

Runtime errors from the migration SQL are displayed with line numbers and the full error context from the database driver.