Supabase Migration Tool

Background information

The Supabase Migration Tool supports the following migration scenarios:

• Migrate from Supabase Cloud to Alibaba Cloud RDS Supabase (cloud-to-cloud migration)

• Migrate between Alibaba Cloud RDS Supabase instances (both source and target are Alibaba Cloud RDS Supabase)

The tool provides two modes:

• CLI mode: Run migrations directly from the terminal. Suitable for CI/CD pipelines, Kubernetes Jobs, and script automation.

• Web UI mode: Provides a visual configuration interface, one-click migration, and real-time progress logs.

Migration covers four core data assets: user authentication data, business data, object storage files, and Edge Functions.

Prerequisites

• You have created an RDS Supabase project that is in the Running state. For instructions, see Create an RDS Supabase project.

• You have added the egress IP of the migration tool's host to the IP whitelists for the following services:

  • The IP whitelist of the RDS PostgreSQL instance managed by your RDS Supabase project. This allows direct connections for pg_restore. For instructions, see Configure an IP whitelist.

  • The IP whitelist for your RDS Supabase instance. Add the IP address in the Whitelist Information section on the details page of your RDS Supabase project.

  • You must also add the egress IP of the migration tool to your source Supabase project's IP whitelist.

  Note

  RDS-to-RDS migration: For migrations between RDS Supabase instances, both the source and target PostgreSQL instances managed by RDS Supabase must have public endpoints enabled. Add the migration tool's egress IP to the whitelists of both the source and target instances.

• Python 3.10 or later is installed on the machine where you will run the migration tool.

• PostgreSQL client tools (pg_dump, pg_restore, and psql) are installed on the machine. The client version must be greater than or equal to the higher of the source and target PostgreSQL server versions.

Important notes

• Default database name: The default database for an RDS Supabase instance is supabase_db. You must use this database name in the target connection string, for example, postgresql://postgres:PASSWORD@pgm-xxx.pg.rds.aliyuncs.com:5432/supabase_db. If you connect to the postgres database by mistake, your business tables will be restored to the wrong database.

• Use the cleanup option with caution: If you enable the clean_target_before_restore option, the tool executes DROP SCHEMA ... CASCADE before the restore process begins. All objects and data within the specified schemas on the target are permanently deleted and cannot be recovered. You can enable this option for the initial migration to an empty instance, but ensure it is disabled if the target already contains business data.

• Fixed pipeline order: The migration pipeline order cannot be changed. The Auth pipeline must run before the Database pipeline. Otherwise, foreign key constraints in business tables referencing the auth.users table will cause the Database restore to fail.

• Storage migration overwrite strategy: File uploads use upsert mode. Re-running the migration overwrites files with the same name on the target. The tool only creates buckets that do not exist on the target and does not modify existing bucket properties.

• Auth pipeline migrates data only: The Auth pipeline migrates only data, not Data Definition Language (DDL). The GoTrue service on the target automatically initializes the auth schema, and attempting to re-create it would cause a conflict.

• API deployment for Edge Functions: When deploying Edge Functions using the API method, the agent-runtime service on the target must be running. This service is enabled by default in RDS Supabase.

• RDS-to-RDS migration notes: Both the source and target databases must have public endpoints enabled (configured in the RDS console). Add the migration tool's IP to the whitelists of both instances. For RDS-to-RDS migrations, we recommend enabling clean_target_before_restore to avoid conflicts with residual data.

Step 1: Download the source code and configure migration parameters

First, download the migration tool source code package to obtain the configuration file templates. Then, select the appropriate template based on your migration scenario and fill in the source and target connection details and pipeline settings.

cp config/default.yaml.example config/default.yaml

source:
  project_ref: "your-project-ref"
  database_url: "postgresql://postgres:YOUR_PASSWORD@db.xxx.supabase.co:5432/postgres"
  service_role_key: "eyJ..."
  management_api_token: "sbp_..."
  api_base: "https://xxx.supabase.co"

target:
  project_url: "http://your-rds-supabase/"
  database_url: "postgresql://postgres:YOUR_PASSWORD@pgm-xxx.pg.rds.aliyuncs.com:5432/supabase_db"
  service_role_key: "eyJ..."
  api_base: "http://your-rds-supabase/"

migration:
  auth:
    enabled: false                                        # Cloud Auth data is restricted; disabled by default. Enable manually if needed.
  database:
    enabled: true
    pg_bin_path: "/opt/homebrew/opt/postgresql@17/bin"   # Local deployment: specify client tools directory. Docker: omit.
    clean_target_before_restore: false                    # Use with caution. This runs DROP SCHEMA CASCADE.
  storage:
    enabled: true
  edge_functions:
    enabled: true
    deploy_method: "api"                                  # Recommended. More reliable for RDS Supabase.

cp config/rds-to-rds.example.yaml config/rds-to-rds.yaml

source:
  project_ref: ""                    # Leave empty for RDS
  database_url: "postgresql://postgres:PASSWORD@source-pgm-xxx:5432/supabase_db"
  service_role_key: "eyJ..."
  management_api_token: ""           # Leave empty to auto-detect RDS mode
  api_base: "http://SOURCE_IP/"

target:
  database_url: "postgresql://postgres:PASSWORD@target-pgm-xxx:5432/supabase_db"
  service_role_key: "eyJ..."
  api_base: "http://TARGET_IP/"

migration:
  database:
    enabled: true
    pg_bin_path: "/opt/homebrew/opt/postgresql@17/bin"
    schemas: ["public"]
    clean_target_before_restore: true   # Recommended for RDS-to-RDS migrations
  auth:
    enabled: true
  storage:
    enabled: true
  edge_functions:
    enabled: true
    deploy_method: "api"

export MIGRATOR_SOURCE__DATABASE_URL="postgresql://..."
export MIGRATOR_SOURCE__SERVICE_ROLE_KEY="eyJ..."

Step 2: Deploy the migration tool

After configuring the parameters in Step 1, choose one of the following deployment methods. Docker deployment is recommended. The Docker image includes Python 3.12 and PostgreSQL 18 clients (backward compatible with PG 17 and PG 15), so you do not need to install dependencies manually.

Step 3: Run the migration

Choose a mode based on your deployment method:

Verify the migration

After the migration is complete, verify the data integrity on the target RDS Supabase instance by checking the following areas:

• Verify Auth data: Log in to the RDS Supabase Dashboard and go to Authentication > Users. Compare the total number of users to that of the source project.

• Verify business data: Connect to the supabase_db database on the target. Run the following SQL queries on both the source and target to compare the number of business tables and the row counts of key tables.

  -- Total number of tables
  SELECT count(*) FROM information_schema.tables WHERE table_schema = 'public';
  
  -- Row count of a key table (replace with your actual table name)
  SELECT count(*) FROM public.your_table;

• Verify Storage files: In the RDS Supabase Dashboard, go to Storage. Confirm that the list of buckets is complete. Randomly check a few files in different buckets to ensure they can be previewed or downloaded correctly.

• Verify Edge Functions: Go to the Edge Functions list and confirm that your functions have been deployed successfully. Use curl or the test button in the Dashboard to invoke the functions and verify that they return the expected results.

CLI command reference

The CLI command structure is as follows:

rds-supabase-migrator <command> [pipeline] [options]

Supported commands:

• validate: Validates configuration and connectivity without performing a migration.

• migrate: Runs the migration. Requires a pipeline to be specified.

• serve: Starts the Web UI service. Example: rds-supabase-migrator serve --host 127.0.0.1 --port 8080.

Pipelines supported by the migrate command:

• all: Full migration (executes Auth, Database, Storage, and Edge Functions in order).

• auth: Migrates only user authentication data.

• database: Migrates only the business database.

• storage: Migrates only Storage files.

• edge-functions: Deploys only Edge Functions.

General parameters:

Exit codes:

API reference

When the Web UI is running (default address: http://127.0.0.1:8080), the tool also exposes the following HTTP endpoints for integration or automation scripts:

FAQ

• Q: Can I retry a migration after it fails?
  A: Yes. Each migration run uses a separate temporary directory that is automatically cleaned up afterward, so it does not affect subsequent runs. You can simply click Start Full Migration again in the web UI.
  

• Q: How does the tool handle files in Storage that already exist on the target?
  A: File uploads use upsert mode. Re-running the migration overwrites files with the same name on the target. The tool only creates buckets that do not exist on the target and does not modify existing bucket properties.
  

• Q: What should I do if the Database migration fails with a pg_dump version mismatch error?
  A: The pg_dump client version must be greater than or equal to the higher of the source and target server versions. In your configuration, point the pg_bin_path to a directory that contains a more recent version of the PostgreSQL client tools.
  

• Q: What should I do if an Edge Functions deployment fails?
  A: When using the API deployment method, ensure that the edge-runtime (agent-runtime) service is running correctly on the target and that the target.api_base configuration parameter is set correctly.
  

• Q: Can I migrate only a single pipeline?
  A: Yes. On the Migration page of the web UI, click the corresponding Migrate [Pipeline Name] Only button. Alternatively, call individual API endpoints such as /api/migrate/auth or /api/migrate/database.
  

• Q: How can I view logs in the Docker container?
  A: You can view logs in two ways:
  

  • View real-time logs on the Logs page of the web UI.

  • Run docker logs -f migrator on the host machine to view the container's standard output.

• Q: How can I view migration logs in CLI mode?
  A: In CLI mode, logs are printed directly to the terminal. To save logs to a file, use output redirection: rds-supabase-migrator migrate all -c config/default.yaml 2>&1 | tee migrate.log.
  

• Q: What is the difference between RDS-to-RDS migration and Cloud-to-RDS migration?
  A: The main differences are: (1) For RDS-to-RDS, management_api_token and project_ref on the source are left empty. The tool auto-detects RDS mode. (2) The source database must have a public endpoint enabled with the migration tool's IP added to the whitelist. (3) We recommend enabling clean_target_before_restore to avoid conflicts with residual data.