spawn migration apply

Usage

spawn migration apply [migration] [options]

Applies one or more migrations to the configured database. By default, requires migrations to be pinned for reproducibility.

Arguments

• [migration] — Optional. Specific migration to apply. If omitted, applies all pending migrations.

Behavior

Single migration

spawn migration apply 20260131120000-add-users-table

Applies the specified migration if not already applied.

All pending migrations

spawn migration apply

Shows a list of pending migrations and prompts for confirmation before applying all.

Pin requirement

By default, apply requires migrations to have a lock.toml. This ensures the exact same component versions are used every time. Use --no-pin to bypass this requirement and use current working tree components — not recommended, and never for production applies.

With --no-pin, the pin_hash recorded to the audit trail is computed by walking the current component tree in a pass separate from the actual template render. If a component file on disk changes between (or during) those two passes, the recorded pin_hash can end up not matching what was actually rendered and executed. Only a pinned migration guarantees the components used are exactly the ones snapshotted in lock.toml, immune to concurrent edits — always apply pinned migrations in any shared or production environment.

Secrets

apply always reveals real secret() values, since it executes the rendered SQL against the database. See the Secrets guide for how secrets are configured and how other commands mask them for inspection.

Retry logic

If a migration previously failed, apply will refuse to run it again unless you pass --retry. This prevents accidental re-execution of partially applied migrations. Retrying a successful migration will run the same migration again.

Connection reuse

By default, each migration creates a fresh database connection. When applying many migrations, this can be slow due to connection setup overhead. Use --reuse-connection to reuse the same connection across all migrations (currently migration status updates still occur in separate connections), which can speed up batch applies.

Examples

Apply all pending migrations:

spawn migration apply

Apply a specific migration without confirmation:

spawn migration apply 20260131120000-add-users-table --yes

Retry a previously successful or failed migration:

spawn migration apply 20260131120000-add-users-table --retry

Use unpinned components (not recommended):

spawn migration apply 20260131120000-add-users-table --no-pin

Apply all pending migrations with connection reuse (faster):

spawn migration apply --reuse-connection

Options

Option	Description
--no-pin	Allow unpinned migrations (use current components)
--variables <path>	Path to variables file (JSON, TOML, or YAML). Values are available in templates under {{ variables }}.
--yes	Skip confirmation prompt
--retry	Retry a previous migration
--reuse-connection	Reuse the same database connection across all migrations
-e, --environment <name>	Override the environment for the target config.
--target <name>	Select which target from spawn.toml to use.
--config-file <path>	Path to config file. Defaults to spawn.toml.
-d, --debug	Turn on debug output.