fix(cli): clarify db diff help for the migra declarative target #6974

Summary

The generic db diff description says the command compares migrations with a live database, but --local --use-migra can compare migrations with a target built from declared SQL instead. That supported branch works with the local stack stopped. The help does not name this exception, so it gives legacy declarative projects the wrong comparison model.

This is an incorrect command description, not a request to change the schema-diff engine or migration behavior. The statement that declarative files are not the migrations baseline is accurate for the source side. The missing distinction is that migra can use those files for the target side.

Steps to reproduce

1. Use the published npm package supabase@2.119.0 through the installed project runner. Run npm exec -- supabase db diff --help and read the description quoted below.
2. In an isolated local Docker project, retain [experimental.pgdelta] enabled = false and set [db.migrations] schema_paths = ["./schemas/*.sql"]. Leave generic experimental and engine/runtime environment overrides unset.
3. Put the following initial definition in one versioned migration and in supabase/schemas/catalog.sql. Start the local project once and verify the initial table exists.

create table public.catalog (
  id bigint generated always as identity primary key,
  label text not null
);

4. Stop only that local project with npm exec -- supabase stop. Change only the declaration to the following definition, leaving migration history unchanged.

create table public.catalog (
  id bigint generated always as identity primary key,
  label text not null,
  category text
);

5. With the local stack still stopped, run npm exec -- supabase db diff --local --use-migra -f add_catalog_category and inspect the emitted migration.

The executed fixture used these steps with a database-only Docker stack. It generated the declaration-only change successfully. The defect can also be inspected without Docker by comparing the command description with the linked declared-target branch.

Expected behavior

The help distinguishes the migrations source from the selected target. It explains that pg-delta normal diff uses the live selected database, while a local migra diff can build its target from configured declarations. It should let a legacy declarative-project user understand why a stopped-stack diff can generate a change that was never applied to the live database.

The closure signal is that help accurately describes both cases and the existing declaration-only fixture still produces the expected migration without requiring a running local database. There is no request to change either engine's comparison behavior.

Actual behavior

The description reads:

Compares a shadow built from supabase/migrations with a live database (--local by default, --linked, or --db-url). Declarative files under supabase/schemas are not part of this baseline.

In the stopped legacy fixture, db diff --local --use-migra -f add_catalog_category exited 0, selected engine=migra, and generated:

alter table "public"."catalog" add column "category" text;

That column existed only in the declaration at diff time. After restart and local application, an explicit local reset replayed both migrations successfully. A second stopped migra diff returned No schema changes found and wrote no migration. These results establish that the declaration target worked; the command description omitted it.

Affected area

Database / Migrations command help. Documentation issue type: incorrect documentation. The description is in apps/cli/src/commands/db/diff/diff.command.ts; the supported target override is in apps/cli/src/commands/db/shared/shadow-source.ts and its consumer in diff.handler.ts.

Runtime or environment

• Supabase CLI 2.119.0, installed as a project-local npm dependency.
• Node.js 22.23.2 and npm 12.0.2.
• macOS arm64 host with Docker Engine 29.8.0, Linux arm64 containers, and PostgreSQL 17.11.
• Legacy migra configuration, pg-delta disabled, no generic experimental flag, and no engine/runtime environment overrides.

Evidence

• The tested release source is v2.119.0, commit 3cb948c5a70d31fbcb0fd1dcc616ee196a125cd0.
• The fetched default branch is develop at 66ccc6f63a9a26b29c368698994a0843d23b80be. Its command description retains the same text.
• At that current revision, shadow-source.ts loads declared schemas for a local legacy target and creates targetUrlOverride. The diff handler consumes that override.
• Merged PR #6920 explicitly retains contrib_regression for migra because it is the declarative diff target.
• All 20 commits from the tested release source to the fetched default SHA were reviewed, together with the complete live open corpus of 80 issues and pull requests and relevant closed issues and merged PRs. No matching command-help report or fix was found. Closed issue #3827 concerns a stopped-stack connection failure in an older release, rather than the successful migra branch and misleading help reported here.

Current-source status comes from source inspection. The executed Docker workflow was against published CLI 2.119.0; the current default revision was not built or executed for this report.

Impact

Users and agents who follow command help cannot tell whether a local migra diff reads their running database or their declarations. They may dismiss a supported declaration workflow or attribute its generated migration to live database changes. Naming the engine-specific target restores a reliable command description.