Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#6,974 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
1/5
Thời gian dự kiến
Dưới một giờ
Mức phù hợp với người mới
88/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
postgresql, typescript
Lĩnh vực
cli, databases, documentation

Hướng nghiên cứu

Bắt đầu từ apps/cli/src/commands/db/diff/diff.command.ts và so sánh nội dung trợ giúp của nó với cách xử lý override target trong apps/cli/src/commands/db/shared/shadow-source.ts và diff.handler.ts. Xác minh rằng phần mô tả phân biệt target cơ sở dữ liệu đang hoạt động của pg-delta với target khai báo legacy cục bộ của migra. Hoàn thành khi nội dung trợ giúp giải thích cả hai trường hợp và fixture chỉ khai báo hiện có của stack đã dừng vẫn tạo ra migration như mong đợi.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

📘 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.

Ngôn ngữ chính
TypeScript
Star
2.4k
Fork
533
Merge trung bình
21 giờ 49 phút
Pull request đã merge (30 ngày)
371

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của supabase/cli

Tất cả issue của supabase/cli

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.