Skip to content

feat(cli): bundle pg-delta for database workflows #6102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avallete wants to merge 21 commits into
base: develop
Choose a base branch
from
Open

feat(cli): bundle pg-delta for database workflows #6102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
1baf8ea
feat(cli): bundle pg-delta next engine
avallete Aug 6, 2026
8078b53
chore: merge develop into pg-delta next
avallete Aug 6, 2026
4b697a2
fix(cli): allow pg-topo parser build script
avallete Aug 6, 2026
c52cf53
fix(cli): embed libpg-query wasm in compiled binary
avallete Aug 6, 2026
1f82bf9
feat(cli): isolate pg-delta next shadow databases
avallete Aug 7, 2026
5bffecb
fix(cli): correct diff and migration execution contracts
avallete Aug 7, 2026
f12b1b9
chore: merge develop into pg-delta next
avallete Aug 7, 2026
958d36c
test(cli): update transactional Go mocks
avallete Aug 7, 2026
d486195
chore(cli): remove unused diff helper
avallete Aug 7, 2026
394ecf8
fix(cli): isolate pg-delta-next baseline behavior
avallete Aug 8, 2026
9f66d41
chore: merge develop into pg-delta next
avallete Aug 8, 2026
438a9ac
fix(cli): warn about manifestless declarative removals
avallete Aug 8, 2026
0ebe58c
fix(cli): warn on pg-delta coverage gaps
avallete Aug 8, 2026
dcdf7e0
fix(cli): format pg-delta SQL by default
avallete Aug 8, 2026
16028da
fix(cli): clarify declarative diff baselines
avallete Aug 8, 2026
b7ad988
test(cli): use malformed branch response type
avallete Aug 8, 2026
7f6fb32
chore(cli): update pg-delta next preview
avallete Aug 8, 2026
f9bd289
feat(cli): improve declarative schema upgrade flow
avallete Aug 8, 2026
46a1614
fix(cli): address pg-delta next review findings
avallete Aug 8, 2026
ca55d8a
chore(cli): use published pg-delta alpha
avallete Aug 9, 2026
f92a8b7
Merge remote-tracking branch 'origin/develop' into feat/upgrade-pg-de…
avallete Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions apps/cli/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@
"@parcel/watcher": "^2.6.0",
"@supabase/api": "workspace:*",
"@supabase/config": "workspace:*",
"@supabase/pg-delta": "1.0.0-alpha.34",
"@supabase/pg-topo": "1.0.0-alpha.5",
"@supabase/process-compose": "workspace:*",
"@supabase/stack": "workspace:*",
"@tsconfig/bun": "catalog:",
Expand Down
53 changes: 53 additions & 0 deletions apps/cli/scripts/build-binary.integration.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { afterEach, describe, expect, test } from "vitest";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";

const fixturePath = fileURLToPath(
new URL("../tests/fixtures/compiled-libpg-query.ts", import.meta.url),
);
const temporaryDirectories: string[] = [];

afterEach(async () => {
await Promise.all(
temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true })),
);
});

describe("compiled binary assets", () => {
test("embeds and loads libpg-query.wasm", async () => {
const directory = await mkdtemp(path.join(tmpdir(), "supabase-compiled-wasm-"));
temporaryDirectories.push(directory);
const executable = path.join(directory, "parser-probe");
const bunExecutable = Bun.which("bun");
if (!bunExecutable) {
throw new Error("Bun executable not found");
}

const build = Bun.spawn(
[bunExecutable, "build", fixturePath, "--compile", `--outfile=${executable}`],
{ stdout: "pipe", stderr: "pipe" },
);
const [buildExitCode, buildStderr] = await Promise.all([
build.exited,
new Response(build.stderr).text(),
]);
expect(buildExitCode, buildStderr).toBe(0);

const probe = Bun.spawn([executable], {
cwd: directory,
env: {},
stdout: "pipe",
stderr: "pipe",
});
const [probeExitCode, stdout, stderr] = await Promise.all([
probe.exited,
new Response(probe.stdout).text(),
new Response(probe.stderr).text(),
]);

expect(probeExitCode, stderr).toBe(0);
expect(stdout).toContain("libpg-query.wasm loaded");
}, 20_000);
});
36 changes: 22 additions & 14 deletions apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ health poll → write `.env` → `db push` → start suggestion. Every step is n
including the migration push (`legacyDbPushCore`, shared with the standalone `supabase db push`
command — see Notes).

The embedded push step does not warm pg-delta state under the default bundled
engine: no next-engine consumer uses the legacy catalog. Setting
`SUPABASE_USE_PG_DELTA_NEXT=false` retains Go's edge-runtime catalog warmup.
`PGDELTA_NPM_REGISTRY`, `.temp/pgdelta-version`, and catalogs directly under
`.temp/pgdelta/` are meaningful only for that legacy opt-out.

## Files Read

| Path | Format | When |
Expand All @@ -20,7 +26,8 @@ command — see Notes).
| `<workdir>/supabase/migrations/*.sql` | SQL | native push step, for each pending migration applied |
| seed files from `[db.seed].sql_paths` | SQL | native push step (`--include-seed` is always set; gated on `[db.seed].enabled`) |
| `<workdir>/supabase/roles.sql` | SQL | native push step (`--include-roles` is always set; existence check + apply) |
| `<workdir>/supabase/.temp/edge-runtime-version` | plain text | native push step's migrations-catalog cache (pg-delta), when a pinned edge-runtime image tag exists — resolved against the bootstrap workdir explicitly, not `cliConfig.workdir` (which is stale after this handler's own `process.chdir`) |
| `<workdir>/supabase/.temp/pgdelta-version` | plain text | always read by push config loading for compatibility; affects the legacy opt-out only |
| `<workdir>/supabase/.temp/edge-runtime-version` | plain text | legacy opt-out only: push-step catalog warmup image tag, resolved against the bootstrap workdir |

## Files Written

Expand All @@ -31,8 +38,8 @@ command — see Notes).
| `<workdir>/supabase/.temp/project-ref` | plain text | always (mandatory; fails the command on write error) |
| `<workdir>/supabase/.temp/{pooler-url,rest-version,gotrue-version,storage-version,storage-migration}` | plain text | best-effort, from `link.LinkServices` |
| `<workdir>/.env` | dotenv | best-effort (write failure prints a warning and continues) |
| `<workdir>/supabase/.temp/pgdelta/catalog-<prefix>-migrations-<hash>-<ts>.json` | JSON | native push step, best-effort, after a successful migration apply, when pg-delta is enabled (a failure only warns on stderr and never fails the push) |
| `<workdir>/supabase/.temp/pgdelta/pgdelta-target-ca.crt` | PEM | native push step, same pg-delta gate, when the target requires SSL |
| `<workdir>/supabase/.temp/pgdelta/catalog-<prefix>-migrations-<hash>-<ts>.json` | JSON | legacy opt-out push step, best-effort after a successful migration apply when pg-delta is enabled; failure only warns |
| `<workdir>/supabase/.temp/pgdelta/pgdelta-target-ca.crt` | PEM | legacy opt-out catalog export when the target requires SSL |
| `<workdir>/supabase/.temp/linked-project.json` | JSON | PersistentPostRun linked-project cache (`Effect.ensuring`); resolves against the bootstrap workdir (the prompted/`--workdir`/env target), not `cliConfig.workdir` |
| `~/.supabase/telemetry.json` | JSON | PersistentPostRun telemetry flush (`Effect.ensuring`) |

Expand Down Expand Up @@ -64,17 +71,18 @@ neither branch ever reaches the temp-login-role/Management-API path a passwordle

## Environment Variables

| Variable | Purpose | Required? |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `SUPABASE_WORKDIR` | target dir (`--workdir` flag → env → prompt → cwd) | no |
| `SUPABASE_DB_PASSWORD` | DB password (`-p` flag → env → prompt/generate) | no |
| `GITHUB_TOKEN` | raise the GitHub API rate limit for template fetch | no |
| `SUPABASE_ACCESS_TOKEN` | auth bypass for ensure-login | no |
| `SUPABASE_PROFILE` | profile name/path (env → `~/.supabase/profile` → `supabase`) | no |
| `SUPABASE_YES` | auto-confirm the native push step's prompts (Go's viper `YES`), read project-`.env`-aware like the standalone `db push` | no |
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the push step's migrations-catalog cache when `[experimental.pgdelta].enabled` is unset, read project-`.env`-aware (see Files Read) | no |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | overrides the push step's pg-delta edge-runtime image registry, read project-`.env`-aware (see Files Read) | no |
| `PGDELTA_NPM_REGISTRY` | overrides the push step's pg-delta edge-runtime npm registry (`.npmrc` + `NPM_CONFIG_REGISTRY` forward), read project-`.env`-aware (see Files Read) | no |
| Variable | Purpose | Required? |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- |
| `SUPABASE_WORKDIR` | target dir (`--workdir` flag → env → prompt → cwd) | no |
| `SUPABASE_DB_PASSWORD` | DB password (`-p` flag → env → prompt/generate) | no |
| `GITHUB_TOKEN` | raise the GitHub API rate limit for template fetch | no |
| `SUPABASE_ACCESS_TOKEN` | auth bypass for ensure-login | no |
| `SUPABASE_PROFILE` | profile name/path (env → `~/.supabase/profile` → `supabase`) | no |
| `SUPABASE_YES` | auto-confirm the native push step's prompts (Go's viper `YES`), read project-`.env`-aware like the standalone `db push` | no |
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the legacy opt-out push cache when `[experimental.pgdelta].enabled` is unset, read project-`.env`-aware | no |
| `SUPABASE_USE_PG_DELTA_NEXT` | set to `false` to retain the legacy push-step catalog warmup, read project-`.env`-aware | no |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | legacy opt-out only: overrides the push step's edge-runtime image registry, read project-`.env`-aware | no |
| `PGDELTA_NPM_REGISTRY` | legacy opt-out only: overrides the push-step edge-runtime npm registry, read project-`.env`-aware | no |

## Exit Codes

Expand Down
Loading
Loading