deployment

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

Branch webhook notification payload format

Branch action run completion webhooks follow the Standard Webhooks format. The payload includes: type (string, e.g., 'run.completed'), timestamp (ISO 8601), and data object containing project_ref, details_url, and action_run object with id, created_at, and steps array. Each step has name (clone, pull, health, configure, migrate, seed, deploy), status (e.g., 'exited'), and updated_at timestamp.

Using custom ORM or seed scripts with preview branches

If you want to use your own ORM for managing migrations and seed scripts instead of Supabase's default behavior, you must run them in GitHub Actions after the preview branch is ready. Branch credentials can be fetched using the Supabase CLI in a GitHub Actions workflow.

Subscribe to branch action run completion webhooks

You can register webhook notifications to be triggered when an action run completes on a persistent branch. The webhook payload follows Standard Webhooks format. A single webhook processor is recommended that dispatches events to downstream services based on the payload type. The easiest deployment method is using an Edge Function.

Accessing branch-specific credentials

Each branch has unique credentials. To access them: (1) Switch to your desired branch in the dashboard, (2) Navigate to Settings > API, (3) Copy the branch-specific URLs and keys.

Branch isolation in Supabase

Branches are completely isolated from each other. Changes made in one branch do not affect others. This isolation includes: database schema and data, storage objects, Edge Functions, and auth configurations.

Example: GitHub Actions workflow for custom ORM migrations

This workflow waits for the Supabase Preview check to complete, then fetches branch credentials and runs custom ORM migrations: ```yaml name: Custom ORM on: pull_request: types: - opened - reopened - synchronize branches: - main paths: - 'supabase/**' jobs: wait: runs-on: ubuntu-latest outputs: status: ${{ steps.check.outputs.conclusion }} steps: - uses: fountainhead/action-wait-for-check@v1.2.0 id: check with: checkName: Supabase Preview ref: ${{ github.event.pull_request.head.sha || github.sha }} token: ${{ secrets.GITHUB_TOKEN }} migrate: needs: - wait if: ${{ needs.wait.outputs.status == 'success' }} runs-on: ubuntu-latest env: SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }} SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }} steps: - uses: supabase/setup-cli@v1 with: version: latest - run: supabase --experimental branches get "$GITHUB_HEAD_REF" -o env >> $GITHUB_ENV - name: Custom ORM migration run: psql "$POSTGRES_URL_NON_POOLING" -c 'select 1' ```

Remote development workflow with branches

The remote development workflow involves: (1) Create a preview branch in the Supabase dashboard, (2) Switch to the branch using the branch dropdown, (3) Make schema changes in the dashboard, (4) Pull changes locally using `supabase db pull`, (5) Commit the generated migration files, (6) Push to your Git repository.

Deploy migrations and seed data

Use `supabase db push --include-seed` to deploy all local migration files and execute the seed.sql script on the remote database.

Enable PITR add-on for large databases

If you expect your database size to be greater than 4 GB, enable the Point in Time Recovery (PITR) add-on in the Settings > Add-ons section of the dashboard.

Add multiple owners to Supabase organization

Consider adding multiple owners on your Supabase org from the Organization > Team section of the dashboard. This ensures that if one of the owners is unreachable or loses access to their account, you still have Owner access to your org.

Perform load testing before production

Perform load testing, preferably on a staging environment. Tools like k6 can simulate traffic from many different users.

Enable MFA enforcement on organization

Consider enabling MFA enforcement on your organization to ensure all users must have a valid MFA-backed session to interact with organization and project resources.

Upgrade database resources if needed

Upgrade your database if you require more resources. If you need anything beyond what is listed in the compute and disk table, contact enterprise@supabase.io.

Contact support for expected traffic surges

If you are expecting a surge in traffic for a big launch and are on a Team or Enterprise Plan, contact support with more details about your launch and they will help keep an eye on your project.

Enable multi-factor authentication on Supabase account

Protect your Supabase Account with multi-factor authentication (MFA). If using GitHub sign-in, enable 2FA on GitHub. If using email+password sign-in, set up MFA for your Supabase account.

Free Plan projects may be paused for inactivity

Supabase may pause applications on the Free Plan that exhibit low activity in a 7-day period to save on server resources. Paused projects can be restored from the Supabase dashboard. Upgrading to Pro guarantees that the project won't be paused for inactivity.

Enable SSL enforcement for database connections

Turn on SSL Enforcement from the Database > Settings > SSL Configuration section of the dashboard before production.

Use branching for testing migrations on Pro Plan

If you're on the Pro Plan, consider enabling branching to test migrations in a preview environment before they reach production.

Enable GitHub integration for production deployments

Connect your GitHub repository and enable Deploy to production in the integration settings to automate deployments from your main branch. This ensures schema changes are deployed consistently and avoids manual supabase db push from a local machine.

Review Realtime limits and contact support if needed

Review the Realtime limits documentation. If you need limits increased, contact support.

Enable network restrictions for database access

Enable Network Restrictions for the database from the Database > Settings > Network Restrictions section of the dashboard.

Database backups not available for Free Plan

Database backups are not available for download for Free Plan projects. Read the Database Backups guide for more options and retention details. If you need a lower recovery point objective (RPO), enable Point-in-Time Recovery (PITR) which allows backing up a project at shorter intervals.

Supabase disk durability specifications

Supabase Projects use disks that offer 99.8-99.9% durability by default. Use Read Replicas if you require availability resilience to a disk failure event. Use PITR if you require durability resilience to a disk failure event.

Notice 2 weeks in advance for high load events

Supabase employs safeguards against bursts of incoming traffic to prevent abuse and help maximize stability. If you're on a Team or Enterprise Plan and expect high load events such as production launches, heavy load testing, or prolonged high resource usage, open a ticket via the support form with at least 2 weeks notice.

Fix permission denied error on db pull from graphql schema

When executing `db pull` on long-running Supabase hosted projects, you may encounter 'permission denied for table _type' errors in the graphql schema. Resolve this by granting postgres role permissions to the graphql schema. Run these queries from Supabase dashboard's SQL Editor: `grant all on all tables in schema graphql to postgres, anon, authenticated, service_role;` `grant all on all functions in schema graphql to postgres, anon, authenticated, service_role;` `grant all on all sequences in schema graphql to postgres, anon, authenticated, service_role;`

Fix permission denied error on db push with custom role

If you create a table using a custom database role, the default postgres user may lack permission to modify it, causing 42501 privilege errors during migrations. Resolve this by granting the postgres user ownership of the custom role with: `grant "custom_role" to "postgres";`

Sync production schema to new staging project

To sync initial schema from production to a new staging project, create a new develop branch from main as the source and push to GitHub. The GitHub Actions staging workflow will deploy existing migrations to the staging project. Alternatively, use `supabase db push` locally to apply migrations to a linked remote database, then verify with `supabase migration list`.

Rebase local migrations after teammate merge

When a teammate merges a new migration file to git main and you need to rebase local schema changes, rename your old migration file with a new timestamp. Run `git pull`, then `supabase migration new <migration_name>`, which creates a file with a new timestamp like `<t+2>_<migration_name>.sql`. Rename your old file to match this timestamp pattern, then run `supabase db reset`. If reset fails, manually edit the migration file to resolve conflicts. Commit and push to GitHub.

Production deployment workflow

Create `.github/workflows/production.yml` to deploy migrations to production on pushes to the main branch. Set environment variables SUPABASE_ACCESS_TOKEN, SUPABASE_DB_PASSWORD (PRODUCTION_DB_PASSWORD secret), and SUPABASE_PROJECT_ID (PRODUCTION_PROJECT_ID secret). Steps: checkout code, setup CLI, run `supabase link --project-ref $SUPABASE_PROJECT_ID`, then `supabase db push`. Triggered on push to main branch and workflow_dispatch.

Multi-environment Git and database structure

Use three Git branches with corresponding Supabase projects: feature branches with local databases, develop branch with staging database, and main branch with production database. Only merge to main after verifying staging project migration success.

New staging project requirement

When setting up a new staging project, create a completely new Supabase project. Do not use a project that has already been modified to reflect the production project's schema, because the CLI would reapply these changes.

Auto-generate database migrations from schema changes

Create tables or make schema changes through the Studio UI at localhost:54323. Generate a schema diff migration by running `supabase db diff -f <migration_name>`. This creates a file at `supabase/migrations/<timestamp>_<migration_name>.sql` with auto-generated DDL statements. Without the `-f` flag, output is written to stdout. Use `--use-migra` experimental flag for more concise migration output using the migra tool.

Pipe SQL files to migration creation

The `supabase migration new` command supports stdin as input, allowing you to pipe existing SQL scripts: `supabase migration new <migration_name> < existing_script.sql`.

Create manual database migrations

Create a new migration script by running `supabase migration new <migration_name>`. This creates a file at `supabase/migrations/<timestamp>_<migration_name>.sql`. Write SQL DDL statements directly in this file. Apply the migration to your local database with `supabase db reset`, which recreates the database from scratch and applies all migration scripts in the `supabase/migrations` directory.

Set up local Supabase development with CLI

Initialize a local Supabase repository by running `supabase init`. This creates a new `supabase` directory. Link your local repository to a Supabase project with `supabase login` followed by `supabase link --project-ref $PROJECT_ID`. Your project ID is found in your project's dashboard URL at `https://supabase.com/dashboard/project/<project-id>`.

Pull existing schema changes from Supabase project

If you're using an existing Supabase project with schema changes made through the Dashboard, run `supabase db pull` before making local schema changes from the CLI. This command creates a new migration in `supabase/migrations/<timestamp>_remote_schema.sql` that reflects previously made schema changes.

GitHub Actions environment variables for Supabase CLI

The Supabase CLI requires three environment variables for non-interactive CI/CD execution: SUPABASE_ACCESS_TOKEN (personal access token), SUPABASE_DB_PASSWORD (project-specific database password), and SUPABASE_PROJECT_ID (project-specific reference string). Add these as encrypted secrets in GitHub Actions.

Start local Supabase development

After initializing the Supabase repository and pulling any existing changes, commit to git with `git add .` and `git commit -m "init supabase"`, then run `supabase start` to begin local development.

CI workflow for testing migrations

Create `.github/workflows/ci.yml` to test migrations on pull requests. The workflow checks out code, sets up the Supabase CLI with version latest, starts the local development setup with `supabase db start`, generates TypeScript types with `supabase gen types typescript --local > types.gen.ts`, and verifies no uncommitted changes exist. Triggered on pull_request and workflow_dispatch events.

Staging deployment workflow

Create `.github/workflows/staging.yml` to deploy migrations to staging on pushes to the develop branch. Set environment variables SUPABASE_ACCESS_TOKEN, SUPABASE_DB_PASSWORD (STAGING_DB_PASSWORD secret), and SUPABASE_PROJECT_ID (STAGING_PROJECT_ID secret). Steps: checkout code, setup CLI, run `supabase link --project-ref $SUPABASE_PROJECT_ID`, then `supabase db push`. Triggered on push to develop branch and workflow_dispatch.

Prototyping phase: Dashboard safe for quick development

The Dashboard is a quick and easy tool for building applications while prototyping. However, migrations should still be used to manage database changes, and CLI commands like supabase db diff can capture Dashboard changes for version control.

Production: Point-in-Time Recovery for growing databases

As a database grows, Point-in-Time Recovery is strongly recommended. It is safer and has less impact on database performance during maintenance windows compared to other backup approaches.

Production: Multiple environment workflow

A safe production workflow should use multiple environments following the sequence: local -> staging -> prod. This should be part of the standard development workflow for managing database changes.

Enterprise: Multi-organization setup for security

For a more secure setup, workload can be run across several organizations. A common pattern is to have a Production organization restricted to only those team members qualified to have direct access to production databases.

Production: Database access and migration execution

Production database passwords, especially the postgres password, must never be shared with the team. All changes must be made via version-controlled migrations run through a bastion host or CI platform like GitHub Actions. GitHub Actions approval workflows should be used to prevent accidental migration execution.

Dashboard access levels prevent unwanted changes

The Dashboard has various access levels that can prevent changes being made via the UI, providing additional control over who can modify database schemas in production.

Collaborating phase: Move to migrations and version control

As soon as team members collaborate, all project changes must be in version control. Dashboard should no longer be used for schema changes; migrations must manage the database and be checked into version control to track every change.

Production: Network restrictions for database access

Production access to the database should be restricted using Network Restrictions.

Production phase: Never use Dashboard for database changes

Once an application is live, the database must never be changed using the Dashboard. All changes must be done with Migrations managed through version control.

Shared Responsibility Model overview

Running databases is a shared responsibility between Supabase and the customer. Supabase is responsible for Postgres backups and observability, operating system maintenance, infrastructure and monitoring and security thereof. Shared responsibilities include API rate-limiting, Postgres security controls, upgrades, performance tuning and resource allocation. The customer is responsible for application architecture and implementation, information and data, database schema and user management.

Customer responsibilities: account and data management

The customer is always responsible for their Supabase account, access management (Supabase account, database, tables, etc), data, and applying security controls.

Security responsibility for data access

If you share database access with other people (either team members or the public), it is your responsibility to ensure that the access levels you provide are correctly managed. You should set internal workflows around what different team members should and should not be able to do, with restricted access to avoid anything deemed dangerous. You are responsible for ensuring that tables with sensitive data have the right level of access. You are also responsible for managing your database secrets and API keys, storing them safely in an encrypted store. Supabase provides Row Level Security (RLS) controls and recommends always applying RLS. Security alerts are provided through Security Advisor and applying those recommendations is your responsibility.

HIPAA compliance customer responsibilities

When storing Protected Health Information (PHI) using Supabase, you are responsible for: (1) Signing a Business Associate Agreement (BAA) with Supabase by submitting a HIPAA add-on request (requires at least Team Plan); (2) Marking specific projects as HIPAA projects and addressing security issues raised by the advisor; (3) Ensuring MFA is enabled on all Supabase accounts and enforcing MFA as a requirement to access the organization; (4) Enabling Point in Time Recovery (requires at least a small compute add-on); (5) Turning on SSL Enforcement; (6) Enabling Network Restrictions; (7) Keeping Postgres connection logging enabled (Supabase sets log_connections to off by default for new projects, but HIPAA compliance requires it to be on for audit trails); (8) Complying with encryption requirements in the HIPAA Security Rule (Supabase encrypts data at rest and in transit, but you can also encrypt at the application layer); (9) Not storing PHI in public Storage buckets; (10) Not transferring projects to a non-HIPAA organization.

SOC 2 compliance environment

Supabase provides a SOC 2 compliant environment for hosting and managing sensitive data. Customers should review the SOC 2 compliance responsibilities document alongside the production checklist.

Database control and optimization responsibility

Supabase places very few guard-rails around the database, giving you control but also the ability to break things. You are responsible for using best-practices to optimize and manage your database: adding indexes, adding filters on large queries, using caching strategies, optimizing database queries, and managing connections to the database. You are responsible for provisioning enough compute to run the workload your application requires. The Supabase Dashboard provides observability tooling to help with this.

Database architecture responsibility

Supabase is not a solution for bad architectural decisions. A poorly designed database will perform poorly regardless of where it is hosted. The database schema is the area where you should spend the most time thinking about design. You can add compute to temporarily compensate for poor design, but eventually performance will degrade. The benefit of Supabase is spending more time designing a scalable database system and less time on mundane tasks like implementing CRUD APIs. If you prefer not to implement logic inside the database, you can use any tools that work with Postgres.

Flexibility in development workflows

There are many ways to work with Supabase: using the Dashboard, client libraries, external tools like Prisma and Drizzle, or migration tools like the CLI, Flyway, Sqitch, and any other Postgres-compatible tools. You can develop directly on your database while prototyping, run migrations from local to production, or use multiple environments. None of these approaches are right or wrong—it depends on the project stage. Direct development on the production database should be avoided once in production, but is fine while prototyping without users.

Third-party service integration responsibility

You are responsible for ensuring that the performance, availability, and security of third-party services you integrate with (such as OAuth and SAML login providers, SMTP and SMS sending APIs, calls to external APIs within Postgres functions or triggers, and calls to external APIs within Edge Functions) match your application's requirements. Supabase does not monitor for outages or performance issues within third-party service integrations. An issue with such an integration could result in performance degradation or an outage for your Supabase project. If your application architecture relies on such integrations, you should monitor relevant logs and metrics to ensure optimal performance.

Production readiness requirements

Before going to production, Supabase recommends reviewing and applying the recommendations offered in the Production Checklist, which covers the shared responsibilities and additional general production readiness best practices.

Terraform Provider resources and data sources overview

The Supabase Terraform Provider provides access to resources and data sources. Resources are infrastructure objects such as a Supabase project that you can declaratively configure. Data sources are sources of information about your Supabase instances.

Give your agent this brain