All Products
Search

This Product

    PolarDB:Download backup files

    Document Center

    PolarDB:Download backup files

    Last Updated:Jun 21, 2026

    PolarDB lets you download backup files from a cluster backup set to your local machine for long-term storage, querying historical data, transferring backups (for example, to OSS), and auditing.

    Note

    You cannot directly restore downloaded backup data to a PolarDB for MySQL cluster. You can restore downloaded backup files to a self-managed MySQL database.

    Release date

    November 24, 2023

    Note

    The backup file download feature is in canary release and will be rolled out gradually.

    Billing

    You can download backup files via URL (temporarily stored in DBS) or transfer them to your OSS. Charges vary by download destination:

    Note

    • If a download task fails, no fees are charged.

    • In the PolarDB console, go to Settings and Management > Backup and Restoration > Backup Download List for your cluster to view the monthly backup conversion volume and monthly outbound internet traffic.

    Storage fees

    • URL: Files are temporarily stored in DBS's built-in storage. No storage fees are charged.

    • OSS: Files are transferred to your OSS bucket. For more information about OSS storage fees, see OSS storage fees.

    Backup set conversion fees

    Converting a backup set to SQL, CSV, Parquet, or CSV-with-header format incurs conversion fees, regardless of whether the destination is a URL or OSS. No free quota is available for this conversion. The price is USD 0.03125 per GB.

    Traffic fees

    • URL:

      • Download over an internal network: Free of charge.

      • Download over the internet: A free quota of 500 GB per cluster per month is provided. Data transfer that exceeds the free quota is billed on a pay-as-you-go basis. Charges are calculated daily based on the amount of data downloaded. For information about pricing, see Network fees.

      Note

      We recommend that you purchase a subscription data transfer plan to cover the network traffic fees for downloading backups over the internet. The larger the capacity of the data transfer plan, the higher the discount.

    • OSS: Files are transferred to your OSS bucket. For information about traffic fees, see OSS traffic fees.

    Prerequisites

    • Cluster: This feature is available only for the Cluster Edition of Enterprise Edition clusters.

    • Region: China (Chengdu), China (Guangzhou), China (Qingdao), China (Beijing), China (Shanghai), China (Zhangjiakou), China (Hangzhou), China (Shenzhen), China (Hong Kong), Malaysia (Kuala Lumpur), Indonesia (Jakarta), Japan (Tokyo), Singapore, US (Silicon Valley), US (Virginia), and Germany (Frankfurt).

      Note

      This feature will be available in other regions soon.

    • Other:

      • The RAM user must have the permissions to download backup files. To grant permissions to a RAM user, see RAM user permissions.

      • Backup data is not encrypted. You cannot download backup files from encrypted PolarDB clusters.

      • Only one download task (running or failed) is allowed per cluster or instance at a time.

    Limitations

    • The download process exports most, but not all, table structures:

      • Supported for export: column information, primary key indexes, non-primary key indexes, unique indexes, partitioned table information, table engines, and character sets and collations at the table or database level.

      • Not supported for export: expression indexes, foreign keys, generated columns, hidden columns, views, functions, stored procedures, system variables, and triggers.

    • Conversion tasks will fail if your data includes fields with the following spatial data types:

      GEOMETRY, POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION

    • The exported files do not include the following system databases:

      information_schema, mysql, performance_schema, sys, __recycle_bin__

    • If you select OSS as the download destination, the storage class of the OSS bucket must be Standard. To change the storage class, see Convert storage classes.

      Note

      You must manually create an OSS bucket. You can skip this step if you have already created a bucket for storing backup files.

    • You can download data only from a level-1 backup. Data from a level-2 backup cannot be downloaded.

    • If cold data archiving is enabled for the cluster, you cannot download a backup set.

    • If the names of the databases or tables to be downloaded contain forward slashes (/), the download task fails.

    Procedure

    (Recommended) Use the console

    1. Log on to the PolarDB console. In the left-side navigation pane, click Clusters. Select the region where the cluster is located, and then click the cluster ID to go to the cluster details page.

    2. In the left-side navigation pane, click Settings and Management > Backup and Restoration.

    3. On the Data Backups tab, find the target backup set and click Download Cluster Backup in the Actions column.

      Note

      • By default, the console displays backups from the last eight days. To view older backups, you must change the time range.

      • If the Download Cluster Backup button is not displayed, verify that your cluster's product version or region meets the prerequisites.

    4. In the Point in Time and Backup Set step, select Download by Point in Time or Download by Backup Set, and then click Next.

      If you select By Backup Set, select a target backup set from the Backup Set drop-down list.

    5. In the Instance, Database, and Table step, click Next. The Instance Download option is pre-selected and cannot be changed.

    6. In the Destination and Format step, select the download destination and format, and complete the configuration.

      Important

      • We recommend that you select OSS as the download destination to save time.

      • A backup download task cannot be canceled after it starts.

      • Backup download tasks incur charges. For more information, see Billing.

      (Recommended) OSS

      If you select OSS as the download destination, data is written directly to your OSS bucket. You can delete the data as needed after the download is complete.

      1. Enter your OSS Bucket Name and a directory prefix, such as xx/xx.

        Note

        • You must manually create an OSS bucket. If you have already created a bucket to store backup files, you can enter its name directly.

        • The storage class of the OSS bucket must be Standard. To change the storage class, see Convert storage classes.

      2. Select a download format. You can set the download format to CSV, SQL, Parquet, or CSV-with-header. Select a format based on your business requirements.

      3. Read and agree to the terms, and then click Complete. You are redirected to the Backup Download List tab. Wait for the download task to complete.

        Note

        • The backup download feature requires DBS to be authorized to access your cloud resources. If you have not granted access permissions, follow the prompts in the console to click Authorize > Submit. After the authorization is successful, you can return to the advanced download configuration page and enter the required information as described in the preceding steps.

        • Format conversion is resource-intensive. A download may fail if server resources are temporarily unavailable. Unsupported special data formats can also cause download failures. If a task fails, we recommend that you retry the download task or contact DBS technical support.

        • No fees are charged for failed tasks.

      4. After the task status changes to Successful, you can view the backup file in the corresponding OSS bucket.

      URL

      If you select URL as the download destination, the system temporarily stores the converted data in the built-in storage of DBS. No storage fees are charged for this process.

      Note

      Downloading from a URL involves data packaging, which requires additional time. The time required is related to the logical size of the backup set. If the backup set is large (for example, larger than 1 TB), we recommend that you download to OSS.

      1. Select a download format. You can set the download format to CSV, SQL, Parquet, or CSV-with-header. Select a format based on your business requirements.

      2. Read and agree to the terms, and then click Complete. You are redirected to the Backup Download List tab. Wait for the download task to complete.

        Note

        • The backup download feature requires DBS to be authorized to access your cloud resources. If you have not granted access permissions, follow the prompts in the console to click Authorize > Submit. After the authorization is successful, you can return to the advanced download configuration page and enter the required information as described in the preceding steps.

        • Format conversion is resource-intensive. A download may fail if server resources are temporarily unavailable. Unsupported special data formats can also cause download failures. If a task fails, we recommend that you retry the download task or contact DBS technical support.

        • No fees are charged for failed tasks.

      3. View the backup file: If the download task status is Successful, the download is complete. In the Download Destination column, click Generate URL, set the Validity Period, and then click Generate URL. You can then use the generated internal or public URL to download the backup data.

        Note

        • You can obtain the download link within three days of the task's completion. The link validity period can be set from 5 minutes to 1 day. The default validity period is 2 hours.

        • Completed tasks expire after three days, at which point the download link also expires. The data from an expired task is automatically deleted after expiration. If you still need the data, you must start a new download task to get a new download link.

        • Save the download link and keep it confidential to prevent data leaks.

        • Using third-party download tools might incur extra download traffic and lead to additional charges. Use these tools with caution. For information about recommended download methods, see Download commands.

    Use an API

    1. DescribeDownloadSupport: queries whether your cluster supports the backup file download feature.

      Note

      If the API response indicates that the feature is not supported, verify that your cluster's product version and region meet the prerequisites.

    2. CreateDownload: creates a backup file download task.

      Note

      • The backup download feature requires you to grant the AliyunDBSDefaultRole permissions to DBS to access your cloud resources. If you have not granted these permissions, you can first grant them by using the console.

      • When TargetType (download destination type) is OSS, you must first manually create the destination bucket and ensure its storage class is Standard.

      • When TargetType (download destination type) is URL, you must save the returned TaskId (task ID) to retrieve the download link.

      • A backup download task cannot be canceled after it starts.

      • Backup download tasks incur charges. For more information, see Billing.

    3. (Optional) DescribeDownloadTask: View the status and other details of your cluster's backup download tasks.

    4. Obtain the backup file:

      • If the download destination is OSS, the system writes the data directly to your OSS bucket, where you can view it.

      • If the download destination is a URL, you can call the DescribeDownloadBackupSetStorageInfo operation to obtain the download link.

        Note

        • You can obtain the download link within three days of the task's completion. The link validity period can be set from 5 minutes to 1 day. The default validity period is 2 hours.

        • Completed tasks expire after three days, at which point the download link also expires. The data from an expired task is automatically deleted after expiration. If you still need the data, you must start a new download task to get a new download link.

        • Save the download link and keep it confidential to prevent data leaks.

        • Using third-party download tools might incur extra download traffic and lead to additional charges. Use these tools with caution. For information about recommended download methods, see Download commands.

    FAQ

    Can I cancel a backup download task that is in progress?

    No. A backup download task cannot be canceled after it starts.

    How do I use the downloaded data backup and log backup files?

    You can restore the downloaded backup files to a self-managed MySQL database.

    Why do I receive the error ERROR 1148 (42000): The used command is not allowed with this MySQL version when I restore a downloaded backup file to a local MySQL database?

    Run the show variables like 'local_infile'; query on your MySQL database. If the result is OFF, run the following statement to enable file import: set global local_infile = 1;. After that, run the import script again.

    Why is the backup size shown in the console different from the actual size of the downloaded backup file?

    Downloaded backup files are compressed and are usually smaller than the backup size displayed in the console. You can restore the file to check whether the data is complete.

    Can I directly restore a downloaded backup file to another PolarDB cluster?

    No, you cannot directly restore a downloaded backup file to another PolarDB cluster. You must first restore the backup file to a self-managed MySQL database and then use Data Transmission Service (DTS) to migrate data from the self-managed MySQL database to PolarDB for MySQL.

    Appendix

    RAM user permissions

    This feature uses RAM to manage permissions. You can configure these permissions to control which RAM users can obtain download links.

    Grant download permission to RAM users

    If you cannot use the backup download feature (for example, you cannot create or query download tasks), check whether your RAM user has the management permissions for data disaster recovery (AliyunDBSFullAccess). For more information about how to grant permissions, see Manage RAM user permissions.

    Block download links for RAM users

    If a RAM user needs permissions to use backup and restoration features but must be prevented from obtaining backup file download links, you can create a custom policy to deny the RAM user permission to call the API operation that retrieves download links. The following script is a policy sample:

    {
    "Version": "1",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "dbs:DescribeDownloadBackupSetStorageInfo",
            "Resource": "*"
        }
    ]
}

    After you create the custom policy, attach the policy to the RAM user. The RAM user is then blocked from obtaining download links.

    Allow read-only users to download backups

    For security reasons, a RAM user who has only read-only permissions for PolarDB (AliyunPolardbReadOnlyAccess) cannot download backup files.

    In this case, if the RAM user needs permissions to download backup files, you can grant the user read-only permissions for data disaster recovery (AliyunDBSReadOnlyAccess). Once this permission is granted, the RAM user can view download links for completed backup tasks. For more information about how to grant permissions, see Manage RAM user permissions.

    Download commands

    Note

    • If the download speed is lower than 64 KB/s, the download may be interrupted. Ensure that you have a stable network connection during the download.

    • If you download backup files to a disk mounted with ossfs, you may need to adjust the multipart_size parameter for ossfs. By default, this parameter supports files up to 100 GB in size. If a backup file is larger than 100 GB, the download fails. For more information about ossfs and its parameters, see ossfs and Mount options.

    • We recommend that you use the wget and curl commands to download backup files. If you use other third-party tools, duplicate downloads may occur, which means the amount of data downloaded is larger than the backup file size. You will also be charged for the excess data transfer because the download uses public network traffic.

    wget

    nohup wget -c -t 0 "backup_file_download_URL" -O /path/to/destination_filename > /path/to/download.log &

    Parameters

    Parameter

    Description

    nohup

    Ensures that the download continues even if the terminal is closed or the session is disconnected. The process automatically exits after the download is complete.

    -c

    Enables resumable download.

    -t

    Specifies the number of retries. If this parameter is set to 0, the number of retries is unlimited.

    -O

    Specifies the destination path and filename for the downloaded file.

    Example

    nohup wget -c -t 0 "http://dbs-xxx.aliyuncs.com/xxx.tar.gz?xxx" -O /backup/examplebackup.tar.gz > /tmp/download.log &

    curl

    nohup curl -C - --retry 10 "backup_file_download_URL" -o custom_filename > /path/to/download.log &

    Parameters

    Parameter

    Description

    nohup

    Ensures that the download continues even if the terminal is closed or the session is disconnected. The process automatically exits after the download is complete.

    -C -

    Automatically enables resumable download.

    --retry

    Specifies the number of retries. If this parameter is set to 10, the command retries 10 times.

    -o

    Specifies the destination path and filename for the downloaded file.

    Example

    nohup curl -C - --retry 10 "http://dbs-xxx.aliyuncs.com/xxx.tar.gz?xxx" -o /backup/examplebackup.tar.gz > /tmp/download.log &