Supabase迁移工具

背景信息

Supabase迁移工具支持以下迁移场景：

• 从 Supabase Cloud 迁移到阿里云 RDS Supabase（从云端迁出）

• 阿里云 RDS Supabase 实例间迁移（源端和目标端均为阿里云 RDS Supabase）

工具提供两种使用方式：

• CLI模式：终端直接执行迁移，适用于CI/CD、K8s Job、脚本自动化场景。

• Web UI模式：提供可视化配置界面、一键迁移和实时进度日志。

迁移覆盖用户认证数据、业务数据、对象存储文件和边缘函数四类核心数据资产。

前提条件

• 已创建 RDS Supabase 项目并处于运行中状态。创建方法请参见开通RDS Supabase项目。

• 已将运行迁移工具的机器出口 IP 添加到下列实例的白名单中：

  • RDS Supabase 项目托管的 RDS PostgreSQL 实例白名单，用于 pg_restore 直连。添加方法，请参见设置IP白名单。

  • RDS Supabase实例配置白名单，添加方式为在 RDS Supabase 项目详情页的白名单信息区域添加。

  • 源端 Supabase 项目侧也需放通迁移工具的出口 IP。

  说明

  RDS 实例间迁移场景：源端和目标端 RDS Supabase 托管的 PostgreSQL 实例均需开通公网端点，并将迁移工具机器的出口 IP 分别加入源端和目标端的白名单。

• 运行迁移工具的机器已安装 Python 3.10 及以上版本。

• 运行迁移工具的机器已安装 PostgreSQL 客户端工具（pg_dump、pg_restore、psql）,且客户端版本不低于源端和目标端 PostgreSQL 服务器版本中的较高者。

注意事项

• RDS Supabase 默认数据库为supabase_db，目标端连接串中必须使用该数据库名，例如 postgresql://postgres:PASSWORD@pgm-xxx.pg.rds.aliyuncs.com:5432/supabase_db。若误连到 postgres 库，会导致业务表恢复到错误的数据库。

• 谨慎使用清理目标端选项。配置项 clean_target_before_restore 启用后会在恢复前执行 DROP SCHEMA ... CASCADE，目标端该 schema 下的所有对象和数据将被永久删除且不可恢复。首次迁移到空实例时可开启，已有业务数据时请务必关闭。

• 迁移管道顺序不可调整。Auth 必须先于 Database 执行，否则业务表对 auth.users 的外键约束会导致 Database 恢复失败。

• Storage 迁移覆盖策略：文件上传使用 upsert 模式，重复迁移会覆盖目标端同名文件；bucket 仅创建不存在的，不会覆盖已有 bucket 属性。

• Auth 管道仅迁移数据，不迁移 DDL。因为目标端的 GoTrue 服务已自动初始化 auth schema，重复创建会冲突。

• Edge Functions 通过 API 方式部署时需要目标端 agent-runtime 服务正常运行。RDS Supabase 默认已启用该服务。

• RDS 实例间迁移特有注意：源端和目标端 DB 都需要开通公网端点（RDS 控制台操作），并将迁移机 IP 加入白名单。RDS 实例间迁移场景下 clean_target_before_restore 建议开启，以避免残留数据冲突。

步骤一：下载源代码并配置迁移参数

先下载迁移工具源代码包获取配置文件模板，然后根据迁移场景选择对应的模板，填入源端和目标端的连接信息及各管道的开关。

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 数据受限，默认关闭；如需迁移请手动开启
  database:
    enabled: true
    pg_bin_path: "/opt/homebrew/opt/postgresql@17/bin"   # 本地部署时填客户端工具目录；Docker 部署可省略
    clean_target_before_restore: false                    # 谨慎开启，会 DROP SCHEMA CASCADE
  storage:
    enabled: true
  edge_functions:
    enabled: true
    deploy_method: "api"                                  # 推荐 api，RDS Supabase 场景下更可靠

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

source:
  project_ref: ""                    # RDS 留空
  database_url: "postgresql://postgres:PASSWORD@source-pgm-xxx:5432/supabase_db"
  service_role_key: "eyJ..."
  management_api_token: ""           # RDS 留空，自动识别为 RDS 模式
  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   # RDS 实例间迁移建议开启
  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..."

步骤二：部署迁移工具

完成步骤一的配置后，选择以下任一方式部署迁移工具。推荐使用 Docker 方式部署，镜像内已包含 Python 3.12 和 PostgreSQL 18 客户端（向下兼容 PG 17/15），无需手动安装依赖。

步骤三：执行迁移

根据部署方式选择执行模式：

验证迁移结果

迁移完成后，建议从以下几个维度逐一验证目标端 RDS Supabase 的数据完整性：

• 验证 Auth 数据：登录 RDS Supabase Dashboard，进入 Authentication > Users，对比用户总数是否与源端一致。

• 验证业务数据：连接目标端 supabase_db，分别在源端和目标端执行以下 SQL 对比业务表数量和关键表的行数。

  -- 表总数
  SELECT count(*) FROM information_schema.tables WHERE table_schema = 'public';
  
  -- 关键表行数(替换为您的实际表名)
  SELECT count(*) FROM public.your_table;

• 验证 Storage 文件：在 RDS Supabase Dashboard 进入 Storage，确认 bucket 列表完整，并随机抽查若干 bucket 下的文件能正常预览或下载。

• 验证 Edge Functions：进入 Edge Functions 列表，确认函数已成功部署，通过 curl 或 Dashboard 内的测试按钮调用函数验证返回结果是否正常。

CLI 命令参考

CLI模式下的命令结构如下：

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

支持的命令：

• validate：验证配置和连通性，不执行迁移。

• migrate：执行迁移，需指定管道。

• serve：启动 Web UI 服务。示例：rds-supabase-migrator serve --host 127.0.0.1 --port 8080。

migrate 命令支持的管道：

• all：全量迁移（依次执行 Auth、Database、Storage、Edge Functions）。

• auth：仅迁移用户认证数据。

• database：仅迁移业务数据库。

• storage：仅迁移 Storage 文件。

• edge-functions：仅部署 Edge Functions。

通用参数：

退出码：

API 接口

Web UI 模式启动后（默认监听 http://127.0.0.1:8080），迁移工具同时对外暴露以下 HTTP 接口，可用于二次集成或自动化脚本调用：

常见问题

• Q：迁移失败后可以重试吗？
  A：可以。每次迁移使用独立的临时目录（结束后自动清理），不会影响下一次执行。直接在 Web UI 重新点击开始全量迁移即可。
  

• Q：Storage 迁移时目标端已有相同文件怎么处理？
  A：文件上传使用 upsert 模式，重复迁移会覆盖目标端同名文件；bucket 仅创建不存在的，不会覆盖已有 bucket 属性。
  

• Q：Database 迁移报错 pg_dump version mismatch 怎么办？
  A：pg_dump 客户端版本必须不低于源端和目标端中的更高版本。在配置中将 pg_bin_path 指向更高版本的 PostgreSQL 客户端工具目录即可。
  

• Q：Edge Functions 部署失败怎么办？
  A：使用 API 方式部署时，确认目标端的 edge-runtime(agent-runtime)服务正常运行，并且配置项 target.api_base 设置正确。
  

• Q：可以只迁移其中一个管道吗？
  A：可以。在 Web UI 的迁移页面点击对应的仅迁移 XXX按钮，或通过 API 调用 /api/migrate/auth、/api/migrate/database 等单独端点。
  

• Q：Docker 容器中如何查看日志？
  A：两种方式：
  

  • 在 Web UI 的日志页面实时查看。

  • 在迁移工具机器上执行 docker logs -f migrator 查看容器标准输出。

• Q：CLI模式下如何查看迁移日志？
  A：CLI模式下日志直接输出到终端。如需保存日志文件，可使用重定向：rds-supabase-migrator migrate all -c config/default.yaml 2>&1 | tee migrate.log。
  

• Q：RDS 实例间迁移和 Cloud 迁移至 RDS 有什么区别？
  A：主要区别：(1) 源端 management_api_token 和 project_ref 留空，工具自动识别为 RDS 模式；(2) 源端 DB 需开通公网端点并配置白名单；(3) 建议开启 clean_target_before_restore 避免残留数据冲突。