Supabase CLI

Bootstrap a Supabase project from a starter template.

1
supabase bootstrap [template] [flags]

Flags

• -p, --password <string>

  Optional

  Password to your remote Postgres database.

Initialize configurations for Supabase local development.

A supabase/config.toml file is created in your current working directory. This configuration is specific to each local project.

You may override the directory path by specifying the SUPABASE_WORKDIR environment variable or --workdir flag.

In addition to config.toml, the supabase directory may also contain other Supabase objects, such as migrations, functions, tests, etc.

To use OrioleDB as the Postgres storage engine, run supabase init --use-orioledb. The command writes the OrioleDB version to db.orioledb_version in supabase/config.toml; --experimental is not required.

1
supabase init [flags]

Flags

• --force

  Optional

  Write a fresh supabase/config.toml, replacing an existing config.toml and removing any config.json or config.jsonc.

• -i, --interactive

  Optional

  Enables interactive mode to configure IDE settings.

• --use-orioledb

  Optional

  Use OrioleDB storage engine for Postgres.

Connect the Supabase CLI to your Supabase account by logging in with your personal access token.

Your access token is stored securely in native credentials storage (the operating system keyring). If native credentials storage is unavailable, it will be written to a plain text file at <SUPABASE_HOME or ~/.supabase>/access-token.

If this behavior is not desired, such as in a CI environment, you may skip login by specifying the SUPABASE_ACCESS_TOKEN environment variable in other commands.

The Supabase CLI uses the stored token to access Management APIs for projects, functions, secrets, etc.

The Management API client retries retryable failures up to 5 times by default. Set SUPABASE_API_MAX_RETRIES to change that. It counts retries after the first attempt, so 0 sends each request once.

1
supabase login [flags]

Flags

• --name <string>

  Optional

  Name that will be used to store token in your settings.

• --no-browser

  Optional

  Do not open browser automatically.

• --token <string>

  Optional

  Use provided token instead of automatic login flow.

Log out and delete access tokens locally.

1
supabase logout [flags]

Show information about the currently logged-in user.

1
supabase whoami [flags]

Link your local development project to a hosted Supabase project. Pass the project ref, or the name of one of its branches, as the argument: supabase link <ref>. The --project-ref flag still works.

PostgREST configurations are fetched from the Supabase platform and validated against your local configuration file.

Optionally, database settings can be validated if you provide a password. Your database password is saved in native credentials storage if available.

If you do not want to be prompted for the database password, such as in a CI environment, you may specify it explicitly via the SUPABASE_DB_PASSWORD environment variable.

Passing --remote to commands like db dump, db push, and db pull targets the linked project, so it must be linked first.

1
supabase link [ref-or-branch] [flags]

Flags

• --project-ref <string>

  Optional

  Project ref of the Supabase project, or the name of one of its branches.

• --skip-pooler

  Optional

  Use direct connection instead of pooler.

Unlink a Supabase project.

1
supabase unlink [flags]

Refreshes local project state from a linked Supabase project or branch in one step, instead of running config pull, db pull, migration fetch, and functions download individually. It runs four steps, always in this order: pull config into supabase/config.toml, optionally fetch the remote migration history table into supabase/migrations, pull the database schema into supabase/migrations (also updating that database's own migration history table), and download every Edge Function's source into supabase/functions. The order is fixed rather than parallel: the database step depends on db.major_version in the config file the first step may have just changed, and on the local migration history the second step may have just populated.

Pass --remote=<ref|branch> to target a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target. --project-ref still works in v3 but is deprecated and removed in v4; use --remote. --remote-label overrides the [remotes.*] block the config step would otherwise reuse or create for that target, identically to config pull's own flag of the same name (see supabase config pull's docs for the reuse/creation rules it follows).

On a fresh checkout, the migration history step runs automatically even without --with-migration-history, whenever supabase/migrations is missing or a raw directory listing of it turns up no entries at all — the same "existing files" check migration fetch itself uses, so a directory holding only a .gitkeep/README.md already counts as non-empty for this purpose (the listing is unfiltered — any entry at all disqualifies it) and the two commands never disagree about it. There's nothing local to overwrite when the directory is truly empty or missing, and it's what lets the database step run at all: without it, db pull would hard-fail comparing an empty local directory against a remote project that already has migration history. Pass --with-migration-history to force a re-fetch whenever the directory already has any files in it, including only non-migration ones — unlike the bootstrap case, this DOES overwrite: any local migration file that shares a name with a remote history entry is replaced.

supabase pull prints the resolved target once (Target: … on stderr), then shows one confirmation before writing anything, covering all four steps. It opens by naming the target (Pulling from project <ref>, or with (branch "<name>") appended when the target is a branch), then lists the four steps in the order they run: the config step's part is a real diff, computed the same way config diff/config pull compute theirs (or "No config differences found." when there is nothing to change); the migration-history line only appears when that step will actually run this invocation, and calls out that it overwrites same-named local files when it's running because of --with-migration-history rather than the bootstrap case; the database line notes that it also updates the remote migration history table and requires Docker; the functions line describes the download. --dry-run prints this exact same disclosure body — not a placeholder or a status-only summary — before exiting without writing or changing anything.

Because the database step records the pulled migration in the remote migration history table, the confirmation is a hosted-mutation consent that defaults to No: Pull project state and update the remote migration history table on <target>?. Declining exits non-zero with context canceled and nothing is written. --yes, or SUPABASE_YES set in the shell environment, confirms it; a SUPABASE_YES in supabase/.env does not. --output-format json|stream-json and non-interactive runs cannot prompt, so they need --yes; an answer piped to stdin is ignored. --yes also lets the database connection remove a network ban that blocks the temporary login role; without it the step fails and suggests re-running with --yes, or running supabase network-bans remove --remote=<ref> for the project whose ban blocked the connection.

supabase pull checks THREE locations for uncommitted or untracked changes in git before writing: supabase/config.toml (or config.json), supabase/migrations, and supabase/functions. The config check only fires when the config step itself has work to write — a config that's already fully converged with the target never triggers it. The other two fire unconditionally: the database step always attempts to run and has no way to know in advance whether it will find schema drift and write into supabase/migrations, and the functions step always runs with no equivalent "nothing to do" signal available without calling the API first — so both are checked every run to avoid silently missing real uncommitted work. Each location's dirty state is tracked separately: the confirmation body and any abort message name exactly which path(s) are actually dirty, e.g. supabase/config.toml has uncommitted or untracked changes... for one, or supabase/config.toml, supabase/migrations, and supabase/functions have uncommitted or untracked changes... when all three are. --force writes even when any of the three is dirty — without it, an interactive run's confirmation body carries the warning, and every other case (non-interactive, machine output format, or --yes on any TTY) aborts outright rather than silently overwriting local edits.

This command is not purely a local, read-only refresh. Pulling the database schema also updates that database's own migration history table on the remote project — the same behavior db pull has always had — not just a local file write. The database step also requires Docker (it runs a shadow Postgres container, and — on the very first pull — a pg_dump container) to compute the schema diff. Without Docker running, that one step fails and is reported as such, but the other three steps (config, migration history, functions) still run and complete normally; a project with nothing in its database yet can still successfully pull its config and functions without Docker installed.

If the database is already in sync with the local migrations, that step reports unchanged rather than failing — this differs from running supabase db pull directly, which treats "nothing to pull" as an error condition.

Storage bucket definitions are not pulled by this command: the Management API doesn't currently return enough detail (file size limits, allowed MIME types, the storage backend path) to populate storage.buckets config faithfully.

Example

supabase pull

Pulls config, database schema, and functions from the linked project, fetching migration history first if supabase/migrations is empty.

supabase pull --remote=staging

Pulls from the staging branch of the linked project.

supabase pull --dry-run

Prints the full confirmation body — the target header, the real config diff (or "No config differences found."), the migration-history/database/functions lines (including the Docker mention and, if applicable, the uncommitted-changes warning) — without writing or changing anything.

supabase pull --remote-label staging

Pulls into the [remotes.staging] block instead of whatever block the target would otherwise reuse or create.

Machine-readable output is available through --output-format json|stream-json — a single object (schema_version, target, dry_run, confirmed, wrote, step_order, steps, counts) with one entry per step under steps, keyed config, migration_history, db, and functions, each carrying its own status (changed, unchanged, skipped, planned, or failed), the paths it wrote, and a step-specific detail object. target carries kind: "linked", project_ref, environment (production, branch, or unverified), project_name and parent_project_ref when known, and branch when --remote named one. The legacy global -o/--output flag is not supported by this command; use --output-format json|stream-json instead.

1
supabase pull [flags]

Flags

• --dry-run

  Optional

  Show what would be pulled without writing or changing anything.

• --force

  Optional

  Write even when the project config file, supabase/migrations, or supabase/functions has uncommitted or untracked changes in git.

• --remote[=<ref|branch>]

  Optional

  Target another project: --remote=<ref|branch>. Defaults to the linked project.

• --remote-label <string>

  Optional

  Name of the [remotes.*] block the config step writes into, overriding the block it would otherwise reuse or create.

• --with-migration-history

  Optional

  Fetch the remote migration history table into supabase/migrations, even when it already has files. Runs automatically when supabase/migrations is missing or empty.

Starts the Supabase local development stack.

Requires supabase/config.toml to be created in your current working directory by running supabase init.

All service containers are started by default. You can exclude those not needed by passing in -x flag. To exclude multiple containers, either pass in a comma separated string, such as -x gotrue,imgproxy, or specify -x flag multiple times.

It is recommended to have at least 7GB of RAM to start all services.

Health checks are automatically added to verify the started containers. Use --ignore-health-check flag to ignore these errors.

If the CLI is running inside a dev container with the Docker socket bind-mounted, set the SUPABASE_SERVICES_HOSTNAME environment variable to the hostname reachable from inside that container, such as host.docker.internal.

1
supabase start [flags]

Flags

• -x, --exclude <strings>

  Optional

  Names of containers to not start. [gotrue,realtime,storage-api,imgproxy,kong,mailpit,postgrest,postgres-meta,studio,edge-runtime,logflare,vector,supavisor]

• --ignore-health-check

  Optional

  Ignore unhealthy services and exit 0

Stops the Supabase local development stack.

Requires supabase/config.toml to be created in your current working directory by running supabase init.

All Docker resources are maintained across restarts. Use --no-backup flag to reset your local development data between restarts.

Use the --all flag to stop all local Supabase projects instances on the machine. Use with caution with --no-backup as it will delete all supabase local projects data.

1
supabase stop [flags]

Flags

• --all

  Optional

  Stop all local Supabase instances from all projects across the machine.

• --no-backup

  Optional

  Deletes all data volumes after stopping.

• --project-id <string>

  Optional

  Local project ID to stop.

Shows status of the Supabase local development stack.

Requires the local development stack to be started by running supabase start or supabase db start.

You can export the connection parameters for initializing supabase-js locally by specifying the -o env flag. Supported parameters include JWT_SECRET, ANON_KEY, and SERVICE_ROLE_KEY.

1
supabase status [flags]

Flags

• --override-name <strings>

  Optional

  Override specific variable names.

Run tests on local Supabase containers.

Subcommands

• supabase test db
• supabase test new

Executes pgTAP tests against a database.

Requires the local development stack to be started by running supabase start.

Runs against the local database by default. Pass --remote for the linked project, or --remote=<ref|branch|url> for another project, a branch of the linked project, or a database URL. The command prints a Target: line on stderr naming the database it resolved.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Running the tests enables the pgTAP extension and drops it again afterwards, so a hosted database (the linked project or a remote database URL) asks for one confirmation (default No) before anything runs. Piped answers are never read, so a script, a JSON run or an agent must pass --yes or set SUPABASE_YES in the shell; a SUPABASE_YES in supabase/.env does not count. The local database never asks.

Runs pg_prove in a container with unit test files volume mounted from supabase/tests directory. The test file can be suffixed by either .sql or .pg extension.

Since each test is wrapped in its own transaction, it will be individually rolled back regardless of success or failure.

1
supabase test db [path] ... [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Create a new test file.

1
supabase test new <name> [flags]

Flags

• -t, --template <[ pgtap ]>

  Optional

  Template framework to generate.

Automatically generates type definitions based on your Postgres database schema.

This command connects to your database and generates typed definitions that match your database tables, views, and stored procedures. It reads the local database unless you pass --remote for the linked project, or --remote=<ref|branch|url> for another project, a branch of the linked project, or a database URL. By default, it generates TypeScript definitions, but also supports Go and Swift.

Generated types give you type safety and autocompletion when working with your database in code, helping prevent runtime errors and improving developer experience.

The types respect relationships, constraints, and custom types defined in your database schema.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote. --project-id is also deprecated; use --remote=<ref>.

Subcommands

• supabase gen bearer-jwt
• supabase gen signing-key
• supabase gen types

Securely generate a private JWT signing key for use in the CLI or to import in the dashboard.

Supported algorithms: ES256 - ECDSA with P-256 curve and SHA-256 (recommended) RS256 - RSA with SHA-256

1
supabase gen signing-key [flags]

Flags

• --algorithm <[ ES256 | RS256 ]>

  Optional

  Algorithm for signing key generation.

• --append

  Optional

  Append new key to existing keys file instead of overwriting.

Generate types from Postgres schema.

1
supabase gen types [flags]

Flags

• --lang <[ typescript | go | python | swift | dart ]>

  Optional

  Output language of the generated types. (default typescript)

• --query-timeout <string>

  Optional

  Maximum timeout allowed for the database query. (default 15s)

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

• --swift-access-control <[ internal | public ]>

  Optional

  Access control for Swift generated types. (default internal)

Generate a Bearer Auth JWT for accessing Data API

1
supabase gen bearer-jwt [flags]

Flags

• --exp <string>

  Optional

  Expiry timestamp for this token.

• --payload <string>

  Optional

  Custom claims in JSON format.

• --role <string>

  Required

  Postgres role to use.

• --sub <string>

  Optional

  User ID to impersonate.

• --valid-for <string>

  Optional

  Validity duration for this token.

Manage Postgres databases.

Subcommands

• supabase db advisors
• supabase db diff
• supabase db dump
• supabase db lint
• supabase db pull
• supabase db push
• supabase db query
• supabase db reset
• supabase db schema
• supabase db start

Pulls schema changes from a database. A new migration file will be created under supabase/migrations directory.

Pulls from the local database by default. Pass --remote to pull from the linked project, which requires your local project to be linked by running supabase link. Pass --remote=<ref|branch|url> to pull from another project, a branch of the linked project, or a database URL such as a self-hosted database. In a linked checkout, a run without --remote prints a hint naming the linked project. The command prints a Target: line on stderr naming the database it resolved.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Note this command requires Docker Desktop (or a running Docker daemon), as it starts a local Postgres container to diff the schema you pull.

After the migration file is written, a new row is inserted into the migration history table to reflect the current state of the database. A hosted database asks for one confirmation first (default No), after the diff and before any file is written; declining stops the command without writing anything. Non-interactive, JSON and agent runs need --yes (or SUPABASE_YES in the shell environment, not in supabase/.env). A pull from the local database and --declarative ask nothing.

If no entries exist in the migration history table, pg-delta (the default diff engine) produces the full migration from the shadow diff alone; with --diff-engine migra, the initial pull instead uses pg_dump to capture all contents of the schemas you have created. Otherwise, this command will only diff schema changes against the target database, similar to running db diff --remote.

Pass --declarative to switch to the declarative pg-delta export workflow instead of writing a migration file. The tree lives in supabase/schemas by default. Change the location with experimental.pgdelta.declarative_schema_path.

On a project that falls back to the legacy migra engine, don't use --declarative. The export also points [db.migrations].schema_paths at the tree it writes. The next local db diff applies those files in lexicographic order without resolving dependencies between them, so it fails when a file sorts before an object it depends on. If you've already run it, re-enable pg-delta, or undo both changes:

1. Delete the files the export wrote to the declarative directory (supabase/schemas/ by default). Files that were already there are left in place.
2. Restore [db.migrations].schema_paths in config.toml to its previous value, or remove it if the export added it.

pg-delta plans are execution-aware: when a plan crosses a transaction boundary — for example ALTER TYPE ... ADD VALUE followed by a statement that uses the new enum value, which cannot run in the same transaction — db pull writes one ordered migration file per plan unit instead of a single file (for example <ts>_remote_schema_1.sql and <ts+1s>_remote_schema_2.sql), each recorded in the migration history. Units whose statements cannot run inside a transaction start with a -- pg-delta: transaction=false directive that the CLI apply paths honor. The common case (a single unit) still produces exactly one <ts>_remote_schema.sql file.

By default the emitted SQL is formatted with the same settings the declarative export uses (uppercase keywords, wrapped at a max width of 180, indented and column-aligned). Configure overrides with [experimental.pgdelta] format_options in config.toml, or set format_options = "null" to opt out and emit raw, unformatted statements.

pg-delta is the default diff engine: the migration-file db pull workflow uses pg-delta for the shadow diff step unless configured otherwise; it does not switch to declarative output. With pg-delta, [db.migrations] schema_paths does not affect this workflow (migra still reads it, for local targets only); use supabase db schema declarative sync for declarative schema files. To fall back to the legacy migra engine, set enabled = false under [experimental.pgdelta] in config.toml, or pass --diff-engine migra for a single run.

When pulling with --remote=<url>, prefer a direct connection (db.<project-ref>.supabase.co:5432) over the connection pooler so pg-delta can introspect the full catalog reliably.

Under the pg-delta engine, a plain db pull captures your own customizations in Supabase-managed schemas: triggers on managed tables whose function lives outside the managed schemas (for example a trigger on auth.users calling a function in public), RLS policies on any auth table, and RLS policies on storage.objects, storage.buckets, and realtime.messages. Other objects you create inside managed schemas, such as your own functions or indexes, are not diffed. On later pulls, --schema restricts the diff to the listed schemas, so a customization in auth is only captured when auth is listed or --schema is omitted; the initial pull ignores --schema. Under the legacy migra engine, the initial pull's pg_dump skips the managed schemas, and the migra diff pass that follows appends your trigger and RLS policy changes there to the same migration file. If an older CLI reports that auth and storage were excluded, capture existing customizations there with --schema auth,storage.

Debugging empty pg-delta pulls

If db pull reports No schema changes found but you expect schema output, set PGDELTA_DEBUG=1 before running the command. Unlike --debug, this keeps SSL enabled for hosted Supabase connections.

PGDELTA_DEBUG=1 supabase db pull --remote="$DATABASE_URL"

When pg-delta returns zero statements, the CLI writes a debug bundle under supabase/.temp/pgdelta/v2/debug/<timestamp>-diff/ containing the source/desired catalog snapshots, the plan, and coverage diagnostics. Catalog files are not written during normal db pull runs.

For TLS tracing without disabling SSL, use SUPABASE_SSL_DEBUG=true alongside PGDELTA_DEBUG=1.

1
supabase db pull [migration name] [flags]

Flags

• --declarative

  Optional

  Replace the declarative schema tree from the selected database instead of creating a migration; migration history is not updated.

• --diff-engine <[ migra | pg-delta ]>

  Optional

  Diff engine to use for migration-style db pull.

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

• --strict-coverage

  Optional

  Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.

Pushes all local migrations to a database.

Pushes to the local database by default. Pass --remote to push to the linked project, which requires your local project to be linked by running supabase link. Pass --remote=<ref|branch|url> to push to another project, a branch of the linked project, or a database URL such as a self-hosted database. In a linked checkout, a run without --remote prints a hint naming the linked project. The command prints a Target: line on stderr naming the database it resolved.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Before changing a hosted database, the command lists what it will do (migrations, custom roles, seed files and vault secrets) and asks once for confirmation, defaulting to No. Pass --yes to confirm without a prompt; JSON output, piped input and agent runs need it. A SUPABASE_YES set in supabase/.env does not confirm, but one set in your shell does.

The first time this command is run, a migration history table will be created under supabase_migrations.schema_migrations. After successfully applying a migration, a new row will be inserted into the migration history table with timestamp as its unique id. Subsequent pushes will skip migrations that have already been applied.

If you need to mutate the migration history table, such as deleting existing entries or inserting new entries without actually running the migration, use the migration repair command.

Use the --dry-run flag to view the list of changes before applying.

1
supabase db push [flags]

Flags

• --dry-run

  Optional

  Print the migrations that would be applied, but don't actually apply them.

• --include-all

  Optional

  Include all migrations not found in the migration history table.

• --include-roles

  Optional

  Include custom roles from supabase/roles.sql.

• --include-seed

  Optional

  Include seed data from your config.

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --skip-vault

  Optional

  Skip updating vault secrets from the config file.

Resets a database to a clean state.

Requires the local development stack to be started by running supabase start.

Recreates the local Postgres container and applies all local migrations found in supabase/migrations directory. If test data is defined in supabase/seed.sql, it will be seeded after the migrations are run. Any other data or schema changes made during local development will be discarded.

Use the --no-seed flag to skip seeding entirely. To override [db.seed].sql_paths for a single reset, pass one or more --sql-paths flags. Each value accepts the same file path or glob pattern syntax as sql_paths, relative to the supabase directory. Passing --sql-paths force-enables seeding for that reset even when [db.seed].enabled = false.

Resets the local database by default. Pass --remote to reset the linked project, or --remote=<ref|branch|url> to reset another project, a branch of the linked project, or a database URL. The command prints a Target: line on stderr naming the database it resolved.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

When running db reset with --remote, a SQL script is executed to identify and drop all user created entities in the remote database. Since Postgres roles are cluster level entities, any custom roles created through the dashboard or supabase/roles.sql will not be deleted by remote reset.

A remote reset asks for one confirmation (default No) after it has worked out what it will do and before anything is dropped. The question lists dropping every user schema, any vault secrets it will upsert, the migrations or schema files it will apply, and the seed files it will run. Declining stops the command without changing the database. Piped answers are never read, so a script, a JSON run or an agent must pass --yes or set SUPABASE_YES in the shell; a SUPABASE_YES in supabase/.env does not count. The local database never asks.

If you combine --sql-paths with --remote, the override seed files are applied to the selected remote database after migrations. Use this only when you intend to seed that remote target.

1
supabase db reset [flags]

Flags

• --last <int>

  Optional

  Reset up to the last n migration versions.

• --no-seed

  Optional

  Skip running the seed script after reset.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --sql-paths <strings>

  Optional

  Override db.seed.sql_paths for this reset. May be repeated; each value accepts a SQL file path or glob pattern relative to the supabase directory and force-enables seeding.

• --version <string>

  Optional

  Reset up to the specified version.

Dumps contents from a database.

Dumps the local database by default. Pass --remote to dump the linked project, which requires your local project to be linked by running supabase link. Pass --remote=<ref|branch|url> to dump another project, a branch of the linked project, or a database URL such as a self-hosted database. The command prints a Target: line on stderr naming the database it resolved, and never asks for confirmation.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Runs pg_dump in a container with additional flags to exclude Supabase managed schemas. The ignored schemas include auth, storage, and those created by extensions.

The default dump does not contain any data or custom roles. To dump those contents explicitly, specify either the --data-only and --role-only flag.

Note on Privilege Migration

When restoring to a new project, tables inherit ALL privileges from default privileges in the target database. To preserve specific privileges from your dump, revoke defaults before restoring:

-- Run BEFORE restoring your schema
ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON TABLES FROM anon, authenticated;

1
supabase db dump [flags]

Flags

• --data-only

  Optional

  Dumps only data records.

• --dry-run

  Optional

  Prints the pg_dump script that would be executed.

• -x, --exclude <strings>

  Optional

  List of schema.tables to exclude from data-only dump.

• -f, --file <string>

  Optional

  File path to save the dumped contents.

• --keep-comments

  Optional

  Keeps commented lines from pg_dump output.

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --role-only

  Optional

  Dumps only cluster roles.

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

• --use-copy

  Optional

  Use copy statements in place of inserts.

Diffs schema changes made to a database.

Diffs the local database by default, which requires the local development stack to be running. Pass --remote to diff the linked project, or --remote=<ref|branch|url> to diff another project, a branch of the linked project, or a database URL such as a self-hosted database. The command prints a Target: line on stderr naming the database it resolved, and never asks for confirmation.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Compares schema differences between the target database and a shadow database, using the bundled pg-delta engine by default. The legacy djrobstep/migra engine, which runs in a container, remains available as a fallback (see below). The shadow database is created by applying migrations in local supabase/migrations directory in a separate container. Output is written to stdout by default. For convenience, you can also save the schema diff as a new migration file by passing in -f flag.

In --from/--to, remote means the linked project; passing --remote together with --from or --to is an error. The deprecated aliases still work there and warn: --project-ref points a remote side at the project it names, and the rest change nothing. Explicit --from/--to mode always uses pg-delta. In this mode, -f is ignored and stdout (or --output) is a flattened representation for review, not a portable apply script. Do not apply it directly with plain psql -f: transactional units can contain SET LOCAL preambles that only take effect inside a transaction, while plans that mix transactional and non-transactional units cannot safely be wrapped in one transaction. To create an applicable migration, use normal target mode with supabase db diff -f <name>, then apply it through supabase db reset locally or supabase db push --remote against the linked project. These paths preserve the plan's per-unit transaction semantics.

By default, all schemas in the target database are diffed. Use the --schema public,extensions flag to restrict diffing to a subset of schemas.

pg-delta is the default diff engine for all projects. To fall back to the legacy migra engine, set enabled = false under [experimental.pgdelta] in config.toml, or pass --use-migra for a single run.

When migra diffs the local database and declarative schema files exist, it diffs against those files instead of the live database, choosing them in this order: [db.migrations] schema_paths when set; otherwise the declarative_schema_path directory while [experimental.pgdelta] enabled is true (so with --use-migra and the default config); otherwise supabase/schemas. Setting enabled = false therefore makes migra skip a custom declarative_schema_path and fall back to supabase/schemas.

With pg-delta, [db.migrations] schema_paths and declarative schema files (such as supabase/schemas) are not inputs: db diff always compares local migrations with the selected database. db diff -f prints a note, with next steps, when it finds declarative files it did not read. To generate a migration from declarative schema files, use supabase db schema declarative sync.

With the bundled pg-delta engine, diff SQL defaults to uppercase keywords, indent 2, a maximum width of 180, trailing commas, and column/key alignment, matching its declarative export. When -f writes migrations, execution-aware transaction semantics are preserved as ordered per-unit files; non-transactional units carry a directive that the CLI apply path honors. Flattened review output retains the rendered SQL and preambles, but not the unit boundaries supplied to a migration runner. Configure overrides with [experimental.pgdelta] format_options, or set format_options = "null" to emit raw, unformatted statements.

Storage buckets are data, not schema, so no diff engine captures them. Under the legacy migra engine, the diff can also miss:

• Changes to publication
• Views with security_invoker attributes

1
supabase db diff [flags]

Flags

• -f, --file <string>

  Optional

  In normal mode, names and saves the complete schema diff as a new migration; it does not filter objects. Ignored with --from/--to.

• --from <string>

  Optional

  Diff from local, migrations, remote (always the linked project), a project ref, a branch, or a Postgres URL.

• -o, --output <string>

  Optional

  Write flattened explicit diff SQL to a file for review; this is not a portable apply script.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

• --strict-coverage

  Optional

  Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.

• --to <string>

  Optional

  Diff to local, migrations, remote (always the linked project), a project ref, a branch, or a Postgres URL.

• --use-migra

  Optional

  Use migra to generate schema diff.

• --use-pg-delta

  Optional

  Use pg-delta to generate schema diff.

• --use-pgadmin

  Optional

  Use pgAdmin to generate schema diff.

Lints a database for schema errors.

Lints the local database by default, which requires the local development stack to be running. Pass --remote to lint the linked project, or --remote=<ref|branch|url> to lint another project, a branch of the linked project, or a database URL such as a self-hosted database. The command prints a Target: line on stderr naming the database it resolved, and never asks for confirmation.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Runs the plpgsql_check extension against the local database (native or container) to check for errors in all schemas. The default lint level is warning and can be raised to error via the --level flag.

To lint against specific schemas only, pass in the --schema flag.

The --fail-on flag can be used to control when the command should exit with a non-zero status code. The possible values are:

• none (default): Always exit with a zero status code, regardless of lint results.
• warning: Exit with a non-zero status code if any warnings or errors are found.
• error: Exit with a non-zero status code only if errors are found.

This flag is particularly useful in CI/CD pipelines where you want to fail the build based on certain lint conditions.

1
supabase db lint [flags]

Flags

• --fail-on <[ none | warning | error ]>

  Optional

  Error level to exit with non-zero status.

• --level <[ warning | error ]>

  Optional

  Error level to emit.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

Inspects the database for common security and performance issues such as missing RLS policies, unindexed foreign keys, exposed auth.users, and more.

Inspects the local database by default. Pass --remote for the linked project, or --remote=<ref|branch|url> for another project, a branch of the linked project, or a database URL. The command prints a Target: line on stderr naming the database it resolved, and never asks for confirmation.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

1
supabase db advisors [flags]

Flags

• --fail-on <[ none | info | warn | error ]>

  Optional

  Issue level to exit with non-zero status: none, info, warn, error.

• --level <[ info | warn | error ]>

  Optional

  Minimum issue level to display: info, warn, error.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --type <[ all | security | performance ]>

  Optional

  Type of advisors to check: all, security, performance.

Execute a SQL query against a database.

Runs against the local database by default. Pass --remote for the linked project, or --remote=<ref|branch|url> for another project, a branch of the linked project, or a database URL. The command prints a Target: line on stderr naming the database it resolved.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

The command cannot tell a read from a write, so a hosted database (the linked project or a remote database URL) asks for one confirmation (default No) before the statement is sent. Piped answers are never read, so a script, a JSON run or an agent must pass --yes or set SUPABASE_YES in the shell; a SUPABASE_YES in supabase/.env does not count. The local database never asks.

Pass --read-only to run a statement that must not change anything. It skips the confirmation on a hosted database. Before the statement is sent or any question is asked, every statement must start with SELECT, WITH, VALUES, TABLE, SHOW, EXPLAIN or a parenthesised query (after whitespace and comments). Any other statement (COMMIT, SET, CALL, DO, COPY, LOCK and so on), input that ends inside a comment, quote or dollar quote, and input that contains a BEGIN ATOMIC function body is rejected. The words begin atomic inside a string, quoted identifier, dollar quote or comment, as in select 'begin atomic', are not. Drop --read-only to run one of these.

The local database or a database URL then runs the statement in a read-only transaction that is always rolled back, with a 5 second lock_timeout so the read cannot wait on heavy locks; Postgres rejects writes inside it. A linked project runs it through the Management API's read_only mode, and the API enforces it.

--read-only does not stop a read statement from calling a function that has side effects, such as pg_terminate_backend or dblink_exec; those still run.

When used by an AI coding agent (auto-detected or via --agent=yes), the default output format is JSON with an untrusted data warning envelope. When used by a human (--agent=no or no agent detected), the default output format is table without the envelope.

1
supabase db query [sql] [flags]

Flags

• -f, --file <string>

  Optional

  Path to a SQL file to execute.

• -o, --output <[ json | table | csv ]>

  Optional

  Output format: table, json, or csv.

• --read-only

  Optional

  Runs the statement in a read-only transaction; a hosted target needs no confirmation.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Starts local Postgres database.

1
supabase db start [flags]

Flags

• --from-backup <string>

  Optional

  Path to a logical backup file.

Manage database schema.

Subcommands

• supabase db schema declarative

Manage declarative database schemas.

Subcommands

• supabase db schema declarative generate
• supabase db schema declarative sync

Generate a new migration by diffing your declarative schema files against the current migration state.

When no declarative schema exists yet, the command offers to run generate first, exporting from the local database. To start from a linked project or a database URL, run generate --remote or generate --remote=<url> yourself first. After computing the diff, you can optionally name the migration and apply it to the local database.

Enabled by default. When [experimental.pgdelta] enabled = false is set in config, pass the --experimental flag to run it.

1
supabase db schema declarative sync [flags]

Flags

• --apply

  Optional

  Apply the generated migration to the local database without prompting.

• -f, --file <string>

  Optional

  Saves schema diff to a new migration file.

• --name <string>

  Optional

  Name for the generated migration file.

• --no-apply

  Optional

  Generate the migration file without prompting or applying it to the local database.

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

• --experimental

  Optional

  enable experimental features

• --no-cache

  Optional

  Disable catalog cache and force fresh shadow database setup.

• --strict-coverage

  Optional

  Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.

Generate declarative schema files from a database.

Exports the schema of a live database into SQL files under the declarative schema directory. This is the entrypoint for bootstrapping declarative mode.

The database is the local one unless you pass --remote for the linked project, or --remote=<ref|branch|url> for another project, a branch of the linked project, or a database URL. The command never asks which database to use. With the local database, --reset recreates it from your migrations first. When the destination already holds files, the command asks before overwriting them (pass --overwrite or --yes to skip the question).

The bundled pg-delta engine writes one directory per schema at the root of that directory (supabase/schemas/public/tables/users.sql, supabase/schemas/public/schema.sql), with cluster-level objects that belong to no schema under a reserved _cluster/ directory (supabase/schemas/_cluster/roles.sql). When platform default grants (anon/authenticated/service_role) need an overlay REVOKE ALL, the export writes adp_wipes.sql after schema.sql in that schema — or _cluster/adp_wipes.sql for cluster-wide overlays — so a load onto a fresh project keeps privileges that were revoked in the source. A schema literally named _cluster or _custom, in any casing, has its leading underscore percent-encoded (%5Fcluster/) so it can never claim a directory the export owns. Hand-authored SQL that pg-delta does not model belongs in _custom/, which the export never writes to and never prunes.

Emitted SQL uses the same default format as db pull (uppercase keywords, indent 2, width 180, column-aligned). Override with [experimental.pgdelta] format_options, or set format_options = "null" for raw statements.

Enabled by default. When [experimental.pgdelta] enabled = false is set in config, pass the --experimental flag to run it.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

1
supabase db schema declarative generate [flags]

Flags

• --output-dir <string>

  Optional

  Write the generated declarative schema to this directory without changing the configured declarative schema path.

• --overwrite

  Optional

  Overwrite declarative schema files without confirmation.

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --reset

  Optional

  Reset local database before generating (local data will be lost).

• -s, --schema <strings>

  Optional

  Comma separated list of schema to include.

• --experimental

  Optional

  enable experimental features

• --no-cache

  Optional

  Disable catalog cache and force fresh shadow database setup.

• --strict-coverage

  Optional

  Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.

Manage database migration scripts.

Subcommands

• supabase migration down
• supabase migration fetch
• supabase migration list
• supabase migration new
• supabase migration repair
• supabase migration squash
• supabase migration up

Creates a new migration file locally.

A supabase/migrations directory will be created if it does not already exists in your current workdir. All schema migration files must be created in this directory following the pattern <timestamp>_<name>.sql.

Outputs from other commands like db diff may be piped to migration new <name> via stdin.

1
supabase migration new <migration name> [flags]

Lists the migration files in supabase/migrations next to the migration history of the target database.

By default, it lists the migration history of your local database. Pass --remote to list the linked project instead, which requires running supabase link. Pass --remote=<ref|branch|url> to list another project, a branch of the linked project, or a database URL such as a self-hosted database.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

Note that URL strings must be escaped according to RFC 3986.

Local migrations are stored in supabase/migrations directory while the target database tracks applied migrations in the supabase_migrations.schema_migrations table. The second column is headed Remote for a project or database URL passed with --remote, and Local DB for the local database. Only the timestamps are compared to identify any differences.

In case of discrepancies between the local and remote migration history, you can resolve them using the migration repair command.

1
supabase migration list [flags]

Flags

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Fetch migration files from history table.

1
supabase migration fetch [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Repairs the migration history table.

By default, it repairs your local database. Pass --remote to repair the linked project, which requires running supabase link. Pass --remote=<ref|branch|url> to repair another project, a branch of the linked project, or a specific database. Repairing a hosted database asks for confirmation before it changes anything (the default answer is No); pass --yes to confirm in scripts and other non-interactive runs.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

If your local and remote migration history goes out of sync, you can repair the remote history by marking specific migrations as --status applied or --status reverted. Marking as reverted will delete an existing record from the migration history table while marking as applied will insert a new record.

For example, your migration history may look like the table below, with missing entries in either local or remote.

$ supabase migration list --remote
Target: project My Project (abcdefghijklmnopqrst) · production
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────
                   │ 20230103054303 │ 2023-01-03 05:43:03
   20230103054315  │                │ 2023-01-03 05:43:15

To reset your migration history to a clean state, first delete your local migration file.

$ rm supabase/migrations/20230103054315_remote_commit.sql

$ supabase migration list --remote
Target: project My Project (abcdefghijklmnopqrst) · production
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────
                   │ 20230103054303 │ 2023-01-03 05:43:03

Then mark the remote migration 20230103054303 as reverted.

$ supabase migration repair 20230103054303 --status reverted --remote
Target: project My Project (abcdefghijklmnopqrst) · production
 • 20230103054303
◇  Mark 1 migration as reverted on project My Project (abcdefghijklmnopqrst) · production?
│  Yes
Repaired migration history: [20230103054303] => reverted
Finished supabase migration repair.

$ supabase migration list --remote
Target: project My Project (abcdefghijklmnopqrst) · production
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────

Now you can run db pull again to dump the remote schema as a local migration file.

$ supabase db pull --remote
Target: project My Project (abcdefghijklmnopqrst) · production
Write 1 migration file to supabase/migrations.
Record them as applied in the remote migration history.
◇  Update the remote migration history table on project My Project (abcdefghijklmnopqrst) · production?
│  Yes
Schema written to supabase/migrations/20240414044403_remote_schema.sql
Finished supabase db pull.

$ supabase migration list --remote
Target: project My Project (abcdefghijklmnopqrst) · production
        LOCAL      │     REMOTE     │     TIME (UTC)
  ─────────────────┼────────────────┼──────────────────────
    20240414044403 │ 20240414044403 │ 2024-04-14 04:44:03

1
supabase migration repair [version] ... [flags]

Flags

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --status <[ applied | reverted ]>

  Required

  Version status to update.

Squashes local schema migrations to a single migration file.

The squashed migration is equivalent to a schema only dump of the local database after applying existing migration files. This is especially useful when you want to remove repeated modifications of the same schema from your migration history.

However, one limitation is that data manipulation statements, such as insert, update, or delete, are omitted from the squashed migration. You will have to add them back manually in a new migration file. This includes cron jobs, storage buckets, and any encrypted secrets in vault.

By default, the latest <timestamp>_<name>.sql file will be updated to contain the squashed migration. You can override the target version using the --version <timestamp> flag.

If your supabase/migrations directory is empty, running supabase squash will do nothing.

Squashing rewrites your local migration files. When the target is a hosted database (--remote or --remote=<ref|branch|url>), it also resets the remote migration history table to the squashed migration. That asks for confirmation before any file is changed (the default answer is No); pass --yes to confirm in scripts and other non-interactive runs. With the default local target it only squashes the files and suggests running supabase migration repair --status applied --remote for the remote history.

--linked, --project-ref, --db-url and --local still work in v3 but are deprecated and removed in v4; use --remote.

1
supabase migration squash [flags]

Flags

• -p, --password <string>

  Optional

  Database password for the project selected with --remote. Not used for the local database or a database URL.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

• --version <string>

  Optional

  Squash up to the specified version.

Apply pending migrations to a database.

1
supabase migration up [flags]

Flags

• --include-all

  Optional

  Include all migrations not found in the migration history table.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Resets applied migrations up to the last n versions.

1
supabase migration down [flags]

Flags

• --last <int>

  Optional

  Reset up to the last n migration versions.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Seed a Supabase project from its config file.

Subcommands

• supabase seed buckets

Seed buckets declared in storage.buckets.

1
supabase seed buckets [flags]

Flags

• --remote[=<ref|branch>]

  Optional

  Target a remote Storage API: the linked project, or --remote=<ref|branch>.

Tools to inspect your Supabase project.

Subcommands

• supabase inspect db
• supabase inspect report

Tools to inspect your Supabase database. They inspect the local database by default; pass --remote for the linked project, or --remote=<ref|branch|url> for another database.

Subcommands

• supabase inspect db bloat
• supabase inspect db blocking
• supabase inspect db calls
• supabase inspect db collation-drift
• supabase inspect db db-stats
• supabase inspect db index-stats
• supabase inspect db locks
• supabase inspect db long-running-queries
• supabase inspect db outliers
• supabase inspect db replication-slots
• supabase inspect db role-stats
• supabase inspect db table-stats
• supabase inspect db toast-sizes
• supabase inspect db traffic-profile
• supabase inspect db vacuum-stats
• supabase inspect db xid-age

This command displays an estimation of table "bloat" - Due to Postgres' MVCC when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the autovaccum process will asynchronously clean the dead tuples. Sometimes the autovaccum is unable to work fast enough to reduce or prevent tables from becoming bloated. High bloat can slow down queries, cause excessive IOPS and waste space in your database.

Tables with a high bloat ratio should be investigated to see if there are vacuuming is not quick enough or there are other issues.

    TYPE  │ SCHEMA NAME │        OBJECT NAME         │ BLOAT │ WASTE
  ────────┼─────────────┼────────────────────────────┼───────┼─────────────
    table │ public      │ very_bloated_table         │  41.0 │ 700 MB
    table │ public      │ my_table                   │   4.0 │ 76 MB
    table │ public      │ happy_table                │   1.0 │ 1472 kB
    index │ public      │ happy_table::my_nice_index │   0.7 │ 880 kB

1
supabase inspect db bloat [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command shows you statements that are currently holding locks and blocking, as well as the statement that is being blocked. This can be used in conjunction with inspect db locks to determine which statements need to be terminated in order to resolve lock contention.

    BLOCKED PID │ BLOCKING STATEMENT           │ BLOCKING DURATION │ BLOCKING PID │ BLOCKED STATEMENT                                                                      │ BLOCKED DURATION
  ──────────────┼──────────────────────────────┼───────────────────┼──────────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────
    253         │ select count(*) from mytable │ 00:00:03.838314   │        13495 │ UPDATE "mytable" SET "updated_at" = '2023─08─03 14:07:04.746688' WHERE "id" = 83719341 │ 00:00:03.821826

1
supabase inspect db blocking [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command is much like the supabase inspect db outliers command, but ordered by the number of times a statement has been called.

You can use this information to see which queries are called most often, which can potentially be good candidates for optimisation.

                        QUERY                      │ TOTAL EXECUTION TIME │ PROPORTION OF TOTAL EXEC TIME │ NUMBER CALLS │  SYNC IO TIME
  ─────────────────────────────────────────────────┼──────────────────────┼───────────────────────────────┼──────────────┼──────────────────
    SELECT * FROM users WHERE id = $1              │ 14:50:11.828939      │ 89.8%                         │  183,389,757 │ 00:00:00.002018
    SELECT * FROM user_events                      │ 01:20:23.466633      │ 1.4%                          │       78,325 │ 00:00:00
    INSERT INTO users (email, name) VALUES ($1, $2)│ 00:40:11.616882      │ 0.8%                          │       54,003 │ 00:00:00.000322

1
supabase inspect db calls [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Show stats such as cache hit rates, total sizes, and WAL size.

1
supabase inspect db db-stats [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Show combined index size, usage percent, scan counts, and unused status.

1
supabase inspect db index-stats [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command displays queries that have taken out an exclusive lock on a relation. Exclusive locks typically prevent other operations on that relation from taking place, and can be a cause of "hung" queries that are waiting for a lock to be granted.

If you see a query that is hanging for a very long time or causing blocking issues you may consider killing the query by connecting to the database and running SELECT pg_cancel_backend(PID); to cancel the query. If the query still does not stop you can force a hard stop by running SELECT pg_terminate_backend(PID);

     PID   │ RELNAME │ TRANSACTION ID │ GRANTED │                  QUERY                  │   AGE
  ─────────┼─────────┼────────────────┼─────────┼─────────────────────────────────────────┼───────────
    328112 │ null    │              0 │ t       │ SELECT * FROM logs;                     │ 00:04:20

1
supabase inspect db locks [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command displays currently running queries, that have been running for longer than 5 minutes, descending by duration. Very long running queries can be a source of multiple issues, such as preventing DDL statements completing or vacuum being unable to update relfrozenxid.

  PID  │     DURATION    │                                         QUERY
───────┼─────────────────┼───────────────────────────────────────────────────────────────────────────────────────
 19578 | 02:29:11.200129 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1450645 LIMIT 1
 19465 | 02:26:05.542653 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1889881 LIMIT 1
 19632 | 02:24:46.962818 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1581884 LIMIT 1

1
supabase inspect db long-running-queries [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command displays statements, obtained from pg_stat_statements, ordered by the amount of time to execute in aggregate. This includes the statement itself, the total execution time for that statement, the proportion of total execution time for all statements that statement has taken up, the number of times that statement has been called, and the amount of time that statement spent on synchronous I/O (reading/writing from the file system).

Typically, an efficient query will have an appropriate ratio of calls to total execution time, with as little time spent on I/O as possible. Queries that have a high total execution time but low call count should be investigated to improve their performance. Queries that have a high proportion of execution time being spent on synchronous I/O should also be investigated.

                 QUERY                   │ EXECUTION TIME   │ PROPORTION OF EXEC TIME │ NUMBER CALLS │ SYNC IO TIME
─────────────────────────────────────────┼──────────────────┼─────────────────────────┼──────────────┼───────────────
 SELECT * FROM archivable_usage_events.. │ 154:39:26.431466 │ 72.2%                   │ 34,211,877   │ 00:00:00
 COPY public.archivable_usage_events (.. │ 50:38:33.198418  │ 23.6%                   │ 13           │ 13:34:21.00108
 COPY public.usage_events (id, reporte.. │ 02:32:16.335233  │ 1.2%                    │ 13           │ 00:34:19.784318
 INSERT INTO usage_events (id, retaine.. │ 01:42:59.436532  │ 0.8%                    │ 12,328,187   │ 00:00:00
 SELECT * FROM usage_events WHERE (alp.. │ 01:18:10.754354  │ 0.6%                    │ 102,114,301  │ 00:00:00

1
supabase inspect db outliers [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command shows information about logical replication slots that are setup on the database. It shows if the slot is active, the state of the WAL sender process ('startup', 'catchup', 'streaming', 'backup', 'stopping') the replication client address and the replication lag in GB.

This command is useful to check that the amount of replication lag is as low as possible, replication lag can occur due to network latency issues, slow disk I/O, long running transactions or lack of ability for the subscriber to consume WAL fast enough.

                       NAME                    │ ACTIVE │ STATE   │ REPLICATION CLIENT ADDRESS │ REPLICATION LAG GB
  ─────────────────────────────────────────────┼────────┼─────────┼────────────────────────────┼─────────────────────
    supabase_realtime_replication_slot         │ t      │ N/A     │ N/A                        │                  0
    datastream                                 │ t      │ catchup │ 24.201.24.106              │                 45

1
supabase inspect db replication-slots [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Show information about roles on the database.

1
supabase inspect db role-stats [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Show combined table size, index size, and estimated row count.

1
supabase inspect db table-stats [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This command analyzes table I/O patterns to show read/write activity ratios based on block-level operations. It combines data from PostgreSQL's pg_stat_user_tables (for tuple operations) and pg_statio_user_tables (for block I/O) to categorize each table's workload profile.

The command classifies tables into categories:

• Read-Heavy - Read operations are more than 5x write operations (e.g., 1:10, 1:50)
• Write-Heavy - Write operations are more than 20% of read operations (e.g., 1:2, 1:4, 2:1, 10:1)
• Balanced - Mixed workload where writes are between 20% and 500% of reads
• Read-Only - Only read operations detected
• Write-Only - Only write operations detected

SCHEMA │ TABLE        │ BLOCKS READ │ WRITE TUPLES │ BLOCKS WRITE │ ACTIVITY RATIO
───────┼──────────────┼─────────────┼──────────────┼──────────────┼────────────────────
public │ user_events  │     450,234 │     9,004,680│       23,450 │ 20:1 (Write-Heavy)
public │ users        │      89,203 │        12,451│        1,203 │ 7.2:1 (Read-Heavy)
public │ sessions     │      15,402 │        14,823│        2,341 │ ≈1:1 (Balanced)
public │ cache_data   │     123,456 │             0│            0 │ Read-Only
auth   │ audit_logs   │           0 │        98,234│       12,341 │ Write-Only

Note: This command only displays tables that have had both read and write activity. Tables with no I/O operations are not shown. The classification ratio threshold (default: 5:1) determines when a table is considered "heavy" in one direction versus balanced.

1
supabase inspect db traffic-profile [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

This shows you stats about the vacuum activities for each table. Due to Postgres' MVCC when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the autovaccum process will aysnchronously clean the dead tuples.

The command lists when the last vacuum and last auto vacuum took place, the row count on the table as well as the count of dead rows and whether autovacuum is expected to run or not. If the number of dead rows is much higher than the row count, or if an autovacuum is expected but has not been performed for some time, this can indicate that autovacuum is not able to keep up and that your vacuum settings need to be tweaked or that you require more compute or disk IOPS to allow autovaccum to complete.

        SCHEMA        │              TABLE               │ LAST VACUUM │ LAST AUTO VACUUM │      ROW COUNT       │ DEAD ROW COUNT │ EXPECT AUTOVACUUM?
──────────────────────┼──────────────────────────────────┼─────────────┼──────────────────┼──────────────────────┼────────────────┼─────────────────────
 auth                 │ users                            │             │ 2023-06-26 12:34 │               18,030 │              0 │ no
 public               │ profiles                         │             │ 2023-06-26 23:45 │               13,420 │             28 │ no
 public               │ logs                             │             │ 2023-06-26 01:23 │            1,313,033 │      3,318,228 │ yes
 storage              │ objects                          │             │                  │             No stats │              0 │ no
 storage              │ buckets                          │             │                  │             No stats │              0 │ no
 supabase_migrations  │ schema_migrations                │             │                  │             No stats │              0 │ no

1
supabase inspect db vacuum-stats [flags]

Flags

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Generate a CSV output for all inspect commands. It reports on the local database by default; pass --remote for the linked project, or --remote=<ref|branch|url> for another database.

1
supabase inspect report [flags]

Flags

• --output-dir <string>

  Optional

  Path to save CSV files in.

• --remote[=<ref|branch|url>]

  Optional

  Target a remote database: the linked project, or --remote=<ref|branch|url>.

Manage Supabase organizations

Subcommands

• supabase orgs create
• supabase orgs list

Create an organization for the logged-in user.

1
supabase orgs create <name> [flags]

List all organizations the logged-in user belongs.

1
supabase orgs list [flags]

Provides tools for creating and managing your Supabase projects.

This command group allows you to list all projects in your organizations, create new projects, delete existing projects, and retrieve API keys. These operations help you manage your Supabase infrastructure programmatically without using the dashboard.

Project management via CLI is especially useful for automation scripts and when you need to provision environments in a repeatable way.

Commands that change your account or projects ask for confirmation first: create defaults to yes, delete defaults to no. Pass --yes (or set SUPABASE_YES in your shell) to confirm in scripts and CI; without it, a run that cannot prompt fails before making any change.

Subcommands

• supabase projects api-keys
• supabase projects create
• supabase projects delete
• supabase projects list

Create a project on Supabase.

1
supabase projects create [name] [flags]

Flags

• --db-password <string>

  Optional

  Database password of the project.

• --high-availability

  Optional

  Enable high availability for the project.

• --org-id <string>

  Optional

  Organization ID to create the project in.

• --region <string>

  Optional

  Select a region close to you for the best performance.

• --size <string>

  Optional

  Select a desired instance size for your project.

List all Supabase projects the logged-in user can access.

1
supabase projects list [flags]

List all API keys for a Supabase project.

1
supabase projects api-keys [flags]

Flags

• --remote[=<ref|branch>]

  Optional

  Target another project: --remote=<ref|branch>. Defaults to the linked project.

• --reveal

  Optional

  Reveal the secret API keys in full (e.g. sb_secret_...).

Delete a Supabase project.

1
supabase projects delete [ref] [flags]

Manage Supabase project configurations.

Subcommands

• supabase config diff
• supabase config pull
• supabase config push

Updates the configurations of a linked Supabase project with the local supabase/config.toml file.

This command allows you to manage project configuration as code by defining settings locally and then pushing them to your remote project.

Pass --remote=<ref|branch> to push to a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target. --project-ref still works in v3 but is deprecated and removed in v4; use --remote.

Before anything is pushed, the command prints the Target: line for the project or branch it resolved (name, ref, and for a branch its parent project), then shows the exact diff for every resource that will change. It then asks once — a single question covering every changed resource, with a default answer of no — and sends nothing until you confirm. If a change enables a paid add-on, its price is printed before the question.

A push with nothing to change never asks. Declining fails the command and writes nothing. Piped answers are never read, so a script, a JSON run (-o json, --output-format json) or an agent must pass --yes or set SUPABASE_YES in the shell; a SUPABASE_YES in supabase/.env does not count. With --yes the command echoes Confirmed by --yes: … to stderr and pushes.

In json output the result carries a target object with the resolved identity (kind, project_ref, project_name, environment, and parent_project_ref for a branch) next to the push summary.

1
supabase config push [flags]

Flags

• --remote[=<ref|branch>]

  Optional

  Target another project: --remote=<ref|branch>. Defaults to the linked project.

Writes the effective configuration of a remote project or branch into the local supabase/config.toml/config.json — the write side of supabase config diff. Every write is a surgical, format-preserving edit: comments, key ordering, and quoting elsewhere in the file are left untouched, and only the values that actually change are rewritten.

Pass --remote=<ref|branch> to pull from a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target. --project-ref still works in v3 but is deprecated and removed in v4; use --remote.

Where a pulled value lands depends on whether the target is already tracked by a [remotes.*] block, not on how you named it: if any block's project_id already matches the resolved ref, that block is reused — whatever its own label — and every value lands there. Otherwise, if the target was named as a branch, a new [remotes.<branch-name>] block is created (a branch resolved by UUID falls back to the project ref itself as its label). Only when neither applies — --remote=<ref> naming a project directly, or the linked project (a bare --remote or no flag) with no branch involved — do values land at the config root. --remote-label overrides the block config pull would otherwise reuse or create; naming a block that already tracks a different project, or naming nothing while a different block already tracks this exact ref, is an error rather than a silent overwrite. A [remotes.*] block whose project_id is an env(...) reference that merely resolves to the target ref is never reused or rewritten — that is a hard error naming the variable, since a value written there would never actually take effect on the next load. Creating a new block always writes its project_id, even when every value it would otherwise carry already matches the local defaults — otherwise the block could never be reused on a later pull.

Writing to the config root can also affect supabase start: a handful of root-scoped settings — auth.site_url, db.settings.*, db.major_version (which changes what supabase start boots), db.pooler.*, and similar — also govern the local stack, so pulling a hosted value into them is a real change to local dev behavior, not just a record of the hosted project's own setting. config pull warns about this rather than refusing; writing the same value into a [remotes.*] block is unaffected. Passing --remote-label is the escape hatch: it diverts what would otherwise be a root-bound pull into a [remotes.<label>] block instead, leaving local dev untouched.

Several kinds of values are never written, and are reported instead of silently skipped: a value whose local declaration resolves from an env(VAR) reference (reported by variable name — replace the reference yourself, or pass --remote-label to target a different block); a value the REMOTE itself spells as an env(VAR) reference (remote_env_reference) — the loader would resolve it against the local environment on the next load, so writing it verbatim would let a remote value read whatever this machine's environment holds at that name; secret values, which the platform never returns in plaintext (a masked-credentials note); a value the file declares that the remote does not report (local-only — never removed); and a handful of already-declared properties config push cannot communicate back at all (an unmanaged note). Local-stack-only sections — [studio], [analytics], [functions], [edge_runtime], port numbers, image version pins, and similar — have no hosted counterpart and are never touched. One family of properties is written despite config push having no way to send it back (auth.oauth_server, disabled storage.analytics/storage.vector, …) — pulling still records the hosted value, with a warning that it cannot be pushed back.

config pull never writes a config.toml/.json it cannot load back on the next command. Pulling a value that GATES other declared fields — e.g. flipping a disabled provider's enabled on — also pulls its now-required sibling values into the same write (not just the gate), so the file never comes out half-configured. When one of those siblings genuinely can't be supplied — the remote doesn't report it, or supplying it would still leave a REQUIRED value missing — the whole toggle is skipped instead, reported with a new reason (requires values pull cannot write in text output, would_invalidate in the machine payload) plus a note naming the missing field(s) and, when a missing field's local spelling is itself an unresolved env(VAR) reference, the exact environment variable to set before rerunning.

--dry-run computes and prints exactly what config diff would show, then stops — no git check, no prompt, no write. --output-format json|stream-json never prompts at all — it returns the confirmation's default value without reading anything, so use --dry-run for a preview in those shapes rather than relying on the prompt. A non-interactive run in the default text format (no TTY on stdin) still prints the confirmation to stderr and reads a single line from piped stdin: an explicit y/yes/n/no answer is honored, an empty line falls back to the default, and any other answer declines. --yes (or SUPABASE_YES) answers the confirmation prompt without asking on an interactive TTY; it does not bypass the uncommitted-changes guard — on the contrary, --yes together with uncommitted (or untracked) changes aborts instead of silently overwriting them, since no human is left to read the warning. --force writes even when supabase/config.toml has uncommitted or untracked changes in git — without it, an interactive run's prompt defaults to "no" instead of "yes", and every other case (non-interactive text, machine-format, or --yes on any TTY) aborts outright.

A second config pull against an already-tracked, unchanged remote always writes nothing — that convergence is the design's own acceptance property, not a special case. It never even checks for uncommitted local changes to the config file in that case, since there is nothing to write either way. A target that isn't tracked yet (a branch or --remote-label name with no existing [remotes.*] block) still creates that block on its first pull, even when every value it carries already matches the local defaults — it's the second pull against that now-tracked block that then writes nothing.

Example

Given supabase/config.toml:

project_id = "abcdefghijklmnopqrst"

[api]
enabled = true
max_rows = 1000

supabase config pull --remote=staging, where staging is a branch of the linked project and no existing [remotes.*] block already tracks it, creates a new block at the end of the file — max_rows lands under its own [remotes.staging.api] sub-table, the same way [api] itself is a sub-table of the document root, not a key directly under [remotes.staging]:

project_id = "abcdefghijklmnopqrst"

[api]
enabled = true
max_rows = 1000

[remotes.staging]
project_id = "cccccccccccccccccccc"

[remotes.staging.api]
max_rows = 250

Running the same command again finds no differences and writes nothing.

Machine-readable output is available through --output-format json|stream-json — a versioned payload (schema_version, config_schema, config_path, format, target, destination, dry_run, wrote, scope, changes[], warnings[], masked[], unmanaged[], counts) — target identifies the pulled project the same way config diff does (kind, project_ref, project_name, environment, parent_project_ref, branch, local_scope) — with per-change paths as segment arrays, each carrying written and, when unwritten, a skipped_reason (env_reference | local_only | remote_env_reference | unwritable | would_invalidate | declined | dry_run). A would_invalidate warning additionally carries missing_fields ([{path, env_variable?}]) naming what actually blocked the family. The legacy global -o/--output flag is not supported by this command; use --output-format json|stream-json instead. Note: the payload spells the root scope "base" (target.local_scope), while text output calls the same thing config root.

1
supabase config pull [flags]

Flags

• --dry-run

  Optional

  Show what would be written without touching the config file.

• --force

  Optional

  Write even when the project config file has uncommitted changes in git.

• --remote[=<ref|branch>]

  Optional

  Target another project: --remote=<ref|branch>. Defaults to the linked project.

• --remote-label <string>

  Optional

  Name of the [remotes.*] block to write into, overriding the block config pull would otherwise reuse or create.

Shows the configuration differences between the local supabase/config.toml and the effective configuration of a remote project or branch. Read-only: it never modifies the local file or any remote configuration.

Pass --remote=<ref|branch> to compare against a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target. --project-ref still works in v3 but is deprecated and removed in v4; use --remote. When the target ref matches a [remotes.*] block's project_id, that block's merged config is the local side of the comparison.

Only platform-managed properties are compared. Local-stack-only sections — [studio], [analytics], [functions], [edge_runtime], port numbers, image version pins, [db.migrations], and similar — have no hosted counterpart and are never reported, whether or not your file declares them.

Each difference is classified as update (the file declares a value that differs remotely), remote-only (the remote differs while the file is silent — the shown local value is the schema default a config push would write), or local-only (the file declares a value the remote did not report). (unset) means the local side has no value at all; (not returned) means the response did not carry the property. Secret values are never compared — the platform only reports digests — and are listed in a masked-credentials note instead, as are declared properties that config push cannot communicate and any block the response omitted entirely.

Local values are shown as the configuration your file would produce once pushed, not its literal spelling: a duration written as "1m" renders as "1m0s", and byte sizes are shown in the units you wrote.

With --exit-code, the command exits 2 when any difference is found, keeping exit 1 for errors — so scripts can distinguish drift from failure.

Machine-readable output is available through --output-format json|stream-json — a versioned payload (schema_version, config_schema, target, scope, changes[], masked[], unmanaged[], counts) with per-change paths as segment arrays. target identifies the compared project: kind (linked), project_ref, project_name and environment (production, branch or unverified) when known, parent_project_ref for a branch, branch when it was named, and local_scope (base or remotes.<name>). The legacy global -o/--output flag is not supported by this command; use --output-format json|stream-json instead.

1
supabase config diff [flags]

Flags

• --exit-code

  Optional

  Exit with status 2 when any difference is found (errors keep exiting 1).

• --remote[=<ref|branch>]

  Optional

  Target another project: --remote=<ref|branch>. Defaults to the linked project.

Manage Supabase preview branches.

Subcommands

• supabase branches create
• supabase branches delete
• supabase branches get
• supabase branches list
• supabase branches pause
• supabase branches unpause
• supabase branches update

Create a preview branch for the linked project.

1
supabase branches create [name] [flags]

Flags

• --git-branch <string>

  Optional

  Associate a git branch with the new preview branch.

• --notify-url <string>

  Optional

  URL to notify when branch is active healthy.

• --persistent

  Optional

  Whether to create a persistent branch.

• --region <string>

  Optional

  Select a region to deploy the branch database.

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

• --size <string>

  Optional

  Select a desired instance size for the branch database.

• --with-data

  Optional

  Whether to clone production data to the branch database.

List all preview branches of the linked project.

1
supabase branches list [flags]

Flags

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

Retrieve details of the specified preview branch.

Note: For the main branch, password-dependent fields (POSTGRES_URL, POSTGRES_URL_NON_POOLING) are not populated because production database credentials are not retrievable via API.

1
supabase branches get [name] [flags]

Flags

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

Update a preview branch by its name or ID.

1
supabase branches update [name] [flags]

Flags

• --git-branch <string>

  Optional

  Change the associated git branch.

• --name <string>

  Optional

  Rename the preview branch.

• --notify-url <string>

  Optional

  URL to notify when branch is active healthy.

• --persistent

  Optional

  Switch between ephemeral and persistent branch.

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

• --status <string>

  Optional

  Override the current branch status.

Pause a preview branch.

1
supabase branches pause [name] [flags]

Flags

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

Unpause a preview branch.

1
supabase branches unpause [name] [flags]

Flags

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

Delete a preview branch by its name or ID.

1
supabase branches delete [name] [flags]

Flags

• --remote[=<ref>]

  Optional

  Target another project: --remote=<ref>. Defaults to the linked project.

Manage Supabase physical backups.

Subcommands

• supabase backups list
• supabase backups restore

Lists available physical backups

1
supabase backups list [flags]

Flags

• --remote[=<ref|branch>]

  Optional

  Target another project: --remote=<ref|branch>. Defaults to the linked project.

Restore to a specific timestamp using PITR

1
supabase backups restore [flags]