Existing issues

• I have searched the existing issues.

Affected area

Migrations

Problem to solve

With the experimental stack backend ([experimental] stack = true), one project can run several local stacks. You select one with --stack <name> or --stack-id <id> on supabase start, status, stop and destroy.

The migration commands can't select a stack. migration up, down, list, repair, squash and fetch with --local always use the project's default stack. You can create and tear down a named stack, but you can't apply or inspect migrations on it.

This makes a common workflow hard: one stack per git worktree or feature branch. For example:

git worktree add .worktrees/feature-a
supabase start --stack feature-a
# there is no way to run `migration up` against feature-a

Stack identity includes the project root and the current git branch. Because of that, the only workaround is to start each stack from inside its own worktree using the default name. That stack is then lost if the worktree switches branches. It also stops you managing stacks by name from one place.

Proposed solution

Add --stack <name> and --stack-id <id|prefix> to the migration commands that pick a database: migration up, down, list, repair, squash and fetch.

supabase migration up --stack feature-a
supabase migration list --stack-id 3f9a
supabase migration fetch --stack feature-a

Behavior:

• Selectors are resolved the same way as in supabase start/status/stop/destroy:
  • --stack matches the current project root, the current branch and the name.
  • --stack-id matches a full ID or a unique prefix of at least 4 characters, from any checkout.
  • Passing both is an error, as it is today.
• A selector implies the local target. It works alone or with --local. Combining it with --linked or --db-url is an error.
• Using a selector without the stack backend enabled is an error that explains how to enable it.
• An unknown or stopped stack fails with a message that names the stack and suggests supabase start --stack <name>.
• Migration files always come from the current directory's supabase/migrations.
• Without a selector, nothing changes: the default stack is used.

Alternatives considered

• Run each worktree's stack as default from inside that worktree. This works today. However, the stack is tied to the worktree's current branch, so it is orphaned when you switch branches, and it can't be addressed by name.
• Use --db-url with the URL from supabase status --stack <name>. This connects to the right database, but the CLI treats it as a remote target. It's also awkward to script, and you have to pass credentials around.
• A global --stack flag on every command. Declaring the flags on each command matches how --db-url, --linked and --local already work. It also limits the change to commands where a stack target makes sense.
• SUPABASE_STACK / SUPABASE_STACK_ID env vars, or running across all stacks at once. Both could be useful follow-ups. They're left out to keep this change small.

Additional context

• Stack lifecycle docs: apps/cli/docs/stack-commands.md
• Related follow-ups, not in scope here: selectors on db *, gen types, inspect and test db.