apply when a migration already exists and the configured runner should apply files selected for handoff.
apply does not generate a new diff and does not regenerate TypeScript or Zod outputs. It reconciles migration history, checks target-pending migrations, runs deploy safety gates, invokes the selected runner when one target is selected, and reconciles history again.
Run it
apply may select one configured sync.targets.<name> entry whose mode is "auto" when workflow.migration_sync is "auto". If more than one target is selected, apply refuses before any runner can mutate a database. If no target is selected, it reports a dry run after disk history reporting and generated-lineage replay checks.
When a selected Supabase CLI target has no resolved database URL, the Supabase CLI owns historical pending selection. In that lane, supaschema checks generated lineage files and does not treat every migration on disk as pending.
Flags
source
Override the before-state source used by safety and verification.
source
Override the target schema source used by safety and verification.
path
Directory containing migration files. Defaults to
config.migrationsDir.url
Explicit target database used for history reconciliation and direct-runner
apply.
name
Override config target selection with one configured
sync.targets.<name> target.direct | supabase-cli
Override the configured runner for the selected target.
Refusal cases
apply stops before handoff when migration history has ghost or out-of-order versions, more than one target is selected, a migration selected for replay check fails check, the selected runner is unavailable, workflow.migration_sync disables apply, deploy safety gates fail, or a remote automatic target lacks its approval variable.
Related
Check
See the replay-safety gate apply runs.
Migrations
Inspect applied and pending history first.