supabase 3.0.0

v3.0.0

on Node.js NPM

Supabase CLI v3.0.0 — 2026-11-02

v3 is a major release. Commands that can run locally now target your local stack by default, one --remote flag replaces --linked, --project-ref and --db-url, and every change to a hosted project asks for confirmation (or --yes in CI). Flags and SUPABASE_* environment variables now override config.toml, and deprecated commands, flags, config keys and the bundled supabase-go binary are gone. Read the breaking changes before you upgrade CI.

The v2 to v3 migration guide walks through each change.

Try the experimental local stack. Each project, worktree or agent gets its own local Supabase that starts in seconds, on Docker or Podman, or with no container engine at all through supabase start --runtime native. Start a new project with SUPABASE_EXPERIMENTAL_STACK=1 supabase init; for an existing one, follow the setup steps in the blog post. The multiple local projects guide covers listing, stopping and removing projects. It's experimental, so its flags and output can still change.

⚠️ Breaking changes

Local by default, one --remote flag

• db push, db pull, db dump, migration fetch/list/repair, inspect db *, inspect report, gen types and storage ls/cp/mv/rm target the local stack when you pass no target. Add --remote for the linked project, --remote=<ref> for another project, --remote=<branch> for a branch of the linked project, or --remote=<postgres-url> for a database URL. SUPABASE_PROJECT_ID on its own no longer selects a hosted project; it only says which project bare --remote means. (#7188)
• --linked, --project-ref, --db-url and gen types --project-id are deprecated. They still work, print a warning naming the --remote form, and are hidden from help. --local does nothing and warns. None of them can be combined with --remote=<value>. (#7188)
• gen types with no target generates from the local database instead of opening a project picker. db schema declarative sync with no declarative files generates them from the local database; run supabase db schema declarative generate --remote first to start from the linked project. (#7188)
• --remote <word> after a command that takes an operand fails with a "did you mean" error when the word looks like a branch name or project ref. Put the operand first (supabase db pull add_profiles --remote) or use --remote=<branch>. (#7188)
• db diff rejects --remote together with --from/--to (use --from=remote or --to=remote), db query rejects SQL passed both as an argument and with --file, and an empty --project-ref= is now an error. Bare --remote in an unlinked checkout opens the project picker in an interactive terminal. (#7188)

Every hosted change needs your consent

• Every command that changes a hosted project asks first, and fails unattended unless you pass --yes. Non-interactive, JSON, stream-json, agent and -o json|yaml|toml|env runs fail with HostedMutationConsentRequiredError. This includes db push, db pull when it updates the remote migration history, pull (except --dry-run), functions deploy/delete, secrets set/unset, config push, branches changes, backups restore, project and org create/delete, and the project settings commands. migration up/down/squash/repair, db reset, test db, db query, seed buckets and storage cp/mv/rm need it against a hosted target; db query --read-only doesn't. The migration guide has the full list. (#7188)
• The default answer is No. Pressing Enter now declines db push, deploys, secrets changes and migration history updates. Only projects, branches, orgs and domains create, and bootstrap, default to Yes. (#7188)
• A y piped on stdin no longer confirms, and SUPABASE_YES in a .env file no longer counts. When an env file in the working directory defines SUPABASE_YES, a shell-exported one doesn't count either. Use --yes. (#7188)
• secrets unset defaults to No and needs --all to remove every secret. Running it with no secret names now fails. (#7172)
• Declining fails with HostedMutationDeclinedError, replacing the per-command cancelled error codes. Declining db pull or pull writes no files. (#7188)
• db push, hosted db reset, config push and functions deploy --prune ask one combined question, and --prune now runs even when every function is up to date. Removing network bans automatically while connecting now needs --yes. migration down and migration repair --all on the local database no longer prompt. (#7188)
• Commands that resolve a target print Target: … once on stderr. JSON object results and error envelopes gain a target object; db reset's target changes from a string to that object, and config push JSON drops declined_addons and its skipped status. (#7188)

Flags and env vars override config

• Every value now resolves as flag > shell environment > project env files > config.json/config.toml > default, and that includes a matched [remotes.<name>] block. Project env files are .env.<SUPABASE_ENV>.local, .env.local, .env.<SUPABASE_ENV> and .env, in supabase/ and then the project root. SUPABASE_ENV defaults to development. (#7074)
• If you deploy with [remotes.*] blocks, audit the SUPABASE_* variables in CI and in your env files. They now beat the block, and config push pushes them (labelled per value; config diff shows the same). Set SUPABASE_ENV in CI so .env.development doesn't apply. (#7074)
• Without a project_id in config.toml, local containers and volumes are named after the project folder, not the project ref. Run supabase stop before upgrading, or set project_id. (#7074)
• An invalid config value or SUPABASE_* variable (for example SUPABASE_STUDIO_PORT=abc) now fails every command that loads config with CliConfigValueError. Boolean variables accept only 1/t/true and 0/f/false (with T, True, TRUE, F, False, FALSE). (#7074)
• Seeding a project matched by a [remotes.*] block asks first unless the block sets db.seed.enabled = true. SUPABASE_DB_PASSWORD is no longer sent to a project other than the linked one, and --password with a local or URL target exits 1. (#7074)
• Without --workdir, the nearest directory with supabase/config.toml or supabase/config.json wins. supabase link --password is ignored, ports with a leading zero are rejected, and MigrationPasswordFlagsError is now DbPasswordFlagsError. (#7074)

Removed commands, flags and config

Each removed command or flag exits 1 and prints its replacement. (#6609, #7109, #7116, #7176)

Other behavior changes

• [auth.sms] enable_confirmations = false, the init default, now turns phone confirmation off on config push. Set it to true to keep phone codes, and run config diff before pushing. (#7221)
• db advisors --remote no longer connects to the database first, so it no longer resolves database settings, creates a temporary login role or removes network bans. (#7297)
• Error messages that quoted Go library errors are reworded, for example expected a boolean instead of strconv.ParseBool: …. Update anything that matches on error text. (#7064)

Highlights

• db reset stops failing at random — the intermittent error running container: exit 1 at "Initialising schema…", mostly seen in CI, is gone. (#7380)
• link works with least-privilege tokens — a project-scoped token that can't read secret API keys can now link and db push; the CLI warns and skips the optional version checks instead of failing. (#7388)
• [auth.email] enabled and [auth.sms] enabled — enable_signup in those sections switched the whole provider off, blocking existing users from signing in, not just new signups. Use enabled for the provider toggle and [auth] enable_signup to stop new signups; the old keys still work but are deprecated. (#7398)

New features

• Plan-gate details in JSON errors — when your plan doesn't include a feature, --output-format json and stream-json errors carry an entitlement object with feature and upgrade_url, so scripts and agents don't have to parse the message. (#7271)

Improvements

• Better editor support for config.toml: the published config schemas use draft-07, which Taplo (Even Better TOML) understands, accept env() on number, boolean, enum and list fields, and mark secret fields with x-secret. (#7330, #7333, #7366)
• With SUPABASE_USE_SLIM_IMAGES, a GHCR rate limit no longer fails supabase start; the CLI pulls the same image from ECR Public instead. (#7350)
• supabase init adds a commented [auth.web3.ethereum] example to config.toml. (#7334)
• Experimental stack: the gateway serves /graphql/v1 (so Studio's GraphiQL works), /rest-admin/v1, /pg/, /analytics/v1/ and /pooler/v2/, forwards X-Forwarded-For and X-Real-IP to upstreams, and Edge Functions that boot together no longer fail with 503 BOOT_ERROR. (#7345, #7347, #7382)

Bug fixes

• supabase start and supabase db start recover from a database container left in Docker's created state, instead of failing with container is not running: created. (#7369)
• Overlapping start and stop runs on the same project no longer fail with network supabase_network_<id> not found. (#7372)
• supabase start works on nested or sandboxed Docker hosts where docker exec fails, instead of timing out on health checks. (#7362)
• secrets set honors --workdir and SUPABASE_WORKDIR instead of uploading secrets from the current directory. (#7361)
• Local db advisors lints every schema exposed in [api], instead of only public or sometimes nothing. (#7379)
• db push and db reset place the migration error caret correctly when accented letters or emoji come before the failing token. (#7351)
• config push no longer fails when you change the OAuth server path or turn the OAuth server on or off. (#7367)
• Restoring a db dump --role-only file as postgres no longer fails on a parameter grant to a reserved role. (#7320)

Plus 106 internal improvements and dependency updates.

Full changelog: v2.122.0...v3.0.0