Complete Migration Guide

AWS DMS: Supabase to Aurora

Step-by-step guide for migrating your Supabase database to AWS Aurora using Database Migration Service

Updated February 2025
Version 2.0
us-east-1

Overview

This guide walks you through migrating your Supabase Helium database to AWS Aurora (helium-mumbai-dev) in us-east-1 using AWS Database Migration Service (DMS). Every step is written so you can follow it one-by-one in the AWS and Supabase consoles without getting lost.

Order of Operations

Follow these steps in sequence for a successful migration:

0

Gather Information

Get Supabase and Aurora connection details

1

Check Database Size

Choose appropriate DMS instance class

2

Pre-Flight Worksheet

Fill in all required values

3

Create Replication Instance

Set up DMS in us-east-1

4

Source Endpoint

Configure Supabase connection

5

Target Endpoint

Configure Aurora connection

6

Migration Task

Set up table mappings and transformations

7

Run & Monitor

Execute migration and track progress

8

Verify Data

Check row counts and data integrity

Part 0: Before You Start – Gather Information

You need three things before touching AWS DMS:

  1. Supabase connection details (host, port, database, user, password)
  2. Supabase database size (so you can pick the right DMS instance class)
  3. Aurora connection details (cluster endpoint, port, database, user, password)

0.1 Get Supabase Connection Details

  1. Open your browser and go to Supabase Dashboard
  2. Log in and select the Helium project
  3. In the left sidebar, click Project Settings (gear icon at the bottom)
  4. In the left menu under Project Settings, click Database
  5. On the Database page you will see:
    • Host: db.gdkwidkzbdwjtzgjezch.supabase.co
    • Port: 5432
    • Database name: postgres
    • User: postgres
    • Password: Click Reveal and copy it
Important

Write these values in the Pre-Flight Worksheet (Part 2)

0.2 Get Aurora Connection Details (Writer Endpoint)

  1. Open AWS Console and switch region to US East (N. Virginia) = us-east-1
  2. In the search bar type RDS and open it
  3. In the left sidebar click Databases
  4. Click the helium-mumbai-dev cluster
  5. Find the Connectivity & security tab
  6. Copy the Writer (cluster) endpoint
    helium-mumbai-dev.cluster-xxxxxxxxxxxx.us-east-1.rds.amazonaws.com
  7. Note:
    • Port: 5432
    • Database name: postgres (or your DB name)
    • User / Password: Master user credentials
Note

Do not use the Reader endpoint for DMS target

Part 1: Know Your Database Size (Choose DMS Instance)

DMS runs on a replication instance. Its size (instance class and storage) should match your database size so the full load finishes in reasonable time and doesn't run out of resources.

1.1 Check Supabase Database Size

Option A – Supabase Dashboard

  1. In Supabase: Project Settings → Database (or Usage)
  2. Look for Database size or Storage

Option B – Run SQL (Recommended)

  1. In Supabase, open SQL Editor
  2. Click New query
  3. Paste this and click Run:
SQL 
SELECT pg_size_pretty(pg_database_size(current_database())) AS db_size;

In the result you will see one row, e.g. 3955 MB or 4 GB. That is your total database size.

For Helium Project

The database size is about 3955 MB (~4 GB)

1.2 Optional: See Size per Schema/Table

To see which tables use the most space:

SQL 
SELECT schemaname, relname AS table_name, n_live_tup AS row_count,
       pg_size_pretty(pg_total_relation_size(schemaname||'.'||relname)) AS total_size
FROM pg_stat_user_tables
WHERE schemaname IN ('public','basejump','auth')
ORDER BY pg_total_relation_size(schemaname||'.'||relname) DESC;

Example for Helium:

  • public.messages – ~3044 MB, ~743k rows
  • public.usage_logs – ~287 MB
  • public.user_dagad_embeddings – ~258 MB
  • auth.audit_log_entries – ~39 MB

1.3 Choose DMS Replication Instance Class and Storage

Database Size Recommended Instance Storage (GiB) Notes
Under 10 GB dms.c5.large 50–100 Good for Helium (~4 GB)
10 GB – 50 GB dms.c5.xlarge 100
50 GB – 200 GB dms.c5.2xlarge 100–200
200 GB – 1 TB dms.c5.4xlarge or larger 200+
For Helium (~4 GB)

Use dms.c5.large and 50 GiB (or 100 GiB to be safe)

Part 2: Pre-Flight Worksheet (Fill This First)

Copy this block and fill the blanks before you start in the AWS Console. That way you can paste values instead of switching between tabs.

Configuration 
=== SOURCE (Supabase Helium) ===
Host:        db.gdkwidkzbdwjtzgjezch.supabase.co
Port:        5432
Database:    postgres
User:        postgres
Password:    ________________ (from Supabase Project Settings → Database)

=== TARGET (Aurora helium-mumbai-dev) ===
Server name: ________________ (from RDS → Databases → helium-mumbai-dev → Endpoint)
Port:        5432
Database:    postgres  (or your DB name)
User:        ________________
Password:    ________________

=== DMS REPLICATION INSTANCE (from Part 1.3) ===
Instance class:  dms.c5.large
Storage (GiB):   50
VPC:             ________________ (same VPC as Aurora – from RDS cluster details)

Part 3: Step-by-Step – Create Replication Instance

  1. Open AWS Console, region us-east-1 (N. Virginia)
  2. Search for DMS or Database Migration Service and open it
  3. In the left sidebar, click Replication instances
  4. Click the orange Create replication instance button
  5. Fill the form exactly as below

Basic Configuration

Field What to Enter
Name helium-supabase-to-aurora (or any name you like)
Description Optional, e.g. Migration from Supabase Helium to Aurora
Instance class Choose dms.c5.large
Engine version Leave default (e.g. 3.4.x)
Multi-AZ Dev or test workload (Single-AZ) to save cost
Allocated storage (GiB) 50 (or 100)

Network Configuration

Field What to Do
VPC Select the same VPC as your Aurora cluster. Find it in RDS → Databases → helium-mumbai-dev → Connectivity & security
Replication subnet group Leave default (or the one that includes private subnets for Aurora)
Publicly accessible Set to Yes so the instance can reach Supabase on the internet
VPC security group(s) Select a security group that allows outbound to Supabase (port 5432) and to Aurora (port 5432 in VPC)
  1. Open the Advanced security and network configuration section if needed
  2. Click Create replication instance
  3. Wait until Status is Available (a few minutes)
Critical Step: Get DMS Instance Public IP
  1. Click your instance name in the Replication instances page
  2. Look for Public IP or IP address and copy it
  3. Go to Supabase Dashboard → Helium project → Project Settings → Database
  4. Find Restrict connections to specific IP addresses
  5. Add the DMS instance public IP (e.g. 52.1.2.3/32). Save.

Without this step, the source endpoint test will fail!

Part 4: Step-by-Step – Create Source Endpoint (Supabase)

  1. In DMS, in the left sidebar click Endpoints
  2. Click Create endpoint
  3. Endpoint type: select Source endpoint
  4. Endpoint configuration – choose Provide access information manually
  5. Fill in using your Pre-Flight worksheet:
Field Value
Endpoint identifier supabase-helium-source
Source engine PostgreSQL
Server name db.gdkwidkzbdwjtzgjezch.supabase.co
Port 5432
User name postgres
Password Your Supabase database password
Database name postgres
SSL mode require (Supabase uses SSL)
  1. Scroll to Test endpoint connection (optional):
    • VPC: Same VPC as your replication instance
    • Replication instance: Select helium-supabase-to-aurora
    • Click Run test
  2. If the test fails:
    • Confirm Supabase Network restrictions allow the DMS instance's public IP
    • Confirm the password and that the user can connect
    • Security group: outbound rule allowing port 5432 to 0.0.0.0/0
  3. When the test shows Successful, click Create endpoint

Part 5: Step-by-Step – Create Target Endpoint (Aurora)

  1. Endpoints → Create endpoint again
  2. Endpoint type: Target endpoint
  3. Endpoint configuration: If you see Select RDS DB instance and your Aurora cluster is listed, you can select helium-mumbai-dev. Otherwise choose Provide access information manually
  4. Fill in:
Field Value
Endpoint identifier aurora-helium-target
Target engine Amazon Aurora PostgreSQL or PostgreSQL
Server name Your Aurora writer endpoint from Pre-Flight worksheet
Port 5432
User name Your Aurora DB user
Password Aurora user password
Database name postgres (or your DB name)
SSL mode prefer or require
  1. Test endpoint connection:
    • VPC: Same as replication instance and Aurora
    • Replication instance: Your DMS replication instance
    • Click Run test
  2. If it fails: check that the replication instance is in the same VPC as Aurora and the security group allows outbound to Aurora on port 5432
  3. When Successful, click Create endpoint

Part 6: Step-by-Step – Create the Migration Task

  1. In the left sidebar click Database migration tasks
  2. Click Create task
  3. Task configuration:
Field Value
Task identifier helium-supabase-aurora-full
Replication instance Your replication instance
Source database endpoint supabase-helium-source
Target database endpoint aurora-helium-target
Migration type Migrate existing data (full load)

Task Settings

  • Target table preparation mode: Do nothing (Aurora tables already exist)
  • Stop task after full-load completes: Stop
  • Include LOB columns: Limited LOB mode with max LOB size (e.g. 64 KB or 1 MB)

Table Mappings (Critical)

5a. Add Selection Rules

Click Add new selection rule:

  • Schema: Enter a schema → Schema name: public → Table name: %
  • Rule action: Include

Click Add new selection rule again:

  • Schema: Enter a schema → Schema name: basejump → Table name: %
  • Rule action: Include

5b. Add Transformation Rule (Rename basejump → helium_auth)

In the same Table mappings section, find Transformation rules:

  • Object locator: Schema name = basejump
  • Rule target: Schema
  • Rule action: Rename
  • Value: helium_auth

5c. JSON Edit Option (Alternative)

If the console has a "JSON" edit option for table mapping, you can paste this:

JSON 
{
  "rules": [
    {
      "rule-type": "selection",
      "rule-id": "1",
      "rule-name": "include-public",
      "object-locator": { "schema-name": "public", "table-name": "%" },
      "rule-action": "include"
    },
    {
      "rule-type": "selection",
      "rule-id": "2",
      "rule-name": "include-basejump",
      "object-locator": { "schema-name": "basejump", "table-name": "%" },
      "rule-action": "include"
    },
    {
      "rule-type": "transformation",
      "rule-id": "3",
      "rule-name": "rename-basejump-to-helium-auth",
      "object-locator": { "schema-name": "basejump" },
      "rule-target": "schema",
      "rule-action": "rename",
      "value": "helium_auth"
    }
  ]
}
  1. Migration task startup configuration:
    • Choose Start task on create to run immediately, or Manually later
  2. Click Create task

Part 7: Run the Migration and Monitor

  1. Open Database migration tasks and click your task helium-supabase-aurora-full
  2. If status is Stopped, click Resume or Start and confirm
  3. Table statistics tab:
    • You'll see each table with state (e.g. Full load completed or Loading)
    • Wait until all tables show Full load completed
    • The largest table (e.g. public.messages) will take the longest
  4. Monitoring tab / CloudWatch:
    • Use the task's CloudWatch log stream to see any errors
  5. If a table fails:
    • Note the table name and the error in the logs
    • Fix (e.g. target table missing, column name different, constraint) and use Reload table
Important

Do not delete the task or replication instance until you've verified data (Part 8)

Part 8: Post-Migration Verification

1. Row Counts on Supabase (Source)

In Supabase SQL Editor run:

SQL 
SELECT schemaname, relname, n_live_tup AS rows
FROM pg_stat_user_tables
WHERE schemaname IN ('public','basejump')
ORDER BY schemaname, relname;

2. Row Counts on Aurora (Target)

Connect to Aurora and run:

SQL 
SELECT schemaname, relname, n_live_tup AS rows
FROM pg_stat_user_tables
WHERE schemaname IN ('public','helium_auth')
ORDER BY schemaname, relname;

3. Compare Results

For each table:

  • public on source should match public on target
  • basejump on source should match helium_auth on target
  • Row counts should match
Note

If pg_stat_user_tables is not updated yet, run ANALYZE; on Aurora and run the query again

4. Spot Check

Pick a few important tables (e.g. public.agents, helium_auth.accounts) and compare a few rows by primary key between Supabase and Aurora.

Troubleshooting

Problem What to Do
Source endpoint test fails
  1. Supabase Network restrictions: add DMS instance public IP
  2. Security group: outbound 5432 to internet
  3. Correct host, port, user, password, SSL = require
Target endpoint test fails
  1. Replication instance in same VPC as Aurora
  2. Security group allows outbound 5432 to Aurora subnet
  3. Correct cluster (writer) endpoint, DB name, user, password
Task fails on a table Open CloudWatch log for the task; find the table and error (e.g. duplicate key, missing column). Fix target schema or add transformation, then Reload that table or restart task
basejump data not in helium_auth Ensure transformation rule is set: schema basejump → rename to helium_auth. Restart task after adding the rule
Very slow full load Increase replication instance class (e.g. to dms.c5.xlarge) or allocated storage; check CloudWatch for CPU/memory

References

Your Environment (Helium)

Supabase project: Helium
Database size: ~3955 MB (~4 GB)
Largest table: public.messages (~3044 MB)
Recommended DMS instance: dms.c5.large, 50 GiB storage
Target: Aurora helium-mumbai-dev, us-east-1
Schemas: public and helium_auth