deployment

428 notes in this subject, read out of this brain and free to use. This is page 3 of 8.

Supabase design principle: everything is portable

To avoid lock-in, Supabase makes it easy to migrate in and out. The cloud offering is compatible with the self-hosted product. Supabase uses existing standards like pg_dump and CSV files and will deprecate proprietary approaches in favor of emerging standards.

Studio Column Privileges

Column-level privilege management in Studio is in public alpha status and fully available on self-hosted deployments.

Supabase Branches for testing and previewing changes

Supabase Branches enable you to test and preview changes before deploying. This feature is in beta status and not available on self-hosted deployments.

PrivateLink feature

PrivateLink is in beta status and not available on self-hosted deployments.

Network restrictions for database access

Network restrictions allow you to restrict IP ranges that can connect to your database. This feature is generally available but not available on self-hosted deployments.

Read replicas for multi-region deployment

Read replicas enable deployment of read-only databases across multiple regions for lower latency and better resource management. This feature is generally available but not available on self-hosted deployments.

SSL enforcement for Postgres clients

SSL enforcement requires Postgres clients to connect via SSL. This feature is generally available but not available on self-hosted deployments.

Log drains for third-party log export

Log drains allow you to export Supabase logs to third-party providers and external tooling. This feature is in public alpha status and fully available on self-hosted deployments.

Daily database backups with Point in Time recovery

Projects are backed up daily with an optional upgrade to Point in Time recovery. Point in Time recovery is generally available and can be self-hosted using wal-g.

Terraform provider for Supabase

A Terraform provider allows you to manage Supabase infrastructure via Terraform as Infrastructure as Code. This feature is in public alpha status and not available on self-hosted deployments.

Studio Single Sign-On

Login to the Supabase Studio dashboard via Single Sign-On (SSO). This feature is generally available on both cloud and self-hosted deployments.

Supabase feature status stages

Supabase features go through four stages: Private Alpha (early access only), Public Alpha (API may change but service is stable), Beta (externally tested for security, stable API with strict communication for breaking changes), and Generally Available (covered by uptime SLA).

create-next-app with Supabase template

To create a Next.js app pre-configured with Cookie-based Auth, TypeScript, and Tailwind CSS, run: npx create-next-app -e with-supabase

Query Supabase from Next.js page file location

Create a new file at app/instruments/page.tsx to define a Next.js page that queries Supabase data.

Local development advantages with Supabase

Local development with Supabase provides several advantages: faster development with instant results without waiting for remote deployments, offline work capability without requiring an internet connection, cost-effectiveness since local development is free and doesn't consume your project's quota, enhanced privacy as sensitive data remains on your local machine, and safe testing to experiment with different configurations and features without affecting your production environment.

Local Supabase instance URL

The local Supabase instance runs at http://localhost:54323.

Secure local development stack on public networks

If your local development machine is connected to an untrusted public network, create a separate Docker network and bind to 127.0.0.1 before starting the local development stack to restrict network access to only your localhost machine. Run: docker network create -o 'com.docker.network.bridge.host_binding_ipv4=127.0.0.1' local-network, then npx supabase start --network-id local-network. Never expose your local development stack publicly.

Local Supabase stack includes

Once the local Supabase stack is set up, you have access to a local Postgres database, Auth, Storage, and other Supabase features in a self-contained environment on your local machine.

Automate database tests in CI with GitHub Action

The Supabase team provides a GitHub Action to automate database tests in your CI pipeline.

GitHub Actions workflow for database tests

Set up automated database testing in CI with a GitHub Actions workflow: use supabase/setup-cli@v1 to install Supabase CLI, run 'supabase start' to start the local instance, then run 'supabase test db' to execute database tests. The workflow should trigger on push to main and on pull requests to main.

Prometheus network requirements for Supabase

If Prometheus runs behind a proxy, it must be able to establish outbound HTTPS connections to *.supabase.co.

Prometheus configuration for Supabase metrics

Add a scrape job to prometheus.yml with the following configuration: job_name 'supabase', scrape_interval 60s, metrics_path /customer/v1/privileged/metrics, scheme https, basic_auth with username and password (Secret API key starting with sb_secret_), and static_configs targeting <project-ref>.supabase.co:443 with a project label.

Prometheus Grafana integration steps

To integrate Prometheus with Grafana, go to Connections → Data sources → Add data source, select Prometheus, set the URL to the Prometheus endpoint (for example http://prometheus:9090), and click Save & test.

Prometheus metrics endpoint for self-hosted monitoring

The Supabase Metrics API is available at https://<project-ref>.supabase.co/customer/v1/privileged/metrics and requires HTTP Basic Auth. This endpoint should be scraped at 60-second intervals to match Supabase's refresh cadence.

Prometheus alerting configuration

Import sample alert rules from https://github.com/supabase/supabase-grafana/blob/main/docs/example-alerts.md into Prometheus or Grafana Alerting. Tailor thresholds for disk utilization, long-running transactions, and connection saturation to your project size. Route notifications via Alertmanager, Grafana OnCall, PagerDuty, or other supported destinations.

Multiple Supabase projects monitoring

To monitor multiple projects, add one scrape job per project reference in Prometheus configuration so metrics and labels can be separated cleanly.

Troubleshoot missing metrics in Grafana Cloud

If metrics are missing, ensure the Grafana Cloud agent can reach `https://<project-ref>.supabase.co` and that the Secret API key used is still valid.

Troubleshoot 401 errors in Grafana Cloud scraping

If receiving 401 errors, create or rotate a Secret API key in Project Settings > API Keys and update the Grafana Cloud credentials with the new key.

Troubleshoot long scrape durations in Grafana Cloud

If scrape durations are long, reduce label cardinality in Grafana queries or lower the time range to focus on recent data.

Supabase integration configuration in Grafana Cloud

To configure the Supabase integration in Grafana Cloud: navigate to Connections > Add new connection > Supabase. Provide your Supabase project ref (e.g. `abcd1234`), the Metrics API endpoint (e.g. `https://<project-ref>.supabase.co/customer/v1/privileged/metrics`), and HTTP Basic Auth credentials using the Secret API key (`sb_secret_...`). Choose a scrape interval of 1 minute (recommended) and test the connection. Grafana Cloud will deploy an agent in the background to scrape the Metrics API and forward data to Prometheus.

Grafana Agent integration pipeline alternative

As an alternative to the Supabase integration, you can reuse an existing Grafana Agent deployment by configuring an integration pipeline with the same Metrics API URL and HTTP Basic Auth credentials.

Grafana Cloud stack creation for Supabase

To create a Grafana Cloud stack: sign in to Grafana Cloud at https://grafana.com/auth/sign-in, then create or select a stack that has Prometheus Metrics enabled.

Grafana Cloud integration one-click setup

Grafana Cloud gives a fully managed Prometheus endpoint plus hosted Grafana dashboards. The Supabase Dashboard integrates with Grafana Cloud with one-click, automatically setting up authentication, metric scraping, and a pre-built dashboard tracking 200+ metrics. The recommended approach is to use this integration rather than manual setup.

Import Supabase dashboard to Grafana Cloud

To import the Supabase dashboard: open your Grafana Cloud dashboard list and click New > Import. Paste the raw contents from `https://raw.githubusercontent.com/supabase/supabase-grafana/refs/heads/main/grafana/dashboard.json`. When prompted for the datasource, select the Prometheus instance that receives the Supabase metrics. The dashboard includes 200+ charts grouped by CPU, IO, connections, replication, WAL, and bloat indicators.

Grafana Cloud Metrics API prerequisites

To manually configure Grafana Cloud with Supabase Metrics API, you need: a Supabase project with access to the Metrics API (Secret API key starting with `sb_secret_`); a Grafana Cloud account with Prometheus metrics enabled (Free or Pro tier); and optionally a Grafana API token with the `metrics:write` and `metrics:read` scopes if pushing data manually.

Grafana Cloud alert rules for Supabase

Example alert rules for Supabase are documented in the `docs/example-alerts.md` file in the supabase-grafana repository. These include suggested rules for disk saturation, long-running queries, and replication lag. Import these into Grafana Cloud's Alerting UI or translate them into Grafana Cloud's managed alert rule format.

AWS Marketplace purchases count toward AWS spend commitment

Purchasing Supabase through AWS Marketplace counts toward AWS spend commitments.

AWS Marketplace subscription cancellation window and refund policy

AWS Marketplace subscriptions can be cancelled within 48 hours of purchase by opening a support ticket via the Supabase dashboard. After the 48-hour period, cancellation is no longer possible. If cancelled within the first 48 hours, the upfront charge for the fixed subscription fee will be refunded. Usage costs incurred up to that point will not be refunded.

Spend Cap availability on AWS Marketplace Pro Plan

For organizations on the Pro Plan managed through AWS Marketplace, the Spend Cap feature is not available. However, in the AWS account, users can set up a budget for marketplace purchases or for a specific marketplace product and receive notifications when the budget is exceeded.

Billing implications when linking to AWS Marketplace

When linking a Supabase organization to an AWS Marketplace subscription, billing details from your AWS account are used (billing address and tax ID managed through AWS Billing and Cost Management console). Charges come from AWS rather than Supabase using the default payment method in your AWS account. The Spend Cap for the organization is disabled and not available for AWS-managed organizations.

Free projects limit when downgrading AWS Marketplace subscription

When you downgrade your plan to the Free Plan through AWS Marketplace, all projects within the organization will be paused if you exceed the free projects limit.

AWS Marketplace subscription linked to one organization

An AWS Marketplace subscription is linked to exactly one Supabase organization. If you want to manage multiple organizations through the AWS Marketplace, you must purchase a separate marketplace subscription for each organization.

Effects of linking existing organization to AWS Marketplace

Linking an existing Supabase organization to an AWS Marketplace subscription results in: the organization being upgraded or downgraded to the purchased plan, the billing cycle being adjusted with the start date set to when the marketplace subscription became active, and the credit card on file with Supabase may receive a closing charge covering usage costs incurred until the marketplace subscription became active.

Prerequisites for linking Supabase organization to AWS Marketplace

The Supabase user must have the Owner or Admin role. There must be no overdue invoices within the organization. The organization must not already be managed through another marketplace such as Vercel Marketplace.

AWS Marketplace subscription management

The subscription plan is managed through the AWS Marketplace. Billing and cost management is handled through the AWS Billing and Cost Management console.

Steps to purchase Supabase through AWS Marketplace

Purchasing Supabase through AWS Marketplace involves five steps: (1) Go to the Supabase product page on the AWS Marketplace and click 'View purchase options'. (2) Select the desired plan (Pro Plan or Team Plan) and configure auto-renewal settings. (3) Click 'Subscribe' at the bottom of the page. (4) After payment confirmation and marketplace subscription activation, click 'Set up your account' to be redirected to the Supabase platform. (5) Complete the setup by linking a Supabase organization to the AWS Marketplace subscription on the Supabase platform.

AWS Marketplace vs Direct Supabase Billing Comparison

When managing a Supabase organization through the AWS Marketplace versus directly through the Supabase platform, there are key differences: Available Plans via AWS Marketplace are Pro, Team, and Enterprise (no Free plan), while direct Supabase platform offers Free, Pro, Team, and Enterprise. Mid-cycle downgrades are not available through AWS Marketplace but are available through the direct platform. Cost Control via Spend Cap is not available through AWS Marketplace but is available through the direct platform. For downgrade behavior, AWS Marketplace downgrades to Free Plan will pause all projects if the free projects limit is exceeded with no option to transfer projects, while the direct platform allows you to prevent pausing by transferring projects. Invoicing via AWS Marketplace is separated into two invoices (one for fixed costs, one for usage costs), while direct platform combines both into one invoice.

AWS Marketplace subscription auto-renewal behavior

When purchasing a Supabase subscription through the AWS Marketplace, you can configure whether the subscription should automatically renew after one month. Disabling auto-renewal means the subscription will be downgraded to the Free Plan after one month. If this downgrade causes you to exceed the free projects limit, all projects within the organization will be paused automatically. When projects are paused, you must manually decide which projects to keep active and manually reactivate them through the Supabase dashboard.

AWS Marketplace subscription invoice (Invoice 1)

Invoice 1 has charge type 'subscription'. It covers the fixed subscription fee paid in advance. You receive it at the time of subscription, and in subsequent months on the same day of the month the subscription was started.

AWS Marketplace invoices location

You can view your invoices in the AWS Billing and Cost Management console at https://console.aws.amazon.com/billing/home#/bills under the Bills section.

AWS Marketplace usage invoice (Invoice 2)

Invoice 2 has charge type 'usage'. It covers usage that exceeds the quota included in the plan, or usage not covered by the plan such as Custom Domain add-on, IPv4 add-on, or additionally provisioned Disk IOPS. You receive it no later than the third day of the month for the previous month, covering the period from the first to the last day of the previous month. This billing cycle is independent of your subscription's billing cycle.

AWS Marketplace plan changes workflow

Plan changes for AWS Marketplace subscriptions are not made on the Supabase dashboard. To change your subscription plan: 1) Go to the organization's billing page in the Supabase dashboard, 2) Navigate to the Subscription Plan section, 3) Click 'Change subscription plan', 4) Follow the link in the side panel to the AWS Marketplace.

AWS Marketplace plan upgrade behavior

When upgrading a plan through AWS Marketplace, the new plan becomes active immediately. You are charged a prorated amount for the remainder of the current billing cycle. The upgrade charge factors in any upfront payment already made for the existing plan.

Manage AWS Marketplace payment methods and billing details

Payment methods and billing details (such as billing address or tax ID) for AWS Marketplace subscriptions are managed through the AWS Billing and Cost Management console at https://console.aws.amazon.com/billing, not through Supabase.

Downgrade to Free Plan on AWS Marketplace

To downgrade to the Free Plan at the end of the current billing cycle, you must disable auto-renewal for the marketplace subscription. If the downgrade causes you to exceed the free projects limit for the organization, all projects within the organization will be paused. You must then manually decide which projects to keep active and reactivate them through the Supabase dashboard.

AWS Marketplace plan downgrade timing

Downgrades through AWS Marketplace can only be performed at the end of the billing cycle, not in the middle of a billing cycle.

Downgrade to paid plan on AWS Marketplace

Downgrading to a lower paid plan through AWS Marketplace involves two steps: (1) Turn off auto-renewal to let the current subscription on the higher plan expire, and (2) Start a new subscription on the lower plan.

Production Branch permissions by role

For the Production Branch: Owner, Administrator, and Developer roles have Read and Write permissions. The Guest role has only Read permission and no Write permission.

Development Branches permissions by role

For Development Branches: Owner, Administrator, and Developer roles have List, Create, Update, and Delete permissions. The Guest role has only List permission; Create, Update, and Delete are not permitted.

First branch creation requires Owner or Administrator

When using dashboard branching without a GitHub integration, the first branch creation registers the project's production branch and is a one-time step that requires Owner or Administrator role. After this initial setup, Developers can create, update, and delete branches normally.

Give your agent this brain