clispec: '001' info: id: cli version: 2.39.2 title: Supabase CLI language: sh source: https://github.com/supabase/cli bugs: https://github.com/supabase/cli/issues spec: https://github.com/supabase/spec/cli_v1_commands.yaml description: | Supabase CLI provides you with tools to develop your application locally, and deploy your application to the Supabase platform. tags: - id: quick-start title: Quick Start - id: local-dev title: Local Development - id: management-api title: Management APIs - id: other-commands title: Additional Commands flags: - id: create-ticket name: --create-ticket description: create a support ticket for any CLI error default_value: 'false' - id: debug name: --debug description: output debug logs to stderr default_value: 'false' - id: dns-resolver name: --dns-resolver <[ native | https ]> description: lookup domain names using the specified resolver default_value: native accepted_values: - id: native name: native type: '[ native | https ]' - id: https name: https type: '[ native | https ]' - id: experimental name: --experimental description: enable experimental features default_value: 'false' - id: help name: -h, --help description: help for supabase default_value: 'false' - id: network-id name: --network-id description: use the specified docker network instead of a generated one default_value: '' - id: output name: -o, --output <[ env | pretty | json | toml | yaml ]> description: output format of status variables default_value: pretty accepted_values: - id: env name: env type: '[ env | pretty | json | toml | yaml ]' - id: pretty name: pretty type: '[ env | pretty | json | toml | yaml ]' - id: json name: json type: '[ env | pretty | json | toml | yaml ]' - id: toml name: toml type: '[ env | pretty | json | toml | yaml ]' - id: yaml name: yaml type: '[ env | pretty | json | toml | yaml ]' - id: profile name: --profile description: use a specific profile for connecting to Supabase API default_value: supabase - id: workdir name: --workdir description: path to a Supabase project directory default_value: '' - id: "yes" name: --yes description: answer yes to all prompts default_value: 'false' commands: - id: supabase-vanity-subdomains title: supabase vanity-subdomains summary: Manage vanity subdomains for Supabase projects description: |- Manage vanity subdomains for Supabase projects. Usage of vanity subdomains and custom domains is mutually exclusive. tags: - management-api links: [] subcommands: - supabase-vanity-subdomains-activate - supabase-vanity-subdomains-check-availability - supabase-vanity-subdomains-delete - supabase-vanity-subdomains-get flags: [] - id: supabase-vanity-subdomains-get title: supabase vanity-subdomains get summary: Get the current vanity subdomain tags: [] links: [] usage: supabase vanity-subdomains get subcommands: [] flags: - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-vanity-subdomains-delete title: supabase vanity-subdomains delete summary: Deletes a project's vanity subdomain description: | Deletes the vanity subdomain for a project, and reverts to using the project ref for routing. tags: [] links: [] usage: supabase vanity-subdomains delete subcommands: [] flags: - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-vanity-subdomains-check-availability title: supabase vanity-subdomains check-availability summary: Checks if a desired subdomain is available for use tags: [] links: [] usage: supabase vanity-subdomains check-availability [flags] subcommands: [] flags: - id: desired-subdomain name: --desired-subdomain description: | The desired vanity subdomain to use for your Supabase project. default_value: '' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-vanity-subdomains-activate title: supabase vanity-subdomains activate summary: Activate a vanity subdomain description: | Activate a vanity subdomain for your Supabase project. This reconfigures your Supabase project to respond to requests on your vanity subdomain. After the vanity subdomain is activated, your project's auth services will no longer function on the {project-ref}.{supabase-domain} hostname. tags: [] links: [] usage: supabase vanity-subdomains activate [flags] subcommands: [] flags: - id: desired-subdomain name: --desired-subdomain description: | The desired vanity subdomain to use for your Supabase project. default_value: '' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-unlink title: supabase unlink summary: Unlink a Supabase project tags: - local-dev links: [] usage: supabase unlink subcommands: [] flags: [] - id: supabase-test title: supabase test summary: Run tests on local Supabase containers tags: - local-dev links: [] subcommands: - supabase-test-db - supabase-test-new flags: [] - id: supabase-test-new title: supabase test new summary: Create a new test file tags: [] links: [] usage: supabase test new [flags] subcommands: [] flags: - id: template name: -t, --template <[ pgtap ]> description: Template framework to generate. default_value: pgtap accepted_values: - id: pgtap name: pgtap type: '[ pgtap ]' - id: supabase-test-db title: supabase test db summary: Tests local database with pgTAP description: |2 Executes pgTAP tests against the local database. Requires the local development stack to be started by running `supabase start`. 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. examples: - id: basic-usage name: Basic usage code: supabase test db response: | /tmp/supabase/tests/nested/order_test.pg .. ok /tmp/supabase/tests/pet_test.sql .......... ok All tests successful. Files=2, Tests=2, 6 wallclock secs ( 0.03 usr 0.01 sys + 0.05 cusr 0.02 csys = 0.11 CPU) Result: PASS tags: [] links: [] usage: supabase test db [path] ... [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Tests the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Runs pgTAP tests on the linked project. default_value: 'false' - id: local name: --local description: Runs pgTAP tests on the local database. default_value: 'true' - id: supabase-storage title: supabase storage summary: Manage Supabase Storage objects tags: - management-api links: [] subcommands: - supabase-storage-cp - supabase-storage-ls - supabase-storage-mv - supabase-storage-rm flags: [] - id: supabase-storage-rm title: supabase storage rm summary: Remove objects by file path tags: [] links: [] usage: supabase storage rm ... [flags] subcommands: [] flags: - id: recursive name: -r, --recursive description: Recursively remove a directory. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: linked name: --linked description: Connects to Storage API of the linked project. default_value: 'true' - id: local name: --local description: Connects to Storage API of the local database. default_value: 'false' - id: supabase-storage-mv title: supabase storage mv summary: Move objects from src to dst path tags: [] links: [] usage: supabase storage mv [flags] subcommands: [] flags: - id: recursive name: -r, --recursive description: Recursively move a directory. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: linked name: --linked description: Connects to Storage API of the linked project. default_value: 'true' - id: local name: --local description: Connects to Storage API of the local database. default_value: 'false' - id: supabase-storage-ls title: supabase storage ls summary: List objects by path prefix tags: [] links: [] usage: supabase storage ls [path] [flags] subcommands: [] flags: - id: recursive name: -r, --recursive description: Recursively list a directory. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: linked name: --linked description: Connects to Storage API of the linked project. default_value: 'true' - id: local name: --local description: Connects to Storage API of the local database. default_value: 'false' - id: supabase-storage-cp title: supabase storage cp summary: Copy objects from src to dst path tags: [] links: [] usage: supabase storage cp [flags] subcommands: [] flags: - id: cache-control name: --cache-control description: Custom Cache-Control header for HTTP upload. default_value: max-age=3600 - id: content-type name: --content-type description: Custom Content-Type header for HTTP upload. default_value: auto-detect - id: jobs name: -j, --jobs description: Maximum number of parallel jobs. default_value: '1' - id: recursive name: -r, --recursive description: Recursively copy a directory. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: linked name: --linked description: Connects to Storage API of the linked project. default_value: 'true' - id: local name: --local description: Connects to Storage API of the local database. default_value: 'false' - id: supabase-stop title: supabase stop summary: Stop all local Supabase containers description: |2- 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. examples: - id: basic-usage name: Basic usage code: supabase stop response: | Stopped supabase local development setup. Local data are backed up to docker volume. - id: clean-up name: Clean up local data after stopping code: supabase stop --no-backup response: | Stopped supabase local development setup. tags: - local-dev links: [] usage: supabase stop [flags] subcommands: [] flags: - id: all name: --all description: | Stop all local Supabase instances from all projects across the machine. default_value: 'false' - id: no-backup name: --no-backup description: Deletes all data volumes after stopping. default_value: 'false' - id: project-id name: --project-id description: Local project ID to stop. default_value: '' - id: supabase-status title: supabase status summary: Show status of local Supabase containers description: |2 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](https://supabase.com/docs/reference/javascript/initializing) locally by specifying the `-o env` flag. Supported parameters include `JWT_SECRET`, `ANON_KEY`, and `SERVICE_ROLE_KEY`. examples: - id: basic-usage name: Basic usage code: supabase status response: | supabase local development setup is running. API URL: http://127.0.0.1:54321 GraphQL URL: http://127.0.0.1:54321/graphql/v1 DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres Studio URL: http://127.0.0.1:54323 Inbucket URL: http://127.0.0.1:54324 JWT secret: super-secret-jwt-token-with-at-least-32-characters-long anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0 service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU - id: output-env name: Format status as environment variables code: supabase status -o env response: | ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0" API_URL="http://127.0.0.1:54321" DB_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres" GRAPHQL_URL="http://127.0.0.1:54321/graphql/v1" INBUCKET_URL="http://127.0.0.1:54324" JWT_SECRET="super-secret-jwt-token-with-at-least-32-characters-long" SERVICE_ROLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU" STUDIO_URL="http://127.0.0.1:54323" - id: output-custom-name name: Customize the names of exported variables code: supabase status -o env --override-name auth.anon_key=SUPABASE_ANON_KEY --override-name auth.service_role_key=SUPABASE_SERVICE_KEY response: | Stopped services: [supabase_inbucket_cli supabase_rest_cli supabase_studio_cli] SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0" DB_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres" GRAPHQL_URL="http://127.0.0.1:54321/graphql/v1" JWT_SECRET="super-secret-jwt-token-with-at-least-32-characters-long" SUPABASE_SERVICE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU" tags: - local-dev links: [] usage: supabase status [flags] subcommands: [] flags: - id: override-name name: --override-name description: Override specific variable names. default_value: '[]' - id: supabase-start title: supabase start summary: Start containers for Supabase local development description: |2 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. examples: - id: basic-usage name: Basic usage code: supabase start response: | Creating custom roles supabase/roles.sql... Applying migration 20220810154536_employee.sql... Seeding data supabase/seed.sql... Started supabase local development setup. - id: without-studio name: Start containers without studio and imgproxy code: supabase start -x studio,imgproxy response: | Excluding container: supabase/studio:20221214-4eecc99 Excluding container: darthsim/imgproxy:v3.8.0 Started supabase local development setup. - id: ignore-health-check name: Ignore service health checks code: supabase start --ignore-health-check response: | service not healthy: [supabase_storage_cli] Started supabase local development setup. tags: - local-dev links: [] usage: supabase start [flags] subcommands: [] flags: - id: exclude name: -x, --exclude description: | Names of containers to not start. [gotrue,realtime,storage-api,imgproxy,kong,mailpit,postgrest,postgres-meta,studio,edge-runtime,logflare,vector,supavisor] default_value: '[]' - id: ignore-health-check name: --ignore-health-check description: Ignore unhealthy services and exit 0 default_value: 'false' - id: supabase-sso title: supabase sso summary: Manage Single Sign-On (SSO) authentication for projects tags: - management-api links: [] subcommands: - supabase-sso-add - supabase-sso-info - supabase-sso-list - supabase-sso-remove - supabase-sso-show - supabase-sso-update flags: [] - id: supabase-sso-update title: supabase sso update summary: Update information about an SSO identity provider description: | Update the configuration settings of a already added SSO identity provider. examples: - id: basic-usage name: Replace domains code: |- supabase sso update 6df4d73f-bf21-405f-a084-b11adf19fea5 \ --project-ref abcdefghijklmnopqrst \ --domains new-company.com,new-company.net response: Information about the updated provider. - id: add-domains name: Add an additional domain code: |- supabase sso update 6df4d73f-bf21-405f-a084-b11adf19fea5 \ --project-ref abcdefghijklmnopqrst \ --add-domains company.net response: Information about the updated provider. - id: remove-domains name: Remove a domain code: |- supabase sso update 6df4d73f-bf21-405f-a084-b11adf19fea5 \ --project-ref abcdefghijklmnopqrst \ --remove-domains company.org response: Information about the updated provider. tags: [] links: [] usage: supabase sso update [flags] subcommands: [] flags: - id: add-domains name: --add-domains description: | Add this comma separated list of email domains to the identity provider. default_value: '[]' - id: attribute-mapping-file name: --attribute-mapping-file description: | File containing a JSON mapping between SAML attributes to custom JWT claims. default_value: '' - id: domains name: --domains description: | Replace domains with this comma separated list of email domains. default_value: '[]' - id: metadata-file name: --metadata-file description: | File containing a SAML 2.0 Metadata XML document describing the identity provider. default_value: '' - id: metadata-url name: --metadata-url description: | URL pointing to a SAML 2.0 Metadata XML document describing the identity provider. default_value: '' - id: remove-domains name: --remove-domains description: | Remove this comma separated list of email domains from the identity provider. default_value: '[]' - id: skip-url-validation name: --skip-url-validation description: | Whether local validation of the SAML 2.0 Metadata URL should not be performed. default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-sso-show title: supabase sso show summary: Show information about an SSO identity provider description: | Provides the information about an established connection to an identity provider. You can use --metadata to obtain the raw SAML 2.0 Metadata XML document stored in your project's configuration. examples: - id: basic-usage name: Show information code: |- supabase sso show 6df4d73f-bf21-405f-a084-b11adf19fea5 \ --project-ref abcdefghijklmnopqrst response: Information about the identity provider in pretty output. - id: metadata-output name: Get raw SAML 2.0 Metadata XML code: |- supabase sso show 6df4d73f-bf21-405f-a084-b11adf19fea5 \ --project-ref abcdefghijklmnopqrst \ --metadata response: |- Raw SAML 2.0 XML assigned to this identity provider. This is the version used in the authentication project, and if using a SAML 2.0 Metadata URL it may change depending on the caching information contained within the metadata. tags: [] links: [] usage: supabase sso show [flags] subcommands: [] flags: - id: metadata name: --metadata description: Show SAML 2.0 XML Metadata only default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-sso-remove title: supabase sso remove summary: Remove an existing SSO identity provider description: | Remove a connection to an already added SSO identity provider. Removing the provider will prevent existing users from logging in. Please treat this command with care. examples: - id: basic-usage name: Remove a provider code: |- supabase sso remove 6df4d73f-bf21-405f-a084-b11adf19fea5 \ --project-ref abcdefghijklmnopqrst response: |- Information about the removed identity provider. It's a good idea to save this in case you need it later on. tags: [] links: [] usage: supabase sso remove subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-sso-list title: supabase sso list summary: List all SSO identity providers for a project description: | List all connections to a SSO identity provider to your Supabase project. tags: [] links: [] usage: supabase sso list subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-sso-info title: supabase sso info summary: | Returns the SAML SSO settings required for the identity provider description: | Returns all of the important SSO information necessary for your project to be registered with a SAML 2.0 compatible identity provider. examples: - id: basic-usage name: Show project information code: supabase sso info --project-ref abcdefghijklmnopqrst response: Information about your project's SAML 2.0 configuration. tags: [] links: [] usage: supabase sso info subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-sso-add title: supabase sso add summary: Add a new SSO identity provider description: | Add and configure a new connection to a SSO identity provider to your Supabase project. examples: - id: basic-usage name: Add with Metadata URL code: |- supabase sso add \ --project-ref abcdefgijklmnopqrst \ --type saml \ --metadata-url 'https://...' \ --domains company.com response: |- Information about the added identity provider. You can use company.com as the domain name on the frontend side to initiate a SSO request to the identity provider. - id: with-xml name: Add with Metadata File code: |- supabase sso add \ --project-ref abcdefgijklmnopqrst \ --type saml \ --metadata-file /path/to/metadata/file.xml \ --domains company.com response: |- Information about the added identity provider. You can use company.com as the domain name on the frontend side to initiate a SSO request to the identity provider. tags: [] links: [] usage: supabase sso add [flags] subcommands: [] flags: - id: attribute-mapping-file name: --attribute-mapping-file description: | File containing a JSON mapping between SAML attributes to custom JWT claims. default_value: '' - id: domains name: --domains description: | Comma separated list of email domains to associate with the added identity provider. default_value: '[]' - id: metadata-file name: --metadata-file description: | File containing a SAML 2.0 Metadata XML document describing the identity provider. default_value: '' - id: metadata-url name: --metadata-url description: | URL pointing to a SAML 2.0 Metadata XML document describing the identity provider. default_value: '' - id: skip-url-validation name: --skip-url-validation description: | Whether local validation of the SAML 2.0 Metadata URL should not be performed. default_value: 'false' - id: type name: -t, --type <[ saml ]> description: Type of identity provider (according to supported protocol). required: true default_value: '' accepted_values: - id: saml name: saml type: '[ saml ]' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-ssl-enforcement title: supabase ssl-enforcement summary: Manage SSL enforcement configuration tags: - management-api links: [] subcommands: - supabase-ssl-enforcement-get - supabase-ssl-enforcement-update flags: [] - id: supabase-ssl-enforcement-update title: supabase ssl-enforcement update summary: Update SSL enforcement configuration tags: [] links: [] usage: supabase ssl-enforcement update [flags] subcommands: [] flags: - id: disable-db-ssl-enforcement name: --disable-db-ssl-enforcement description: | Whether the DB should disable SSL enforcement for all external connections. default_value: 'false' - id: enable-db-ssl-enforcement name: --enable-db-ssl-enforcement description: | Whether the DB should enable SSL enforcement for all external connections. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-ssl-enforcement-get title: supabase ssl-enforcement get summary: Get the current SSL enforcement configuration tags: [] links: [] usage: supabase ssl-enforcement get subcommands: [] flags: - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-snippets title: supabase snippets summary: Manage Supabase SQL snippets tags: - management-api links: [] subcommands: - supabase-snippets-download - supabase-snippets-list flags: [] - id: supabase-snippets-list title: supabase snippets list summary: List all SQL snippets description: List all SQL snippets of the linked project. tags: [] links: [] usage: supabase snippets list subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-snippets-download title: supabase snippets download summary: Download contents of a SQL snippet description: Download contents of the specified SQL snippet. tags: [] links: [] usage: supabase snippets download subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-services title: supabase services summary: Show versions of all Supabase services tags: - local-dev links: [] usage: supabase services subcommands: [] flags: [] - id: supabase-seed title: supabase seed summary: Seed a Supabase project from supabase/config.toml tags: - local-dev links: [] subcommands: - supabase-seed-buckets flags: [] - id: supabase-seed-buckets title: supabase seed buckets summary: Seed buckets declared in [storage.buckets] tags: [] links: [] usage: supabase seed buckets subcommands: [] flags: - id: linked name: --linked description: Seeds the linked project. default_value: 'false' - id: local name: --local description: Seeds the local database. default_value: 'true' - id: supabase-secrets title: supabase secrets summary: Manage Supabase secrets description: |2 Provides tools for managing environment variables and secrets for your Supabase project. This command group allows you to set, unset, and list secrets that are securely stored and made available to Edge Functions as environment variables. Secrets management through the CLI is useful for: - Setting environment-specific configuration - Managing sensitive credentials securely Secrets can be set individually or loaded from .env files for convenience. tags: - management-api links: [] subcommands: - supabase-secrets-list - supabase-secrets-set - supabase-secrets-unset flags: [] - id: supabase-secrets-unset title: supabase secrets unset summary: Unset a secret(s) on Supabase description: Unset a secret(s) from the linked Supabase project. tags: [] links: [] usage: supabase secrets unset [NAME] ... subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-secrets-set title: supabase secrets set summary: Set a secret(s) on Supabase description: Set a secret(s) to the linked Supabase project. tags: [] links: [] usage: supabase secrets set ... [flags] subcommands: [] flags: - id: env-file name: --env-file description: Read secrets from a .env file. default_value: '' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-secrets-list title: supabase secrets list summary: List all secrets on Supabase description: List all secrets in the linked project. tags: [] links: [] usage: supabase secrets list subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-projects title: supabase projects summary: Manage Supabase projects description: |2 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. tags: - management-api links: [] subcommands: - supabase-projects-api-keys - supabase-projects-create - supabase-projects-delete - supabase-projects-list flags: [] - id: supabase-projects-list title: supabase projects list summary: List all Supabase projects description: List all Supabase projects the logged-in user can access. tags: [] links: [] usage: supabase projects list subcommands: [] flags: [] - id: supabase-projects-delete title: supabase projects delete summary: Delete a Supabase project tags: [] links: [] usage: supabase projects delete [ref] subcommands: [] flags: [] - id: supabase-projects-create title: supabase projects create summary: Create a project on Supabase tags: [] links: [] usage: supabase projects create [project name] [flags] subcommands: [] flags: - id: db-password name: --db-password description: Database password of the project. default_value: '' - id: org-id name: --org-id description: Organization ID to create the project in. default_value: '' - id: region name: --region description: Select a region close to you for the best performance. default_value: '' accepted_values: - id: ap-northeast-1 name: ap-northeast-1 type: string - id: ap-northeast-2 name: ap-northeast-2 type: string - id: ap-south-1 name: ap-south-1 type: string - id: ap-southeast-1 name: ap-southeast-1 type: string - id: ap-southeast-2 name: ap-southeast-2 type: string - id: ca-central-1 name: ca-central-1 type: string - id: eu-central-1 name: eu-central-1 type: string - id: eu-west-1 name: eu-west-1 type: string - id: eu-west-2 name: eu-west-2 type: string - id: eu-west-3 name: eu-west-3 type: string - id: sa-east-1 name: sa-east-1 type: string - id: us-east-1 name: us-east-1 type: string - id: us-west-1 name: us-west-1 type: string - id: us-west-2 name: us-west-2 type: string - id: size name: --size description: Select a desired instance size for your project. default_value: '' accepted_values: - id: large name: large type: string - id: medium name: medium type: string - id: micro name: micro type: string - id: 12xlarge name: 12xlarge type: string - id: 16xlarge name: 16xlarge type: string - id: 24xlarge name: 24xlarge type: string - id: 24xlarge_high_memory name: 24xlarge_high_memory type: string - id: 24xlarge_optimized_cpu name: 24xlarge_optimized_cpu type: string - id: 24xlarge_optimized_memory name: 24xlarge_optimized_memory type: string - id: 2xlarge name: 2xlarge type: string - id: 48xlarge name: 48xlarge type: string - id: 48xlarge_high_memory name: 48xlarge_high_memory type: string - id: 48xlarge_optimized_cpu name: 48xlarge_optimized_cpu type: string - id: 48xlarge_optimized_memory name: 48xlarge_optimized_memory type: string - id: 4xlarge name: 4xlarge type: string - id: 8xlarge name: 8xlarge type: string - id: pico name: pico type: string - id: small name: small type: string - id: xlarge name: xlarge type: string - id: supabase-projects-api-keys title: supabase projects api-keys summary: List all API keys for a Supabase project tags: [] links: [] usage: supabase projects api-keys [flags] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-postgres-config title: supabase postgres-config summary: Manage Postgres database config tags: - management-api links: [] subcommands: - supabase-postgres-config-delete - supabase-postgres-config-get - supabase-postgres-config-update flags: [] - id: supabase-postgres-config-update title: supabase postgres-config update summary: Update Postgres database config description: |- Overriding the default Postgres config could result in unstable database behavior. Custom configuration also overrides the optimizations generated based on the compute add-ons in use. tags: [] links: [] usage: supabase postgres-config update [flags] subcommands: [] flags: - id: config name: --config description: Config overrides specified as a 'key=value' pair default_value: '[]' - id: no-restart name: --no-restart description: Do not restart the database after updating config. default_value: 'false' - id: replace-existing-overrides name: --replace-existing-overrides description: | If true, replaces all existing overrides with the ones provided. If false (default), merges existing overrides with the ones provided. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-postgres-config-get title: supabase postgres-config get summary: Get the current Postgres database config overrides tags: [] links: [] usage: supabase postgres-config get subcommands: [] flags: - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-postgres-config-delete title: supabase postgres-config delete summary: Delete specific Postgres database config overrides description: | Delete specific config overrides, reverting them to their default values. tags: [] links: [] usage: supabase postgres-config delete [flags] subcommands: [] flags: - id: config name: --config description: Config keys to delete (comma-separated) default_value: '[]' - id: no-restart name: --no-restart description: Do not restart the database after deleting config. default_value: 'false' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-orgs title: supabase orgs summary: Manage Supabase organizations tags: - management-api links: [] subcommands: - supabase-orgs-create - supabase-orgs-list flags: [] - id: supabase-orgs-list title: supabase orgs list summary: List all organizations description: List all organizations the logged-in user belongs. tags: [] links: [] usage: supabase orgs list subcommands: [] flags: [] - id: supabase-orgs-create title: supabase orgs create summary: Create an organization description: Create an organization for the logged-in user. tags: [] links: [] usage: supabase orgs create subcommands: [] flags: [] - id: supabase-network-restrictions title: supabase network-restrictions summary: Manage network restrictions tags: - management-api links: [] subcommands: - supabase-network-restrictions-get - supabase-network-restrictions-update flags: [] - id: supabase-network-restrictions-update title: supabase network-restrictions update summary: Update network restrictions tags: [] links: [] usage: supabase network-restrictions update [flags] subcommands: [] flags: - id: bypass-cidr-checks name: --bypass-cidr-checks description: Bypass some of the CIDR validation checks. default_value: 'false' - id: db-allow-cidr name: --db-allow-cidr description: CIDR to allow DB connections from. default_value: '[]' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-network-restrictions-get title: supabase network-restrictions get summary: Get the current network restrictions tags: [] links: [] usage: supabase network-restrictions get subcommands: [] flags: - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-network-bans title: supabase network-bans summary: Manage network bans description: |- Network bans are IPs that get temporarily blocked if their traffic pattern looks abusive (e.g. multiple failed auth attempts). The subcommands help you view the current bans, and unblock IPs if desired. tags: - management-api links: [] subcommands: - supabase-network-bans-get - supabase-network-bans-remove flags: [] - id: supabase-network-bans-remove title: supabase network-bans remove summary: Remove a network ban tags: [] links: [] usage: supabase network-bans remove [flags] subcommands: [] flags: - id: db-unban-ip name: --db-unban-ip description: IP to allow DB connections from. default_value: '[]' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-network-bans-get title: supabase network-bans get summary: Get the current network bans tags: [] links: [] usage: supabase network-bans get subcommands: [] flags: - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-migration title: supabase migration summary: Manage database migration scripts tags: - local-dev links: [] subcommands: - supabase-migration-down - supabase-migration-fetch - supabase-migration-list - supabase-migration-new - supabase-migration-repair - supabase-migration-squash - supabase-migration-up flags: [] - id: supabase-migration-up title: supabase migration up summary: Apply pending migrations to local database tags: [] links: [] usage: supabase migration up [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Applies migrations to the database specified by the connection string (must be percent-encoded). default_value: '' - id: include-all name: --include-all description: Include all migrations not found on remote history table. default_value: 'false' - id: linked name: --linked description: Applies pending migrations to the linked project. default_value: 'false' - id: local name: --local description: Applies pending migrations to the local database. default_value: 'true' - id: supabase-migration-squash title: supabase migration squash summary: Squash migrations to a single file description: |2 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 `_.sql` file will be updated to contain the squashed migration. You can override the target version using the `--version ` flag. If your `supabase/migrations` directory is empty, running `supabase squash` will do nothing. tags: [] links: [] usage: supabase migration squash [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Squashes migrations of the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Squashes the migration history of the linked project. default_value: 'false' - id: local name: --local description: Squashes the migration history of the local database. default_value: 'true' - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: version name: --version description: Squash up to the specified version. default_value: '' - id: supabase-migration-repair title: supabase migration repair summary: Repair the migration history table description: |2 Repairs the remote migration history table. Requires your local project to be linked to a remote database by running `supabase link`. 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. ```bash $ supabase migration list 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. ```bash $ rm supabase/migrations/20230103054315_remote_commit.sql $ supabase migration list LOCAL │ REMOTE │ TIME (UTC) ─────────────────┼────────────────┼────────────────────── │ 20230103054303 │ 2023-01-03 05:43:03 ``` Then mark the remote migration `20230103054303` as reverted. ```bash $ supabase migration repair 20230103054303 --status reverted Connecting to remote database... Repaired migration history: [20220810154537] => reverted Finished supabase migration repair. $ supabase migration list LOCAL │ REMOTE │ TIME (UTC) ─────────────────┼────────────────┼────────────────────── ``` Now you can run `db pull` again to dump the remote schema as a local migration file. ```bash $ supabase db pull Connecting to remote database... Schema written to supabase/migrations/20240414044403_remote_schema.sql Update remote migration history table? [Y/n] Repaired migration history: [20240414044403] => applied Finished supabase db pull. $ supabase migration list LOCAL │ REMOTE │ TIME (UTC) ─────────────────┼────────────────┼────────────────────── 20240414044403 │ 20240414044403 │ 2024-04-14 04:44:03 ``` examples: - id: basic-usage name: Mark a migration as reverted code: supabase migration repair 20230103054303 --status reverted response: | Repaired migration history: 20230103054303 => reverted - id: mark-applied name: Mark a migration as applied code: supabase migration repair 20230222032233 --status applied response: | Repaired migration history: 20230222032233 => applied tags: [] links: [] usage: supabase migration repair [version] ... [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Repairs migrations of the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Repairs the migration history of the linked project. default_value: 'true' - id: local name: --local description: Repairs the migration history of the local database. default_value: 'false' - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: status name: --status <[ applied | reverted ]> description: Version status to update. required: true default_value: '' accepted_values: - id: applied name: applied type: '[ applied | reverted ]' - id: reverted name: reverted type: '[ applied | reverted ]' - id: supabase-migration-new title: supabase migration new summary: Create an empty migration script description: |2 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 `_.sql`. Outputs from other commands like `db diff` may be piped to `migration new ` via stdin. examples: - id: basic-usage name: Basic usage code: supabase migration new schema_test response: | Created new migration at supabase/migrations/20230306095710_schema_test.sql. - id: pipe-stdin name: With statements piped from stdin code: echo "create schema if not exists test;" | supabase migration new schema_test response: | Created new migration at supabase/migrations/20230306095710_schema_test.sql. tags: [] links: [] usage: supabase migration new subcommands: [] flags: [] - id: supabase-migration-list title: supabase migration list summary: List local and remote migrations description: |2 Lists migration history in both local and remote databases. Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag. > Note that URL strings must be escaped according to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986). Local migrations are stored in `supabase/migrations` directory while remote migrations are tracked in `supabase_migrations.schema_migrations` table. 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. examples: - id: basic-usage name: Basic usage code: supabase migration list response: |2 LOCAL │ REMOTE │ TIME (UTC) ─────────────────┼────────────────┼────────────────────── │ 20230103054303 │ 2023-01-03 05:43:03 │ 20230103093141 │ 2023-01-03 09:31:41 20230222032233 │ │ 2023-02-22 03:22:33 - id: with-db-url name: Connect to self-hosted database code: supabase migration list --db-url 'postgres://postgres[:percent_encoded_password]@127.0.0.1[:port]/postgres' response: |2 LOCAL │ REMOTE │ TIME (UTC) ─────────────────┼────────────────┼────────────────────── 20230103054303 │ 20230103054303 │ 2023-01-03 05:43:03 20230103093141 │ 20230103093141 │ 2023-01-03 09:31:41 tags: [] links: [] usage: supabase migration list [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Lists migrations of the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Lists migrations applied to the linked project. default_value: 'true' - id: local name: --local description: Lists migrations applied to the local database. default_value: 'false' - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: supabase-migration-fetch title: supabase migration fetch summary: Fetch migration files from history table tags: [] links: [] usage: supabase migration fetch [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Fetches migrations from the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Fetches migration history from the linked project. default_value: 'true' - id: local name: --local description: Fetches migration history from the local database. default_value: 'false' - id: supabase-migration-down title: supabase migration down summary: Resets applied migrations up to the last n versions tags: [] links: [] usage: supabase migration down [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Resets applied migrations on the database specified by the connection string (must be percent-encoded). default_value: '' - id: last name: --last description: Reset up to the last n migration versions. default_value: '1' - id: linked name: --linked description: Resets applied migrations on the linked project. default_value: 'false' - id: local name: --local description: Resets applied migrations on the local database. default_value: 'true' - id: supabase-logout title: supabase logout summary: Log out and delete access tokens locally tags: - local-dev links: [] usage: supabase logout subcommands: [] flags: [] - id: supabase-login title: supabase login summary: Authenticate using an access token description: |2 Connect the Supabase CLI to your Supabase account by logging in with your [personal access token](https://supabase.com/dashboard/account/tokens). Your access token is stored securely in [native credentials storage](https://github.com/zalando/go-keyring#dependencies). If native credentials storage is unavailable, it will be written to a plain text file at `~/.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. examples: - id: basic-usage name: Basic usage code: supabase login response: | You can generate an access token from https://supabase.com/dashboard/account/tokens Enter your access token: sbp_**************************************** Finished supabase login. tags: - local-dev links: [] usage: supabase login [flags] subcommands: [] flags: - id: name name: --name description: Name that will be used to store token in your settings default_value: built-in token name generator - id: no-browser name: --no-browser description: Do not open browser automatically default_value: 'false' - id: token name: --token description: Use provided token instead of automatic login flow default_value: '' - id: supabase-link title: supabase link summary: Link to a Supabase project description: |2 Link your local development project to a hosted Supabase project. 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. Some commands like `db dump`, `db push`, and `db pull` require your project to be linked first. examples: - id: basic-usage name: Basic usage code: supabase link --project-ref ******************** response: | Enter your database password (or leave blank to skip): ******** Finished supabase link. - id: without-password name: Link without database password code: supabase link --project-ref ******************** <<< "" response: | Enter your database password (or leave blank to skip): Finished supabase link. - id: using-alternate-dns name: Link using DNS-over-HTTPS resolver code: supabase link --project-ref ******************** --dns-resolver https response: | Enter your database password (or leave blank to skip): Finished supabase link. tags: - local-dev links: [] usage: supabase link [flags] subcommands: [] flags: - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-inspect title: supabase inspect summary: Tools to inspect your Supabase project tags: - local-dev links: [] subcommands: - supabase-inspect-db - supabase-inspect-report flags: [] - id: supabase-inspect-report title: supabase inspect report summary: Generate a CSV output for all inspect commands tags: [] links: [] usage: supabase inspect report [flags] subcommands: [] flags: - id: output-dir name: --output-dir description: Path to save CSV files in default_value: . - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db title: supabase inspect db summary: Tools to inspect your Supabase database tags: [] links: [] subcommands: - supabase-inspect-db-bloat - supabase-inspect-db-blocking - supabase-inspect-db-calls - 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-vacuum-stats flags: [] - id: supabase-inspect-db-vacuum-stats title: supabase inspect db vacuum-stats summary: Show statistics related to vacuum operations per table description: |2 This shows you stats about the vacuum activities for each table. Due to Postgres' [MVCC](https://www.postgresql.org/docs/current/mvcc.html) when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the [autovaccum](https://supabase.com/docs/guides/platform/database-size#vacuum-operations) 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 ``` tags: [] links: [] usage: supabase inspect db vacuum-stats subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-table-stats title: supabase inspect db table-stats summary: | Show combined table size, index size, and estimated row count tags: [] links: [] usage: supabase inspect db table-stats subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-role-stats title: supabase inspect db role-stats summary: Show information about roles on the database tags: [] links: [] usage: supabase inspect db role-stats subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-replication-slots title: supabase inspect db replication-slots summary: Show information about replication slots on the database description: |2- This command shows information about [logical replication slots](https://www.postgresql.org/docs/current/logical-replication.html) 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 ``` tags: [] links: [] usage: supabase inspect db replication-slots subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-outliers title: supabase inspect db outliers summary: | Show queries from pg_stat_statements ordered by total execution time description: |2 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 ``` tags: [] links: [] usage: supabase inspect db outliers subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-long-running-queries title: supabase inspect db long-running-queries summary: | Show currently running queries running for longer than 5 minutes description: |2 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 ``` tags: [] links: [] usage: supabase inspect db long-running-queries subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-locks title: supabase inspect db locks summary: | Show queries which have taken out an exclusive lock on a relation description: |2 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 ``` tags: [] links: [] usage: supabase inspect db locks subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-index-stats title: supabase inspect db index-stats summary: | Show combined index size, usage percent, scan counts, and unused status tags: [] links: [] usage: supabase inspect db index-stats subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-db-stats title: supabase inspect db db-stats summary: | Show stats such as cache hit rates, total sizes, and WAL size tags: [] links: [] usage: supabase inspect db db-stats subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-calls title: supabase inspect db calls summary: | Show queries from pg_stat_statements ordered by total times called description: |2 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 ``` tags: [] links: [] usage: supabase inspect db calls subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-blocking title: supabase inspect db blocking summary: | Show queries that are holding locks and the queries that are waiting for them to be released description: |2 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 ``` tags: [] links: [] usage: supabase inspect db blocking subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-inspect-db-bloat title: supabase inspect db bloat summary: | Estimates space allocated to a relation that is full of dead tuples description: |2 This command displays an estimation of table "bloat" - Due to Postgres' [MVCC](https://www.postgresql.org/docs/current/mvcc.html) when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the [autovaccum](https://supabase.com/docs/guides/platform/database-size#vacuum-operations) 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 ``` tags: [] links: [] usage: supabase inspect db bloat subcommands: [] flags: - id: db-url name: --db-url description: | Inspect the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Inspect the linked project. default_value: 'true' - id: local name: --local description: Inspect the local database. default_value: 'false' - id: supabase-init title: supabase init summary: Initialize a local project description: |2 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. examples: - id: basic-usage name: Basic usage code: supabase init response: Finished supabase init. - id: from-workdir name: Initialize from an existing directory code: supabase init --workdir . response: Finished supabase init. tags: - local-dev links: [] usage: supabase init [flags] subcommands: [] flags: - id: force name: --force description: Overwrite existing supabase/config.toml. default_value: 'false' - id: use-orioledb name: --use-orioledb description: Use OrioleDB storage engine for Postgres. default_value: 'false' - id: with-intellij-settings name: --with-intellij-settings description: Generate IntelliJ IDEA settings for Deno. default_value: 'false' - id: with-vscode-settings name: --with-vscode-settings description: Generate VS Code settings for Deno. default_value: 'false' - id: supabase-gen title: supabase gen summary: Run code generation tools description: |2 Automatically generates type definitions based on your Postgres database schema. This command connects to your database (local or remote) and generates typed definitions that match your database tables, views, and stored procedures. 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. tags: - local-dev links: [] subcommands: - supabase-gen-keys - supabase-gen-signing-key - supabase-gen-types flags: [] - id: supabase-gen-types title: supabase gen types summary: Generate types from Postgres schema tags: [] links: [] usage: supabase gen types [flags] subcommands: [] flags: - id: db-url name: --db-url description: Generate types from a database url. default_value: '' - id: lang name: --lang <[ typescript | go | swift ]> description: Output language of the generated types. default_value: typescript accepted_values: - id: typescript name: typescript type: '[ typescript | go | swift ]' - id: go name: go type: '[ typescript | go | swift ]' - id: swift name: swift type: '[ typescript | go | swift ]' - id: linked name: --linked description: Generate types from the linked project. default_value: 'false' - id: local name: --local description: Generate types from the local dev database. default_value: 'false' - id: postgrest-v9-compat name: --postgrest-v9-compat description: | Generate types compatible with PostgREST v9 and below. Only use together with --db-url. default_value: 'false' - id: project-id name: --project-id description: Generate types from a project ID. default_value: '' - id: schema name: -s, --schema description: Comma separated list of schema to include. default_value: '[]' - id: swift-access-control name: --swift-access-control <[ internal | public ]> description: Access control for Swift generated types. default_value: internal accepted_values: - id: internal name: internal type: '[ internal | public ]' - id: public name: public type: '[ internal | public ]' - id: supabase-gen-signing-key title: supabase gen signing-key summary: Generate a JWT signing key description: | 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 tags: [] links: [] usage: supabase gen signing-key [flags] subcommands: [] flags: - id: algorithm name: --algorithm <[ RS256 | ES256 ]> description: Algorithm for signing key generation. default_value: ES256 accepted_values: - id: RS256 name: RS256 type: '[ RS256 | ES256 ]' - id: ES256 name: ES256 type: '[ RS256 | ES256 ]' - id: append name: --append description: Append new key to existing keys file instead of overwriting. default_value: 'false' - id: supabase-gen-keys title: supabase gen keys summary: Generate keys for preview branch tags: [] links: [] usage: supabase gen keys [flags] subcommands: [] flags: - id: override-name name: --override-name description: Override specific variable names. default_value: '[]' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: experimental name: --experimental description: enable experimental features required: true default_value: 'false' - id: supabase-functions title: supabase functions summary: Manage Supabase Edge functions description: |2 Manage Supabase Edge Functions. Supabase Edge Functions are server-less functions that run close to your users. Edge Functions allow you to execute custom server-side code without deploying or scaling a traditional server. They're ideal for handling webhooks, custom API endpoints, data validation, and serving personalized content. Edge Functions are written in TypeScript and run on Deno compatible edge runtime, which is a secure runtime with no package management needed, fast cold starts, and built-in security. tags: - management-api links: [] subcommands: - supabase-functions-delete - supabase-functions-deploy - supabase-functions-download - supabase-functions-list - supabase-functions-new - supabase-functions-serve flags: [] - id: supabase-functions-serve title: supabase functions serve summary: Serve all Functions locally description: |2 Serve all Functions locally. `supabase functions serve` command includes additional flags to assist developers in debugging Edge Functions via the v8 inspector protocol, allowing for debugging via Chrome DevTools, VS Code, and IntelliJ IDEA for example. Refer to the [docs guide](/docs/guides/functions/debugging-tools) for setup instructions. 1. `--inspect` * Alias of `--inspect-mode brk`. 2. `--inspect-mode [ run | brk | wait ]` * Activates the inspector capability. * `run` mode simply allows a connection without additional behavior. It is not ideal for short scripts, but it can be useful for long-running scripts where you might occasionally want to set breakpoints. * `brk` mode same as `run` mode, but additionally sets a breakpoint at the first line to pause script execution before any code runs. * `wait` mode similar to `brk` mode, but instead of setting a breakpoint at the first line, it pauses script execution until an inspector session is connected. 3. `--inspect-main` * Can only be used when one of the above two flags is enabled. * By default, creating an inspector session for the main worker is not allowed, but this flag allows it. * Other behaviors follow the `inspect-mode` flag mentioned above. Additionally, the following properties can be customized via `supabase/config.toml` under `edge_runtime` section. 1. `inspector_port` * The port used to listen to the Inspector session, defaults to 8083. 2. `policy` * A value that indicates how the edge-runtime should forward incoming HTTP requests to the worker. * `per_worker` allows multiple HTTP requests to be forwarded to a worker that has already been created. * `oneshot` will force the worker to process a single HTTP request and then exit. (Debugging purpose, This is especially useful if you want to reflect changes you've made immediately.) tags: [] links: [] usage: supabase functions serve [flags] subcommands: [] flags: - id: env-file name: --env-file description: | Path to an env file to be populated to the Function environment. default_value: '' - id: import-map name: --import-map description: Path to import map file. default_value: '' - id: inspect name: --inspect description: Alias of --inspect-mode brk. default_value: 'false' - id: inspect-main name: --inspect-main description: Allow inspecting the main worker. default_value: 'false' - id: inspect-mode name: --inspect-mode <[ run | brk | wait ]> description: Activate inspector capability for debugging. default_value: '' accepted_values: - id: run name: run type: '[ run | brk | wait ]' - id: brk name: brk type: '[ run | brk | wait ]' - id: wait name: wait type: '[ run | brk | wait ]' - id: no-verify-jwt name: --no-verify-jwt description: Disable JWT verification for the Function. default_value: 'false' - id: supabase-functions-new title: supabase functions new summary: Create a new Function locally description: |2 Creates a new Edge Function with boilerplate code in the `supabase/functions` directory. This command generates a starter TypeScript file with the necessary Deno imports and a basic function structure. The function is created as a new directory with the name you specify, containing an `index.ts` file with the function code. After creating the function, you can edit it locally and then use `supabase functions serve` to test it before deploying with `supabase functions deploy`. tags: [] links: [] usage: supabase functions new subcommands: [] flags: [] - id: supabase-functions-list title: supabase functions list summary: List all Functions in Supabase description: List all Functions in the linked Supabase project. tags: [] links: [] usage: supabase functions list [flags] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-functions-download title: supabase functions download summary: Download a Function from Supabase description: | Download the source code for a Function from the linked Supabase project. tags: [] links: [] usage: supabase functions download [flags] subcommands: [] flags: - id: legacy-bundle name: --legacy-bundle description: Use legacy bundling mechanism. default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-functions-deploy title: supabase functions deploy summary: Deploy a Function to Supabase description: Deploy a Function to the linked Supabase project. tags: [] links: [] usage: supabase functions deploy [Function name] [flags] subcommands: [] flags: - id: import-map name: --import-map description: Path to import map file. default_value: '' - id: jobs name: -j, --jobs description: Maximum number of parallel jobs. default_value: '1' - id: no-verify-jwt name: --no-verify-jwt description: Disable JWT verification for the Function. default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: prune name: --prune description: | Delete Functions that exist in Supabase project but not locally. default_value: 'false' - id: use-api name: --use-api description: Use Management API to bundle functions. default_value: 'false' - id: use-docker name: --use-docker description: Use Docker to bundle functions. default_value: 'true' - id: supabase-functions-delete title: supabase functions delete summary: Delete a Function from Supabase description: | Delete a Function from the linked Supabase project. This does NOT remove the Function locally. tags: [] links: [] usage: supabase functions delete [flags] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-encryption title: supabase encryption summary: Manage encryption keys of Supabase projects tags: - management-api links: [] subcommands: - supabase-encryption-get-root-key - supabase-encryption-update-root-key flags: [] - id: supabase-encryption-update-root-key title: supabase encryption update-root-key summary: Update root encryption key of a Supabase project tags: [] links: [] usage: supabase encryption update-root-key subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-encryption-get-root-key title: supabase encryption get-root-key summary: Get the root encryption key of a Supabase project tags: [] links: [] usage: supabase encryption get-root-key subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-domains title: supabase domains summary: Manage custom domain names for Supabase projects description: | Manage custom domain names for Supabase projects. Use of custom domains and vanity subdomains is mutually exclusive. tags: - management-api links: [] subcommands: - supabase-domains-activate - supabase-domains-create - supabase-domains-delete - supabase-domains-get - supabase-domains-reverify flags: [] - id: supabase-domains-reverify title: supabase domains reverify summary: Re-verify the custom hostname config for your project tags: [] links: [] usage: supabase domains reverify subcommands: [] flags: - id: include-raw-output name: --include-raw-output description: Include raw output (useful for debugging). default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-domains-get title: supabase domains get summary: Get the current custom hostname config description: | Retrieve the custom hostname config for your project, as stored in the Supabase platform. tags: [] links: [] usage: supabase domains get subcommands: [] flags: - id: include-raw-output name: --include-raw-output description: Include raw output (useful for debugging). default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-domains-delete title: supabase domains delete summary: Deletes the custom hostname config for your project tags: [] links: [] usage: supabase domains delete subcommands: [] flags: - id: include-raw-output name: --include-raw-output description: Include raw output (useful for debugging). default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-domains-create title: supabase domains create summary: Create a custom hostname description: |- Create a custom hostname for your Supabase project. Expects your custom hostname to have a CNAME record to your Supabase project's subdomain. tags: [] links: [] usage: supabase domains create [flags] subcommands: [] flags: - id: custom-hostname name: --custom-hostname description: The custom hostname to use for your Supabase project. default_value: '' - id: include-raw-output name: --include-raw-output description: Include raw output (useful for debugging). default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-domains-activate title: supabase domains activate summary: Activate the custom hostname for a project description: |2 Activates the custom hostname configuration for a project. This reconfigures your Supabase project to respond to requests on your custom hostname. After the custom hostname is activated, your project's third-party auth providers will no longer function on the Supabase-provisioned subdomain. Please refer to [Prepare to activate your domain](/docs/guides/platform/custom-domains#prepare-to-activate-your-domain) section in our documentation to learn more about the steps you need to follow. tags: [] links: [] usage: supabase domains activate subcommands: [] flags: - id: include-raw-output name: --include-raw-output description: Include raw output (useful for debugging). default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-db title: supabase db summary: Manage Postgres databases tags: - local-dev links: [] subcommands: - supabase-db-diff - supabase-db-dump - supabase-db-lint - supabase-db-pull - supabase-db-push - supabase-db-reset - supabase-db-start flags: [] - id: supabase-db-start title: supabase db start summary: Starts local Postgres database tags: [] links: [] usage: supabase db start [flags] subcommands: [] flags: - id: from-backup name: --from-backup description: Path to a logical backup file. default_value: '' - id: supabase-db-reset title: supabase db reset summary: Resets the local database to current migrations description: |2 Resets the local 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. When running db reset with `--linked` or `--db-url` flag, 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. examples: - id: basic-usage name: Basic usage code: supabase db reset response: | Resetting database... Initializing schema... Applying migration 20220810154537_create_employees_table.sql... Seeding data supabase/seed.sql... Finished supabase db reset on branch main. tags: [] links: [] usage: supabase db reset [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Resets the database specified by the connection string (must be percent-encoded). default_value: '' - id: last name: --last description: Reset up to the last n migration versions. default_value: '0' - id: linked name: --linked description: Resets the linked project with local migrations. default_value: 'false' - id: local name: --local description: Resets the local database with local migrations. default_value: 'true' - id: no-seed name: --no-seed description: Skip running the seed script after reset. default_value: 'false' - id: version name: --version description: Reset up to the specified version. default_value: '' - id: supabase-db-push title: supabase db push summary: Push new migrations to the remote database description: |2 Pushes all local migrations to a remote database. Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag. 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. examples: - id: basic-usage name: Basic usage code: supabase db push response: | Linked project is up to date. - id: self-hosted name: Self hosted code: supabase db push --db-url "postgres://user:pass@127.0.0.1:5432/postgres" response: | Pushing migration 20230410135622_create_employees_table.sql... Finished supabase db push. - id: dry-run name: Dry run code: supabase db push --dry-run response: | DRY RUN: migrations will *not* be pushed to the database. Would push migration 20230410135622_create_employees_table.sql... Would push migration 20230425064254_my_table.sql... Finished supabase db push. tags: [] links: [] usage: supabase db push [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Pushes to the database specified by the connection string (must be percent-encoded). default_value: '' - id: dry-run name: --dry-run description: | Print the migrations that would be applied, but don't actually apply them. default_value: 'false' - id: include-all name: --include-all description: Include all migrations not found on remote history table. default_value: 'false' - id: include-roles name: --include-roles description: Include custom roles from supabase/roles.sql. default_value: 'false' - id: include-seed name: --include-seed description: Include seed data from your config. default_value: 'false' - id: linked name: --linked description: Pushes to the linked project. default_value: 'true' - id: local name: --local description: Pushes to the local database. default_value: 'false' - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: supabase-db-pull title: supabase db pull summary: Pull schema from the remote database description: |2 Pulls schema changes from a remote database. A new migration file will be created under `supabase/migrations` directory. Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag. Optionally, a new row can be inserted into the migration history table to reflect the current state of the remote database. If no entries exist in the migration history table, `pg_dump` will be used to capture all contents of the remote schemas you have created. Otherwise, this command will only diff schema changes against the remote database, similar to running `db diff --linked`. examples: - id: basic-usage name: Basic usage code: supabase db pull response: | Connecting to remote database... Schema written to supabase/migrations/20240414044403_remote_schema.sql Update remote migration history table? [Y/n] Repaired migration history: [20240414044403] => applied Finished supabase db pull. The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them. - id: local-studio name: Local studio code: supabase db pull --local response: | Connecting to local database... Setting up initial schema.... Creating custom roles supabase/roles.sql... Applying migration 20240414044403_remote_schema.sql... No schema changes found The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them. exit status 1 - id: custom-schemas name: Custom schemas code: supabase db pull --schema auth,storage response: | Connecting to remote database... Setting up initial schema.... Creating custom roles supabase/roles.sql... Applying migration 20240414044403_remote_schema.sql... No schema changes found Try rerunning the command with --debug to troubleshoot the error. exit status 1 tags: [] links: [] usage: supabase db pull [migration name] [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Pulls from the database specified by the connection string (must be percent-encoded). default_value: '' - id: linked name: --linked description: Pulls from the linked project. default_value: 'true' - id: local name: --local description: Pulls from the local database. default_value: 'false' - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: schema name: -s, --schema description: Comma separated list of schema to include. default_value: '[]' - id: supabase-db-lint title: supabase db lint summary: Checks local database for typing error description: |2- Lints local database for schema errors. Requires the local development stack to be running when linting against the local database. To lint against a remote or self-hosted database, specify the `--linked` or `--db-url` flag respectively. Runs `plpgsql_check` extension in the local Postgres 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. examples: - id: basic-usage name: Basic usage code: supabase db lint response: | Linting schema: public No schema errors found - id: schema-warnings name: Warnings for a specific schema code: supabase db lint --level warning --schema storage response: | Linting schema: storage [ { "function": "storage.search", "issues": [ { "level": "warning", "message": "unused variable \"_bucketid\"", "sqlState": "00000" } ] } ] tags: [] links: [] usage: supabase db lint [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Lints the database specified by the connection string (must be percent-encoded). default_value: '' - id: fail-on name: --fail-on <[ none | warning | error ]> description: Error level to exit with non-zero status. default_value: none accepted_values: - id: none name: none type: '[ none | warning | error ]' - id: warning name: warning type: '[ none | warning | error ]' - id: error name: error type: '[ none | warning | error ]' - id: level name: --level <[ warning | error ]> description: Error level to emit. default_value: warning accepted_values: - id: warning name: warning type: '[ warning | error ]' - id: error name: error type: '[ warning | error ]' - id: linked name: --linked description: Lints the linked project for schema errors. default_value: 'false' - id: local name: --local description: Lints the local database for schema errors. default_value: 'true' - id: schema name: -s, --schema description: Comma separated list of schema to include. default_value: '[]' - id: supabase-db-dump title: supabase db dump summary: Dumps data or schemas from the remote database description: |2 Dumps contents from a remote database. Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag. 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. examples: - id: basic-usage name: Basic usage code: supabase db dump -f supabase/schema.sql response: | Dumping schemas from remote database... Dumped schema to supabase/schema.sql. - id: role-only name: Role only code: supabase db dump -f supabase/roles.sql --role-only response: | Dumping roles from remote database... Dumped schema to supabase/roles.sql. - id: data-only name: Data only code: supabase db dump -f supabase/seed.sql --data-only response: | Dumping data from remote database... Dumped schema to supabase/seed.sql. tags: [] links: [] usage: supabase db dump [flags] subcommands: [] flags: - id: data-only name: --data-only description: Dumps only data records. default_value: 'false' - id: db-url name: --db-url description: | Dumps from the database specified by the connection string (must be percent-encoded). default_value: '' - id: dry-run name: --dry-run description: Prints the pg_dump script that would be executed. default_value: 'false' - id: exclude name: -x, --exclude description: List of schema.tables to exclude from data-only dump. default_value: '[]' - id: file name: -f, --file description: File path to save the dumped contents. default_value: '' - id: keep-comments name: --keep-comments description: Keeps commented lines from pg_dump output. default_value: 'false' - id: linked name: --linked description: Dumps from the linked project. default_value: 'true' - id: local name: --local description: Dumps from the local database. default_value: 'false' - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: role-only name: --role-only description: Dumps only cluster roles. default_value: 'false' - id: schema name: -s, --schema description: Comma separated list of schema to include. default_value: '[]' - id: use-copy name: --use-copy description: Uses copy statements in place of inserts. default_value: 'false' - id: supabase-db-diff title: supabase db diff summary: Diffs the local database for schema changes description: |2 Diffs schema changes made to the local or remote database. Requires the local development stack to be running when diffing against the local database. To diff against a remote or self-hosted database, specify the `--linked` or `--db-url` flag respectively. Runs [djrobstep/migra](https://github.com/djrobstep/migra) in a container to compare schema differences between the target database and a shadow database. 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. By default, all schemas in the target database are diffed. Use the `--schema public,extensions` flag to restrict diffing to a subset of schemas. While the diff command is able to capture most schema changes, there are cases where it is known to fail. Currently, this could happen if you schema contains: - Changes to publication - Changes to storage buckets - Views with `security_invoker` attributes examples: - id: basic-usage name: Basic usage code: supabase db diff -f my_table response: | Connecting to local database... Creating shadow database... Applying migration 20230425064254_remote_commit.sql... Diffing schemas: auth,extensions,public,storage Finished supabase db diff on branch main. No schema changes found - id: linked-project name: Against linked project code: supabase db diff -f my_table --linked response: | Connecting to local database... Creating shadow database... Diffing schemas: auth,extensions,public,storage Finished supabase db diff on branch main. WARNING: The diff tool is not foolproof, so you may need to manually rearrange and modify the generated migration. Run supabase db reset to verify that the new migration does not generate errors. - id: specific-schema name: For a specific schema code: supabase db diff -f my_table --schema auth response: | Connecting to local database... Creating shadow database... Diffing schemas: auth Finished supabase db diff on branch main. No schema changes found tags: [] links: [] usage: supabase db diff [flags] subcommands: [] flags: - id: db-url name: --db-url description: | Diffs against the database specified by the connection string (must be percent-encoded). default_value: '' - id: file name: -f, --file description: Saves schema diff to a new migration file. default_value: '' - id: linked name: --linked description: Diffs local migration files against the linked project. default_value: 'false' - id: local name: --local description: Diffs local migration files against the local database. default_value: 'true' - id: schema name: -s, --schema description: Comma separated list of schema to include. default_value: '[]' - id: use-migra name: --use-migra description: Use migra to generate schema diff. default_value: 'true' - id: use-pg-schema name: --use-pg-schema description: Use pg-schema-diff to generate schema diff. default_value: 'false' - id: use-pgadmin name: --use-pgadmin description: Use pgAdmin to generate schema diff. default_value: 'false' - id: supabase-config title: supabase config summary: Manage Supabase project configurations tags: - management-api links: [] subcommands: - supabase-config-push flags: [] - id: supabase-config-push title: supabase config push summary: Pushes local config.toml to the linked project description: |2 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. tags: [] links: [] usage: supabase config push subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-completion title: supabase completion summary: Generate the autocompletion script for the specified shell description: | Generate the autocompletion script for supabase for the specified shell. See each sub-command's help for details on how to use the generated script. tags: - other-commands links: [] subcommands: - supabase-completion-bash - supabase-completion-fish - supabase-completion-powershell - supabase-completion-zsh flags: [] - id: supabase-completion-zsh title: supabase completion zsh summary: Generate the autocompletion script for zsh description: | Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once: echo "autoload -U compinit; compinit" >> ~/.zshrc To load completions in your current shell session: source <(supabase completion zsh) To load completions for every new session, execute once: #### Linux: supabase completion zsh > "${fpath[1]}/_supabase" #### macOS: supabase completion zsh > $(brew --prefix)/share/zsh/site-functions/_supabase You will need to start a new shell for this setup to take effect. tags: [] links: [] usage: supabase completion zsh [flags] subcommands: [] flags: - id: no-descriptions name: --no-descriptions description: disable completion descriptions default_value: 'false' - id: supabase-completion-powershell title: supabase completion powershell summary: Generate the autocompletion script for powershell description: | Generate the autocompletion script for powershell. To load completions in your current shell session: supabase completion powershell | Out-String | Invoke-Expression To load completions for every new session, add the output of the above command to your powershell profile. tags: [] links: [] usage: supabase completion powershell [flags] subcommands: [] flags: - id: no-descriptions name: --no-descriptions description: disable completion descriptions default_value: 'false' - id: supabase-completion-fish title: supabase completion fish summary: Generate the autocompletion script for fish description: | Generate the autocompletion script for the fish shell. To load completions in your current shell session: supabase completion fish | source To load completions for every new session, execute once: supabase completion fish > ~/.config/fish/completions/supabase.fish You will need to start a new shell for this setup to take effect. tags: [] links: [] usage: supabase completion fish [flags] subcommands: [] flags: - id: no-descriptions name: --no-descriptions description: disable completion descriptions default_value: 'false' - id: supabase-completion-bash title: supabase completion bash summary: Generate the autocompletion script for bash description: | Generate the autocompletion script for the bash shell. This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager. To load completions in your current shell session: source <(supabase completion bash) To load completions for every new session, execute once: #### Linux: supabase completion bash > /etc/bash_completion.d/supabase #### macOS: supabase completion bash > $(brew --prefix)/etc/bash_completion.d/supabase You will need to start a new shell for this setup to take effect. tags: [] links: [] usage: supabase completion bash subcommands: [] flags: - id: no-descriptions name: --no-descriptions description: disable completion descriptions default_value: 'false' - id: supabase-branches title: supabase branches summary: Manage Supabase preview branches tags: - management-api links: [] subcommands: - supabase-branches-create - supabase-branches-delete - supabase-branches-get - supabase-branches-list - supabase-branches-pause - supabase-branches-unpause - supabase-branches-update flags: [] - id: supabase-branches-update title: supabase branches update summary: Update a preview branch description: Update a preview branch by its name or ID. tags: [] links: [] usage: supabase branches update [name] [flags] subcommands: [] flags: - id: git-branch name: --git-branch description: Change the associated git branch. default_value: '' - id: name name: --name description: Rename the preview branch. default_value: '' - id: persistent name: --persistent description: Switch between ephemeral and persistent branch. default_value: 'false' - id: status name: --status description: Override the current branch status. default_value: '' accepted_values: - id: RUNNING_MIGRATIONS name: RUNNING_MIGRATIONS type: string - id: MIGRATIONS_PASSED name: MIGRATIONS_PASSED type: string - id: MIGRATIONS_FAILED name: MIGRATIONS_FAILED type: string - id: FUNCTIONS_DEPLOYED name: FUNCTIONS_DEPLOYED type: string - id: FUNCTIONS_FAILED name: FUNCTIONS_FAILED type: string - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-branches-unpause title: supabase branches unpause summary: Unpause a preview branch tags: [] links: [] usage: supabase branches unpause [name] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-branches-pause title: supabase branches pause summary: Pause a preview branch tags: [] links: [] usage: supabase branches pause [name] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-branches-list title: supabase branches list summary: List all preview branches description: List all preview branches of the linked project. tags: [] links: [] usage: supabase branches list subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-branches-get title: supabase branches get summary: Retrieve details of a preview branch description: Retrieve details of the specified preview branch. tags: [] links: [] usage: supabase branches get [name] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-branches-delete title: supabase branches delete summary: Delete a preview branch description: Delete a preview branch by its name or ID. tags: [] links: [] usage: supabase branches delete [name] subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-branches-create title: supabase branches create summary: Create a preview branch description: Create a preview branch for the linked project. tags: [] links: [] usage: supabase branches create [name] [flags] subcommands: [] flags: - id: persistent name: --persistent description: Whether to create a persistent branch. default_value: 'false' - id: region name: --region description: Select a region to deploy the branch database. default_value: '' accepted_values: - id: ap-northeast-1 name: ap-northeast-1 type: string - id: ap-northeast-2 name: ap-northeast-2 type: string - id: ap-south-1 name: ap-south-1 type: string - id: ap-southeast-1 name: ap-southeast-1 type: string - id: ap-southeast-2 name: ap-southeast-2 type: string - id: ca-central-1 name: ca-central-1 type: string - id: eu-central-1 name: eu-central-1 type: string - id: eu-west-1 name: eu-west-1 type: string - id: eu-west-2 name: eu-west-2 type: string - id: eu-west-3 name: eu-west-3 type: string - id: sa-east-1 name: sa-east-1 type: string - id: us-east-1 name: us-east-1 type: string - id: us-west-1 name: us-west-1 type: string - id: us-west-2 name: us-west-2 type: string - id: size name: --size description: Select a desired instance size for the branch database. default_value: '' accepted_values: - id: large name: large type: string - id: medium name: medium type: string - id: micro name: micro type: string - id: 12xlarge name: 12xlarge type: string - id: 16xlarge name: 16xlarge type: string - id: 24xlarge name: 24xlarge type: string - id: 24xlarge_high_memory name: 24xlarge_high_memory type: string - id: 24xlarge_optimized_cpu name: 24xlarge_optimized_cpu type: string - id: 24xlarge_optimized_memory name: 24xlarge_optimized_memory type: string - id: 2xlarge name: 2xlarge type: string - id: 48xlarge name: 48xlarge type: string - id: 48xlarge_high_memory name: 48xlarge_high_memory type: string - id: 48xlarge_optimized_cpu name: 48xlarge_optimized_cpu type: string - id: 48xlarge_optimized_memory name: 48xlarge_optimized_memory type: string - id: 4xlarge name: 4xlarge type: string - id: 8xlarge name: 8xlarge type: string - id: pico name: pico type: string - id: small name: small type: string - id: xlarge name: xlarge type: string - id: with-data name: --with-data description: Whether to clone production data to the branch database. default_value: 'false' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-bootstrap title: supabase bootstrap summary: Bootstrap a Supabase project from a starter template tags: - quick-start links: [] usage: supabase bootstrap [template] [flags] subcommands: [] flags: - id: password name: -p, --password description: Password to your remote Postgres database. default_value: '' - id: supabase-backups title: supabase backups summary: Manage Supabase physical backups tags: - management-api links: [] subcommands: - supabase-backups-list - supabase-backups-restore flags: [] - id: supabase-backups-restore title: supabase backups restore summary: Restore to a specific timestamp using PITR tags: [] links: [] usage: supabase backups restore [flags] subcommands: [] flags: - id: timestamp name: -t, --timestamp description: The recovery time target in seconds since epoch. default_value: '0' - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: '' - id: supabase-backups-list title: supabase backups list summary: Lists available physical backups tags: [] links: [] usage: supabase backups list subcommands: [] flags: - id: project-ref name: --project-ref description: Project ref of the Supabase project. default_value: ''