fix(local-development): migra cache volume survives stop --no-backup

Start with apps/cli/src/commands/db/shared/migra.ts and trace the cache mount through edge-runtime-script.layer.ts and docker-run.args.ts. Then inspect docker-remove-all.ts and stop.command.ts, and run the documented database-only reproduction. Done means stop --no-backup removes the unused task-created cache volume while preserving unrelated project volumes.

Summary

On published CLI 2.119.0, a stopped-stack db diff --local --use-migra creates an unlabeled edge-runtime Deno cache volume. A later stop --no-backup exits successfully but leaves this project-owned volume behind. This occurs when the normal Edge Runtime service has not already created a labeled volume, as in a database-only local stack.

Steps to reproduce

Use a disposable local project with Docker running and free configured ports. The sequence below reduces the recorded successful workflow to its relevant setup and cleanup operations; this shortened sequence has not been rerun separately.

1. Install the pinned CLI locally and initialize the project:

mkdir cli-cache-repro
cd cli-cache-repro
npm init -y
npm install --save-dev --save-exact [email protected]
npm exec -- supabase init

2. In supabase/config.toml, set project_id = "cache_repro", set enabled = false under [experimental.pgdelta], and set schema_paths = ["./schemas/*.sql"] under [db.migrations]. Keep the Docker runtime and no runtime or schema-engine environment overrides. Create identical initial migration and declaration files:

mkdir -p supabase/migrations supabase/schemas
cat > supabase/migrations/20260101000000_initial_catalog.sql <<'SQL'
create table public.catalog (
  id bigint generated always as identity primary key,
  label text not null
);
SQL
cp supabase/migrations/20260101000000_initial_catalog.sql supabase/schemas/catalog.sql

3. Start a database-only stack with health checks enabled, then stop it while retaining the database volume:

npm exec -- supabase start --exclude gotrue,realtime,storage-api,imgproxy,kong,mailpit,postgrest,postgres-meta,studio,edge-runtime,logflare,vector,supavisor
npm exec -- supabase stop

4. Add a nullable column to the declaration and generate the legacy migration while the stack is stopped:

cat > supabase/schemas/catalog.sql <<'SQL'
create table public.catalog (
  id bigint generated always as identity primary key,
  label text not null,
  category text
);
SQL
npm exec -- supabase db diff --local --use-migra -f add_catalog_category

5. Request complete project-volume cleanup, then inspect the exact cache volume and its remaining users:

npm exec -- supabase stop --no-backup
docker volume inspect --format '{{json .Labels}}' supabase_edge_runtime_cache_repro
docker ps -a --filter volume=supabase_edge_runtime_cache_repro --format '{{.Names}}'

Expected behavior

stop --no-backup describes its behavior as "Deletes all data volumes after stopping." It should remove the unused cache volume created by this project's schema-diff workflow while preserving unrelated project volumes. After successful cleanup, inspection of the exact task-created cache volume should fail because the volume no longer exists.

Actual behavior

In the recorded workflow, the legacy diff exited 0 and generated exactly alter table "public"."catalog" add column "category" text;. After applying and replaying migrations, a stopped-stack convergence diff also exited 0 and reported no schema changes. Final stop --no-backup exited 0, but inspection still found the project-specific supabase_edge_runtime_<project_id> volume with Labels: null. The container-reference query returned no names. Removing only that inspected, task-created unused volume restored the pre-run resource inventory.

These are recorded observations, not a verbatim full terminal transcript. The reproduction uses a generic project identifier rather than the identifier from that run.

Affected area

Local development / Docker cleanup, specifically the TypeScript legacy migra path and project-scoped stop --no-backup. The regular long-lived Edge Runtime service was excluded from this run.

Runtime or environment

• Supabase CLI 2.119.0, installed through a project-local npm dependency; released source revision 3cb948c5a70d31fbcb0fd1dcc616ee196a125cd0.
• macOS 27.0 arm64; Node 22.23.2; npm 12.0.2.
• Docker Desktop 4.92.0; Docker client 29.8.1; Docker Engine 29.8.0 on Linux arm64.
• Local PostgreSQL 17.11; edge-runtime image v1.77.1; Docker runtime; pg-delta disabled; explicit legacy schema_paths.

Evidence

Current default-branch source at develop revision 66ccc6f63a9a26b29c368698994a0843d23b80be still mounts the named cache volume directly. The released executable supplied the runtime observations above; this current revision has been source-inspected, not built or executed.

• migra.ts mounts the project cache at /root/.cache/deno.
• edge-runtime-script.layer.ts forwards the bind to DockerRun, and docker-run.args.ts emits docker run --rm -v. This path does not pre-create a project-labeled volume.
• docker-remove-all.ts prunes volumes only by project label, so it does not select the observed unlabeled cache.
• stop.command.ts retains the all-data-volumes description.

Impact

A disposable project's cache data remains on disk after successful destructive cleanup. Repeated unique projects leave additional volumes that require manual identification and removal. A regression check should begin without this project's cache volume, run the legacy diff with Edge Runtime excluded, then verify that stop --no-backup removes that exact unused volume and preserves an unrelated volume.

Additional context

The full 20-commit range from the released baseline to the current default-branch SHA, the complete paginated open-issue corpus, and relevant closed issues and merged PRs were checked. The migra mount and label-filtered volume-prune mechanisms remain; changes to these command paths in that range add telemetry. No matching open report was found.

Closed #1982 and #2230 concern earlier Go-era cleanup of labeled volumes. The --all prune fix from #1989 is already present in the inspected source. This report concerns a volume with no labels, which the project-label filter cannot select. Open #6962 and #6963 concern experimental stack helper containers after owner or state-directory loss; the recorded run used the ordinary Docker local runtime and successful commands.