feat: add pg delta declarative sync command

[avallete]

Summary

This PR introduces an experimental pg-delta powered declarative schema workflow to the CLI.

It adds a new supabase db declarative command group so users can generate declarative SQL files from a database, edit those files as the source of truth, and sync them back into the migration workflow by generating a new migration from the declarative diff.

In addition to the new command surface, this PR expands the underlying pg-delta integration with declarative export/apply support, reusable catalog caching, explicit source/target diffing, configurable declarative paths and formatting, and better debug artifacts for failed sync/apply flows.

Main Changes

• Adds supabase db declarative generate to export a database into structured declarative SQL files.
• Adds supabase db declarative sync to diff declarative files against the migrations state, generate a migration, warn on destructive statements, and optionally apply it locally.
• Adds pg-delta declarative export and apply support through shared edge-runtime execution.
• Extends supabase db diff with explicit --from / --to refs and optional --output.
• Extends supabase db pull so it can export declarative schema files through pg-delta instead of only generating timestamped migration SQL.
• Introduces hashed catalog caching for both migrations and declarative schemas to reduce repeated shadow-db work.
• Adds debug bundle generation for sync/apply failures to make pg-delta issues easier to report and reproduce.
• Adds [experimental.pgdelta] config support, including:
  • enabled
  • declarative_schema_path
  • format_options

End-to-End Flow

1. Enable [experimental.pgdelta] in config.toml.
2. Run supabase db declarative generate to export the current database state into declarative SQL files.
3. Edit the declarative schema files locally.
4. Run supabase db declarative sync.
5. The CLI builds a source catalog from migrations and a target catalog from the declarative files, reusing cached snapshots when possible.
6. pg-delta computes the SQL diff and the CLI writes a new migration file.
7. The CLI surfaces drop warnings and can optionally apply the generated migration to the local database.

Notes

• Related flows such as db pull, db diff, db start, db push, and migration rollback/setup were updated so pg-delta-backed catalog state stays warm and consistent across commands.
• The declarative flow is gated behind the experimental pg-delta configuration.

[Copilot]

Pull request overview

This PR adds an experimental pg-delta–backed declarative schema workflow to the CLI, introducing a new supabase db declarative command group and extending existing DB flows (diff/pull/start/push/reset) to support declarative export/apply plus catalog caching for faster pg-delta operations.

Changes:

• Adds supabase db declarative generate and supabase db declarative sync command flows (including interactive UX and debug bundle artifacts).
• Extends pg-delta integration with declarative export/apply scripts, explicit db diff --from/--to, and reusable catalog snapshot caching.
• Adds [experimental.pgdelta] config support (enabled flag, declarative path, formatting options) and updates related tests/docs/examples.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
pkg/config/templates/config.toml	Documents new [experimental.pgdelta] config options in the template.
pkg/config/config.go	Adds PgDeltaConfig, resolves declarative path, and validates JSON formatting options.
pkg/config/config_test.go	Adds parsing + validation tests for experimental pgdelta config.
internal/utils/misc.go	Introduces DeclarativeDir, GetDeclarativeDir(), and IsPgDeltaEnabled().
internal/utils/misc_test.go	Tests declarative dir resolution behavior.
internal/utils/edgeruntime.go	Adds shared Edge Runtime script runner helper.
internal/pgdelta/templates/pgdelta_declarative_apply.ts	Adds Edge Runtime TS script to apply declarative schemas and emit JSON results.
internal/pgdelta/apply.go	Adds Go wrapper to apply declarative schemas via Edge Runtime + pg-delta.
internal/migration/format/format_test.go	Updates config-template formatting test expectations.
internal/migration/down/down.go	Warms migration-catalog cache after reset/migrate.
internal/db/start/start.go	Warms migration-catalog cache after local setup/migrations.
internal/db/push/push.go	Warms migration-catalog cache after applying remote migrations.
internal/db/pull/pull.go	Adds pg-delta path to export declarative files during db pull when requested.
internal/db/pull/pull_test.go	Updates tests for new pull.Run signature.
internal/db/pgcache/cache.go	Adds migration-catalog hashing, snapshot writing, retention cleanup, and export via Edge Runtime.
internal/db/pgcache/cache_test.go	Adds tests for snapshot resolution and retention cleanup.
internal/db/diff/templates/pgdelta.ts	Updates pg-delta diff script to support catalog refs + optional SQL formatting.
internal/db/diff/templates/pgdelta_declarative_export.ts	Adds pg-delta declarative export script (catalog ref or URL inputs).
internal/db/diff/templates/pgdelta_catalog_export.ts	Adds pg-delta catalog export script.
internal/db/diff/pgdelta.go	Adds catalog-ref support, declarative export support, and unified Edge Runtime execution.
internal/db/diff/pgadmin.go	Refactors SaveDiff into diff package scope usage.
internal/db/diff/migra.go	Moves migra execution to shared Edge Runtime helper.
internal/db/diff/diff.go	Adds deterministic schema file ordering and optional declarative apply via pg-delta.
internal/db/diff/diff_test.go	Updates tests for new diff signatures.
internal/db/diff/explicit.go	Adds explicit db diff --from/--to implementation (local/linked/migrations/url refs).
internal/db/diff/explicit_test.go	Adds tests for explicit-ref resolution and output writing.
internal/db/declarative/declarative.go	Implements declarative generate/sync, catalog caching, baseline handling, and drop warnings.
internal/db/declarative/declarative_test.go	Adds extensive unit tests for declarative export/write, caching, hashing, and warmup flows.
internal/db/declarative/debug.go	Adds debug bundle generation and user guidance for reporting issues.
internal/db/declarative/debug_test.go	Tests debug bundle output and migration list collection.
docs/templates/examples.yaml	Adds examples for supabase db declarative sync workflow.
cmd/db_declarative.go	Adds new CLI command group + interactive flows for generate/sync/apply + debug handling.
cmd/db_declarative_test.go	Adds tests for helper functions and debug bundle behavior.
cmd/db.go	Adds explicit diff flags, integrates pg-delta selection logic, and wires db pull pg-delta option.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[coveralls]

Pull Request Test Coverage Report for Build 23352230634

Details

• 520 of 1449 (35.89%) changed or added relevant lines in 18 files are covered.
• 39 unchanged lines in 4 files lost coverage.
• Overall coverage increased (+1.5%) to 63.16%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
internal/db/push/push.go	1	3	33.33%
internal/utils/edgeruntime.go	27	29	93.1%
internal/db/start/start.go	9	13	69.23%
internal/migration/down/down.go	3	7	42.86%
internal/db/diff/pgadmin.go	7	16	43.75%
cmd/db.go	6	24	25.0%
internal/db/declarative/debug.go	38	56	67.86%
internal/db/diff/diff.go	7	37	18.92%
internal/db/pull/pull.go	5	37	13.51%
internal/pgdelta/apply.go	0	38	0.0%

Files with Coverage Reduction	New Missed Lines	%
cmd/db.go	1	50.95%
internal/storage/rm/rm.go	2	80.61%
internal/utils/git.go	5	57.14%
internal/db/diff/diff.go	31	48.48%

Totals
Change from base Build 23294227365:	1.5%
Covered Lines:	9191
Relevant Lines:	14552

---

💛 - Coveralls

[jgoux]

I'm just not fully convinced by the command name with "declarative". I would prefer we rely on supabase db schema namespace even if it means a new --declarative flag or a new supabase db schema declarative subcommand as we're really treating the same subject here.

[avallete]

I'm just not fully convinced by the command name with "declarative". I would prefer we rely on supabase db schema namespace even if it means a new --declarative flag or a new supabase db schema declarative subcommand as we're really treating the same subject here.

Updated in favor of supabase db schema declarative, must either run with explicit --experimental flag our have:

[experimental.pgdelta]
enabled = true

In the config.