Skip to content

docs(cli): document SUPABASE_USE_SLIM_IMAGES side effects #6383

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 5 commits into from
+168 −124
Open

docs(cli): document SUPABASE_USE_SLIM_IMAGES side effects #6383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
617ce33
docs(cli): document SUPABASE_USE_SLIM_IMAGES side effects
avallete Aug 28, 2026
a2d12ee
docs(cli): align slim-image side effects with current contracts
avallete Aug 28, 2026
596dd7c
docs(cli): note slim-image flag is ambient process.env only
avallete Aug 28, 2026
32a3a4d
docs(cli): drop stale slim Vector secretFiles claim
avallete Aug 28, 2026
aebe9e5
docs(cli): update slim side effects for current image contracts
avallete Aug 29, 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
25 changes: 13 additions & 12 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 @@ -69,18 +69,19 @@ 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, read project-`.env`-aware like the standalone `db push` | no |
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the legacy opt-out's catalog cache when `[experimental.pgdelta].enabled` is unset, read project-`.env`-aware | no |
| `SUPABASE_USE_PG_DELTA_NEXT` | set to `false` for legacy catalog warming, read project-`.env`-aware | no |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | legacy opt-out's edge-runtime image registry, read project-`.env`-aware | no |
| `PGDELTA_NPM_REGISTRY` | legacy opt-out's edge-runtime npm registry, read project-`.env`-aware | 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, read project-`.env`-aware like the standalone `db push` | no |
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the legacy opt-out's catalog cache when `[experimental.pgdelta].enabled` is unset, read project-`.env`-aware | no |
| `SUPABASE_USE_PG_DELTA_NEXT` | set to `false` for legacy catalog warming, read project-`.env`-aware | no |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | legacy opt-out's edge-runtime image registry, read project-`.env`-aware | no |
| `SUPABASE_USE_SLIM_IMAGES` | resolves the legacy opt-out's edge-runtime image from the slim `ghcr.io/supabase/cli/edge-runtime` build (`true`/`1` enable); `deno_version = 1` keeps its docker.io image | no |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document historical edge-runtime pin exceptions

When the legacy pg-delta opt-out runs with a historical <workdir>/supabase/.temp/edge-runtime-version pin, legacyResolveEdgeRuntimeImage deliberately keeps the image on docker.io because only the current Dockerfile tag is slim-translated. This row exempts only deno_version = 1, so it incorrectly promises a slim image for another supported bootstrap configuration; add the historical-pin exception here as well.

AGENTS.md reference: apps/cli/AGENTS.md:L359-L366

Useful? React with 👍 / 👎.

| `PGDELTA_NPM_REGISTRY` | legacy opt-out's edge-runtime npm registry, read project-`.env`-aware | no |

## Exit Codes

Expand Down
1 change: 1 addition & 0 deletions apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ of this command's own target resolve, ahead of the differ container.
| `PGDELTA_NPM_REGISTRY` | legacy opt-out's scoped npm registry | no |
| `SUPABASE_SSL_DEBUG` | migra SSL debug logging | no |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | overrides the differ's / shadow's image registry (shell **or** project `.env`, applied for the run via `legacyApplyProjectEnv`, matching `db push`/`db pull`/`db dump`) | no |
| `SUPABASE_USE_SLIM_IMAGES` | resolves the shadow/pg-meta images from the slim `ghcr.io/supabase/cli/<service>` builds (`true`/`1` enable); the differ image has no slim build and stays on docker.io | no |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document only images db diff actually uses

The db diff implementation never launches a pg-meta image: diff.handler.ts resolves a Postgres image for the shadow, while the pgAdmin path launches the separate differ image. Describing this as “shadow/pg-meta images” incorrectly expands the command's documented subprocess surface; identify the slim image as the shadow Postgres image instead.

AGENTS.md reference: apps/cli/AGENTS.md:L277-L279

Useful? React with 👍 / 👎.


`SUPABASE_DB_SHADOW_PORT`/`SUPABASE_NETWORK_ID`/`--network-id`/`SUPABASE_PROJECT_ID`/
`SUPABASE_DB_HEALTH_TIMEOUT` all apply to `--use-pgadmin` too — its shadow is provisioned
Expand Down
15 changes: 8 additions & 7 deletions apps/cli/src/legacy/commands/db/dump/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,14 @@ script run inside the local Postgres image to stdout or `--file`.

## Environment Variables

| Variable | Purpose |
| ----------------------------------------------------------------------------- | --------------------------------------------- |
| `SUPABASE_DB_PASSWORD` (`DB_PASSWORD` viper key; `--password`/`-p` overrides) | remote DB password |
| `SUPABASE_ACCESS_TOKEN` | `--linked` auth |
| `BITBUCKET_CLONE_DIR` | (no-op for dump — no `--security-opt` is set) |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | rewrite the pg image registry |
| `DOCKER_HOST` | docker daemon endpoint |
| Variable | Purpose |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `SUPABASE_DB_PASSWORD` (`DB_PASSWORD` viper key; `--password`/`-p` overrides) | remote DB password |
| `SUPABASE_ACCESS_TOKEN` | `--linked` auth |
| `BITBUCKET_CLONE_DIR` | (no-op for dump — no `--security-opt` is set) |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | rewrite the pg image registry |
| `SUPABASE_USE_SLIM_IMAGES` | resolve the pg image from the slim `ghcr.io/supabase/cli` builds |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document the db dump fallback images

When db.major_version is 13, 14, or 15, an OrioleDB version is configured, or .temp/postgres-version contains a historical pin, legacyResolveDbImage deliberately returns a docker.io image even with this flag enabled. This row currently promises a slim pg image for all dump configurations, so it should list the same fallback and historical-pin exceptions documented for db start.

AGENTS.md reference: apps/cli/AGENTS.md:L277-L279

Useful? React with 👍 / 👎.

| `DOCKER_HOST` | docker daemon endpoint |

## Exit Codes

Expand Down
1 change: 1 addition & 0 deletions apps/cli/src/legacy/commands/db/pull/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ baseline, so it is never cached.
| `SUPABASE_DB_MAJOR_VERSION` / `SUPABASE_DB_HEALTH_TIMEOUT` / `SUPABASE_DB_SETTINGS_*` | shadow container-config overrides, same as `db start`/`db reset` | no |
| `SUPABASE_PROJECT_ID` | overrides the shadow container's project id/labels, same as `db start`/`db reset` (`utils.DbId`); ALSO the linked-ref resolution fallback `--project-ref` supersedes — see Notes for the narrower scope of the flag | no |
| `SUPABASE_NETWORK_ID` (`--network-id`) | forces the shadow container/network onto an existing Docker network | no |
| `SUPABASE_USE_SLIM_IMAGES` | resolves the shadow Postgres and `pg_dump` container images from the slim `ghcr.io/supabase/cli` builds instead of the docker.io Dockerfile pins (`true`/`1` enable) | no |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve the db pull Postgres fallback exceptions

For an initial pull or shadow using PostgreSQL 13/14/15, an OrioleDB version, or a historical .temp/postgres-version pin, both paths ultimately use legacyResolveDbImage, which deliberately returns a docker.io image even when this flag is enabled. This unconditional row therefore misdocuments supported pull configurations; list the same fallback and historical-pin exceptions as db start.

AGENTS.md reference: apps/cli/AGENTS.md:L359-L366

Useful? React with 👍 / 👎.

| `SUPABASE_HOME` | overrides the `~/.supabase` root used for the shadow baseline cache (and other CLI state) | no |
| `SUPABASE_SHADOW_CACHE` | shadow baseline cache; opt-in (`1`/`true`); the shadow's post-baseline PGDATA is snapshotted to a tar and restored into the next run's fresh container (see Notes) | no |
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | force pg-delta diff engine | no |
Expand Down
1 change: 1 addition & 0 deletions apps/cli/src/legacy/commands/db/push/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ before migrations unless `--skip-vault` is set.
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the migrations-catalog cache when `[experimental.pgdelta].enabled` is unset | no (project `.env` or shell) |
| `SUPABASE_USE_PG_DELTA_NEXT` | selects the pg-delta implementation; `false` selects the legacy edge-runtime engine and thereby restores the migrations-catalog cache warmup (unset/unrecognized defaults to the next engine, which skips it); shell presence wins over project `.env`, even an empty shell value | no (project `.env` or shell) |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | overrides the pg-delta edge-runtime image registry for the cache export | no (project `.env` or shell) |
| `SUPABASE_USE_SLIM_IMAGES` | resolves the pg-delta edge-runtime image from the slim `ghcr.io/supabase/cli/edge-runtime` build (`true`/`1` enable); `deno_version = 1` keeps its docker.io image | no (ambient shell only) |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve historical edge-runtime pin exceptions

When db push performs the legacy pg-delta cache export with a historical supabase/.temp/edge-runtime-version pin, legacyResolveEdgeRuntimeImage deliberately keeps the docker.io image because historical slim tags are unpublished. This row lists only deno_version = 1 as an exception and therefore promises a slim image for another supported configuration; add the historical-pin exception here and to the analogous db reset row.

AGENTS.md reference: apps/cli/AGENTS.md:L359-L366

Useful? React with 👍 / 👎.

| `PGDELTA_NPM_REGISTRY` | overrides the pg-delta edge-runtime npm registry (`.npmrc` + `NPM_CONFIG_REGISTRY` forward) for the cache export | no (project `.env` or shell) |

## Exit Codes
Expand Down
1 change: 1 addition & 0 deletions apps/cli/src/legacy/commands/db/reset/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,7 @@ the whole reset** (not just "skip buckets").
| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the post-reset migrations-catalog cache (see Files Written) when `[experimental.pgdelta].enabled` is unset — distinct from `SUPABASE_EXPERIMENTAL_PGDELTA_ENABLED` above, which switches the reset's own apply branch instead | no (project `.env` or shell) |
| `SUPABASE_USE_PG_DELTA_NEXT` | selects the pg-delta implementation; `false` selects the legacy edge-runtime engine and thereby restores the migrations-catalog cache (unset/unrecognized defaults to the next engine, which skips it); shell presence wins over project `.env`, even an empty shell value | no (project `.env` or shell) |
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | overrides the pg-delta edge-runtime image registry for the migrations-catalog cache export (scoped for the whole run via `legacyApplyProjectEnv`, matching `db push`) | no (project `.env` or shell) |
| `SUPABASE_USE_SLIM_IMAGES` | resolves the pg-delta edge-runtime image from the slim `ghcr.io/supabase/cli/edge-runtime` build (`true`/`1` enable); `deno_version = 1` keeps its docker.io image | no (ambient shell only) |
| `PGDELTA_NPM_REGISTRY` | overrides the pg-delta edge-runtime npm registry (`.npmrc` + `NPM_CONFIG_REGISTRY` forward) for the migrations-catalog cache export (scoped for the whole run via `legacyApplyProjectEnv`, matching `db push`) | no (project `.env` or shell) |
| `SUPABASE_DB_PORT` / `SUPABASE_DB_MAJOR_VERSION` / `SUPABASE_DB_HEALTH_TIMEOUT` / `SUPABASE_DB_SETTINGS_*` | local-path container-recreate config overrides, same as `db start` | no |
| `SUPABASE_NETWORK_ID` (`--network-id`) | forces the recreated container/network onto an existing Docker network | no |
Expand Down
Loading
Loading