From a2f2644a72c57b6741fcff655e234a71a0364f94 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 2 Nov 2026 15:06:55 +0100 Subject: [PATCH 1/4] docs: document the experimental local stack for faster CI --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 71347c7..24ed3db 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,51 @@ steps: - run: bun test ``` +## Faster local stack (experimental) + +Supabase CLI v3 includes an experimental local stack that starts much faster +than the default Docker setup. On `ubuntu-latest`, it answers API requests +about 20s after `supabase start`, compared to about 85s for the default stack +([benchmark](https://github.com/jgoux/setup-cli-testing/actions/runs/41458685893)). + +Enable it in `supabase/config.toml`, or create a new project with +`SUPABASE_EXPERIMENTAL_STACK=1 supabase init`: + +```toml +[experimental] +stack = true +``` + +Then start it with the native runtime and export its env vars for your tests: + +```yaml +steps: + - uses: actions/checkout@v6 + - uses: supabase/setup-cli@v3 + with: + version: ^3 + - run: supabase start --runtime native + - name: Export local Supabase env vars + run: | + supabase status --env \ + --override-name API_URL=SUPABASE_URL \ + --override-name SERVICE_ROLE_KEY=SUPABASE_SERVICE_ROLE_KEY \ + >> .env.test + - run: bun test +``` + +- The native runtime needs Linux with glibc 2.35+ (`ubuntu-22.04` or later) or + macOS 14+ on Apple silicon. Without `--runtime`, the stack uses Docker when + it is available, which is about as fast on `ubuntu-latest`. +- Ports are assigned per project, so read URLs and keys from + `supabase status --env` instead of hard-coding `127.0.0.1:54321`. +- Commit `supabase/supabase.lock`. It pins the services the stack downloads, + and when `CI` is set, `supabase start` fails instead of updating an + out-of-date lock. +- Services other than Postgres start on their first request. +- Caching the downloaded services between runs is not needed: restoring them + from the Actions cache takes about as long as downloading them. + ## Develop After you've cloned the repository to your local machine or codespace, you'll From 6d73a20fea27c1a1f5c8820c8c5521d7cf677b57 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 2 Nov 2026 15:24:46 +0100 Subject: [PATCH 2/4] docs: cover starting the stack without init and pinned ports --- README.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 24ed3db..294ae8a 100644 --- a/README.md +++ b/README.md @@ -203,14 +203,17 @@ than the default Docker setup. On `ubuntu-latest`, it answers API requests about 20s after `supabase start`, compared to about 85s for the default stack ([benchmark](https://github.com/jgoux/setup-cli-testing/actions/runs/41458685893)). -Enable it in `supabase/config.toml`, or create a new project with -`SUPABASE_EXPERIMENTAL_STACK=1 supabase init`: +Enable it in `supabase/config.toml`: ```toml [experimental] stack = true ``` +Without a `config.toml`, set `SUPABASE_EXPERIMENTAL_STACK=1` for the job +instead. `supabase init` is not needed: `supabase start` runs the stack with +default settings. + Then start it with the native runtime and export its env vars for your tests: ```yaml @@ -232,11 +235,15 @@ steps: - The native runtime needs Linux with glibc 2.35+ (`ubuntu-22.04` or later) or macOS 14+ on Apple silicon. Without `--runtime`, the stack uses Docker when it is available, which is about as fast on `ubuntu-latest`. -- Ports are assigned per project, so read URLs and keys from - `supabase status --env` instead of hard-coding `127.0.0.1:54321`. -- Commit `supabase/supabase.lock`. It pins the services the stack downloads, - and when `CI` is set, `supabase start` fails instead of updating an - out-of-date lock. +- Ports that `config.toml` doesn't set are picked per project, so read URLs + and keys from `supabase status --env` instead of hard-coding + `127.0.0.1:54321`. Ports a config sets explicitly, like those written by + `supabase init` before the stack was enabled, are kept as is. +- With a `config.toml`, commit the `supabase/supabase.lock` that + `supabase start` writes. It pins the services the stack downloads, and when + `CI` is set, `supabase start` fails instead of updating an out-of-date lock. +- `supabase start` rejects some settings the stack does not support yet, such + as `api.tls` or a `db.major_version` other than 15 or 17. - Services other than Postgres start on their first request. - Caching the downloaded services between runs is not needed: restoring them from the Actions cache takes about as long as downloading them. From d5abe119b017667f40d034b85b345d5dd35278a8 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 2 Nov 2026 15:27:23 +0100 Subject: [PATCH 3/4] docs: cover native runtime platforms, root containers, and fixed ports --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 294ae8a..8b5bbe2 100644 --- a/README.md +++ b/README.md @@ -232,13 +232,20 @@ steps: - run: bun test ``` -- The native runtime needs Linux with glibc 2.35+ (`ubuntu-22.04` or later) or - macOS 14+ on Apple silicon. Without `--runtime`, the stack uses Docker when - it is available, which is about as fast on `ubuntu-latest`. +- The native runtime needs Linux on amd64 or arm64 with glibc 2.35+ + (`ubuntu-22.04` or later), or macOS 14+ on Apple silicon. It doesn't run as + root: in a root CI container, set `SUPABASE_NATIVE_POSTGRES_USER` to a + non-root account. See the + [native runtime requirements](https://supabase.com/docs/guides/local-development/docker-and-native-runtimes#native-runtime-requirements). + Without `--runtime`, the stack uses Docker when it is available, which is + about as fast on `ubuntu-latest`. - Ports that `config.toml` doesn't set are picked per project, so read URLs and keys from `supabase status --env` instead of hard-coding `127.0.0.1:54321`. Ports a config sets explicitly, like those written by - `supabase init` before the stack was enabled, are kept as is. + `supabase init` before the stack was enabled, are used as is, and + `supabase start` fails if one is taken. + [Remove them](https://supabase.com/docs/guides/local-development/running-multiple-local-projects#remove-fixed-ports-from-configtoml) + to let the stack pick free ports. - With a `config.toml`, commit the `supabase/supabase.lock` that `supabase start` writes. It pins the services the stack downloads, and when `CI` is set, `supabase start` fails instead of updating an out-of-date lock. From 0e30d8c013f8676a09e72ca59eb46af93bf18234 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 2 Nov 2026 15:30:07 +0100 Subject: [PATCH 4/4] docs: default the experimental stack example to Docker --- README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8b5bbe2..fd7312e 100644 --- a/README.md +++ b/README.md @@ -199,7 +199,7 @@ steps: ## Faster local stack (experimental) Supabase CLI v3 includes an experimental local stack that starts much faster -than the default Docker setup. On `ubuntu-latest`, it answers API requests +than the default one. On `ubuntu-latest`, it answers API requests about 20s after `supabase start`, compared to about 85s for the default stack ([benchmark](https://github.com/jgoux/setup-cli-testing/actions/runs/41458685893)). @@ -214,7 +214,7 @@ Without a `config.toml`, set `SUPABASE_EXPERIMENTAL_STACK=1` for the job instead. `supabase init` is not needed: `supabase start` runs the stack with default settings. -Then start it with the native runtime and export its env vars for your tests: +Then start it and export its env vars for your tests: ```yaml steps: @@ -222,7 +222,7 @@ steps: - uses: supabase/setup-cli@v3 with: version: ^3 - - run: supabase start --runtime native + - run: supabase start - name: Export local Supabase env vars run: | supabase status --env \ @@ -232,13 +232,10 @@ steps: - run: bun test ``` -- The native runtime needs Linux on amd64 or arm64 with glibc 2.35+ - (`ubuntu-22.04` or later), or macOS 14+ on Apple silicon. It doesn't run as - root: in a root CI container, set `SUPABASE_NATIVE_POSTGRES_USER` to a - non-root account. See the - [native runtime requirements](https://supabase.com/docs/guides/local-development/docker-and-native-runtimes#native-runtime-requirements). - Without `--runtime`, the stack uses Docker when it is available, which is - about as fast on `ubuntu-latest`. +- `supabase start` runs the stack on Docker when it is available. On runners + without Docker, such as `macos-latest`, use `supabase start --runtime native` + (see the + [native runtime requirements](https://supabase.com/docs/guides/local-development/docker-and-native-runtimes#native-runtime-requirements)). - Ports that `config.toml` doesn't set are picked per project, so read URLs and keys from `supabase status --env` instead of hard-coding `127.0.0.1:54321`. Ports a config sets explicitly, like those written by