如何迁移Supabase项目

迁移路径

• 从Supabase Cloud迁移至AnalyticDB Supabase。

• 从自托管Supabase项目迁移至AnalyticDB Supabase。

• AnalyticDB Supabase项目之间迁移。

迁移内容

• 数据库模式：包括Schema、表结构、函数和触发器等。

• 数据库数据：包括用户数据、auth数据及其他系统数据。

• PostgreSQL扩展：自动在目标项目安装所需插件。

• 存储对象 (Storage)：存储桶（Buckets）和其中的文件。

• 边缘函数 (Edge Functions)：函数代码及其相关配置。

• 角色与权限：数据库的用户和权限设置。

必选参数

• 源环境配置

  • Supabase Cloud源配置

    --source-project-ref string         # 源项目引用ID (必需)
    --source-anon-key string            # 源项目匿名密钥 (必需)
    --source-service-role-key string    # 源项目服务角色密钥 (必需)

  • 自托管Supabase项目或AnalyticDB Supabase

    --source-api-url string             # 源API URL (必需)
    --source-anon-key string            # 源项目匿名密钥 (必需)
    --source-service-role-key string    # 源项目服务角色密钥 (必需)
    --source-database-url string        # 源数据库URL (必需) 且需要 percent-encoded

• 目标环境配置

  --target-api-url string             # 目标API URL(必需)
  --target-anon-key string            # 目标项目匿名密钥 (必需) 
  --target-service-role-key string    # 目标项目服务角色密钥 (必需)
  --target-database-url string        # 目标数据库URL(必需)且需要 percent-encoded

可选参数

• Supabase Cloud源配置

  --source-database-url string        # 源数据库URL (可选) 需要 percent-encoded

• 迁移内容

  --include-data                     # 包含数据库数据（默认：true）
  --include-storage                  # 包含存储对象（默认：true）
  --include-functions                # 包含Edge Functions（默认：true）
  --include-system-data              # 包含系统模块数据（默认：true）

• 执行选项

  --use-local-exec                   # 使用本地执行器，不依赖Docker容器，需要本地按转pgdump等工具
  --concurrency int                  # 并发操作数（默认：2）
  --dry-run                          # 预览模式，不执行实际迁移
  --resume-from string               # 从指定步骤恢复（database|storage|functions）

• 安全选项

  重要

  使用--allow-truncate参数时，请确保源端和目标端配置正确，防止误操作清理源库数据。

  --allow-truncate                  # 允许清理表数据（默认：false）
  --preserve-extra-tables           # 保留目标库额外表（默认：true）

步骤一：获取项目信息并配置环境变量

1. 获取源端配置信息。

   以Supabase Cloud为例，需从项目设置页面获取以下信息。

   • Project Ref：20字符的项目ID。

     • 访问 Supabase 控制台。

     • 单击源端项目，查看URL（例如https://supabase.com/dashboard/project/qeqfhfoebrtkbmwd****），URL末尾即为Project Ref（例如qeqfhfoebrtkbmwd****）。

   • Anon Key：匿名密钥（以eyJ开头）。

   • Service Role Key：服务角色密钥（以eyJ开头），需要具备读取所有数据的权限。

   • Database URL（可选）：PostgreSQL连接字符串。

     单击源端项目页面上方connect，切换到Connection String页签下，Method选择Transaction pooler。

     

2. 获取目标端AnalyticDB Supabase配置信息。具体操作，请参见获取API Keys。

   • API URL：完整的API地址（如 https://your-domain.supabase.opentrust.net）。

   • Anon Key：目标环境的匿名密钥。

   • Service Role Key：目标环境的服务角色密钥，需要具备完整的管理权限。

   • Database URL：PostgreSQL连接字符串，目标数据库用户需要创建表、插件等权限。

3. （可选）建议将项目信息配置到环境变量中，避免在命令行中暴露敏感信息。

   • 从Supabase Cloud迁移至AnalyticDB Supabase

     # 创建配置文件
     cat > migration.env << 'EOF'
     SOURCE_PROJECT_REF="your-project-ref"
     SOURCE_ANON_KEY="eyJ..."
     SOURCE_SERVICE_ROLE_KEY="eyJ..."
     TARGET_API_URL="https://your-domain.supabase.opentrust.net"
     TARGET_ANON_KEY="eyJ..."
     TARGET_SERVICE_ROLE_KEY="eyJ..."
     TARGET_DATABASE_URL="postgres://postgres:password@{your-project-id}.supabase.opentrust.net:5432/postgres"
     EOF
     
     # 加载环境变量
     source migration.env

   • 从自托管Supabase或AnalyticDB Supabase迁移至AnalyticDB Supabase

     # 创建配置文件
     cat > migration.env << 'EOF'
     SOURCE_API_URL="http://localhost:54321"
     SOURCE_ANON_KEY="eyJ..."
     SOURCE_SERVICE_ROLE_KEY="eyJ..."
     SOURCE_DATABASE_URL="postgres://postgres:password@{your-project-id}.supabase.opentrust.net:5432/postgres"
     TARGET_API_URL="https://your-domain.supabase.opentrust.net"
     TARGET_ANON_KEY="eyJ..."
     TARGET_SERVICE_ROLE_KEY="eyJ..."
     TARGET_DATABASE_URL="postgres://postgres:password@{your-project-id}.supabase.opentrust.net:5432/postgres"
     EOF
     
     # 加载环境变量
     source migration.env

步骤二：下载迁移工具并登录

1. 请根据操作系统和架构，下载对应的supabase-cli工具。后续执行相关命令时，请将supabase-cli替换为下载的cli工具名称。

   • supabase-cli-linux-arm64-20260403

   • supabase-cli-linux-arm-20260403

   • supabase-cli-linux-amd64-20260403

   • supabase-cli-linux-386-20260403

   • supabase-cli-windows-amd64-20260403.exe

   • supabase-cli-windows-386-20260403.exe

   • supabase-cli-darwin-amd64-20260403

   • supabase-cli-darwin-arm64-20260403

2. 执行以下命令，并根据提示信息完成登录。

   ./supabase-cli login

步骤三：（可选）预览迁移

• 从Supabase Cloud迁移至AnalyticDB Supabase

  ./supabase-cli migrate-project \
    --source-project-ref "$SOURCE_PROJECT_REF" \
    --source-anon-key "$SOURCE_ANON_KEY" \
    --source-service-role-key "$SOURCE_SERVICE_ROLE_KEY" \
    --target-api-url "$TARGET_API_URL" \
    --target-anon-key "$TARGET_ANON_KEY" \
    --target-service-role-key "$TARGET_SERVICE_ROLE_KEY" \
    --target-database-url "$TARGET_DATABASE_URL" \
    --dry-run

• 从自托管Supabase或AnalyticDB Supabase迁移至AnalyticDB Supabase

  ./supabase-cli migrate-project \
    --source-hosted \
    --source-api-url "$SOURCE_API_URL" \
    --source-anon-key "$SOURCE_ANON_KEY" \
    --source-service-role-key "$SOURCE_SERVICE_ROLE_KEY" \
    --source-database-url "$SOURCE_DATABASE_URL" \
    --target-api-url "$TARGET_API_URL" \
    --target-anon-key "$TARGET_ANON_KEY" \
    --target-service-role-key "$TARGET_SERVICE_ROLE_KEY" \
    --target-database-url "$TARGET_DATABASE_URL" \
    --dry-run

步骤四：迁移Supabase项目

连接源数据库报错“connections refused”，如何解决？

使用以下命令检查网络连接。

# 检查网络连接
ping db.your-project-ref.supabase.co

# 检查数据库URL格式
# 正确格式：postgres://postgres:password@host:port/database

权限报错“permission denied for schema auth”，如何解决？

• 确保使用的是Service role key，而不是Anon key。

• 检查密钥是否有足够的权限，权限要求请参见前提条件。

• 确认目标数据库用户具有管理员权限。

报错“插件 xxx 在目标数据库中不可用”，如何解决？

安装缺失的插件，或在源数据库中移除不必要的插件。

序列冲突报错“relation "test_id_seq" already exists”，如何解决？

参考以下命令：

# 使用更安全的表清理策略
supabase migrate-project ... --preserve-extra-tables=true --allow-truncate=true

数据库连接串中存在特殊字符，如何处理？

建议您将项目配置到环境变量中。如果未配置环境变量，则需对特殊字符转义处理，转义规则如下：

! : %21
@ : %40
# : %23
$ : %24
% : %25
^ : %5e
& : %26
* : %2a
( : %28
) : %29
_ : %5f
+ : %2b
= : %3d