Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#6,974 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
1/5
Tiempo estimado
Menos de una hora
Aptitud para principiantes
88/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
postgresql, typescript
Área
cli, databases, documentation

Línea de trabajo

Comienza en apps/cli/src/commands/db/diff/diff.command.ts y compara su texto de ayuda con el manejo de la sobrescritura del destino en apps/cli/src/commands/db/shared/shadow-source.ts y diff.handler.ts. Verifica que la descripción distinga entre el destino de base de datos en vivo de pg-delta y el destino de declaración local legacy de migra. Se considera terminado cuando la ayuda explica ambos casos y el fixture existente de solo declaración para un stack detenido sigue generando la migración esperada.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

📘 Docs supabase/cli

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 [email protected] 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
);
  1. 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
);
  1. 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.

Lenguaje dominante
TypeScript
Estrellas
2.4k
Forks
533
Merge medio
21 h 24 min
PR fusionados (30 d)
378

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de supabase/cli

Todos los issues de supabase/cli

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.