迁移本地数据库的全量备份数据到阿里云RDS SQL Server - 云数据库 RDS

RDS SQL Server提供了将本地SQL Server数据库迁移到阿里云RDS SQL Server的数据库上云方案。您只需将本地SQL Server数据库的全量备份数据上传至阿里云的对象存储服务（OSS），然后通过RDS控制台将全量备份数据上云至指定RDS SQL Server数据库中。适用于数据备份、迁移和灾备恢复等场景。

前提条件

RDS SQL Server实例需满足如下条件：
- 实例剩余空间需大于待上云的数据文件。若空间不足，请提前升级实例空间。
- 2012及以上版本、2008 R2云盘：需确保实例中不存在与待迁移数据库名称相同的数据库。
- 2008 R2高性能本地盘版本：需确保实例中已创建与待迁移数据库名称相同的数据库。

如果通过RAM用户登录，需满足以下条件：
- RAM账号具备AliyunOSSFullAccess权限和AliyunRDSFullAccess权限。如何为RAM用户授权，请参见通过RAM对OSS进行权限管理和通过RAM对RDS进行权限管理。
- 阿里云账号（主账号）已授权RDS官方服务账号可以访问您OSS的权限。
  点击展开查看授权方法
  1. 前往RDS实例详情页备份恢复页面，单击OSS备份数据恢复上云按钮。
  2. 在数据导入向导页面单击两次下一步，进入3. 数据导入步骤。
    
    若该页面左下角显示您已授权RDS官方服务账号可以访问您OSS的权限，则表示已授权。否则表示还未授权，单击该页面的授权地址同意授权即可。
- 所在阿里云账号（主账号）需手动创建权限策略，然后将权限添加到RAM账号中。
  点击展开查看策略内容
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "ram:GetRole"
            ],
            "Resource": "acs:ram:*:*:role/AliyunRDSImportRole",
            "Effect": "Allow"
        }
    ]
}
```

注意事项

迁移级别：本方案仅支持单个数据库的迁移（数据库级）。如需迁移多个或所有数据库，请使用实例级迁移方案。
版本兼容性：备份文件所在本地SQL Server版本不支持迁移到低版本RDS SQL Server实例。
权限管理：授予RDS服务账号访问OSS权限后，系统会在访问控制RAM的角色管理中创建名为AliyunRDSImportRole的角色，请勿修改或删除该角色，否则会导致上云任务失败。若误操作，需通过数据上云向导重新授权。
账号管理：迁移完成后，原有数据库账号无法使用，需在RDS控制台重新创建账号。
OSS文件保留：在上云任务完成前，请勿删除OSS上的备份文件，否则会导致任务失败。
备份文件要求：
- 文件名限制：文件名不得包含特殊字符（如!@#$%^&*()_+-=），否则会导致上云失败。
- 文件后缀：RDS支持的备份文件为.bak（全量备份）、.diff（差异备份）、.trn或.log（日志备份），系统无法识别其他文件类型。
- 文件类型：仅支持上传全量备份文件。不支持差异备份或日志备份。
- 文件来源：若源数据是此前下载的RDS SQL Server全量备份文件（默认为.zip格式），需解压为.bak文件后再进行上云操作。

费用说明

本方案中仅会产生OSS的相关费用，详情如下图所示。

场景	费用说明
将本地数据备份文件上传至OSS	不产生费用。
备份文件存储在OSS	会产生OSS的存储费用，计费详情请参见OSS定价。
将备份文件从OSS迁移至RDS	通过内网迁移至RDS，不产生费用。通过外网迁移至RDS，OSS会产生外网流出流量的费用，计费详情请参见OSS定价。

准备工作

在本地数据库环境中执行DBCC CHECKDB语句，以确保数据库中没有任何的allocation errors和consistency errors。正常执行结果如下：

...
CHECKDB found 0 allocation errors and 0 consistency errors in database 'xxx'.
DBCC execution completed. If DBCC printed error messages, contact your system administrator.

1. 备份本地数据库

请根据RDS SQL Server实例版本，选择对应方案。

2012及以上版本、2008 R2云盘

说明

在对本地数据库做全量备份之前，请确保已停止写入数据。备份过程中新写入的数据将不会被备份。

执行如下命令，确认原数据库当前的恢复模式。

SELECT
    name AS DatabaseName,
    recovery_model_desc AS RecoveryModel,
    state_desc AS State
FROM sys.databases
ORDER BY name;

建议您在生产备份以上云到RDS云数据库之前，将数据库的恢复模式改成FULL：

ALTER DATABASE [db_simple] SET RECOVERY FULL WITH NO_WAIT;

下载备份脚本，用SSMS（SQL Server Management Studio）打开备份脚本。

修改脚本中SELECT语句中的如下参数，位于脚本中YOU HAVE TO INIT PUBLIC VARIABLES HERE下。

配置项	说明
@backup_databases_list	需要备份的数据库，多个数据库以分号（;）或者半角逗号（,）分隔。
@backup_type	备份类型。参数值如下： FULL：全量备份。 DIFF：差异备份。 LOG：日志备份。
@backup_folder	备份文件所在的本地目录。如不存在，会自动创建。
@is_run	是否执行备份。参数值如下： 1：执行备份。 0：只做检查，不执行备份。

执行备份脚本。

2008 R2高性能本地盘

打开Microsoft SQL Server Management Studio（SSMS）客户端。
登录待迁移的数据库。

执行如下命令，确认源数据库当前的恢复模式。

USE master;
GO
SELECT name, CASE recovery_model
WHEN 1 THEN 'FULL'
WHEN 2 THEN 'BULK_LOGGED'
WHEN 3 THEN 'SIMPLE' END model FROM sys.databases
WHERE name NOT IN ('master','tempdb','model','msdb');
GO

如果返回结果中的model值不为FULL，请执行步骤4。
如果返回结果中的model值为FULL，请执行步骤5。

执行如下命令，将源数据库的恢复模式设置为FULL。
```
ALTER DATABASE [dbname] SET RECOVERY FULL;
GO
ALTER DATABASE [dbname] SET AUTO_CLOSE OFF;
GO
```
重要
恢复模式设置为FULL后，会使SQL Server的日志信息增多，请确保具备足够的硬盘空间。
执行如下命令，备份源数据库。

本案例中，将dbtest数据库备份至backup.bak文件为例演示。
```
USE master;
GO
BACKUP DATABASE [dbtest] to disk ='d:\backup\backup.bak' WITH COMPRESSION,INIT;
GO
```
执行如下命令，校验备份文件的完整性。
```
USE master
 GO
 RESTORE FILELISTONLY 
   FROM DISK = N'D:\backup\backup.bak';
```
重要
- 如果有结果集返回，代表备份文件有效。
- 如果提示错误，请重新执行备份操作。
可选：执行如下命令，还原数据库的恢复模式。
重要
如果数据库的恢复模式原本就是FULL，无需执行本步骤。
```
ALTER DATABASE [dbname] SET RECOVERY SIMPLE;
GO
```

2. 上传备份文件到OSS

请根据RDS SQL Server实例版本，选择对应方案。

2012及以上版本、2008 R2云盘

将备份文件上传至OSS前，您需先在OSS中创建存储空间Bucket。

若OSS中已存在Bucket，请确保该Bucket满足以下要求：
- Bucket存储类型存储类型为标准存储。不能是低频访问存储、归档存储、冷归档存储、深度冷归档存储。
- Bucket未开启服务端加密。

若OSS中没有Bucket，需要先行创建。（请确保已开通OSS服务）

登录OSS管理控制台，单击Bucket列表，然后单击创建Bucket。

配置如下关键参数，其他参数可以保持默认。

重要

创建的存储空间主要用于本次数据上云，只需配置关键参数即可，上云完成后可以及时删除以避免数据泄露及产生相关费用。
创建Bucket时请勿开启服务端加密。

参数	说明	取值示例
Bucket 名称	存储空间名称，全局唯一，设置后无法修改。命名规则：只能包括小写字母、数字和短划线（-）。必须以小写字母或者数字开头和结尾。长度必须在3~63字符之间。	migratetest
地域	Bucket所属的地域，如果您通过ECS内网上传数据至Bucket中，且通过内网将数据恢复至RDS中，则需要三者地域保持一致。	华东1（杭州）
存储类型	选择标准存储。本文上云操作不支持其他存储类型的Bucket。	标准存储

上传备份文件到OSS。

本地数据库备份完成后，请将备份文件上传到与您的RDS实例同地域的OSS Bucket中，两者处于同一地域时可通过内网互通（不会产生外网流量费用），且数据上传速度更快。您可以采用如下方法之一：

使用ossbrowser工具上传（推荐）

下载ossbrowser。
以Windows x64操作系统为例，解压下载的oss-browser-win32-x64.zip压缩包，双击运行oss-browser.exe应用程序。
使用AK登录方式，配置参数AccessKeyId和AccessKeySecret，其他参数保持默认，然后单击登入。

说明
AccessKey用于身份验证，确保数据安全，请妥善保管。
单击目标Bucket，进入存储空间。
单击，选择需要上传的备份文件，然后单击打开，即可将本地文件上传至OSS中。

使用OSS控制台上传

说明

如果备份文件小于5 GB，建议您直接通过OSS控制台上传备份文件。

登录OSS管理控制台。
单击Bucket列表，然后单击目标Bucket名称。
在文件列表中，单击上传文件。
您可以将备份文件拖拽至待上传文件区域，也可以单击扫描文件，选择需要上传的备份文件。
单击页面下方的上传文件，即可将本地备份文件上传至OSS中。

使用OSS API分片上传（以Python 3项目为例）

说明

如果备份文件大于5 GB，建议您调用OSS API采用分片上传的方式将备份文件上传到OSS Bucket中。

# -*- coding: utf-8 -*-
"""
Alibaba Cloud OSS Python SDK v2
依赖：pip install alibabacloud-oss-v2
"""

import os
import sys
from pathlib import Path
import alibabacloud_oss_v2 as oss
from alibabacloud_oss_v2 import exceptions as oss_ex


def get_client_from_env(region: str, endpoint: str | None = None) -> oss.Client:
    """
    从环境变量创建 v2 客户端。
    - 优先使用 Region（推荐），也支持自定义 Endpoint（可选）。
    - 同时兼容 AK 与 STS：
        * AK: 需要 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET
        * STS: 另需 OSS_SESSION_TOKEN（兼容旧变量 OSS_SECURITY_TOKEN）
    """
    # 兼容：如果用户使用了老变量 OSS_SECURITY_TOKEN，则映射到 v2 期望的 OSS_SESSION_TOKEN
    sec_token_legacy = os.getenv("OSS_SECURITY_TOKEN")
    if sec_token_legacy and not os.getenv("OSS_SESSION_TOKEN"):
        os.environ["OSS_SESSION_TOKEN"] = sec_token_legacy

    ak = os.getenv("OSS_ACCESS_KEY_ID")
    sk = os.getenv("OSS_ACCESS_KEY_SECRET")
    st = os.getenv("OSS_SESSION_TOKEN")  # STS Token（可选）

    if not (ak and sk):
        raise ValueError("未找到有效的 AK，请设置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。"
                         "如使用 STS，请同时设置 OSS_SESSION_TOKEN（或旧名 OSS_SECURITY_TOKEN）。")

    # 提示所用凭据类型
    if st:
        print("检测到 STS Token（OSS_SESSION_TOKEN），使用 STS 凭证。")
    else:
        print("未检测到 STS Token，使用 AccessKey (AK) 凭证。")

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 基本网络配置
    cfg.region = region  # 例如：'cn-hangzhou'
    if endpoint:
        # 可选：自定义 Endpoint（如内网、加速、专有域）
        cfg.endpoint = endpoint

    # 也可以在此添加其它配置，如：cfg.use_accelerate_endpoint = True
    return oss.Client(cfg)


def resumable_upload_file_v2(
    client: oss.Client,
    bucket_name: str,
    object_key: str,
    file_path: str,
    part_size: int = 1 * 1024 * 1024,
    parallel_num: int = 4,
    checkpoint_dir: str | None = None,
):
    """
    实现分片并发 + 断点续传上传。

    :param client: 已初始化的 oss.Client
    :param bucket_name: 目标 Bucket 名称
    :param object_key: 目标 Object Key（不包含 Bucket 名）
    :param file_path: 本地文件完整路径
    :param part_size: 分片大小（单位：字节），默认 1MB
    :param parallel_num: 并发上传线程数，默认 4
    :param checkpoint_dir: 断点信息存储目录；若为 None，则不启用断点续传
    """
    file_path = str(file_path)
    if not Path(file_path).exists():
        raise FileNotFoundError(f"错误: 本地文件未找到，请检查 file_path 配置: {file_path}")

    # 构造 Uploader；根据是否传入checkpoint_dir来启用断点续传
    if checkpoint_dir:
        uploader = client.uploader(
            enable_checkpoint=True,
            checkpoint_dir=checkpoint_dir,
            part_size=part_size,
            parallel_num=parallel_num,
        )
    else:
        uploader = client.uploader(
            part_size=part_size,
            parallel_num=parallel_num,
        )

    print(f"开始上传文件: {file_path}")
    print(f"目标 Bucket: {bucket_name}")
    print(f"目标 Object: {object_key}")
    print(f"分片大小: {part_size} 字节, 并发数: {parallel_num}")
    if checkpoint_dir:
        print(f"断点续传: 已启用（checkpoint_dir={checkpoint_dir}）")
    else:
        print("断点续传: 未启用（如需启用请设置 checkpoint_dir）")

    # 执行上传（Uploader 会自动根据大小选择多/单分片并发上传）
    result = uploader.upload_file(
        oss.PutObjectRequest(bucket=bucket_name, key=object_key),
        filepath=file_path,
    )

    print("-" * 30)
    print("文件上传成功!")
    print(f"HTTP Status: {result.status_code}")
    print(f"ETag: {result.etag}")
    print(f"请求 ID: {result.request_id}")
    # CRC64 校验值；v2 默认启用数据校验
    print(f"CRC64: {result.hash_crc64}")
    print("-" * 30)


def main():
    # 运行代码示例之前，请确保已设置相应的环境变量。
    # macOS/Linux:
    #   AK方式:
    #     export OSS_ACCESS_KEY_ID=YOUR_AK_ID
    #     export OSS_ACCESS_KEY_SECRET=YOUR_AK_SECRET
    #   STS方式:
    #     export OSS_ACCESS_KEY_ID=YOUR_STS_ID
    #     export OSS_ACCESS_KEY_SECRET=YOUR_STS_SECRET
    #     export OSS_SECURITY_TOKEN=YOUR_STS_TOKEN
    #
    # Windows:
    #   Powershell: $env:OSS_ACCESS_KEY_ID="YOUR_AK_ID"
    #   cmd: set OSS_ACCESS_KEY_ID=YOUR_AK_ID

    # ===================== 参数区（按需修改） =====================
    # Region 示例：'cn-hangzhou'；建议优先使用 Region
    region = "cn-hangzhou"

    # 可选：自定义 Endpoint（如需内网、专有域、加速域名等）
    # 例如：'https://oss-cn-hangzhou.aliyuncs.com'
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'  

    # Bucket 与 Object
    bucket_name = "examplebucket"
    object_key = "test.bak"

    # 待上传的本地文件完整路径。
    # Windows示例: r'D:\localpath\examplefile.txt'  (注意前面的 r)
    # macOS/Linux示例: '/Users/test/examplefile.txt'
    file_path = r"D:\oss\test.bak"

    # 分片与并发
    part_size = 1 * 1024 * 1024  # 默认 1MB；OSS 要求单片最小 100KB
    parallel_num = 4

    # 断点续传目录（传 None 则不启用；建议指定到一个可写目录）
    checkpoint_dir = str(Path.cwd() / ".oss_checkpoints")
    # =================== 参数区结束 ===================

    print("脚本开始执行...")
    try:
        client = get_client_from_env(region=region, endpoint=endpoint)
        # 若启用断点续传，确保目录存在
        if checkpoint_dir:
            Path(checkpoint_dir).mkdir(parents=True, exist_ok=True)

        resumable_upload_file_v2(
            client=client,
            bucket_name=bucket_name,
            object_key=object_key,
            file_path=file_path,
            part_size=part_size,
            parallel_num=parallel_num,
            checkpoint_dir=checkpoint_dir,
        )
    except FileNotFoundError as e:
        print(e)
    except oss_ex.ServiceError as e:
        # OSS 服务端返回的错误
        print("\n发生 OSS 服务端错误。")
        print(f"HTTP Status: {getattr(e, 'status_code', 'N/A')}")
        print(f"Error Code: {getattr(e, 'code', 'N/A')}")
        print(f"Message: {getattr(e, 'message', 'N/A')}")
        print(f"Request ID: {getattr(e, 'request_id', 'N/A')}")
        print(f"Endpoint: {getattr(e, 'request_target', 'N/A')}")
    except oss_ex.BaseError as e:
        # SDK 本地/序列化/反序列化/凭据等错误
        print("\n发生 OSS SDK 客户端错误。")
        print(str(e))
    except Exception as e:
        print(f"\n发生未知错误: {e}")


if __name__ == "__main__":
    main()

2008 R2高性能本地盘

将备份文件上传至OSS前，您需先在OSS中创建存储空间Bucket。

若OSS中已存在Bucket，请确保该Bucket满足以下要求：
- Bucket存储类型存储类型为标准存储。不能是低频访问存储、归档存储、冷归档存储、深度冷归档存储。
- Bucket未开启服务端加密。

若OSS中没有Bucket，需要先行创建。（请确保已开通OSS服务）

登录OSS管理控制台，单击Bucket列表，然后单击创建Bucket。

配置如下关键参数，其他参数可以保持默认。

重要

创建的存储空间主要用于本次数据上云，只需配置关键参数即可，上云完成后可以及时删除以避免数据泄露及产生相关费用。
创建Bucket时请勿开启服务端加密。

参数	说明	取值示例
Bucket 名称	存储空间名称，全局唯一，设置后无法修改。命名规则：只能包括小写字母、数字和短划线（-）。必须以小写字母或者数字开头和结尾。长度必须在3~63字符之间。	migratetest
地域	Bucket所属的地域，如果您通过ECS内网上传数据至Bucket中，且通过内网将数据恢复至RDS中，则需要三者地域保持一致。	华东1（杭州）
存储类型	选择标准存储。本文上云操作不支持其他存储类型的Bucket。	标准存储

上传备份文件到OSS。

使用ossbrowser工具上传（推荐）

下载ossbrowser。
以Windows x64操作系统为例，解压下载的oss-browser-win32-x64.zip压缩包，双击运行oss-browser.exe应用程序。
使用AK登录方式，配置参数AccessKeyId和AccessKeySecret，其他参数保持默认，然后单击登入。

说明
AccessKey用于身份验证，确保数据安全，请妥善保管。
单击目标Bucket，进入存储空间。
单击，选择需要上传的备份文件，然后单击打开，即可将本地文件上传至OSS中。

使用OSS控制台上传

说明

如果备份文件小于5 GB，建议您直接通过OSS控制台上传备份文件。

登录OSS管理控制台。
单击Bucket列表，然后单击目标Bucket名称。
在文件列表中，单击上传文件。
您可以将备份文件拖拽至待上传文件区域，也可以单击扫描文件，选择需要上传的备份文件。
单击页面下方的上传文件，即可将本地备份文件上传至OSS中。

使用OSS API分片上传（以Python 3项目为例）

说明

如果备份文件大于5 GB，建议您调用OSS API采用分片上传的方式将备份文件上传到OSS Bucket中。

# -*- coding: utf-8 -*-
"""
Alibaba Cloud OSS Python SDK v2
依赖：pip install alibabacloud-oss-v2
"""

import os
import sys
from pathlib import Path
import alibabacloud_oss_v2 as oss
from alibabacloud_oss_v2 import exceptions as oss_ex


def get_client_from_env(region: str, endpoint: str | None = None) -> oss.Client:
    """
    从环境变量创建 v2 客户端。
    - 优先使用 Region（推荐），也支持自定义 Endpoint（可选）。
    - 同时兼容 AK 与 STS：
        * AK: 需要 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET
        * STS: 另需 OSS_SESSION_TOKEN（兼容旧变量 OSS_SECURITY_TOKEN）
    """
    # 兼容：如果用户使用了老变量 OSS_SECURITY_TOKEN，则映射到 v2 期望的 OSS_SESSION_TOKEN
    sec_token_legacy = os.getenv("OSS_SECURITY_TOKEN")
    if sec_token_legacy and not os.getenv("OSS_SESSION_TOKEN"):
        os.environ["OSS_SESSION_TOKEN"] = sec_token_legacy

    ak = os.getenv("OSS_ACCESS_KEY_ID")
    sk = os.getenv("OSS_ACCESS_KEY_SECRET")
    st = os.getenv("OSS_SESSION_TOKEN")  # STS Token（可选）

    if not (ak and sk):
        raise ValueError("未找到有效的 AK，请设置环境变量 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET。"
                         "如使用 STS，请同时设置 OSS_SESSION_TOKEN（或旧名 OSS_SECURITY_TOKEN）。")

    # 提示所用凭据类型
    if st:
        print("检测到 STS Token（OSS_SESSION_TOKEN），使用 STS 凭证。")
    else:
        print("未检测到 STS Token，使用 AccessKey (AK) 凭证。")

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 基本网络配置
    cfg.region = region  # 例如：'cn-hangzhou'
    if endpoint:
        # 可选：自定义 Endpoint（如内网、加速、专有域）
        cfg.endpoint = endpoint

    # 也可以在此添加其它配置，如：cfg.use_accelerate_endpoint = True
    return oss.Client(cfg)


def resumable_upload_file_v2(
    client: oss.Client,
    bucket_name: str,
    object_key: str,
    file_path: str,
    part_size: int = 1 * 1024 * 1024,
    parallel_num: int = 4,
    checkpoint_dir: str | None = None,
):
    """
    实现分片并发 + 断点续传上传。

    :param client: 已初始化的 oss.Client
    :param bucket_name: 目标 Bucket 名称
    :param object_key: 目标 Object Key（不包含 Bucket 名）
    :param file_path: 本地文件完整路径
    :param part_size: 分片大小（单位：字节），默认 1MB
    :param parallel_num: 并发上传线程数，默认 4
    :param checkpoint_dir: 断点信息存储目录；若为 None，则不启用断点续传
    """
    file_path = str(file_path)
    if not Path(file_path).exists():
        raise FileNotFoundError(f"错误: 本地文件未找到，请检查 file_path 配置: {file_path}")

    # 构造 Uploader；根据是否传入checkpoint_dir来启用断点续传
    if checkpoint_dir:
        uploader = client.uploader(
            enable_checkpoint=True,
            checkpoint_dir=checkpoint_dir,
            part_size=part_size,
            parallel_num=parallel_num,
        )
    else:
        uploader = client.uploader(
            part_size=part_size,
            parallel_num=parallel_num,
        )

    print(f"开始上传文件: {file_path}")
    print(f"目标 Bucket: {bucket_name}")
    print(f"目标 Object: {object_key}")
    print(f"分片大小: {part_size} 字节, 并发数: {parallel_num}")
    if checkpoint_dir:
        print(f"断点续传: 已启用（checkpoint_dir={checkpoint_dir}）")
    else:
        print("断点续传: 未启用（如需启用请设置 checkpoint_dir）")

    # 执行上传（Uploader 会自动根据大小选择多/单分片并发上传）
    result = uploader.upload_file(
        oss.PutObjectRequest(bucket=bucket_name, key=object_key),
        filepath=file_path,
    )

    print("-" * 30)
    print("文件上传成功!")
    print(f"HTTP Status: {result.status_code}")
    print(f"ETag: {result.etag}")
    print(f"请求 ID: {result.request_id}")
    # CRC64 校验值；v2 默认启用数据校验
    print(f"CRC64: {result.hash_crc64}")
    print("-" * 30)


def main():
    # 运行代码示例之前，请确保已设置相应的环境变量。
    # macOS/Linux:
    #   AK方式:
    #     export OSS_ACCESS_KEY_ID=YOUR_AK_ID
    #     export OSS_ACCESS_KEY_SECRET=YOUR_AK_SECRET
    #   STS方式:
    #     export OSS_ACCESS_KEY_ID=YOUR_STS_ID
    #     export OSS_ACCESS_KEY_SECRET=YOUR_STS_SECRET
    #     export OSS_SECURITY_TOKEN=YOUR_STS_TOKEN
    #
    # Windows:
    #   Powershell: $env:OSS_ACCESS_KEY_ID="YOUR_AK_ID"
    #   cmd: set OSS_ACCESS_KEY_ID=YOUR_AK_ID

    # ===================== 参数区（按需修改） =====================
    # Region 示例：'cn-hangzhou'；建议优先使用 Region
    region = "cn-hangzhou"

    # 可选：自定义 Endpoint（如需内网、专有域、加速域名等）
    # 例如：'https://oss-cn-hangzhou.aliyuncs.com'
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'  

    # Bucket 与 Object
    bucket_name = "examplebucket"
    object_key = "test.bak"

    # 待上传的本地文件完整路径。
    # Windows示例: r'D:\localpath\examplefile.txt'  (注意前面的 r)
    # macOS/Linux示例: '/Users/test/examplefile.txt'
    file_path = r"D:\oss\test.bak"

    # 分片与并发
    part_size = 1 * 1024 * 1024  # 默认 1MB；OSS 要求单片最小 100KB
    parallel_num = 4

    # 断点续传目录（传 None 则不启用；建议指定到一个可写目录）
    checkpoint_dir = str(Path.cwd() / ".oss_checkpoints")
    # =================== 参数区结束 ===================

    print("脚本开始执行...")
    try:
        client = get_client_from_env(region=region, endpoint=endpoint)
        # 若启用断点续传，确保目录存在
        if checkpoint_dir:
            Path(checkpoint_dir).mkdir(parents=True, exist_ok=True)

        resumable_upload_file_v2(
            client=client,
            bucket_name=bucket_name,
            object_key=object_key,
            file_path=file_path,
            part_size=part_size,
            parallel_num=parallel_num,
            checkpoint_dir=checkpoint_dir,
        )
    except FileNotFoundError as e:
        print(e)
    except oss_ex.ServiceError as e:
        # OSS 服务端返回的错误
        print("\n发生 OSS 服务端错误。")
        print(f"HTTP Status: {getattr(e, 'status_code', 'N/A')}")
        print(f"Error Code: {getattr(e, 'code', 'N/A')}")
        print(f"Message: {getattr(e, 'message', 'N/A')}")
        print(f"Request ID: {getattr(e, 'request_id', 'N/A')}")
        print(f"Endpoint: {getattr(e, 'request_target', 'N/A')}")
    except oss_ex.BaseError as e:
        # SDK 本地/序列化/反序列化/凭据等错误
        print("\n发生 OSS SDK 客户端错误。")
        print(str(e))
    except Exception as e:
        print(f"\n发生未知错误: {e}")


if __name__ == "__main__":
    main()

设置备份文件的链接有效时间，并获取文件的链接地址。
1. 登录OSS 管理控制台。
2. 单击Bucket 列表，然后单击目标Bucket名称。
3. 在左侧导航栏，选择文件管理 > 文件列表。
4. 单击目标数据库备份文件操作列的详情，在弹出面板中，将过期时间 (秒)修改为28800秒，即8小时。
  
  重要
  将备份文件从OSS迁移至RDS时，需要使用备份文件的链接地址，如果超过了链接有效时间，将导致数据迁移失败。
5. 单击复制文件URL，获取文件的链接地址。
6. 修改获取到的数据备份文件链接地址。
  
  默认获取的是文件的外网连接地址，如需通过内网迁移数据，您需要将文件链接地址中的Endpoint改成内网Endpoint。
  
  例如，备份文件的链接地址为http://rdstest.oss-cn-shanghai.aliyuncs.com/testmigraterds_20170906143807_FULL.bak?Expires=15141****&OSSAccessKeyId=TMP****，您需要将链接地址中的oss-cn-shanghai.aliyuncs.com修改为oss-cn-shanghai-internal.aliyuncs.com。
  
  重要
  不同的网络类型、不同地域所对应的内网Endpoint不同。具体详情，请参见访问域名和数据中心。

3. OSS备份数据导入RDS

请根据RDS SQL Server实例版本，选择对应方案。

2012及以上版本、2008 R2云盘

访问RDS实例列表，在上方选择地域，然后单击目标实例ID。
在左侧菜单栏中选择备份恢复。
单击页面上方的OSS备份数据恢复上云。
在数据导入向导页面，单击两次下一步，进入数据导入步骤。
说明
- 首次使用OSS备份数据恢复上云功能，需授权RDS账号访问OSS，请单击授权地址并同意授权，否则会因权限问题导致OSS Bucket下拉列表为空。
- 在该页面选不到目标文件时，请检查OSS内备份文件后缀是否符合要求（可在本文注意事项查看后缀要求），并确保RDS实例与OSS Bucket处于同一地域。

设置如下参数。

配置项	说明
数据库名	备份数据导入目标RDS实例上的数据库名，名称需要符合SQL Server官方限制。重要进行上云操作前，请确保目标实例上不存在与备份文件指定要还原的数据库名称相同的数据库，也不存在相同名称的未附加数据库文件。若都不存在，则可以使用备份集中同名数据库文件名称还原数据库。如果目标实例上存在与备份文件指定要还原的数据库名称相同的数据库，或者存在同名的未附加数据库文件，上云操作将失败。
OSS Bucket	选择备份文件所在的OSS Bucket。
OSS文件列表	单击右侧按钮，可以按照备份文件名前缀模糊查找，会展示文件名、文件大小和更新时间。请选择需要上云的备份文件。
上云方案	打开数据库（只有一个全量备份文件）：全量上云，适合仅有一个完全备份文件上云的场景。本操作选择打开数据库（只有一个全量备份文件），此时CreateMigrateTask中的`BackupMode = FULL`并且`IsOnlineDB = True`。不打开数据库（还有差异备份或日志文件）：增量上云，适合有完全备份文件加上日志备份（或者差异备份文件）上云的场景，此时CreateMigrateTask中的`BackupMode = UPDF` 并且`IsOnlineDB = False`。
一致性检查方式	异步执行DBCC：在打开数据库时系统不做DBCC CheckDB，而是在打开数据库任务结束以后，异步执行DBCC CheckDB操作，以此节约打开数据库操作的时间开销（数据库比较大，DBCC CheckDB非常耗时），减少您的业务停机时间。如果您对业务停机时间要求非常敏感，且不关心DBCC CheckDB结果，建议使用异步执行DBCC。此时CreateMigrateTask 中的`CheckDBMode = AsyncExecuteDBCheck`。同步执行DBCC：相对于异步执行DBCC，有的用户非常关心DBCC CheckDB的结果，以此来找出用户线下数据库数据一致性错误。此时，建议您选择同步执行DBCC，影响是会拉长打开数据库的时间。此时CreateMigrateTask 中的`CheckDBMode = SyncExecuteDBCheck`。

单击确定。

请耐心等待上云任务完成，您可以单击刷新以查看任务的最新状态。如上云任务失败，请根据任务描述提示排查错误，具体可参见本文常见错误。

说明
数据上云完成后，系统会根据RDS实例的自动备份策略在指定的备份时间（该时间可手动调整）发起备份，生成的备份集将包含已上云的数据，您可以在RDS实例详情页的备份恢复页面查看。

如果尚未到达备份时间点，但您急需在云上生成备份，也可以选择进行手动备份。

2008 R2高性能本地盘

访问RDS实例列表，在上方选择地域，然后单击目标实例ID。
在左侧导航栏，单击数据库管理。
找到目标数据库，单击操作列的从OSS上的备份文件迁入。
在数据导入向导对话框中，阅读提示内容，单击下一步。
阅读OSS上传的相关提示内容，单击下一步。
在备份文件OSS URL栏中填写备份文件在OSS的链接地址，单击确定。

说明
RDS SQL Server 2008 R2高性能本地盘实例当前仅支持将全量备份文件一次性迁入云上的方案。

4. 查看备份上云进度

请根据RDS SQL Server实例版本，选择对应方案。

2012及以上版本、2008 R2云盘

访问RDS实例左侧导航栏备份恢复页面，在备份数据上云记录页签内查看备份上云记录，包括任务状态、任务开始和结束时间等。默认展示最近一周的记录，可按需调整时间区间。

说明

任务状态为失败时，请查看任务描述或单击目标迁移任务后面的查看文件详情，确认任务失败的原因并修复，然后重新执行数据迁移。

2008 R2高性能本地盘

访问RDS实例左侧导航栏数据上云页面，然后找到目标迁移任务来查看数据迁移的进度。

说明

任务状态为失败时，请查看任务描述或单击目标迁移任务后面的查看文件详情，确认任务失败的原因并修复，然后重新执行数据迁移。

常见错误

每条备份上云恢复记录中都会有任务描述信息，您可以通过这些描述信息发现任务失败或报错的原因。常见的错误信息如下：

同名数据库已经存在
- 错误信息1：The database (xxx) is already exist on RDS, please backup and drop it, then try again.
- 错误信息2：Database 'xxx' already exists. Choose a different database name.
- 错误原因：为了保证RDS SQL Server上数据的安全性，RDS SQL Server不支持同名数据库的上云操作。
- 解决方法：如果您确实需要对现有数据库的数据进行覆盖，请先自行备份已经存在的数据，然后删除数据库，最后再重新执行数据上云任务。
使用差异备份文件
- 错误信息：Backup set (xxx.bak) is a Database Differential backup, we only accept a FULL Backup.
- 错误原因：您提供的备份文件是差异备份，不是全量备份文件，一次性全量迁入上云仅支持全量备份文件，不支持差异备份。
使用日志备份文件
- 错误信息：Backup set (xxx.trn) is a Transaction Log backup, we only accept a FULL Backup.
- 错误原因：您提供的备份文件是日志备份，不是全量备份文件，一次性全量迁入上云仅支持全量备份文件，不支持日志备份。
备份文件校验失败
- 错误信息：Failed to verify xxx.bak, backup file was corrupted or newer edition than RDS.
- 错误原因：备份文件损坏或者备份文件所在的本地环境SQL Server实例版本比RDS SQL Server版本高，导致校验失败。例如将一个SQL Server 2016的备份还原到RDS SQL Server 2012版本，就会报告这个错误。
- 解决方法：如果是备份文件损坏，请在本地环境重新做一个全量备份，重新生成迁移上云任务；如果是版本过高，请使用与本地环境版本一致或者更高的RDS SQL Server。
  
  说明
  如需将已有RDS SQL Server实例升级到更高版本，请参见升级数据库版本。
DBCC CHECKDB失败
- 错误信息：DBCC checkdb failed.
- 错误原因：DBCC CheckDB检查操作报错，说明数据库在本地环境中已经发生错误。
- 解决方法：使用如下命令修复本地环境数据库错误后重新上云。
  
  重要
  使用该命令修复错误的过程，可能会导致数据丢失。
```
DBCC CHECKDB (DBName, REPAIR_ALLOW_DATA_LOSS) WITH NO_INFOMSGS, ALL_ERRORMSGS
```
空间不足1
- 错误信息：Not Enough Disk Space for restoring, space left (xxx MB) < needed (xxx MB).
- 错误原因：RDS实例剩余空间不满足备份文件上云所需要的最小空间要求。
- 解决方法：升级实例存储空间。
空间不足2
- 错误信息：Not Enough Disk Space, space left xxx MB < bak file xxx MB.
- 错误原因：RDS实例剩余空间比备份文件本身小，不满足最小空间要求。
- 解决方法：升级实例存储空间。
登录账号权限不足
- 错误信息：Cannot open database "xxx" requested by the login. The login failed.
- 错误原因：登录RDS实例的用户账号无数据库的访问权限。
- 解决方案：在RDS实例账号管理页面为用户账号授予数据库访问或操作权限。具体详情，请参见为账号授权和各类型账号支持的权限列表。
没有高权限账号
- 错误信息：Your RDS doesn’t have any init account yet, please create one and grant permissions on RDS console to this migrated database (xxx).
- 错误原因：RDS实例不存在高权限账号，OSS备份数据上云任务不知道需要为哪个用户授权，但是备份文件已经成功还原到目标实例上，所以任务状态是成功的。
- 解决方法：创建高权限账号。
RAM子账号操作权限不足
- Q1：执行创建数据上云任务步骤5时，各配置项参数均已填写完整，但确定按钮为灰色无法单击？
- A1：无法单击的原因可能是您为RAM用户，您的账号权限不足。请参见本文前提条件，确保相应权限已授予。
- Q2：使用RAM子账号进行AliyunRDSImportRole授权时提示没有权限如何解决？
- A2：使用阿里云主账号为RAM子账号临时增加AliyunRAMFullAccess权限解决。
数据库名称与SQL Server系统数据库重合
- 错误信息：The database (xxx) is mssql system db, change your database name and try again.
- 错误原因：指定的数据库名称与SQL Server系统数据库重合（如master、msdb、tempdb、model等）。
- 解决方法：重新指定一个数据库名称。
数据库名称与RDS系统数据库重合
- 错误信息：The database (xxx) is RDS system db, change your database name and try again.
- 错误原因：指定的数据库名称与RDS SQL Server云数据库实例的管控数据库重合（如rdscore等）。
- 解决方法：重新指定一个数据库名称。
数据库数量超出上限
- 错误信息：The database (xxx) migration failed due to databases count limitation: xxx.
- 错误原因：数据库数量超出上限。
- 解决方法：尝试减少实例上数据库数量后重试。
OSS下载链接问题
- 错误信息1：Failed to download backup (xxx) since OSS URL was expired.
- 错误信息2：Failed to download since could not find backup file (xxx) on OSS.
- 错误原因：OSS下载链接过期，下载未正确授权RDS服务账号、无权限、或文件不存在。
- 解决方法：检查OSS文件是否存在、权限管理是否正确放开、是否正确授权等问题后重试。
Striped Backup多文件问题
- 错误信息：Failed to verify (xxx.bak), error message:The media set has xxx media families but only 1 are provided. All members must be provided. VERIFY DATABASE is terminating abnormally.
- 错误原因：原库备份时使用了Striped Backup特性，把一个全备写进了多个bak文件备份文件里，通过OSS上云到RDS时只提供了一个文件。RDS不支持一次基于多个文件上云。
- 解决方法：建议将原库备份到一个bak文件后重试。

常见返回信息

任务类型	任务状态	任务描述	说明
全量备份文件一次性迁入	成功	`success`	上云成功。
	失败	`Failed to download backup file since OSS URL was expired.`	OSS下载URL有效期过期，导致上云失败。
		`Your backup is corrupted or newer than RDS, failed to verify.`	备份文件损坏或者比RDS的版本更高，导致上云失败。
		`DBCC checkdb failed`	DBCC checkdb失败，导致上云失败。
		`autotest_2008r2_std_testmigrate_log.trn is a Transaction Log backup, we only accept a FULL Backup.`	日志备份，导致上云失败。
		`autotest_2008r2_std_testmigrate_diff.bak is a Database Differential backup, we only accept a FULL Backup.`	差异备份，导致上云失败。

API	描述
CreateMigrateTask	将OSS上的备份文件还原到RDS SQL Server实例，创建数据上云任务。
CreateOnlineDatabaseTask	打开RDS SQL Server备份数据上云任务的数据库。
DescribeMigrateTasks	查询RDS SQL Server实例备份数据上云任务列表。
DescribeOssDownloads	查询RDS SQL Server备份数据上云任务的文件详情。

云数据库 RDS：全量备份数据上云

前提条件

注意事项

费用说明

准备工作

1. 备份本地数据库

2012及以上版本、2008 R2云盘

2008 R2高性能本地盘

2. 上传备份文件到OSS

2012及以上版本、2008 R2云盘

2008 R2高性能本地盘

3. OSS备份数据导入RDS

2012及以上版本、2008 R2云盘

2008 R2高性能本地盘

4. 查看备份上云进度

2012及以上版本、2008 R2云盘

2008 R2高性能本地盘

常见错误

常见返回信息

相关API