The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs(cli): add local-dev workflow guide and restructure CLI docs (#47932)
Andrey A.7cffbcc47f57
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 2c1ee5514fd..dbcfb17e112 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -2452,25 +2452,14 @@ export const local_development: NavMenuConstant = {title: 'Local Dev / CLI',url: '/guides/local-development',items: [- { name: 'Overview', url: '/guides/local-development' },+ { name: 'Overview & quickstart', url: '/guides/local-development' },+ { name: 'Install and run the CLI', url: '/guides/local-development/cli/getting-started' },+ { name: 'Local development workflow', url: '/guides/local-development/cli-workflows' },{- name: 'CLI',- url: undefined,- items: [- { name: 'Getting started', url: '/guides/local-development/cli/getting-started' },- {- name: 'Configuration',- url: '/guides/local-development/cli/config',- enabled: localDevelopmentEnabled,- },- { name: 'CLI commands', url: '/reference/cli' },- ],- },- {- name: 'Local development',+ name: 'Guides',url: undefined,items: [- { name: 'Getting started', url: '/guides/local-development/overview' },+ { name: 'Database migrations', url: '/guides/local-development/database-migrations' },{name: 'Declarative database schemas',url: '/guides/local-development/declarative-database-schemas' as `/${string}`,@@ -2495,6 +2484,18 @@ export const local_development: NavMenuConstant = {},],},+ {+ name: 'Reference',+ url: undefined,+ items: [+ {+ name: 'CLI configuration',+ url: '/guides/local-development/cli/config',+ enabled: localDevelopmentEnabled,+ },+ { name: 'CLI commands', url: '/reference/cli' },+ ],+ },{name: 'Testing',url: undefined,diff --git a/apps/docs/content/guides/local-development.mdx b/apps/docs/content/guides/local-development.mdxindex 6b9490c59cf..4be1f523163 100644--- a/apps/docs/content/guides/local-development.mdx+++ b/apps/docs/content/guides/local-development.mdx@@ -3,13 +3,13 @@ title: Local Development & CLIsubtitle: Learn how to develop locally and use the Supabase CLI----Develop locally while running the Supabase stack on your machine.+To develop your applications using the locally running Supabase stack, you'll need to install the [Supabase CLI](#cli) and a container runtime.<Admonition type="note">-As a prerequisite, you must install a container runtime compatible with Docker APIs.+A container manager compatible with Docker APIs is a prerequisite:-- [Docker Desktop](https://docs.docker.com/desktop/) (macOS, Windows, Linux)+- [Docker Desktop](https://docs.docker.com/desktop/) (macOS, Windows, Linux) - preferred option- [Rancher Desktop](https://rancherdesktop.io/) (macOS, Windows, Linux)- [Podman](https://podman.io/) (macOS, Windows, Linux)- [OrbStack](https://orbstack.dev/) (macOS)@@ -18,6 +18,12 @@ As a prerequisite, you must install a container runtime compatible with Docker A## Quickstart+<Admonition type="note">++Pick an install method and use the same tab in every step below. **Homebrew** gives you a global `supabase` command. **npm, pnpm, and yarn** install the CLI into your project as a dev dependency, so you run it through your package runner (`npx supabase`, `pnpm supabase`, or `yarn supabase`). See [Install and run the CLI](/docs/guides/local-development/cli/getting-started) for details.++</Admonition>+1. Install the Supabase CLI:<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">@@ -52,7 +58,7 @@ As a prerequisite, you must install a container runtime compatible with Docker A</TabPanel></Tabs>-2. In your repo, initialize the Supabase project:+2. In your repo, initialize the local Supabase project:<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">@@ -69,7 +75,7 @@ As a prerequisite, you must install a container runtime compatible with Docker A</TabPanel><TabPanel id="pnpm" label="pnpm">```sh- pnpx supabase init+ pnpm supabase init```</TabPanel><TabPanel id="brew" label="brew">@@ -82,7 +88,7 @@ As a prerequisite, you must install a container runtime compatible with Docker A</Tabs>-3. Start the Supabase stack:+3. Start the local Supabase stack:<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">@@ -99,7 +105,7 @@ As a prerequisite, you must install a container runtime compatible with Docker A</TabPanel><TabPanel id="pnpm" label="pnpm">```sh- pnpx supabase start+ pnpm supabase start```</TabPanel><TabPanel id="brew" label="brew">@@ -135,15 +141,13 @@ Local development with Supabase allows you to work on your projects in a self-co2. Offline work: You can continue development even without an internet connection.3. Cost-effective: Local development is free and doesn't consume your project's quota.4. Enhanced privacy: Sensitive data remains on your local machine during development.-5. Easy testing: You can experiment with different configurations and features without affecting your production environment.--To get started with local development, you'll need to install the [Supabase CLI](#cli) and Docker. The Supabase CLI allows you to start and manage your local Supabase stack, while Docker is used to run the necessary services.+5. Safe testing: You can experiment with different configurations and features without affecting your production environment.Once set up, you can initialize a new Supabase project, start the local stack, and begin developing your application using local Supabase services. This includes access to a local Postgres database, Auth, Storage, and other Supabase features.## CLI-The Supabase CLI is a powerful tool that enables developers to manage their Supabase projects directly from the terminal. It provides a suite of commands for various tasks, including:+The Supabase CLI is a tool that enables developers to run Supabase services locally and manage hosted projects directly from the terminal. It provides a suite of commands for various tasks, including:- Setting up and managing local development environments- Generating TypeScript types for your database schemadiff --git a/apps/docs/content/guides/local-development/cli-workflows.mdx b/apps/docs/content/guides/local-development/cli-workflows.mdxnew file mode 100644index 00000000000..226ad9c936b--- /dev/null+++ b/apps/docs/content/guides/local-development/cli-workflows.mdx@@ -0,0 +1,480 @@+---+id: 'cli-workflows'+title: 'Local development workflow'+description: 'Set up and run your day-to-day local development workflow with the Supabase CLI.'+subtitle: 'Set up and run your day-to-day local development workflow with the Supabase CLI.'+---++This guide walks through two common starting points for local development with the Supabase CLI, and shows how they converge into the same daily workflow. By the end, you'll have a `./supabase` directory in your repo that anyone can clone to recreate the full project, locally or on a fresh remote instance.++There are two starting points, both leading to the same place: database schema and migrations tracked in version control, with seed data for local development.++- **[Move an existing project to local development](#move-an-existing-project-to-local-development)**: you have a project on the Supabase platform and want to bring it into a proper local development workflow.+- **[Start a new project from scratch](#start-a-new-project-from-scratch)**: you're building locally and will eventually push to a remote instance.++## Before you begin++You need the Supabase CLI installed and a Docker-compatible runtime running. If you haven't set these up yet, see [Install and run the CLI](/docs/guides/local-development/cli/getting-started) for installation across macOS, Windows, and Linux, and for the details of what `supabase start` brings up and how to access each service.++Keep in mind that **the local stack is for development only**. It is not hardened for production use and must never be exposed to external traffic. It has no TLS, no rate limiting, and default credentials. Use it to develop and test, then deploy to the [Supabase Platform](https://supabase.com) or a proper self-hosted setup for anything beyond that.++<Admonition type="note" label="`supabase` vs. `npx supabase`">++How you invoke the CLI depends on how you installed it:++- Installed globally with **Homebrew or Scoop**: run `supabase <command>`.+- Added as a **project dependency** with npm, pnpm, yarn, or bun: run it through your package runner instead, for example `npx supabase <command>` (or `pnpm supabase`, `yarn supabase`, `bunx supabase`).++Every example in this guide is written as `supabase <command>`. Translate it to whichever form matches your install. See [Install and run the CLI](/docs/guides/local-development/cli/getting-started) for the full setup.++</Admonition>++<Admonition type="tip" label="Starting from a template">++If you want a working project to explore rather than an empty one, `supabase bootstrap` scaffolds a starter application (Next.js, Flutter, and more) with schema, migrations, and config already wired up. It's an alternative entry point to `supabase init` when starting a new project from scratch.++</Admonition>++## The `./supabase` directory++After `supabase init`, your project contains a `./supabase` directory. Here's what goes in it and what to commit:++| Path | Purpose | Commit? |+| ---------------------- | ----------------------------------------------------------------- | ------- |+| `config.toml` | Local stack configuration (ports, auth settings, etc.) | Yes |+| `migrations/` | Timestamped SQL migration files, applied in order | Yes |+| `seed.sql` | Dev/test data, applied after migrations on `start` and `db reset` | Yes |+| `schemas/` | Declarative schema files (if using that approach) | Yes |+| `.temp/`, `.branches/` | CLI internal state | No |++The `config.toml` is safe to commit. It contains no secrets by default. If you add sensitive values (OAuth credentials, API keys), use the `env()` function to reference environment variables instead of hardcoding them. See [Managing config and secrets](/docs/guides/local-development/managing-config).++<Admonition type="note" label="Local vs. remote targets">++Many database commands accept `--local` and `--linked` flags to choose what they act on. The defaults are not the same across commands: `db diff` and `db reset` default to `--local`, while `db pull`, `db push`, and `db dump` default to `--linked`. When in doubt, pass the flag explicitly.++</Admonition>++## Move an existing project to local development++You've built a project on the Supabase platform, with tables created via the Dashboard, SQL editor, or client libraries. Now you want a local dev setup with everything in version control.++### Step 1: Initialize++In your project root:++```bash+supabase init+```++This creates `./supabase/config.toml`. If you already have a project directory with application code, run this at the root. The `supabase/` directory will sit alongside your app code.++### Step 2: Authenticate++```bash+supabase login+```++Opens a browser to generate an access token. The token is stored locally and used for all subsequent CLI commands that interact with the platform.++### Step 3: Link to your remote project++```bash+supabase link --project-ref <project-id>+```++Find your project ID in the Supabase Dashboard URL: `https://supabase.com/dashboard/project/<project-id>`.++This tells the CLI which remote project to connect to for `db pull`, `db push`, and other remote operations. You'll be prompted for the database password, which is the password set when you created the project.++### Step 4: Pull the remote schema++```bash+supabase db pull+```++This connects to your remote database, dumps the entire schema, and saves it as a migration file:++```+supabase/migrations/<timestamp>_remote_schema.sql+```++This initial migration is your baseline. It represents the current state of your database, and all future changes build on top of it. `db pull` also records this migration as already applied in the remote migration history (the `supabase_migrations.schema_migrations` table), so a later `db push` won't try to reapply it.++<Admonition type="caution" label="Review the generated migration">++`db pull` diffs your remote database against the CLI's default local stack, so the generated file can include statements you didn't expect. A common example is `DROP EXTENSION pg_net;`, emitted when your remote project has an extension disabled that the local stack enables by default. These statements apply silently on `db reset` and change your local schema, so read the file before committing it. See [Cleaning up generated migrations](#cleaning-up-generated-migrations) for what to look for.++</Admonition>++<Admonition type="tip">++If you also use Supabase Auth or Storage and have customized their schemas, pull them separately:++```bash+supabase db pull --schema auth -f pull-auth-schema+supabase db pull --schema storage -f pull-storage-schema+```++These schemas are managed by Supabase and typically don't need to be pulled unless you've made custom modifications.++</Admonition>++### Step 5: Create seed data++You have two options:++**Option A: Dump existing data from remote** (then clean it up):++```bash+supabase db dump --data-only --linked > supabase/seed.sql+```++<Admonition type="caution">++Review and clean up the dump before committing. Remove production user data, secrets, personal information, and anything sensitive. Keep only representative test data that a developer needs to work with the project.++</Admonition>++**Option B: Write seed data by hand** (recommended for most projects):++Create `supabase/seed.sql` with INSERT statements that set up a useful local development state: a few test users, sample data, and so on. This is often better than dumping production data because you control exactly what's in it.++For more on organizing seed files, glob patterns, and generating realistic data, see [Seeding your database](/docs/guides/local-development/seeding-your-database).++### Step 6: Verify++```bash+supabase start+supabase db reset+```++`db reset` destroys the local database and recreates it from scratch: it applies all migrations in order, then runs `seed.sql`. If this succeeds, your setup is reproducible. Anyone who clones the repo can do the same.++### Step 7: Commit++```bash+git add supabase/+git commit -m "add supabase local development setup"+```++Your project now has a fully reproducible local development environment.++<Admonition type="note" label="What about declarative schemas?">++For an existing project, the pulled migration already serves as your schema baseline. You don't need to also create a `schemas/` directory, because that would mean maintaining two representations of the same schema. If you want to adopt declarative schemas later, see [Declarative database schemas](/docs/guides/local-development/declarative-database-schemas). For day-to-day changes going forward, see [The daily workflow](#the-daily-workflow) below.++</Admonition>++## Start a new project from scratch++No remote project yet. You're building from scratch and want to do it right from the start.++### Step 1: Initialize++```bash+supabase init+```++### Step 2: Start the local stack++```bash+supabase start+```++On first run, Docker images are pulled, which takes a few minutes. Subsequent starts are fast. Once running, the CLI outputs local service URLs and credentials, including the Studio URL for a local instance of the Dashboard. See [Install and run the CLI](/docs/guides/local-development/cli/getting-started#access-your-projects-services) for the full output and how to reach each service.++### Step 3: Create your schema++Two approaches, pick one:++**Option A: Declarative schema** (recommended for new projects)++Declare the state you want your database to be in as a file in `supabase/schemas/`, for example:++```sql title="supabase/schemas/schema.sql"+create table public.todos (+ id bigint generated by default as identity primary key,+ created_at timestamptz default now() not null,+ title text not null,+ is_complete boolean default false not null,+ user_id uuid references auth.users (id) default auth.uid() not null+);++alter table public.todos enable row level security;++create policy "Users can read their own todos"+ on public.todos for select+ using (auth.uid() = user_id);++create policy "Users can create their own todos"+ on public.todos for insert+ with check (auth.uid() = user_id);+```++Then generate a migration from it:++```bash+supabase db diff -f initial-schema+```++This compares your declared schema against the current (empty) database and generates a migration file in `supabase/migrations/`. For the full declarative workflow, including managing views and functions, ordering schema files, and known caveats, see [Declarative database schemas](/docs/guides/local-development/declarative-database-schemas).++**Option B: Write the migration directly**++```bash+supabase migration new initial-schema+```++This creates an empty file at `supabase/migrations/<timestamp>_initial-schema.sql`. Write your SQL in it, then apply:++```bash+supabase db reset+```++### Step 4: Add seed data++Create `supabase/seed.sql`:++```sql title="supabase/seed.sql"+-- Create a test user (Supabase Auth)+-- Note: this is a placeholder row so seeded data has a user_id to reference.+-- It has no password, so it can't be used to sign in. To create a+-- login-capable user, use the Auth admin API or the local Studio.+insert into auth.users (id, email, raw_user_meta_data)+values ('d0e3c8f0-1234-5678-9abc-def012345678', '[email protected]', '{}');++-- Seed application data+insert into public.todos (title, user_id)+values+ ('Buy groceries', 'd0e3c8f0-1234-5678-9abc-def012345678'),+ ('Write documentation', 'd0e3c8f0-1234-5678-9abc-def012345678');+```++### Step 5: Verify++```bash+supabase db reset+```++Drops everything, applies migrations, runs seed. If this passes, your project is reproducible.++### Step 6: Commit++```bash+git add supabase/+git commit -m "add supabase local development setup"+```++## The daily workflow++Both starting points converge here. You have a working `./supabase` directory in your repo. Here's how day-to-day development works.++### Making schema changes++Which approach you use is a project-level decision, set when you first created your schema - not a per-change choice. It depends on whether you keep declarative files in `supabase/schemas/`. Pick the tab that matches your project.++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="declarative"+ queryGroup="schema-approach"+>+<TabPanel id="declarative" label="Declarative schemas">++1. Edit your schema file(s) in `supabase/schemas/` (add a table, a column, a policy, etc.)+2. Generate a migration: `supabase db diff -f add-due-date-to-todo`+3. Review the generated migration file. See [Cleaning up generated migrations](#cleaning-up-generated-migrations)+4. Verify the full chain: `supabase db reset`+5. Commit the schema file **and** the migration together++<Admonition type="caution">++`db diff` compares your `supabase/schemas/` files against your existing migrations; it does **not** read the live local database. Changes you make directly in Studio or via SQL are ignored, so `db diff` reports "No schema changes found" and silently drops them. Always edit the schema files, then diff.++</Admonition>++ </TabPanel>+ <TabPanel id="imperative" label="Imperative migrations">++**If you made changes through the local Studio UI:**++```bash+supabase db diff -f add-due-date-to-todo+```++This captures your UI changes as a migration file. This works only when your project has **no** declarative files in `supabase/schemas/`: `db diff` then compares the live local database against your migrations. If you use declarative schemas, don't edit through Studio expecting `db diff` to catch it - see the **Declarative schemas** tab.++**If you prefer to write SQL directly:**++```bash+supabase migration new add-due-date-to-todo+```++Write the SQL in the generated file. Then verify:++```bash+supabase db reset+```++Commit the migration.++</TabPanel>+</Tabs>++### Generating types++If your app uses the generated TypeScript types, regenerate them whenever your schema changes:++```bash+supabase gen types --lang typescript --local > database.types.ts+```++Use `--linked` instead of `--local` to generate from your remote project. TypeScript is the default language; pass `--lang go`, `--lang swift`, or `--lang python` for others.++For working with the generated types (helper types, JSON inference, type-safe queries) and automating regeneration in CI, see [Generating types](/docs/guides/api/rest/generating-types).++### Staying in sync with your team++When someone else pushes new migrations:++```bash+git pull+supabase db reset+```++`db reset` replays all migrations from scratch, so you'll always match the current state of the repo.++## Pushing to a remote project++When you're ready to deploy your schema to a remote Supabase instance:++```bash+# Authenticate (if not already)+supabase login++# Link to the remote project (if not already)+supabase link --project-ref <project-id>++# Preview what will be applied+supabase db push --dry-run++# Apply migrations+supabase db push+```++`db push` applies only migrations that haven't been applied to the remote yet. It tracks this via the `supabase_migrations.schema_migrations` table created automatically on the remote database.++To also seed a fresh remote instance (dev/staging environments only):++```bash+supabase db push --include-seed+```++<Admonition type="caution">++Never use `--include-seed` on a production database. Seed data is for development and testing.++</Admonition>++### Resetting a remote dev or staging project++If a dev or staging remote drifts or gets into a messy state, you can wipe it and rebuild it from your local migrations:++```bash+supabase db reset --linked+```++Unlike the default `supabase db reset`, which targets your local database, the `--linked` flag runs against the remote project you connected with `supabase link`: it drops the remote schema, then replays every local migration in order. Add `--include-seed` to reload seed data as well.++<Admonition type="danger">++`db reset --linked` is destructive: it erases all data in the linked remote database. Only run it against throwaway dev or staging projects, and double-check which project you're linked to (`supabase projects list` shows the linked one) before running it. Never use it on production.++</Admonition>++For multi-environment setups with CI/CD (feature branches, staging, production), see [Managing Environments](/docs/guides/deployment/managing-environments).++## Key commands at a glance++| Command | What it does |+| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |+| `supabase init` | Creates `./supabase/config.toml` |+| `supabase start` | Starts the local stack, applies migrations + seed |+| `supabase stop` | Stops the local stack (data persists until `db reset`) |+| `supabase db reset` | Destroys local DB, applies all migrations + seed from scratch |+| `supabase db reset --linked` | Destroys the **linked remote** DB and rebuilds it from local migrations (destructive; dev/staging only) |+| `supabase db diff -f <name>` | Generates a migration by diffing current DB state against a shadow database |+| `supabase db pull` | Pulls remote schema into a new local migration file |+| `supabase db push` | Applies pending local migrations to the remote database |+| `supabase db dump` | Exports remote DB schema (or `--data-only` for data) via `pg_dump` |+| `supabase migration new <name>` | Creates an empty migration file |+| `supabase migration list` | Compares local migrations against remote migration history |+| `supabase gen types --lang typescript` | Generates TypeScript types from your database schema |+| `supabase link --project-ref` | Connects local project to a remote Supabase project |+| `supabase login` | Authenticates with the Supabase platform |++For the full command reference and every flag, see the [CLI reference](/docs/reference/cli).++## Cleaning up generated migrations++When `supabase db diff` generates a migration, it may include statements that are technically correct but noisy. Review every generated migration before committing.++### Grants++You may see lines like:++```sql+GRANT MAINTAIN, REFERENCES, TRIGGER, TRUNCATE ON public.todos TO anon;+GRANT MAINTAIN, REFERENCES, TRIGGER, TRUNCATE ON public.todos TO authenticated;+GRANT MAINTAIN, REFERENCES, TRIGGER, TRUNCATE ON public.todos TO service_role;+```++These appear because the diff tool treats permissions as part of the schema state. For tables in the `public` schema, these grants are applied by default and the lines are redundant. They're harmless, but if you want clean migrations, you can remove them. Be consistent across your team about whether you keep or remove them.++### Revoke/re-grant patterns++Sometimes a diff produces:++```sql+REVOKE ALL ON TABLE public.todos FROM anon;+GRANT ALL ON TABLE public.todos TO anon;+```++This is the diff tool being overly cautious. If you haven't changed permissions, these lines can be safely removed.++### Extension statements++`CREATE EXTENSION IF NOT EXISTS ...` may appear. Keep these if the extension is required by your migration. Remove them if the extension is already created by a previous migration or is part of the default Supabase setup.++### Known limitations of `db diff`++The diff is generated by `pg-delta`, the default schema diff engine. (The older [`migra`](https://github.com/djrobstep/migra) engine is still available: set `enabled = false` under `[experimental.pgdelta]` in `config.toml`, or pass `--use-migra`.) No diff engine captures everything. Most notably, DML (INSERT, UPDATE, DELETE) is not tracked, so data changes must be added to the migration manually, and some entities like RLS policy renames and certain view properties don't diff cleanly. See the [full list of caveats](/docs/guides/local-development/declarative-database-schemas#known-caveats) in the declarative schemas guide.++Treat `db diff` output as a draft, not a final migration. When in doubt, review the generated SQL and adjust it manually.++## Troubleshooting++**`db reset` fails with a migration error**++The output will show which migration file failed and the SQL error. Fix the migration file, then run `db reset` again.++**`db push` says migrations are already applied**++The remote database already has those migrations in its history. Run `supabase migration list` to compare local vs. remote state. If they're out of sync, use `supabase migration repair` to correct the remote history.++**Schema drift: remote was changed outside of migrations**++If someone modified the remote database directly (via Dashboard, SQL editor, etc.), run `supabase db pull` to capture those changes as a new migration file. Then `supabase db reset` locally to verify everything still works.++**Docker issues on `supabase start`**++Ensure Docker is running and has at least 7 GB of RAM allocated. If containers fail health checks, try:++```bash+supabase stop+supabase start+```++If problems persist, `supabase stop --no-backup` for a clean restart (this removes local database data).diff --git a/apps/docs/content/guides/local-development/cli/getting-started.mdx b/apps/docs/content/guides/local-development/cli/getting-started.mdxindex 10838693b14..b752929f3ed 100644--- a/apps/docs/content/guides/local-development/cli/getting-started.mdx+++ b/apps/docs/content/guides/local-development/cli/getting-started.mdx@@ -9,6 +9,19 @@ The Supabase CLI enables you to run the entire Supabase stack locally, on your m1. `supabase init` to create a new local project2. `supabase start` to launch the Supabase services+<Admonition type="note" label="Global command vs. project dependency">++There are two ways to install the CLI, and they change the command you type:++- **Project dependency** with `npm`, `pnpm`, or `yarn` installs the CLI into a single project (there is no global `supabase` command with this method). Run it through your package runner instead, for example `npx supabase <command>`.+- **Global install** with Homebrew, Scoop, or Linux packages. Run commands as `supabase <command>`.++Either way, the CLI is **project-scoped**: most commands (including `start`) expect to run inside a directory that has been initialized with `supabase init`, which creates the `supabase/` folder and `config.toml`. Run `init` first, then the other commands from the same directory.++The rest of this page writes examples as `supabase <command>`; translate them to `npx supabase <command>` if you installed the CLI as a project dependency.++</Admonition>+## Installing the Supabase CLI<Tabs@@ -16,8 +29,30 @@ The Supabase CLI enables you to run the entire Supabase stack locally, on your msize="small"type="underlined"defaultActiveId="npm"- queryGroup="platform">+<TabPanel id="npm" label="npm">++Install the CLI as a project dev dependency. This adds it to a single project rather than installing a global command:++```sh+npm install supabase --save-dev+# or: pnpm add -D supabase / yarn add -D supabase / bun add -D supabase+```++Pin the version in `package.json` so your whole team uses the same CLI version. Then run every command through your package runner:++```sh+npx supabase --help+# or: pnpm supabase / yarn supabase / bunx supabase+```++<Admonition type="caution">++The Supabase CLI requires **Node.js 20 or later** when run via `npx` or `npm`. Older Node.js versions, such as 16, are not supported and fail to start the CLI.++</Admonition>++</TabPanel><TabPanel id="macos" label="macOS">Install the CLI with [Homebrew](https://brew.sh):@@ -39,7 +74,7 @@ scoop install supabase</TabPanel><TabPanel id="linux" label="Linux">-The CLI is available through [Homebrew](https://brew.sh) and Linux packages.+The CLI is available via [Homebrew](https://brew.sh) and Linux packages.#### Homebrew@@ -57,27 +92,6 @@ and run one of the following:- `sudo dpkg -i <...>.deb`- `sudo rpm -i <...>.rpm`-</TabPanel>-<TabPanel id="npm" label="Node.js">--Run the CLI by prefixing each command with `npx` or `bunx`:--```sh-npx supabase --help-```--<Admonition type="caution">--The Supabase CLI requires **Node.js 20 or later** when run via `npx` or `npm`. Older Node.js versions, such as 16, are not supported and fail to start the CLI.--</Admonition>--You can also install the CLI as dev dependency via [npm](https://www.npmjs.com/package/supabase):--```sh-npm install supabase --save-dev-```-</TabPanel></Tabs>@@ -90,8 +104,22 @@ Pre-release CLI builds ship from the development branch (`X.Y.Z-beta.N` versionssize="small"type="underlined"defaultActiveId="npm"- queryGroup="platform">+<TabPanel id="npm" label="npm">++Install as a dev dependency:++```sh+npm install supabase@beta --save-dev+```++Or run without installing:++```sh+npx supabase@beta --help+```++</TabPanel><TabPanel id="macos" label="macOS">```sh@@ -121,21 +149,6 @@ brew link --overwrite supabase-betaBeta builds are attached to [GitHub pre-releases](https://github.com/supabase/cli/releases). Download the `.apk`, `.deb`, or `.rpm` for your platform and install with the same commands as [Linux packages](#linux-packages) above.-</TabPanel>-<TabPanel id="npm" label="Node.js">--Install as a dev dependency:--```sh-npm install supabase@beta --save-dev-```--Or run without installing:--```sh-npx supabase@beta --help-```-</TabPanel></Tabs>@@ -147,8 +160,7 @@ When a new [version](https://github.com/supabase/cli/releases) is released, youscrollablesize="small"type="underlined"- defaultActiveId="npm"- queryGroup="platform"+ defaultActiveId="macos"><TabPanel id="macos" label="macOS">@@ -199,7 +211,7 @@ brew upgrade supabase-beta- `sudo rpm -i <...>.rpm`</TabPanel>-<TabPanel id="npm" label="Node.js">+<TabPanel id="npm" label="npm">If you have installed the CLI as dev dependency via [npm](https://www.npmjs.com/package/supabase), you can update it with:@@ -230,9 +242,9 @@ supabase stop --no-backup</Admonition>-## Running Supabase locally+## Running a local Supabase project-The Supabase CLI uses Docker containers to manage the local development stack. Follow the official guide to install and configure [Docker Desktop](https://docs.docker.com/desktop) on your machine.+The most common thing you'll do with the CLI is run the full Supabase stack (Postgres, Auth, Storage, and the rest) on your own machine. That stack runs in Docker containers, so you need a container runtime installed first. Follow the official guide to install and configure [Docker Desktop](https://docs.docker.com/desktop) on your machine.Alternately, you can use a different container tool that offers Docker compatible APIs.@@ -241,7 +253,7 @@ Alternately, you can use a different container tool that offers Docker compatibl- [OrbStack](https://orbstack.dev/) (macOS)- [colima](https://github.com/abiosoft/colima) (macOS)-Inside the folder where you want to create your project, run:+With a container runtime running, go to the folder where you want to create your project and initialize it:```bashsupabase init@@ -249,12 +261,18 @@ supabase initThis creates a new `supabase` folder. It's safe to commit this folder to version control.-Now, to start the Supabase stack, run:+Now, from the same folder, start the Supabase stack:```bashsupabase start```+<Admonition type="note">++If you installed the CLI as a project dependency (npm, pnpm, yarn, or bun), run these as `npx supabase init` and `npx supabase start` instead. See the [note above](#installing-the-supabase-cli).++</Admonition>+This takes time on your first run because the CLI needs to download the Docker images to your local machine. The CLI includes the entire Supabase stack, and a few additional images useful for local development (like a local SMTP server and a database diff tool).## Access your project's services@@ -362,7 +380,7 @@ http://localhost:54321/auth/v1/ # Auth (GoTrue)</TabPanel><TabPanel id="analytics" label="Analytics">-Local logs rely on the Supabase Analytics Server which accesses the docker logging driver by either volume mounting `/var/run/docker.sock` domain socket on Linux and macOS, or exposing `tcp://localhost:2375` daemon socket on Windows. These settings must be configured manually after [installing](/docs/guides/cli/getting-started#installing-the-supabase-cli) the Supabase CLI.+Local logs rely on the Supabase Analytics Server which accesses the docker logging driver by either volume mounting `/var/run/docker.sock` domain socket on Linux and macOS, or exposing `tcp://localhost:2375` daemon socket on Windows. These settings must be configured manually after [installing](/docs/guides/local-development/cli/getting-started#installing-the-supabase-cli) the Supabase CLI.<Admonition type="note">diff --git a/apps/docs/content/guides/local-development/overview.mdx b/apps/docs/content/guides/local-development/database-migrations.mdxsimilarity index 88%rename from apps/docs/content/guides/local-development/overview.mdxrename to apps/docs/content/guides/local-development/database-migrations.mdxindex 0c2b6f00169..530fb2941a0 100644--- a/apps/docs/content/guides/local-development/overview.mdx+++ b/apps/docs/content/guides/local-development/database-migrations.mdx@@ -1,8 +1,8 @@----id: 'overview'-title: 'Local development with schema migrations'-description: 'Develop locally with the Supabase CLI and schema migrations.'-subtitle: 'Develop locally with the Supabase CLI and schema migrations.'+id: 'database-migrations'+title: 'Database migrations'+description: 'Track and version your database schema changes with migrations.'+subtitle: 'Track and version your database schema changes with migrations.'video: 'https://www.youtube-nocookie.com/v/vyHyYpvjaks'tocVideo: 'vyHyYpvjaks'---@@ -13,6 +13,12 @@ Develop locally using the CLI to run a local Supabase stack. You can use the intAlternatively, if you're comfortable with migration files and SQL, you can write your own migrations and push them to the local database for testing before sharing your changes.+<Admonition type="tip" label="Looking for the full end-to-end workflow?">++This page is a focused tutorial on migrations. If you want to move an existing platform project to local development, or set up a reproducible project from scratch and take it all the way to a remote deploy, see the [Local development workflow](/docs/guides/local-development/cli-workflows) guide. It covers both starting points, the daily development loop, pushing to production, cleaning up generated migrations, and troubleshooting.++</Admonition>+## Database migrationsDatabase changes are managed through "migrations." Database migrations are a common way of tracking changes to your database over time.@@ -231,33 +237,23 @@ npx supabase login### Link your project-Associate your project with your remote project using [`supabase link`](/docs/reference/cli/usage#supabase-link).+Associate your local project with your remote project using [`supabase link`](/docs/reference/cli/usage#supabase-link).```bashsupabase link --project-ref <project-id># You can get <project-id> from your project's dashboard URL: https://supabase.com/dashboard/project/<project-id>--supabase db pull-# Capture any changes that you have made to your remote database before you went through the steps above-# If you have not made any changes to the remote database, skip this step```-`supabase/migrations` is now populated with a migration in `<timestamp>_remote_schema.sql`.-This migration captures any changes required for your local database to match the schema of your remote Supabase project.+<Admonition type="note">-Review the generated migration file and once happy, apply the changes to your local instance:+If your remote database already has schema changes that aren't in your local migrations (for example, tables you created directly in the Dashboard), capture them before you push:```bash-# To apply the new migration to your local database:-supabase migration up--# To reset your local database completely:+supabase db pullsupabase db reset```-<Admonition type="note">--There are a few commands required to link your project. We are in the process of consolidating these commands into a single command. Bear with us!+`db pull` writes those changes to a `<timestamp>_remote_schema.sql` migration so your local and remote histories line up, and `db reset` re-applies your migrations locally to confirm they're consistent. For a brand-new remote project with nothing in it yet, skip this step.</Admonition>diff --git a/apps/docs/content/guides/local-development/declarative-database-schemas.mdx b/apps/docs/content/guides/local-development/declarative-database-schemas.mdxindex bcbacbe281a..e820b4971b3 100644--- a/apps/docs/content/guides/local-development/declarative-database-schemas.mdx+++ b/apps/docs/content/guides/local-development/declarative-database-schemas.mdx@@ -11,6 +11,8 @@ Declarative schemas provide a developer-friendly way to maintain <InfoTooltip to[Migrations](/docs/guides/deployment/database-migrations) are traditionally managed imperatively (you provide the instructions on how exactly to change the database). This can lead to related information being scattered over multiple migration files. With declarative schemas, you instead declare the state you want your database to be in, and the instructions are generated for you.+Because the schema files are the source of truth, make every change by editing them - not through Studio or the SQL editor. `supabase db diff` compares your schema files, not the live database, so changes made directly to the database are not picked up.+## Schema migrationsSchema migrations are SQL statements written in Data Definition Language. They are versioned in your `supabase/migrations` directory to ensure schema consistency between local and remote environments.@@ -89,6 +91,12 @@ supabase migration up### Updating your schema+<Admonition type="caution" label="Edit the schema files, not the database">++With declarative schemas, the files in `supabase/schemas/` are the source of truth. `supabase db diff` compares **those files** against your migrations - it does **not** read the live database. Changes you make directly (Studio, the SQL editor, `psql`) are invisible to the diff: it reports "No schema changes found" and the change is silently dropped. Always edit the schema files, then run `db diff`.++</Admonition>+<StepHikeCompact><StepHikeCompact.Step step={1}>@@ -341,7 +349,7 @@ SQL statements generated in a down migration are usually destructive. You must r## Known caveats-The `migra` diff tool used for generating schema diff is capable of tracking most database changes. However, there are edge cases where it can fail.+Schema diffs are generated by `pg-delta`, the default diff engine, which tracks most database changes. However, there are edge cases where schema diff can fail. The known cases below were documented against the legacy [`migra`](https://github.com/djrobstep/migra) engine (still available via `enabled = false` under `[experimental.pgdelta]` in `config.toml`, or `--use-migra`); some, such as duplicated grants from default privileges, also apply to `pg-delta`. Review every generated migration regardless of engine.If you need to use any of the entities below, remember to add them through [versioned migrations](/docs/guides/deployment/database-migrations) instead.diff --git a/apps/docs/content/guides/local-development/seeding-your-database.mdx b/apps/docs/content/guides/local-development/seeding-your-database.mdxindex 48e55d531a2..777239a1fe2 100644--- a/apps/docs/content/guides/local-development/seeding-your-database.mdx+++ b/apps/docs/content/guides/local-development/seeding-your-database.mdx@@ -58,7 +58,13 @@ The CLI processes seed files in the order they are declared in the `sql_paths` a## Generating seed data-You can generate seed data for local development using [Snaplet](https://github.com/snaplet/seed).+For most projects, a hand-written `supabase/seed.sql` (see [Using seed files](#using-seed-files) above) is the simplest and most reliable approach. If you need large volumes of realistic data, you can generate it with [Snaplet Seed](https://github.com/supabase-community/seed).++<Admonition type="note">++Snaplet wound down as a company in 2024 and open-sourced its tooling. `@snaplet/seed` is now community-maintained at [supabase-community/seed](https://github.com/supabase-community/seed) and receives only occasional fixes, so treat it as an optional convenience rather than a required part of the workflow.++</Admonition><Admonition type="tip">@@ -160,23 +166,22 @@ Running `npx tsx seed.ts > supabase/seed.sql` generates the relevant SQL stateme```sql-- The `Post.createdBy` user with an email address ending in `"@acme.org"`-INSERT INTO "User" (name, email) VALUES ("John Snow", "[email protected]")+insert into "User" (name, email) values ('John Snow', '[email protected]');---- A `Post` with the title `"There is a lot of snow around here!"`-INSERT INTO "Post" (title, content, createdBy) VALUES (- "There is a lot of snow around here!",- "Lorem ipsum dolar",- 1)+-- - A `Post` with the title `"There is a lot of snow around here!"`+insert into "Post" (title, content, createdBy)+values+ ('There is a lot of snow around here!', 'Lorem ipsum dolar', 1);---- Three `Post.Comment` from three different users.-INSERT INTO "User" (name, email) VALUES ("Stephanie Shadow", "[email protected]")-INSERT INTO "Comment" (text, userId, postId) VALUES ("I love cheese", 2, 1)+-- - Three `Post.Comment` from three different users.+insert into "User" (name, email) values ('Stephanie Shadow', '[email protected]');+insert into "Comment" (text, userId, postId) values ('I love cheese', 2, 1);-INSERT INTO "User" (name, email) VALUES ("John Rambo", "[email protected]")-INSERT INTO "Comment" (text, userId, postId) VALUES ("Lorem ipsum dolar sit", 3, 1)+insert into "User" (name, email) values ('John Rambo', '[email protected]');+insert into "Comment" (text, userId, postId) values ('Lorem ipsum dolar sit', 3, 1);-INSERT INTO "User" (name, email) VALUES ("Steven Plank", "[email protected]")-INSERT INTO "Comment" (text, userId, postId) VALUES ("Actually, that's not correct...", 4, 1)+insert into "User" (name, email) values ('Steven Plank', '[email protected]');+insert into "Comment" (text, userId, postId) values ('Actually, that''s not correct...', 4, 1);```Whenever your database structure changes, you will need to regenerate `@snaplet/seed` to keep it in sync with the new structure. You can do this by running:@@ -199,4 +204,4 @@ npx @snaplet/seed syncnpx tsx seed.ts > supabase/seed.sql```-For more information, check out Snaplet's [seed documentation](https://snaplet-seed.netlify.app/seed/integrations/supabase)+For more information, see the [Snaplet Seed repository](https://github.com/supabase-community/seed).diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.jsindex 9459f13b311..d43b2a315b5 100644--- a/apps/www/lib/redirects.js+++ b/apps/www/lib/redirects.js@@ -2904,7 +2904,12 @@ module.exports = [{permanent: true,source: '/docs/guides/cli/local-development',- destination: '/docs/guides/local-development/overview',+ destination: '/docs/guides/local-development/database-migrations',+ },+ {+ permanent: true,+ source: '/docs/guides/local-development/overview',+ destination: '/docs/guides/local-development/database-migrations',},{permanent: true,