mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 01:15:03 +03:00
e357ec8f9f
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. ## What is the current behavior? Linear: [CLI-1618](https://linear.app/supabase/issue/CLI-1618/update-cli-workflow-docs-for-pg-delta-default-diffing) Four docs pages lag the shipped CLI behavior now that `pg-delta` is the default diff engine for projects created by a recent `supabase init`: - **CLI workflows** claims `db diff` compares `supabase/schemas/` against migrations. Under `pg-delta`, declarative files are never the `db diff` baseline (and `[db.migrations].schema_paths` no longer changes it) — the declarative flow goes through `supabase db schema declarative sync`. The cleanup guidance describes `migra`-era output. - **Declarative database schemas** teaches the old `db diff -f` + `schema_paths` flow throughout, and its known-caveats list is the `migra` issue list. - **Managing environments** still presents `--use-migra` as an "experimental flag" for a "more concise" diff — inverted now. - **Backup and restore (migrating within Supabase)** and the CLI workflows guide both steer users to `db diff`/`db pull` with `--schema auth,storage`. Under `pg-delta`, `--schema` layers an extra exclude policy on top of the Supabase profile: it can only narrow a diff, never re-include managed schemas, and managed-schema selections can even fail closed (e.g. `--schema auth` when a trigger function lives in `public`). Unfiltered diffs are the supported path. ## What is the new behavior? All claims verified against the CLI source at current `develop` — including supabase/cli#6300, which upgraded the engine to `@supabase/pg-delta` 1.0.0-alpha.46 — against the pinned pg-delta package source (profile rules, format defaults, coverage doc), and against a live dogfood run of the documented workflows on `develop` `38f31b4` (two OSS corpus projects, warm shadow cache). - **`cli-workflows.mdx`**: adds a "Which diff engine you're on" note (`pg-delta` for new `supabase init` projects, `migra` for existing ones until they opt in by adding `[experimental.pgdelta] enabled = true`; per-run fallbacks `--use-migra` on `db diff` / `--diff-engine migra` on `db pull`); corrects `db pull` and `db diff` mechanics (shadow built from migrations vs. live database; the baseline history record is offered, not unconditional); switches the declarative flow to `supabase db schema declarative sync`; reworks the cleanup section around pg-delta output (uppercase keywords at max width 180, `format_options`, per-unit migration files with numeric segment suffixes, the `-- pg-delta: transaction=false` directive on genuinely non-transactional files, engine-neutral grant/revoke review guidance, coverage warnings + `--strict-coverage`); documents what pg-delta captures in managed schemas (user triggers, RLS policies on `auth` tables and on `storage.objects`/`storage.buckets`/`realtime.messages`) versus what it doesn't; adds key-command rows for the declarative commands and troubleshooting entries (`db pull` non-zero exit when in sync, the `schema_paths` warning, `PGDELTA_DEBUG=1` bundles under `supabase/.temp/pgdelta/v2/debug/`). - **`declarative-database-schemas.mdx`**: swaps `db diff -f` for `db schema declarative sync -f` throughout; replaces lexicographic/`schema_paths` ordering guidance with automatic dependency ordering and the `generate` export layout (`_cluster/`, reserved `_custom/`); bootstraps from production via `db schema declarative generate --linked` (explicit target + `--overwrite` in scripts) and refreshes via `db pull --declarative`; rewrites known caveats for pg-delta (DML including storage buckets, untracked object kinds + the `_custom/` escape hatch, managed schemas, extension-managed objects, and the two gates when adopting an existing schema tree: `[experimental.webhooks]` for `pg_net` migrations and declaring the tree's extensions) keeping the `migra` workflow and issue list under a legacy section for projects that haven't enabled it. - **`managing-environments.mdx`**: frames the verbose grant sample as legacy-engine output, notes that generated migrations can include grant statements on any engine, describes `--use-migra` as a single-run fallback, and adds a `db diff --strict-coverage` CI step. - **`backup-restore.mdx`**: replaces `db diff --linked --schema auth,storage` with a plain `db diff --linked` on `pg-delta` (keeping the `--schema auth,storage` form for the legacy engine) and explains what the engine includes (user triggers on managed tables, user RLS policies on `auth`, `storage.objects`/`storage.buckets`/`realtime.messages`) and what must be recreated manually. - **New `diff-engines.mdx` page** (from #49889): the single home for how the engine is selected, a behavior matrix for `pg-delta` versus `migra`, the per-command fallback flags, a procedure for switching an existing project (the first `db pull` after enabling may write a catch-up migration), and how to go back with `enabled = false`. Registered in navigation. A shared `diff_engine_check` partial replaces the inline engine parentheticals across seven pages, and a `managed_schemas_diff_capture` partial carries the managed-schema capture rules. - **CLI reference (`cli_v1_commands.yaml`, `cli_v1_config.yaml`)**: `db pull`, `db schema declarative sync`/`generate` flags and descriptions, `experimental.pgdelta.*` and `db.migrations.schema_paths` config keys, and the `db diff` description updated to describe both engines. Note that `cli_v1_commands.yaml` is generated from the CLI repo; [supabase/cli#6557](https://github.com/supabase/cli/pull/6557) carries the matching `db pull` example and overlay text so the next publish keeps it. - **`examples/prompts/declarative-database-schema.md`**: rewritten for the `db schema declarative sync` flow, with the `[experimental.pgdelta]` prerequisite. ## Additional context The first draft was written against pg-delta 1.0.0-alpha.42. supabase/cli#6300 (engine upgrade to alpha.46) then changed two documented behaviors, both reflected here: generated SQL now defaults to uppercase pretty-printed keywords, and user RLS policies on `storage.objects`/`storage.buckets`/`realtime.messages` are included via the engine's `SUPABASE_USER_POLICY_SURFACES` allowlist. A follow-up dogfood run on `develop` `38f31b4` then falsified three more claims (pg-delta emits no grant noise, `_schema_changes`/`_after_enum_values` multi-file names, directive on every split file), all corrected in the last commit. **Update (Sep 14 to 17):** [#49889](https://github.com/supabase/supabase/pull/49889) and [#50220](https://github.com/supabase/supabase/pull/50220) were merged into this branch, so this PR now carries the full stack. #50220 corrected the `schema_paths` warning wording (the CLI warns only when the setting lists paths), added `auth` RLS policies to the managed-schema partial, and described the migra initial pull accurately (the `pg_dump` skips managed schemas and the migra diff pass that follows appends the trigger and policy changes). It also reframed `pg-delta` as the default for every project ahead of supabase/cli#6391. That plan changed: no breaking default flip before Select, so [#50332](https://github.com/supabase/supabase/pull/50332) restores the opt-in framing (`pg-delta` requires `[experimental.pgdelta] enabled = true`, which `supabase init` writes for new projects) and also resolves the four CodeRabbit findings from the latest review round. Two claims are pending confirmation from the owning teams: that branching runs every migration in a transaction and ignores the `-- pg-delta: transaction=false` directive, and the `--db-url` pooler-versus-direct connection advice, which currently disagrees with the CLI's own `db pull` docs. Stale spots found in the CLI repo's own docs while verifying (out of scope here, worth follow-ups): four `SIDE_EFFECTS.md` files still claim lowercase output, `docs/supabase/db/diff.md` still lists `migra`-era "known failure cases" that alpha.46 fully models, the `supabase init` template's commented `format_options` example shows `maxWidth: 80` against an actual default of 180, and the CLI upgrade recipe appends `--experimental` even when the config already enables pg-delta. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01SUuaVmXLRbV6tZjzhka3cp <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified `pg-delta` and legacy `migra` behavior, configuration, and switching guidance. * Expanded declarative schema workflows, including synchronization, migration generation, baselines, deployment, and legacy-engine support. * Documented managed schemas, permissions, extensions, transaction handling, dependency ordering, and troubleshooting. * Added guidance for strict coverage checks, output directories, non-interactive workflows, and declarative pull modes. * Added a dedicated diff engines guide and updated CLI navigation, backup and restore, branching, deployment, and CI documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Wen Bo Xie <wenbox323@gmail.com>
161 lines
5.3 KiB
Plaintext
161 lines
5.3 KiB
Plaintext
---
|
|
title: Local Development & CLI
|
|
subtitle: Learn how to develop locally and use the Supabase CLI
|
|
---
|
|
|
|
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">
|
|
|
|
A container manager compatible with Docker APIs is a prerequisite:
|
|
|
|
- [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)
|
|
|
|
</Admonition>
|
|
|
|
## 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">
|
|
|
|
```sh
|
|
npm install supabase --save-dev
|
|
```
|
|
|
|
</TabPanel><TabPanel id="yarn" label="yarn">
|
|
|
|
```sh
|
|
NODE_OPTIONS=--no-experimental-fetch yarn add supabase --dev
|
|
```
|
|
|
|
</TabPanel><TabPanel id="pnpm" label="pnpm">
|
|
|
|
```sh
|
|
pnpm add supabase --save-dev --allow-build=supabase
|
|
```
|
|
|
|
<Admonition type="note">
|
|
|
|
The `--allow-build=supabase` flag is required on pnpm version 10 or higher. If you're using an older version of pnpm, omit this flag.
|
|
|
|
</Admonition>
|
|
|
|
</TabPanel><TabPanel id="brew" label="brew">
|
|
|
|
```sh
|
|
brew install supabase/tap/supabase
|
|
```
|
|
|
|
</TabPanel></Tabs>
|
|
|
|
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">
|
|
|
|
```sh
|
|
npx supabase init
|
|
```
|
|
|
|
</TabPanel><TabPanel id="yarn" label="yarn">
|
|
|
|
```sh
|
|
yarn supabase init
|
|
```
|
|
|
|
</TabPanel><TabPanel id="pnpm" label="pnpm">
|
|
|
|
```sh
|
|
pnpm supabase init
|
|
```
|
|
|
|
</TabPanel><TabPanel id="brew" label="brew">
|
|
|
|
```sh
|
|
supabase init
|
|
```
|
|
|
|
</TabPanel>
|
|
|
|
</Tabs>
|
|
|
|
3. Start the local Supabase stack:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">
|
|
|
|
```sh
|
|
npx supabase start
|
|
```
|
|
|
|
</TabPanel><TabPanel id="yarn" label="yarn">
|
|
|
|
```sh
|
|
yarn supabase start
|
|
```
|
|
|
|
</TabPanel><TabPanel id="pnpm" label="pnpm">
|
|
|
|
```sh
|
|
pnpm supabase start
|
|
```
|
|
|
|
</TabPanel><TabPanel id="brew" label="brew">
|
|
|
|
```sh
|
|
supabase start
|
|
```
|
|
|
|
</TabPanel>
|
|
|
|
</Tabs>
|
|
|
|
4. View your local Supabase instance at [http://localhost:54323](http://localhost:54323).
|
|
|
|
<Admonition type="caution">
|
|
|
|
If your local development machine is connected to an untrusted public network, you should create a separate Docker network and bind to 127.0.0.1 before starting the local development stack. This restricts network access to only your localhost machine.
|
|
|
|
```sh
|
|
docker network create -o 'com.docker.network.bridge.host_binding_ipv4=127.0.0.1' local-network
|
|
npx supabase start --network-id local-network
|
|
```
|
|
|
|
You should never expose your local development stack publicly.
|
|
|
|
</Admonition>
|
|
|
|
## Local development
|
|
|
|
Local development with Supabase allows you to work on your projects in a self-contained environment on your local machine. Working locally has several advantages:
|
|
|
|
1. Faster development: You can make changes and see results instantly without waiting for remote deployments.
|
|
2. 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. 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 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 schema
|
|
- Handling [database migrations](/docs/guides/local-development/database-migrations) and [declarative database schemas](/docs/guides/local-development/declarative-database-schemas)
|
|
- Managing environment variables and secrets
|
|
- Deploying your project to the Supabase platform
|
|
|
|
With the CLI, you can streamline your development workflow, automate repetitive tasks, and maintain consistency across different environments. It's an essential tool for both local development and CI/CD pipelines.
|
|
|
|
See the [CLI Getting Started guide](/docs/guides/local-development/cli/getting-started) for more information.
|