Skip to content

feat(stack): target named stacks from every stack-backed command (CLI-2547, CLI-2698) - #7679

Open
7ttp wants to merge 2 commits into
developfrom
7ttp/cli-2547-target-named-stacks-from-every-stack-backed
Open

7ttp wants to merge 2 commits into
developfrom
7ttp/cli-2547-target-named-stacks-from-every-stack-backed

Conversation

@7ttp

@7ttp 7ttp commented Nov 17, 2026

Copy link
Copy Markdown
Member

TL;DR

adds --stack and --stack-id to every command that talks to a local stack, with SUPABASE_STACK and SUPABASE_STACK_ID as the fallback.

whats introduced?

db, migration, inspect, storage, gen types, test db, seed buckets and functions serve now target a named stack, the way start and stop already do.

a selected stack never falls back to the default one. a missing or stopped stack fails naming it, and only db start creates one.

with no selector nothing changes.

how?

stackForProject resolves the selection through the same StackTargetResolver the stack commands use.

the flags are per command like logs, so commands that never reach a stack reject them instead of ignoring them.

visual rep:
flowchart TD
  cmd["db, migration, gen types, ..."] --> sel{"--stack or --stack-id, else SUPABASE_STACK or SUPABASE_STACK_ID"}
  sel -- none --> def["default stack, unchanged"]
  sel -- "flag with --remote, or legacy backend" --> rej["rejected"]
  sel -- "name or id" --> res["StackTargetResolver"]
  res -- running --> run["runs on that stack"]
  res -- "stopped or missing" --> err["error naming the stack"]
  res -- "missing, db start" --> make["creates it"]
Loading

ref

@7ttp 7ttp self-assigned this Nov 17, 2026
@7ttp
7ttp requested a review from a team as a code owner November 17, 2026 22:28
@7ttp
7ttp requested a review from Coly010 November 17, 2026 22:28
@github-actions

Copy link
Copy Markdown
Contributor

CLI benchmark (Lightweight Commands): no changes found

Commit 29dad75 against develop at 0d1a3be · 10 runs each · report only, never blocks merging

Command Workload Before After Change
supabase --version version 467 ms 507 ms no real change (+9%, within normal variation)
supabase --help help 374 ms 363 ms no real change
supabase init init 332 ms 312 ms no real change (-6%, within normal variation)
supabase migration new bench migration-new 323 ms 339 ms no real change (+5%, within normal variation)
supabase config convert config-convert 350 ms 345 ms no real change
supabase config validate config-validate 337 ms 393 ms no real change (+17%, within normal variation)
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 451 ms 514 ms no real change (+14%, within normal variation)
supabase projects list projects-list 363 ms 368 ms no real change
supabase functions list --project-ref replayfixtureprojref functions-list 407 ms 390 ms no real change

API calls: unchanged for all 9 commands.

Binary size: 135.2 MB, up 16.0 KB from 135.2 MB.

Details: timing ranges, API calls per command, slowest phases

Timing ranges

Command Workload Before range After range Change Verdict
supabase --version version 370-587 ms 390-644 ms +40 ms (+9%) within noise
supabase --help help 282-453 ms 332-455 ms -10 ms (-3%) within noise
supabase init init 276-409 ms 265-385 ms -20 ms (-6%) within noise
supabase migration new bench migration-new 280-591 ms 266-671 ms +16 ms (+5%) within noise
supabase config convert config-convert 252-691 ms 259-450 ms -5 ms (-1%) within noise
supabase config validate config-validate 299-868 ms 303-542 ms +56 ms (+17%) within noise
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 338-613 ms 336-651 ms +63 ms (+14%) within noise
supabase projects list projects-list 291-420 ms 301-506 ms +5 ms (+1%) within noise
supabase functions list --project-ref replayfixtureprojref functions-list 355-641 ms 293-631 ms -16 ms (-4%) within noise

API calls per command

Command Workload Before After Endpoint changes
supabase --version version 0 0
supabase --help help 0 0
supabase init init 0 0
supabase migration new bench migration-new 0 0
supabase config convert config-convert 0 0
supabase config validate config-validate 0 0
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 2 2
supabase projects list projects-list 1 1
supabase functions list --project-ref replayfixtureprojref functions-list 2 2

Slowest phases

No command moved beyond noise, so there are no phase deltas.

Workflow run

Comment /bench to run the lightweight benchmark (this comment) again on the latest commit, or /bench full to also run the integration-heavy benchmark, which posts in its own comment.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI Review

CLI reference prose guidance: snapshot supabase/supabase@f78870c supplied to reviewers (advisory, not a style pass).

Both independent reviews were available. Static verification confirms all three Claude findings at nit severity: two misleading error messages and one advisory prose issue supported by the available pinned guidance. Codex reported no findings.

Findings

Severity Location Category Sources Claim
⚪ NIT apps/cli/src/command-internal/stack-local-database.ts:177 error-handling claude A selected stack whose database is still starting is reported as "not running" and receives advice to start it again instead of waiting.
⚪ NIT apps/cli/src/command-internal/target/resolve-target.ts:87 error-handling claude On the legacy backend, combining --stack with --linked, --remote, or --db-url suggests enabling the experimental backend even though the same invocation would then fail because local-stack and remote selectors conflict.
⚪ NIT apps/cli/src/commands/experimental/stack/start/start.command.ts:34 docs-style claude The modified flag description "Open an existing stack by id or unique id prefix (defaults to SUPABASE_STACK_ID)." uses lowercase "id", contrary to the supplied terminology guidance. The modified descriptions in stack status, stop, restart, logs, and destroy have the same issue.

Stats

Claude findings: 3 · Codex findings: 0 · Confirmed: 3 · Refuted: 0 · Uncertain: 0


Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

@Coly010 Coly010 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One design change we'd like before this lands: can we collapse --stack and --stack-id into a single --stack that takes either a name or an ID, and do the same for the env with just SUPABASE_STACK? Two selectors that both mean "this stack" feels like more surface than people need, and it lets us drop the "both variables set" error entirely.

A few things that fall out of it:

  • Stack names can be any non-blank string, so cafe or 1234 could be either. I'd resolve a name under the current project and branch first, then an exact ID or unique prefix (4+ hex chars), so a name always wins on a collision and the result stays deterministic
  • The project scoping you have for SUPABASE_STACK_ID should carry over: SUPABASE_STACK resolving to an ID only selects a stack of the current project, while an explicit --stack <id> can still reach another checkout's stack
  • stack start --stack X would open an existing stack X matches by name or ID, otherwise create one named X. A mistyped ID would then create a stack with that name, which I think is acceptable, but shout if you'd rather handle it differently
  • supabase logs --stack-id shipped in v3.1.0, so I think it needs to stay on logs as a hidden deprecated alias for --stack. The stack subcommands sit outside the compatibility promise so they can just drop it
  • The printed hints from describeStackSelector would all become --stack <value>

On precedence, from my read it holds today: a flag beats the env, and the env is ignored rather than an error alongside --linked/--db-url and on the legacy backend, while an explicit flag errors in both. Can we keep that through the change? Unless I'm missing them, I couldn't find tests for the env-ignored cases (SUPABASE_STACK with --linked, SUPABASE_STACK on the legacy backend), so it'd be great to add those alongside a case where a --stack name beats a SUPABASE_STACK ID.

Otherwise, it looks good to me!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

stack: target migration commands at a specific stack with --stack / --stack-id

2 participants