From b49e9f816c161586d3e1dced4a68ec3e73c4e00f Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Tue, 4 Aug 2026 15:06:06 +0100 Subject: [PATCH 1/3] fix(cli): deprecate db diff --use-pg-schema, keep as sole Go delegation (CLI-1960) --use-pg-schema wraps the in-process Go library stripe/pg-schema-diff (apps/cli-go/internal/db/diff/pgschema.go) with no TS/container equivalent, so it is the M9 milestone's own sanctioned keep-in-Go exception rather than a port candidate. Deprecate the flag instead: print a TS-only stderr warning before delegating (additive to Go's own unchanged "experimental" warning), mark it deprecated in --help, and record the boundary/migration path (--use-pg-delta or the default migra engine) in SIDE_EFFECTS.md and go-cli-porting-status.md. --- apps/cli/docs/go-cli-porting-status.md | 4 +- .../legacy/commands/db/diff/SIDE_EFFECTS.md | 35 +++++++++++++ .../legacy/commands/db/diff/diff.command.ts | 10 +++- .../legacy/commands/db/diff/diff.handler.ts | 18 +++++-- .../commands/db/diff/diff.integration.test.ts | 49 ++++++++++++++++--- 5 files changed, 103 insertions(+), 13 deletions(-) diff --git a/apps/cli/docs/go-cli-porting-status.md b/apps/cli/docs/go-cli-porting-status.md index 19f91e2a70..1835658348 100644 --- a/apps/cli/docs/go-cli-porting-status.md +++ b/apps/cli/docs/go-cli-porting-status.md @@ -82,7 +82,7 @@ These commands exist in the TS CLI today but have no direct top-level equivalent | Old command | TS status | TS command path or `missing` | Missing flags/params | Extra TS flags/params | Notes | | --------------------------------- | --------- | -------------------------------------------------- | -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `db diff` | `ported` | `legacy/commands/db/diff/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra diff via edge-runtime against a Go-seam-provisioned live shadow (`db __shadow`); `--use-pgadmin` / `--use-pg-schema` delegate to the Go binary. | +| `db diff` | `ported` | `legacy/commands/db/diff/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra diff via edge-runtime against a Go-seam-provisioned live shadow (`db __shadow`); `--use-pgadmin` / `--use-pg-schema` delegate to the Go binary. `--use-pg-schema` is deprecated (CLI-1960: TS-only stderr warning + `--help` note) in favor of `--use-pg-delta`/the default migra engine, and is the **sole remaining Go delegation** after the M9 milestone's cleanup — it wraps the in-process `stripe/pg-schema-diff` Go library, which has no TS/container equivalent, so it is a documented keep-in-Go boundary, not a pending port. | | `db dump` | `ported` | `legacy/commands/db/dump/` | `n/a` | `n/a` | Native TS port. Streams `pg_dump`/`pg_dumpall` via a Docker container (`LegacyDockerRun`); schema/data/role modes, `--dry-run` script print, IPv4 transaction-pooler fallback. | | `db lint` | `ported` | `legacy/commands/db/lint/` | `n/a` | `n/a` | Native TS port. Runs `plpgsql_check` in a rolled-back transaction via LegacyDbConnection; emits Go-parity pretty JSON. | | `db pull` | `ported` | `legacy/commands/db/pull/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra migration + `--declarative` pg-delta export; reconciles `schema_migrations`. The initial-migra pull dumps the remote schema natively (`pg_dump`) then appends the migra diff. Only `--experimental` (structured dump) still delegates to Go, pending a TS PostgreSQL DDL parser for `format.WriteStructuredSchemas`. | @@ -298,7 +298,7 @@ Legend: | `test db` | `ported` | [`../src/legacy/commands/test/db/db.command.ts`](../src/legacy/commands/test/db/db.command.ts) | | `test new` | `ported` | [`../src/legacy/commands/test/new/new.command.ts`](../src/legacy/commands/test/new/new.command.ts) | | `seed buckets` | `ported` | [`../src/legacy/commands/seed/buckets/buckets.command.ts`](../src/legacy/commands/seed/buckets/buckets.command.ts) | -| `db diff` | `ported` | [`../src/legacy/commands/db/diff/diff.command.ts`](../src/legacy/commands/db/diff/diff.command.ts) — native pg-delta / migra; `--use-pgadmin` / `--use-pg-schema` delegate to Go | +| `db diff` | `ported` | [`../src/legacy/commands/db/diff/diff.command.ts`](../src/legacy/commands/db/diff/diff.command.ts) — native pg-delta / migra; `--use-pgadmin` / `--use-pg-schema` delegate to Go. `--use-pg-schema` is deprecated (CLI-1960) — kept as the sole remaining Go delegation (in-process `stripe/pg-schema-diff` library, no TS/container equivalent); migrate to `--use-pg-delta`/the default migra engine. | | `db dump` | `ported` | [`../src/legacy/commands/db/dump/dump.command.ts`](../src/legacy/commands/db/dump/dump.command.ts) | | `db push` | `ported` | [`../src/legacy/commands/db/push/push.command.ts`](../src/legacy/commands/db/push/push.command.ts) | | `db pull` | `ported` | [`../src/legacy/commands/db/pull/pull.command.ts`](../src/legacy/commands/db/pull/pull.command.ts) — native pg-delta / migra; `--declarative` (deprecated alias `--use-pg-delta`) + `--diff-engine` (migra\|pg-delta); initial-migra pull dumps the schema natively (`pg_dump`) + appends the diff; only `--experimental` structured dump still delegates to Go (needs a TS DDL parser for `WriteStructuredSchemas`) | diff --git a/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md index a019c95594..13ac3ce032 100644 --- a/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md +++ b/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md @@ -82,3 +82,38 @@ Progress strings still go to stderr; stdout carries a single structured envelope binary (their side effects are Go's); the Go child's telemetry is disabled so the single `cli_command_executed` event comes from this TS command. - Explicit `--from`/`--to` mode always uses pg-delta and writes to `--output` (or stdout). + +### `--use-pg-schema` is deprecated (CLI-1960) — sole remaining Go delegation + +`--use-pg-schema` wraps the in-process Go library `stripe/pg-schema-diff` +(`apps/cli-go/internal/db/diff/pgschema.go`). Unlike `--use-pgadmin` (which shells +out to a container/binary path that could in principle be re-invoked from TS), this +engine is called **in-process** inside the Go binary — there is no container image, +no TS binding, and no WASM build of the library available or reasonably buildable +within the M9 "Final Cleanup — Go Removal" milestone's scope. It was evaluated +against that milestone's keep-in-Go policy and is the milestone's own sanctioned +exception: after every other Go delegation in this command (and this milestone) is +removed, `--use-pg-schema` is intended to be the **sole remaining Go delegation** in +the whole CLI. + +Given that, the flag is now deprecated rather than ported: + +- A TS-only stderr deprecation warning is printed immediately before delegating + (both text and machine `--output-format` modes — diagnostics stay stderr-only, + the CLI-1546 rule): `--use-pg-schema is deprecated and will be removed in a +future release. Use --use-pg-delta (or the default migra engine) instead.` +- This is **additive** to (printed before) Go's own pre-existing "experimental" + warning (`cmd/db.go:121`, unchanged): `--use-pg-schema flag is experimental and +may not include all entities, such as views and grants.` The delegated child + still prints its own warning; the TS wrapper does not suppress or replace it. +- `--help` for the flag now also carries a `Deprecated: …` suffix pointing at the + same migration path. +- Actual flag removal and any PostHog usage-telemetry gate for that removal are + explicitly out of scope for CLI-1960 — this is a documentation/deprecation-notice + change only, tracked as a follow-up decision outside this milestone. + +Going forward, any review finding that argues this delegation should instead be +ported belongs against this documented decision (see +`~/.claude/skills/go-removal-sweep/references/keep-in-go-policy.md`), not +re-litigated per PR — re-open only if a TS/WASM binding for +`stripe/pg-schema-diff` ships. diff --git a/apps/cli/src/legacy/commands/db/diff/diff.command.ts b/apps/cli/src/legacy/commands/db/diff/diff.command.ts index a6f20725c2..bb8fc03373 100644 --- a/apps/cli/src/legacy/commands/db/diff/diff.command.ts +++ b/apps/cli/src/legacy/commands/db/diff/diff.command.ts @@ -22,7 +22,15 @@ const config = { Flag.optional, ), usePgSchema: Flag.boolean("use-pg-schema").pipe( - Flag.withDescription("Use pg-schema-diff to generate schema diff."), + // CLI-1960: deprecated in favor of --use-pg-delta (or the default migra + // engine); kept as the sole remaining Go delegation (in-process + // stripe/pg-schema-diff library, no TS/container equivalent). The flag + // itself is not marked deprecated in Go (no `MarkDeprecated` upstream), so + // this description-only notice is TS-only — see diff.handler.ts's runtime + // warning for the enforced half of the deprecation. + Flag.withDescription( + "Use pg-schema-diff to generate schema diff. Deprecated: use --use-pg-delta (or the default migra engine) instead.", + ), Flag.optional, ), usePgDelta: Flag.boolean("use-pg-delta").pipe( diff --git a/apps/cli/src/legacy/commands/db/diff/diff.handler.ts b/apps/cli/src/legacy/commands/db/diff/diff.handler.ts index 61fb818dbc..6c0fe08e7e 100644 --- a/apps/cli/src/legacy/commands/db/diff/diff.handler.ts +++ b/apps/cli/src/legacy/commands/db/diff/diff.handler.ts @@ -44,6 +44,15 @@ import { const warnDiff = `WARNING: The diff tool is not foolproof, so you may need to manually rearrange and modify the generated migration. Run ${legacyAqua("supabase db reset")} to verify that the new migration does not generate errors.`; +// TS-only deprecation notice (CLI-1960): `--use-pg-schema` wraps the in-process +// Go library `stripe/pg-schema-diff` (`apps/cli-go/internal/db/diff/pgschema.go`), +// which has no TS/container equivalent, so it stays the sole remaining Go +// delegation after the M9 milestone's cleanup — but the flag itself is now +// deprecated in favor of the pg-delta engine. This is additive to (and prints +// before) Go's own "experimental" warning (`cmd/db.go:121`), which the delegated +// child still prints unchanged. +const warnPgSchemaDeprecated = `${legacyYellow("WARNING:")} --use-pg-schema is deprecated and will be removed in a future release. Use --use-pg-delta (or the default migra engine) instead.`; + /** * Rebuilds the `db diff` argv for the pgAdmin / pg-schema delegate path. Flags * stay flags (the Go-proxy channel-parity rule). The explicit `--from`/`--to` and @@ -323,9 +332,12 @@ export const legacyDbDiff = Effect.fn("legacy.db.diff")(function* (flags: Legacy return; } if (usePgSchema) { - // The delegated Go `db diff --use-pg-schema` prints the experimental - // warning itself in its RunE (`cmd/db.go`), so don't pre-print it here — - // doing so would double the warning. Mirror the --use-pgadmin branch above. + // CLI-1960: TS-only deprecation notice, printed before delegating (in both + // text and machine output modes — diagnostics stay stderr-only per CLI-1546). + // The delegated Go `db diff --use-pg-schema` still prints its own experimental + // warning itself in its RunE (`cmd/db.go`); this is additive, not a + // replacement, so don't drop it. Mirror the --use-pgadmin branch above. + yield* output.raw(`${warnPgSchemaDeprecated}\n`, "stderr"); yield* delegateDiff("pg-schema"); return; } diff --git a/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts b/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts index f1a531c7a9..fcbab76737 100644 --- a/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts +++ b/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts @@ -412,17 +412,46 @@ describe("legacy db diff", () => { }).pipe(Effect.provide(s.layer)); }); - it.effect("delegates --use-pg-schema to the Go binary without a duplicate warning", () => { - const s = setup(tmp.current); + it.effect( + "delegates --use-pg-schema to the Go binary, printing a deprecation warning without duplicating Go's own warning", + () => { + const s = setup(tmp.current); + return Effect.gen(function* () { + yield* legacyDbDiff(flags({ usePgSchema: Option.some(true) })); + // CLI-1960: the TS wrapper prints its own deprecation notice pointing at + // pg-delta / the default migra engine, additive to (not a replacement for) + // the delegated Go child's own "experimental" warning (`cmd/db.go:121`, + // unchanged, printed by the real Go binary rather than this mocked proxy). + expect(stderr(s.out)).toContain( + "--use-pg-schema is deprecated and will be removed in a future release. Use --use-pg-delta (or the default migra engine) instead.", + ); + // The TS wrapper must not print a second copy of Go's own warning. + expect(stderr(s.out)).not.toContain("--use-pg-schema flag is experimental"); + // Delegation to Go is unchanged besides the new warning. + expect(s.proxyCalls[0]?.args).toEqual(["db", "diff", "--use-pg-schema"]); + }).pipe(Effect.provide(s.layer)); + }, + ); + + it.effect("does not print the --use-pg-schema deprecation warning on other diff paths", () => { + const s = setup(tmp.current, { diffSql: "create table g ();\n" }); return Effect.gen(function* () { - yield* legacyDbDiff(flags({ usePgSchema: Option.some(true) })); - // The delegated Go `db diff --use-pg-schema` prints the experimental - // warning itself; the TS wrapper must not print a second copy. - expect(stderr(s.out)).not.toContain("--use-pg-schema flag is experimental"); - expect(s.proxyCalls[0]?.args).toEqual(["db", "diff", "--use-pg-schema"]); + yield* legacyDbDiff(flags()); + expect(stderr(s.out)).not.toContain("--use-pg-schema is deprecated"); }).pipe(Effect.provide(s.layer)); }); + it.effect( + "does not print the --use-pg-schema deprecation warning when delegating --use-pgadmin", + () => { + const s = setup(tmp.current); + return Effect.gen(function* () { + yield* legacyDbDiff(flags({ usePgAdmin: Option.some(true) })); + expect(stderr(s.out)).not.toContain("--use-pg-schema is deprecated"); + }).pipe(Effect.provide(s.layer)); + }, + ); + it.effect("--use-pgadmin in json mode wraps the captured SQL in a structured envelope", () => { // Regression: the delegated child inherited stdout and returned without // output.success, so machine-mode stdout carried the Go child's raw SQL @@ -452,6 +481,12 @@ describe("legacy db diff", () => { expect(s.proxyCaptureCalls).toHaveLength(1); const success = s.out.messages.find((m) => m.type === "success"); expect(success?.data).toMatchObject({ diff: "create table e ();\n", engine: "pg-schema" }); + // CLI-1960: the deprecation notice is a diagnostic, so it must still reach + // stderr in machine output mode (CLI-1546) rather than being dropped or + // leaking into the stdout payload. + expect(stderr(s.out)).toContain( + "--use-pg-schema is deprecated and will be removed in a future release. Use --use-pg-delta (or the default migra engine) instead.", + ); }).pipe(Effect.provide(s.layer)); }); From 282da4d9cab66c1a55e30c8e447c19aa4e831845 Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Tue, 4 Aug 2026 15:32:42 +0100 Subject: [PATCH 2/3] fix(cli): address review findings on db diff --use-pg-schema deprecation (CLI-1960) Fix three review-flagged doc problems from the --use-pg-schema deprecation notice: replace the unresolvable ~/.claude/skills reference in SIDE_EFFECTS.md with inline keep-in-Go criteria and a CLI-1960 decision-record citation, drop the meta-commentary about PR review process, and rephrase the "sole remaining Go delegation" claim as conditional (--use-pgadmin, the db __shadow/ __db-bootstrap seams, and other in-flight M9 issues still delegate today) in both SIDE_EFFECTS.md and docs/go-cli-porting-status.md. Also drop the unowned removal-timeline promise from the deprecation warning and --help text, pointing at "the pg-delta engine" instead of the bare --use-pg-delta flag name (ambiguous with db pull's own deprecated flag), and update the integration test assertions to check a stable substring instead of the full sentence. --- apps/cli/docs/go-cli-porting-status.md | 92 +++++++++---------- .../legacy/commands/db/diff/SIDE_EFFECTS.md | 43 ++++----- .../legacy/commands/db/diff/diff.command.ts | 14 +-- .../legacy/commands/db/diff/diff.handler.ts | 13 +-- .../commands/db/diff/diff.integration.test.ts | 14 ++- 5 files changed, 88 insertions(+), 88 deletions(-) diff --git a/apps/cli/docs/go-cli-porting-status.md b/apps/cli/docs/go-cli-porting-status.md index 1835658348..eabd8f9d6a 100644 --- a/apps/cli/docs/go-cli-porting-status.md +++ b/apps/cli/docs/go-cli-porting-status.md @@ -80,51 +80,51 @@ These commands exist in the TS CLI today but have no direct top-level equivalent ## Database -| Old command | TS status | TS command path or `missing` | Missing flags/params | Extra TS flags/params | Notes | -| --------------------------------- | --------- | -------------------------------------------------- | -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `db diff` | `ported` | `legacy/commands/db/diff/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra diff via edge-runtime against a Go-seam-provisioned live shadow (`db __shadow`); `--use-pgadmin` / `--use-pg-schema` delegate to the Go binary. `--use-pg-schema` is deprecated (CLI-1960: TS-only stderr warning + `--help` note) in favor of `--use-pg-delta`/the default migra engine, and is the **sole remaining Go delegation** after the M9 milestone's cleanup — it wraps the in-process `stripe/pg-schema-diff` Go library, which has no TS/container equivalent, so it is a documented keep-in-Go boundary, not a pending port. | -| `db dump` | `ported` | `legacy/commands/db/dump/` | `n/a` | `n/a` | Native TS port. Streams `pg_dump`/`pg_dumpall` via a Docker container (`LegacyDockerRun`); schema/data/role modes, `--dry-run` script print, IPv4 transaction-pooler fallback. | -| `db lint` | `ported` | `legacy/commands/db/lint/` | `n/a` | `n/a` | Native TS port. Runs `plpgsql_check` in a rolled-back transaction via LegacyDbConnection; emits Go-parity pretty JSON. | -| `db pull` | `ported` | `legacy/commands/db/pull/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra migration + `--declarative` pg-delta export; reconciles `schema_migrations`. The initial-migra pull dumps the remote schema natively (`pg_dump`) then appends the migra diff. Only `--experimental` (structured dump) still delegates to Go, pending a TS PostgreSQL DDL parser for `format.WriteStructuredSchemas`. | -| `db push` | `ported` | `legacy/commands/db/push/` | `n/a` | `n/a` | Native TS port. Connects local/linked/`--db-url`; pushes pending migrations, `--include-seed` seeds (`seed_files` hash tracking), `--include-roles`, `[db.vault]` secrets including decrypted `encrypted:` values; `--dry-run`; best-effort pg-delta migrations-catalog cache (warning-only on failure). Pipeline-incompatible statements (`CREATE INDEX CONCURRENTLY`, `VACUUM`, …) run standalone outside the batch transaction — from the closed Go PR supabase/cli#5156, also ported into `apps/cli-go` (CLI-1989 ruling). | -| `db reset` | `ported` | `legacy/commands/db/reset/` | `n/a` | `n/a` | Remote path native (drop user schemas, vault upsert, MigrateAndSeed, `--version`/`--last`, `--sql-paths` seed override). Local path native: running check, recreate + migrate + seed via the hidden Go `db __db-bootstrap` seam, storage-gated bucket seeding (reuses `seed buckets`), git-branch `Finished…` line. Only the niche `--experimental` remote schema-files path still delegates to the Go binary (telemetry-disabled). Pipeline-incompatible statements run standalone outside the batch transaction, same as `db push` (closed Go PR supabase/cli#5156, CLI-1989 ruling). | -| `db start` | `ported` | `legacy/commands/db/start/` | `n/a` | `n/a` | Native TS port. Validates config, checks "already running" (prints Go's line), else delegates the container bootstrap (create + health + initial schema/roles/migrations/seed + `_current_branch`) to the hidden Go `db __db-bootstrap --mode start` seam. No status table / `cli_stack_started` (those are `supabase start`). `--from-backup` supported. | -| `inspect report` | `ported` | `legacy/commands/inspect/report/` | `n/a` | `n/a` | Native TS port. Runs every inspect query via server-side `COPY ... CSV`, writes 14 CSVs under `//`, then renders a Go-parity Glamour rules summary (bounded csvq-subset evaluator; custom `[experimental.inspect.rules]` supported). | -| `inspect db db-stats` | `ported` | `legacy/commands/inspect/db/db-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db replication-slots` | `ported` | `legacy/commands/inspect/db/replication-slots/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db locks` | `ported` | `legacy/commands/inspect/db/locks/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db blocking` | `ported` | `legacy/commands/inspect/db/blocking/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db outliers` | `ported` | `legacy/commands/inspect/db/outliers/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db calls` | `ported` | `legacy/commands/inspect/db/calls/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db index-stats` | `ported` | `legacy/commands/inspect/db/index-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db long-running-queries` | `ported` | `legacy/commands/inspect/db/long-running-queries/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db bloat` | `ported` | `legacy/commands/inspect/db/bloat/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db role-stats` | `ported` | `legacy/commands/inspect/db/role-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db vacuum-stats` | `ported` | `legacy/commands/inspect/db/vacuum-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db table-stats` | `ported` | `legacy/commands/inspect/db/table-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db traffic-profile` | `ported` | `legacy/commands/inspect/db/traffic-profile/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | -| `inspect db cache-hit` | `ported` | `legacy/commands/inspect/db/cache-hit/` | `n/a` | `n/a` | Native TS port. Deprecated (use db-stats); routes to the active query. | -| `inspect db index-usage` | `ported` | `legacy/commands/inspect/db/index-usage/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | -| `inspect db total-index-size` | `ported` | `legacy/commands/inspect/db/total-index-size/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | -| `inspect db index-sizes` | `ported` | `legacy/commands/inspect/db/index-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | -| `inspect db table-sizes` | `ported` | `legacy/commands/inspect/db/table-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | -| `inspect db table-index-sizes` | `ported` | `legacy/commands/inspect/db/table-index-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | -| `inspect db total-table-sizes` | `ported` | `legacy/commands/inspect/db/total-table-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | -| `inspect db unused-indexes` | `ported` | `legacy/commands/inspect/db/unused-indexes/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | -| `inspect db table-record-counts` | `ported` | `legacy/commands/inspect/db/table-record-counts/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | -| `inspect db seq-scans` | `ported` | `legacy/commands/inspect/db/seq-scans/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | -| `inspect db role-configs` | `ported` | `legacy/commands/inspect/db/role-configs/` | `n/a` | `n/a` | Native TS port. Deprecated (use role-stats); routes to the active query. | -| `inspect db role-connections` | `ported` | `legacy/commands/inspect/db/role-connections/` | `n/a` | `n/a` | Native TS port. Deprecated (use role-stats); routes to the active query. | -| `migration down` | `ported` | `legacy/commands/migration/down/` | `n/a` | `n/a` | Native TS port. Revert prompt → drop user schemas → vault upsert → migrate&seed to the target version; defaults to `--local`. Skips Go's pgcache catalog write. | -| `migration fetch` | `ported` | `legacy/commands/migration/fetch/` | `n/a` | `n/a` | Native TS port. Reads `schema_migrations` and writes `supabase/migrations/_.sql`; overwrite prompt for a non-empty dir. | -| `migration list` | `ported` | `legacy/commands/migration/list/` | `n/a` | `n/a` | Native TS port. Merges remote `schema_migrations` with local files into a Glamour ASCII table (Local / Remote / Time-UTC columns); defaults to `--linked`. | -| `migration new` | `ported` | `legacy/commands/migration/new/` | `n/a` | `n/a` | Native TS port. Writes `supabase/migrations/_.sql` (mode 0644) from piped stdin; no DB/API. | -| `migration repair` | `ported` | `legacy/commands/migration/repair/` | `n/a` | `n/a` | Native TS port. Transactional create-table + TRUNCATE/UPSERT/DELETE; applied mode reads local files; repair-all prompt; defaults to `--linked`. | -| `migration squash` | `missing` | `missing` | `n/a` | `n/a` | No native TS implementation yet. Wrapped in legacy shell. | -| `migration up` | `ported` | `legacy/commands/migration/up/` | `n/a` | `n/a` | Native TS port. Computes pending migrations, upserts `[db.vault]`, applies each transactionally (pipeline-incompatible statements run standalone — closed Go PR supabase/cli#5156, ported into `apps/cli-go`, CLI-1989 ruling); `--include-all` for out-of-order; defaults to `--local`. Does not seed (matches Go). | -| `seed buckets` | `ported` | `legacy/commands/seed/buckets/` | `n/a` | `n/a` | Native TS port. Local-only (Go's `seed` defines no `--project-ref`, so the ref is always empty): seeds `[storage.buckets]` + `[storage.vector]` against the local Storage service gateway; remote/analytics paths are unreachable and omitted. `--linked`/`--local` accepted for surface parity (both seed local). Vector graceful-skip WARNINGs ported. | -| `test db` | `ported` | `legacy/commands/test/db/` | `n/a` | `n/a` | Native TS port. `--db-url`/`--local`/`--linked` + variadic paths; runs `supabase/pg_prove:3.36` via `docker run`; pgTAP enable/disable via `@effect/sql-pg`. `--network-id` override and `[images]` config override not modeled (documented divergences). | -| `test new` | `ported` | `legacy/commands/test/new/` | `n/a` | `n/a` | Native TS port. Writes `supabase/tests/_test.sql` from the embedded pgtap template; `--template` (pgtap). | +| Old command | TS status | TS command path or `missing` | Missing flags/params | Extra TS flags/params | Notes | +| --------------------------------- | --------- | -------------------------------------------------- | -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `db diff` | `ported` | `legacy/commands/db/diff/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra diff via edge-runtime against a Go-seam-provisioned live shadow (`db __shadow`); `--use-pgadmin` / `--use-pg-schema` delegate to the Go binary. `--use-pg-schema` is deprecated (CLI-1960: TS-only stderr warning + `--help` note) in favor of the pg-delta engine or the default migra engine — it wraps the in-process `stripe/pg-schema-diff` Go library, which has no TS/container equivalent, so it is a documented keep-in-Go exception, not a pending port. It will be the sole remaining Go delegation once `--use-pgadmin`, the `db __shadow`/`db __db-bootstrap` seams, and the other in-flight M9 issues are done. | +| `db dump` | `ported` | `legacy/commands/db/dump/` | `n/a` | `n/a` | Native TS port. Streams `pg_dump`/`pg_dumpall` via a Docker container (`LegacyDockerRun`); schema/data/role modes, `--dry-run` script print, IPv4 transaction-pooler fallback. | +| `db lint` | `ported` | `legacy/commands/db/lint/` | `n/a` | `n/a` | Native TS port. Runs `plpgsql_check` in a rolled-back transaction via LegacyDbConnection; emits Go-parity pretty JSON. | +| `db pull` | `ported` | `legacy/commands/db/pull/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra migration + `--declarative` pg-delta export; reconciles `schema_migrations`. The initial-migra pull dumps the remote schema natively (`pg_dump`) then appends the migra diff. Only `--experimental` (structured dump) still delegates to Go, pending a TS PostgreSQL DDL parser for `format.WriteStructuredSchemas`. | +| `db push` | `ported` | `legacy/commands/db/push/` | `n/a` | `n/a` | Native TS port. Connects local/linked/`--db-url`; pushes pending migrations, `--include-seed` seeds (`seed_files` hash tracking), `--include-roles`, `[db.vault]` secrets including decrypted `encrypted:` values; `--dry-run`; best-effort pg-delta migrations-catalog cache (warning-only on failure). Pipeline-incompatible statements (`CREATE INDEX CONCURRENTLY`, `VACUUM`, …) run standalone outside the batch transaction — from the closed Go PR supabase/cli#5156, also ported into `apps/cli-go` (CLI-1989 ruling). | +| `db reset` | `ported` | `legacy/commands/db/reset/` | `n/a` | `n/a` | Remote path native (drop user schemas, vault upsert, MigrateAndSeed, `--version`/`--last`, `--sql-paths` seed override). Local path native: running check, recreate + migrate + seed via the hidden Go `db __db-bootstrap` seam, storage-gated bucket seeding (reuses `seed buckets`), git-branch `Finished…` line. Only the niche `--experimental` remote schema-files path still delegates to the Go binary (telemetry-disabled). Pipeline-incompatible statements run standalone outside the batch transaction, same as `db push` (closed Go PR supabase/cli#5156, CLI-1989 ruling). | +| `db start` | `ported` | `legacy/commands/db/start/` | `n/a` | `n/a` | Native TS port. Validates config, checks "already running" (prints Go's line), else delegates the container bootstrap (create + health + initial schema/roles/migrations/seed + `_current_branch`) to the hidden Go `db __db-bootstrap --mode start` seam. No status table / `cli_stack_started` (those are `supabase start`). `--from-backup` supported. | +| `inspect report` | `ported` | `legacy/commands/inspect/report/` | `n/a` | `n/a` | Native TS port. Runs every inspect query via server-side `COPY ... CSV`, writes 14 CSVs under `//`, then renders a Go-parity Glamour rules summary (bounded csvq-subset evaluator; custom `[experimental.inspect.rules]` supported). | +| `inspect db db-stats` | `ported` | `legacy/commands/inspect/db/db-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db replication-slots` | `ported` | `legacy/commands/inspect/db/replication-slots/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db locks` | `ported` | `legacy/commands/inspect/db/locks/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db blocking` | `ported` | `legacy/commands/inspect/db/blocking/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db outliers` | `ported` | `legacy/commands/inspect/db/outliers/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db calls` | `ported` | `legacy/commands/inspect/db/calls/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db index-stats` | `ported` | `legacy/commands/inspect/db/index-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db long-running-queries` | `ported` | `legacy/commands/inspect/db/long-running-queries/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db bloat` | `ported` | `legacy/commands/inspect/db/bloat/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db role-stats` | `ported` | `legacy/commands/inspect/db/role-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db vacuum-stats` | `ported` | `legacy/commands/inspect/db/vacuum-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db table-stats` | `ported` | `legacy/commands/inspect/db/table-stats/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db traffic-profile` | `ported` | `legacy/commands/inspect/db/traffic-profile/` | `n/a` | `n/a` | Native TS port. Queries Postgres directly via LegacyDbConnection; renders Go-parity Glamour tables. | +| `inspect db cache-hit` | `ported` | `legacy/commands/inspect/db/cache-hit/` | `n/a` | `n/a` | Native TS port. Deprecated (use db-stats); routes to the active query. | +| `inspect db index-usage` | `ported` | `legacy/commands/inspect/db/index-usage/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | +| `inspect db total-index-size` | `ported` | `legacy/commands/inspect/db/total-index-size/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | +| `inspect db index-sizes` | `ported` | `legacy/commands/inspect/db/index-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | +| `inspect db table-sizes` | `ported` | `legacy/commands/inspect/db/table-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | +| `inspect db table-index-sizes` | `ported` | `legacy/commands/inspect/db/table-index-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | +| `inspect db total-table-sizes` | `ported` | `legacy/commands/inspect/db/total-table-sizes/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | +| `inspect db unused-indexes` | `ported` | `legacy/commands/inspect/db/unused-indexes/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | +| `inspect db table-record-counts` | `ported` | `legacy/commands/inspect/db/table-record-counts/` | `n/a` | `n/a` | Native TS port. Deprecated (use table-stats); routes to the active query. | +| `inspect db seq-scans` | `ported` | `legacy/commands/inspect/db/seq-scans/` | `n/a` | `n/a` | Native TS port. Deprecated (use index-stats); routes to the active query. | +| `inspect db role-configs` | `ported` | `legacy/commands/inspect/db/role-configs/` | `n/a` | `n/a` | Native TS port. Deprecated (use role-stats); routes to the active query. | +| `inspect db role-connections` | `ported` | `legacy/commands/inspect/db/role-connections/` | `n/a` | `n/a` | Native TS port. Deprecated (use role-stats); routes to the active query. | +| `migration down` | `ported` | `legacy/commands/migration/down/` | `n/a` | `n/a` | Native TS port. Revert prompt → drop user schemas → vault upsert → migrate&seed to the target version; defaults to `--local`. Skips Go's pgcache catalog write. | +| `migration fetch` | `ported` | `legacy/commands/migration/fetch/` | `n/a` | `n/a` | Native TS port. Reads `schema_migrations` and writes `supabase/migrations/_.sql`; overwrite prompt for a non-empty dir. | +| `migration list` | `ported` | `legacy/commands/migration/list/` | `n/a` | `n/a` | Native TS port. Merges remote `schema_migrations` with local files into a Glamour ASCII table (Local / Remote / Time-UTC columns); defaults to `--linked`. | +| `migration new` | `ported` | `legacy/commands/migration/new/` | `n/a` | `n/a` | Native TS port. Writes `supabase/migrations/_.sql` (mode 0644) from piped stdin; no DB/API. | +| `migration repair` | `ported` | `legacy/commands/migration/repair/` | `n/a` | `n/a` | Native TS port. Transactional create-table + TRUNCATE/UPSERT/DELETE; applied mode reads local files; repair-all prompt; defaults to `--linked`. | +| `migration squash` | `missing` | `missing` | `n/a` | `n/a` | No native TS implementation yet. Wrapped in legacy shell. | +| `migration up` | `ported` | `legacy/commands/migration/up/` | `n/a` | `n/a` | Native TS port. Computes pending migrations, upserts `[db.vault]`, applies each transactionally (pipeline-incompatible statements run standalone — closed Go PR supabase/cli#5156, ported into `apps/cli-go`, CLI-1989 ruling); `--include-all` for out-of-order; defaults to `--local`. Does not seed (matches Go). | +| `seed buckets` | `ported` | `legacy/commands/seed/buckets/` | `n/a` | `n/a` | Native TS port. Local-only (Go's `seed` defines no `--project-ref`, so the ref is always empty): seeds `[storage.buckets]` + `[storage.vector]` against the local Storage service gateway; remote/analytics paths are unreachable and omitted. `--linked`/`--local` accepted for surface parity (both seed local). Vector graceful-skip WARNINGs ported. | +| `test db` | `ported` | `legacy/commands/test/db/` | `n/a` | `n/a` | Native TS port. `--db-url`/`--local`/`--linked` + variadic paths; runs `supabase/pg_prove:3.36` via `docker run`; pgTAP enable/disable via `@effect/sql-pg`. `--network-id` override and `[images]` config override not modeled (documented divergences). | +| `test new` | `ported` | `legacy/commands/test/new/` | `n/a` | `n/a` | Native TS port. Writes `supabase/tests/_test.sql` from the embedded pgtap template; `--template` (pgtap). | ## Code Generation @@ -298,7 +298,7 @@ Legend: | `test db` | `ported` | [`../src/legacy/commands/test/db/db.command.ts`](../src/legacy/commands/test/db/db.command.ts) | | `test new` | `ported` | [`../src/legacy/commands/test/new/new.command.ts`](../src/legacy/commands/test/new/new.command.ts) | | `seed buckets` | `ported` | [`../src/legacy/commands/seed/buckets/buckets.command.ts`](../src/legacy/commands/seed/buckets/buckets.command.ts) | -| `db diff` | `ported` | [`../src/legacy/commands/db/diff/diff.command.ts`](../src/legacy/commands/db/diff/diff.command.ts) — native pg-delta / migra; `--use-pgadmin` / `--use-pg-schema` delegate to Go. `--use-pg-schema` is deprecated (CLI-1960) — kept as the sole remaining Go delegation (in-process `stripe/pg-schema-diff` library, no TS/container equivalent); migrate to `--use-pg-delta`/the default migra engine. | +| `db diff` | `ported` | [`../src/legacy/commands/db/diff/diff.command.ts`](../src/legacy/commands/db/diff/diff.command.ts) — native pg-delta / migra; `--use-pgadmin` / `--use-pg-schema` delegate to Go. `--use-pg-schema` is deprecated (CLI-1960) — a keep-in-Go exception (in-process `stripe/pg-schema-diff` library, no TS/container equivalent), not yet the sole remaining Go delegation (`--use-pgadmin` and other in-flight M9 issues still delegate too); migrate to the pg-delta engine or the default migra engine. | | `db dump` | `ported` | [`../src/legacy/commands/db/dump/dump.command.ts`](../src/legacy/commands/db/dump/dump.command.ts) | | `db push` | `ported` | [`../src/legacy/commands/db/push/push.command.ts`](../src/legacy/commands/db/push/push.command.ts) | | `db pull` | `ported` | [`../src/legacy/commands/db/pull/pull.command.ts`](../src/legacy/commands/db/pull/pull.command.ts) — native pg-delta / migra; `--declarative` (deprecated alias `--use-pg-delta`) + `--diff-engine` (migra\|pg-delta); initial-migra pull dumps the schema natively (`pg_dump`) + appends the diff; only `--experimental` structured dump still delegates to Go (needs a TS DDL parser for `WriteStructuredSchemas`) | diff --git a/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md index 13ac3ce032..28836f4744 100644 --- a/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md +++ b/apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md @@ -83,37 +83,38 @@ Progress strings still go to stderr; stdout carries a single structured envelope single `cli_command_executed` event comes from this TS command. - Explicit `--from`/`--to` mode always uses pg-delta and writes to `--output` (or stdout). -### `--use-pg-schema` is deprecated (CLI-1960) — sole remaining Go delegation +### `--use-pg-schema` is deprecated (CLI-1960) — keep-in-Go exception `--use-pg-schema` wraps the in-process Go library `stripe/pg-schema-diff` -(`apps/cli-go/internal/db/diff/pgschema.go`). Unlike `--use-pgadmin` (which shells -out to a container/binary path that could in principle be re-invoked from TS), this -engine is called **in-process** inside the Go binary — there is no container image, -no TS binding, and no WASM build of the library available or reasonably buildable -within the M9 "Final Cleanup — Go Removal" milestone's scope. It was evaluated -against that milestone's keep-in-Go policy and is the milestone's own sanctioned -exception: after every other Go delegation in this command (and this milestone) is -removed, `--use-pg-schema` is intended to be the **sole remaining Go delegation** in -the whole CLI. +(`apps/cli-go/internal/db/diff/pgschema.go`). It is a keep-in-Go exception rather +than a pending port because: + +- it runs **in-process** inside the Go binary, with no container/binary boundary + to re-invoke from TS — unlike `--use-pgadmin`, which shells out to a + container/binary path that could in principle be called from TS; +- no TS binding and no WASM build of the library exists, or is reasonably + buildable, within the M9 "Final Cleanup — Go Removal" milestone's scope; +- this specific exception (`db diff --use-pg-schema`) was pre-named when the M9 + milestone was scoped. + +The decision record is Linear issue CLI-1960 and the pull request that introduced +this deprecation notice; re-open only if a TS/WASM binding for +`stripe/pg-schema-diff` ships. It will become the CLI's sole remaining Go delegation +once `--use-pgadmin`'s delegation, the `db __shadow`/`db __db-bootstrap` seams, and +the rest of the M9 milestone's in-flight issues are done — it is not there yet. Given that, the flag is now deprecated rather than ported: - A TS-only stderr deprecation warning is printed immediately before delegating (both text and machine `--output-format` modes — diagnostics stay stderr-only, - the CLI-1546 rule): `--use-pg-schema is deprecated and will be removed in a -future release. Use --use-pg-delta (or the default migra engine) instead.` + the CLI-1546 rule): `"--use-pg-schema" is deprecated. Use the pg-delta engine ([experimental.pgdelta] enabled = true / --use-pg-delta) or the default migra engine instead.` + The warning text intentionally does not promise a removal timeline. - This is **additive** to (printed before) Go's own pre-existing "experimental" - warning (`cmd/db.go:121`, unchanged): `--use-pg-schema flag is experimental and -may not include all entities, such as views and grants.` The delegated child + warning (`cmd/db.go:121`, unchanged): `--use-pg-schema flag is experimental and may not include all entities, such as views and grants.` The delegated child still prints its own warning; the TS wrapper does not suppress or replace it. - `--help` for the flag now also carries a `Deprecated: …` suffix pointing at the same migration path. - Actual flag removal and any PostHog usage-telemetry gate for that removal are explicitly out of scope for CLI-1960 — this is a documentation/deprecation-notice - change only, tracked as a follow-up decision outside this milestone. - -Going forward, any review finding that argues this delegation should instead be -ported belongs against this documented decision (see -`~/.claude/skills/go-removal-sweep/references/keep-in-go-policy.md`), not -re-litigated per PR — re-open only if a TS/WASM binding for -`stripe/pg-schema-diff` ships. + change only, tracked as a follow-up decision outside this milestone, with no + owning issue yet. diff --git a/apps/cli/src/legacy/commands/db/diff/diff.command.ts b/apps/cli/src/legacy/commands/db/diff/diff.command.ts index bb8fc03373..0aa0d9b1ff 100644 --- a/apps/cli/src/legacy/commands/db/diff/diff.command.ts +++ b/apps/cli/src/legacy/commands/db/diff/diff.command.ts @@ -22,14 +22,14 @@ const config = { Flag.optional, ), usePgSchema: Flag.boolean("use-pg-schema").pipe( - // CLI-1960: deprecated in favor of --use-pg-delta (or the default migra - // engine); kept as the sole remaining Go delegation (in-process - // stripe/pg-schema-diff library, no TS/container equivalent). The flag - // itself is not marked deprecated in Go (no `MarkDeprecated` upstream), so - // this description-only notice is TS-only — see diff.handler.ts's runtime - // warning for the enforced half of the deprecation. + // CLI-1960: deprecated in favor of the pg-delta engine (or the default + // migra engine); a keep-in-Go exception (in-process stripe/pg-schema-diff + // library, no TS/container equivalent — see SIDE_EFFECTS.md), not a pending + // port. The flag itself is not marked deprecated in Go (no `MarkDeprecated` + // upstream), so this description-only notice is TS-only — see + // diff.handler.ts's runtime warning for the enforced half of the deprecation. Flag.withDescription( - "Use pg-schema-diff to generate schema diff. Deprecated: use --use-pg-delta (or the default migra engine) instead.", + "Use pg-schema-diff to generate schema diff. Deprecated: use the pg-delta engine ([experimental.pgdelta] enabled = true / --use-pg-delta) or the default migra engine instead.", ), Flag.optional, ), diff --git a/apps/cli/src/legacy/commands/db/diff/diff.handler.ts b/apps/cli/src/legacy/commands/db/diff/diff.handler.ts index 6c0fe08e7e..6a2910aa87 100644 --- a/apps/cli/src/legacy/commands/db/diff/diff.handler.ts +++ b/apps/cli/src/legacy/commands/db/diff/diff.handler.ts @@ -46,12 +46,13 @@ Run ${legacyAqua("supabase db reset")} to verify that the new migration does not // TS-only deprecation notice (CLI-1960): `--use-pg-schema` wraps the in-process // Go library `stripe/pg-schema-diff` (`apps/cli-go/internal/db/diff/pgschema.go`), -// which has no TS/container equivalent, so it stays the sole remaining Go -// delegation after the M9 milestone's cleanup — but the flag itself is now -// deprecated in favor of the pg-delta engine. This is additive to (and prints -// before) Go's own "experimental" warning (`cmd/db.go:121`), which the delegated -// child still prints unchanged. -const warnPgSchemaDeprecated = `${legacyYellow("WARNING:")} --use-pg-schema is deprecated and will be removed in a future release. Use --use-pg-delta (or the default migra engine) instead.`; +// which has no TS/container equivalent — a keep-in-Go exception, not a pending +// port (see SIDE_EFFECTS.md). The flag itself is now deprecated in favor of the +// pg-delta engine. This is additive to (and prints before) Go's own +// "experimental" warning (`cmd/db.go:121`), which the delegated child still +// prints unchanged. No removal timeline is promised: actual removal is out of +// scope for CLI-1960. +const warnPgSchemaDeprecated = `${legacyYellow("WARNING:")} "--use-pg-schema" is deprecated. Use the pg-delta engine ([experimental.pgdelta] enabled = true / --use-pg-delta) or the default migra engine instead.`; /** * Rebuilds the `db diff` argv for the pgAdmin / pg-schema delegate path. Flags diff --git a/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts b/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts index fcbab76737..e89962eafc 100644 --- a/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts +++ b/apps/cli/src/legacy/commands/db/diff/diff.integration.test.ts @@ -422,9 +422,9 @@ describe("legacy db diff", () => { // pg-delta / the default migra engine, additive to (not a replacement for) // the delegated Go child's own "experimental" warning (`cmd/db.go:121`, // unchanged, printed by the real Go binary rather than this mocked proxy). - expect(stderr(s.out)).toContain( - "--use-pg-schema is deprecated and will be removed in a future release. Use --use-pg-delta (or the default migra engine) instead.", - ); + // Assert on a stable substring so future wording tweaks don't require + // touching every test site. + expect(stderr(s.out)).toContain('"--use-pg-schema" is deprecated'); // The TS wrapper must not print a second copy of Go's own warning. expect(stderr(s.out)).not.toContain("--use-pg-schema flag is experimental"); // Delegation to Go is unchanged besides the new warning. @@ -437,7 +437,7 @@ describe("legacy db diff", () => { const s = setup(tmp.current, { diffSql: "create table g ();\n" }); return Effect.gen(function* () { yield* legacyDbDiff(flags()); - expect(stderr(s.out)).not.toContain("--use-pg-schema is deprecated"); + expect(stderr(s.out)).not.toContain('"--use-pg-schema" is deprecated'); }).pipe(Effect.provide(s.layer)); }); @@ -447,7 +447,7 @@ describe("legacy db diff", () => { const s = setup(tmp.current); return Effect.gen(function* () { yield* legacyDbDiff(flags({ usePgAdmin: Option.some(true) })); - expect(stderr(s.out)).not.toContain("--use-pg-schema is deprecated"); + expect(stderr(s.out)).not.toContain('"--use-pg-schema" is deprecated'); }).pipe(Effect.provide(s.layer)); }, ); @@ -484,9 +484,7 @@ describe("legacy db diff", () => { // CLI-1960: the deprecation notice is a diagnostic, so it must still reach // stderr in machine output mode (CLI-1546) rather than being dropped or // leaking into the stdout payload. - expect(stderr(s.out)).toContain( - "--use-pg-schema is deprecated and will be removed in a future release. Use --use-pg-delta (or the default migra engine) instead.", - ); + expect(stderr(s.out)).toContain('"--use-pg-schema" is deprecated'); }).pipe(Effect.provide(s.layer)); }); From 7f747efb77870e9e6d2f864fa9b876d3ff68b280 Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Tue, 4 Aug 2026 17:34:07 +0100 Subject: [PATCH 3/3] docs(cli): reformat go-cli-porting-status.md table (oxfmt column widths) --- apps/cli/docs/go-cli-porting-status.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/cli/docs/go-cli-porting-status.md b/apps/cli/docs/go-cli-porting-status.md index 808c97f1f8..3c815a0ab0 100644 --- a/apps/cli/docs/go-cli-porting-status.md +++ b/apps/cli/docs/go-cli-porting-status.md @@ -85,7 +85,7 @@ These commands exist in the TS CLI today but have no direct top-level equivalent | `db diff` | `ported` | `legacy/commands/db/diff/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra diff via edge-runtime against a Go-seam-provisioned live shadow (`db __shadow`); `--use-pgadmin` / `--use-pg-schema` delegate to the Go binary. `--use-pg-schema` is deprecated (CLI-1960: TS-only stderr warning + `--help` note) in favor of the pg-delta engine or the default migra engine — it wraps the in-process `stripe/pg-schema-diff` Go library, which has no TS/container equivalent, so it is a documented keep-in-Go exception, not a pending port. It will be the sole remaining Go delegation once `--use-pgadmin`, the `db __shadow`/`db __db-bootstrap` seams, and the other in-flight M9 issues are done. | | `db dump` | `ported` | `legacy/commands/db/dump/` | `n/a` | `n/a` | Native TS port. Streams `pg_dump`/`pg_dumpall` via a Docker container (`LegacyDockerRun`); schema/data/role modes, `--dry-run` script print, IPv4 transaction-pooler fallback. | | `db lint` | `ported` | `legacy/commands/db/lint/` | `n/a` | `n/a` | Native TS port. Runs `plpgsql_check` in a rolled-back transaction via LegacyDbConnection; emits Go-parity pretty JSON. | -| `db pull` | `ported` | `legacy/commands/db/pull/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra migration + `--declarative` pg-delta export; reconciles `schema_migrations`. The initial-migra pull dumps the remote schema natively (`pg_dump`) then appends the migra diff. Only `--experimental` (structured dump) still delegates to Go, deprecated in favor of `--declarative` (CLI-1957) — it needs a TS PostgreSQL DDL parser for Go's `format.WriteStructuredSchemas` that has no equivalent in this repo, and `--declarative` already delivers the same per-object schema split via pg-delta catalog introspection. | +| `db pull` | `ported` | `legacy/commands/db/pull/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra migration + `--declarative` pg-delta export; reconciles `schema_migrations`. The initial-migra pull dumps the remote schema natively (`pg_dump`) then appends the migra diff. Only `--experimental` (structured dump) still delegates to Go, deprecated in favor of `--declarative` (CLI-1957) — it needs a TS PostgreSQL DDL parser for Go's `format.WriteStructuredSchemas` that has no equivalent in this repo, and `--declarative` already delivers the same per-object schema split via pg-delta catalog introspection. | | `db push` | `ported` | `legacy/commands/db/push/` | `n/a` | `n/a` | Native TS port. Connects local/linked/`--db-url`; pushes pending migrations, `--include-seed` seeds (`seed_files` hash tracking), `--include-roles`, `[db.vault]` secrets including decrypted `encrypted:` values; `--dry-run`; best-effort pg-delta migrations-catalog cache (warning-only on failure). Pipeline-incompatible statements (`CREATE INDEX CONCURRENTLY`, `VACUUM`, …) run standalone outside the batch transaction — from the closed Go PR supabase/cli#5156, also ported into `apps/cli-go` (CLI-1989 ruling). | | `db reset` | `ported` | `legacy/commands/db/reset/` | `n/a` | `n/a` | Remote path native (drop user schemas, vault upsert, MigrateAndSeed, `--version`/`--last`, `--sql-paths` seed override). Local path native: running check, recreate + migrate + seed via the hidden Go `db __db-bootstrap` seam, storage-gated bucket seeding (reuses `seed buckets`), git-branch `Finished…` line. Only the niche `--experimental` remote schema-files path still delegates to the Go binary (telemetry-disabled). Pipeline-incompatible statements run standalone outside the batch transaction, same as `db push` (closed Go PR supabase/cli#5156, CLI-1989 ruling). | | `db start` | `ported` | `legacy/commands/db/start/` | `n/a` | `n/a` | Native TS port. Validates config, checks "already running" (prints Go's line), else delegates the container bootstrap (create + health + initial schema/roles/migrations/seed + `_current_branch`) to the hidden Go `db __db-bootstrap --mode start` seam. No status table / `cli_stack_started` (those are `supabase start`). `--from-backup` supported. |