supabase/cli v3.1.0

on GitHub

Supabase CLI v3.1.0 — 2026-11-09

This release adds inspect db diagnostics, a config.jsonc option, and an API retry cap for CI. Most of the rest is fixes for start, link, and db connections, plus a few local-stack behaviors that now match the hosted platform. One gotcha: local CORS on /functions/v1 changed (see Improvements).

Highlights

• Pinned Supabase CA on every linked database connection — db push/pull/dump/diff/reset/lint/advisors/query, migration *, and inspect * now verify the hosted server certificate. Previously only gen types did. (#7518)
• TypeScript types for linked projects come from your local config.toml — gen types --lang typescript respects [api].extra_search_path and falls back to the Management API when needed. Remote output now matches local output. (#7520)
• config.jsonc support — comments and trailing commas work, and the CLI keeps them when it writes the file. (#7488)
• inspect db gets three new commands — xid-age, toast-sizes, and collation-drift, which reports indexes whose collation version has drifted and prints the fix steps. (#6527, #6528, #7460)

New features

• SUPABASE_API_MAX_RETRIES caps Management API retries — set 0 in CI to send each request once. It applies to every API client, including login and services, and functions deploy respects it while still honouring rate limits. (#7394)
• inspect db xid-age — lists user tables by transaction ID age, oldest first. Useful for spotting wraparound risk. (#6527)
• inspect db toast-sizes — lists tables by TOAST storage, largest first. (#6528)
• inspect db collation-drift — read-only check for btree indexes affected by OS collation changes. Run it, then follow the printed amcheck → REINDEX INDEX CONCURRENTLY → REFRESH VERSION steps. (#7460)
• Logs commands unified — supabase logs is a single entry point for local and hosted logs, with an interactive explorer and structured output for scripts. (#7437)
• config.jsonc and commented JSON configs — the loader reads config.json, config.jsonc, and config.toml from supabase/. Edits from the CLI preserve your comments. (#7488)
• Config schema version is declared and checked — add $schema to config.json/config.jsonc, or #:schema at the top of config.toml. No declaration means v1. (#7514)
• init writes a schema directive — new config.toml files start with #:schema https://supabase.com/schemas/config/v1.json, so Taplo, Tombi, and VS Code get autocomplete and validation. (#7464)
• [auth.email] require_current_password — set it in config.toml to require the current password for password changes. config push/pull/diff support it too. (#7458)
• Local stack serves auth email templates from content_path — templates are read on every fetch, so edits show up without a restart. (#7527)
• Config-load telemetry records the failing key — config_key is added to cli_command_executed events. (#7468)

Improvements

• Stack CORS now matches the hosted platform — preflights return 200 instead of 204, with a wider method list. A live parity test keeps them aligned. (#7485)
• Gotcha: CORS on /functions/v1 is now handled by your function — the gateway no longer adds Access-Control-Allow-Origin: *, so a function that sends no CORS headers will be blocked by browsers. Add the headers in the function, or check your function's CORS handling if you call it from a browser. (#7472)
• Linked sso list and sso show fail faster — each attempt is capped at 10s instead of 60s. When an SSO call fails, the CLI also warns if the project isn't ACTIVE_HEALTHY. (#7491)
• supabase start skips Docker's first health-check wait — when services are already up, startup no longer waits about 10s on that check. (#7430)
• supabase stop no longer shows an error for functions serve — stopping the stack while functions serve runs is treated as a normal stop, not a crash. (#7463)
• Clearer migration errors for LOCK TABLE — a migration that fails with SQLSTATE 25P01 now explains the fix. Wrap the lock in BEGIN/COMMIT. (#7487)
• Clearer Docker-down detection — newer Docker daemon-down messages, including the Windows form, are recognised. (#7505)

Bug fixes

• supabase start no longer hangs after the output pipe closes — piping into a reader that exits early, like projects list | true, now ends the command. (#7469)
• db push works against a remote Postgres without TLS — an unset or sslmode=prefer URL falls back to plaintext, like psql. (#7509)
• db start --from-backup works on Windows — the drive letter is kept in the backup bind path. (#7498)
• link no longer carries the old project's service versions — relinking to a new project no longer runs the old Auth, PostgREST, or Storage versions. (#7476)
• gen types includes views from db-extra-search-path schemas — embeds that work at runtime are no longer rejected by the generated types. (#7515)
• Studio's Logs pages are hidden when Logflare is off — with [analytics] enabled = false, Studio no longer shows Logs pages that fail with a 500. (#7530)
• Functions get [edge_runtime.secrets] as written — secret names keep their case, and supabase/functions/<slug>/.env is read. (#7481, #7499)
• Stack image transforms match the legacy backend — imgproxy gets the same tuning, so browsers that accept WebP get WebP. (#7483)
• Studio can create vector buckets on the stack — the local S3 keys are passed through. (#7486)
• Binary request bodies type-check correctly in the Management API client — Uint8Array, ArrayBuffer, and Blob uploads to the update-function body are accepted again. (#7443)
• Linked project health is surfaced on SSO failures — the warning above appears when a project isn't healthy. (#7491)
• Docker start no longer leaves containers with a ~1B open-file limit — supabase start caps Erlang port tables for realtime, analytics, and the pooler. (#7512)
• Missing supabase_privileged_role gets its own error — the login-role mint failure now says what's missing instead of a generic status error. (#7461)
• Functions deploy errors are classified by cause — a malformed deno.json or import map counts as invalid config, not an internal bug. (#7510)
• Stack gateway and registry fixes — the port registry opens in WAL mode so concurrent reads don't fail on Windows, and a directory restriction no longer strips a traverse bit. (#7342, #7276)
• Timeout and readiness errors name the stalled step — engine and helper timeouts report which command or container stalled. (#7407, #7319)
• Edge runtime exit 15 is treated as a stop — see the Improvements note above. (#7463)

Plus 5 internal improvements and dependency updates.

Full changelog: v3.0.0...v3.1.0