|
| 1 | +--- |
| 2 | +title: "Migrate MySQL on-premises or Virtual Machine (VM) workload to Azure Database for MySQL - Flexible Server using Azure MySQL Import CLI" |
| 3 | +description: This tutorial describes how to use the Azure MySQL Import CLI to migrate MySQL on-premises or VM workload to Azure Database for MySQL - Flexible Server. |
| 4 | +author: adig |
| 5 | +ms.author: adig |
| 6 | +ms.reviewer: maghan |
| 7 | +ms.date: 07/03/2023 |
| 8 | +ms.service: mysql |
| 9 | +ms.subservice: flexible-server |
| 10 | +ms.topic: quickstart |
| 11 | +ms.custom: |
| 12 | + - mvc |
| 13 | + - devx-track-azurecli |
| 14 | + - mode-api |
| 15 | +ms.devlang: azurecli |
| 16 | +--- |
| 17 | +# Migrate MySQL on-premises or Virtual Machine (VM) workload to Azure Database for MySQL - Flexible Server using Azure MySQL Import CLI |
| 18 | + |
| 19 | +Azure MySQL Import enables you to migrate your MySQL on-premises or Virtual Machine (VM) workload seamlessly to Azure Database for MySQL - Flexible Server. It uses a user-provided physical backup file and restores the source server's physical data files to the target server offering a simple and fast migration path. Post MySQL Import operation, you can take advantage of the benefits of Flexible Server, including better price & performance, granular control over database configuration, and custom maintenance windows. |
| 20 | + |
| 21 | +Based on user-inputs, it takes up the responsibility of provisioning your target Flexible Server and then restoring the user-provided physical backup of the source server stored in the Azure Blob storage account to the target Flexible Server instance. |
| 22 | + |
| 23 | +This tutorial shows how to use the Azure MySQL Import CLI command to migrate your Migrate MySQL on-premises or Virtual Machine (VM) workload to Azure Database for MySQL - Flexible Server. |
| 24 | + |
| 25 | +## Launch Azure Cloud Shell |
| 26 | + |
| 27 | +The [Azure Cloud Shell](../../cloud-shell/overview.md) is a free interactive shell that you can use to run the steps in this article. It has common Azure tools preinstalled and configured to use with your account. |
| 28 | + |
| 29 | +As the feature is currently in private preview, this tutorial requires you to install Azure Edge Build and use the CLI locally, see [Install Azure Edge Build CLI](https://github.com/Azure/azure-cli#edge-builds). |
| 30 | + |
| 31 | +## Setup |
| 32 | + |
| 33 | +You must sign in to your account using the [az sign-in](/cli/azure/reference-index#az-login) command. Note the **id** property, which refers to your Azure account's **Subscription ID**. |
| 34 | + |
| 35 | +```azurecli-interactive |
| 36 | +az login |
| 37 | +``` |
| 38 | + |
| 39 | +Select the specific subscription under your account where you want to deploy the target Flexible Server using the [az account set](/cli/azure/account#az-account-set) command. Note the **id** value from the **az login** output to use as the value for the **subscription** argument in the command. To get all your subscriptions, use [az account list](/cli/azure/account#az-account-list). |
| 40 | + |
| 41 | +```azurecli-interactive |
| 42 | +az account set --subscription <subscription id> |
| 43 | +``` |
| 44 | + |
| 45 | +## Prerequisites |
| 46 | + |
| 47 | +* Source server should have the following parameters: |
| 48 | + * Lower_case_table_names = 1 |
| 49 | + * Innodb_file_per_table = ON |
| 50 | + * System tablespace name should be ibdata1. |
| 51 | + * System tablespace size should be greater than or equal to 12 MB. (MySQL Default) |
| 52 | + * Innodb_page_size = 16348 (MySQL Default) |
| 53 | + * Only INNODB engine is supported. |
| 54 | +* Take a physical backup of your MySQL workload using Percona XtraBackup |
| 55 | +The following are the steps for using Percona XtraBackup to take a full backup : |
| 56 | + * Install Percona XtraBackup on the on-premises or VM workload, see [Installing Percona XtraBackup 2.4]( https://docs.percona.com/percona-xtrabackup/2.4/installation.html). |
| 57 | + * For instructions for taking a Full backup with Percona XtraBackup 2.4, see [Full backup]( https://docs.percona.com/percona-xtrabackup/2.4/backup_scenarios/full_backup.html). |
| 58 | + * [Create an Azure Blob container](../../storage/blobs/storage-quickstart-blobs-portal.md#create-a-container) and get the Shared Access Signature (SAS) Token ([Azure portal](../../ai-services/translator/document-translation/how-to-guides/create-sas-tokens.md?tabs=Containers#create-sas-tokens-in-the-azure-portal) or [Azure CLI](../../storage/blobs/storage-blob-user-delegation-sas-create-cli.md)) for the container. Ensure that you grant Add, Create and Write in the **Permissions** drop-down list. Copy and paste the Blob SAS token and URL values in a secure location. They're only displayed once and can't be retrieved once the window is closed. |
| 59 | +* Upload the full backup file to your Azure Blob storage. Follow steps [here]( ../../storage/common/storage-use-azcopy-blobs-upload.md#upload-a-file). |
| 60 | +* For performing an online migration, capture and store the bin-log position of the backup file taken using Percona XtraBackup by running the **cat xtrabackup_info** command and copying the bin_log pos output. |
| 61 | + |
| 62 | +## Limitations |
| 63 | + |
| 64 | +* Source server configuration isn't migrated. You must configure the target Flexible server appropriately. |
| 65 | +* Users and privileges aren't migrated as part of MySQL Import. You must take a manual dump of users and privileges before initiating MySQL Import to migrate logins post import operation by restoring them on the target Flexible Server. |
| 66 | +* High Availability (HA) enabled Flexible Servers are returned as HA disabled servers to increase the speed of migration operation post the import migration. Enable HA for your target Flexible Server post migration. |
| 67 | + |
| 68 | +## Recommendations for an optimal migration experience |
| 69 | + |
| 70 | +* Consider keeping the Azure Blob storage account and the target Flexible Server to be deployed in the same region for better import performance. |
| 71 | +* Recommended SKU configuration for target Azure Database for MySQL Flexible Server – |
| 72 | + * Setting Burstable SKU for target isn't recommended in order to optimize migration time when running the MySQL Import operation. We recommend scaling to General Purpose/ Business Critical for the course of the import operation, post, which you can scale down to Burstable SKU. |
| 73 | + |
| 74 | +## Trigger a MySQL Import operation to migrate from Azure Database for MySQL -Flexible Server |
| 75 | + |
| 76 | +Trigger a MySQL Import operation with the `az mysql flexible-server import create` command. The following command creates a target Flexible Server and performs instance-level import from backup file to target destination using your Azure CLI's local context: |
| 77 | + |
| 78 | +```azurecli |
| 79 | +az mysql flexible-server import create --data-source-type |
| 80 | + --data-source |
| 81 | + --data-source-sas-token |
| 82 | + --resource-group |
| 83 | + --name |
| 84 | + --sku-name |
| 85 | + --tier |
| 86 | + --version |
| 87 | + --location |
| 88 | + [--data-source-backup-dir] |
| 89 | + [--storage-size] |
| 90 | + [--mode] |
| 91 | + [--admin-password] |
| 92 | + [--admin-user] |
| 93 | + [--auto-scale-iops {Disabled, Enabled}] |
| 94 | + [--backup-identity] |
| 95 | + [--backup-key] |
| 96 | + [--backup-retention] |
| 97 | + [--database-name] |
| 98 | + [--geo-redundant-backup {Disabled, Enabled}] |
| 99 | + [--high-availability {Disabled, SameZone, ZoneRedundant}] |
| 100 | + [--identity] |
| 101 | + [--iops] |
| 102 | + [--key] |
| 103 | + [--private-dns-zone] |
| 104 | + [--public-access] |
| 105 | + [--resource-group] |
| 106 | + [--standby-zone] |
| 107 | + [--storage-auto-grow {Disabled, Enabled}] |
| 108 | + [--subnet] |
| 109 | + [--subnet-prefixes] |
| 110 | + [--tags] |
| 111 | + [--vnet] |
| 112 | + [--zone] |
| 113 | +
|
| 114 | +
|
| 115 | +The following example takes in the data source information for your source MySQL server’s backup file and target Flexible Server information, creates a target Flexible Server named `test-flexible-server` in the `westus` location and performs an import from backup file to target. |
| 116 | +
|
| 117 | +azurecli-interactive |
| 118 | +az mysql flexible-server import create --data-source-type "azure_blob" --data-source "https://onprembackup.blob.core.windows.net/onprembackup" --data-source-backup-dir "mysql_backup_percona" –-data-source-token "{sas-token}" --resource-group "test-rg" --name "test-flexible-server" –-sku-name Standard_D2ds_v4 --tier GeneralPurpose –-version 5.7 -–location "westus” |
| 119 | +``` |
| 120 | + |
| 121 | +Here are the details for the arguments above: |
| 122 | + |
| 123 | +**Setting** | **Sample value** | **Description** |
| 124 | +---|---|--- |
| 125 | +data-source-type | azure_blob | The type of data source that serves as the source destination for triggering MySQL Import. Accepted values: [azure_blob]. Description of accepted values- azure_blob: Azure Blob storage. |
| 126 | +data-source | {resourceID} | The resource ID of the Azure Blob container. |
| 127 | +data-source-backup-dir | mysql_percona_backup | The directory of the Azure Blob storage container in which the backup file was uploaded. This value is required only when the backup file isn't stored in the root folder of Azure Blob container. |
| 128 | +data-source-sas-token | {sas-token} | The Shared Access Signature (SAS) token generated for granting access to import from the Azure Blob storage container. |
| 129 | +resource-group | test-rg | The name of the Azure resource group of the target Azure Database for MySQL Flexible Server. |
| 130 | +mode | Offline | The mode of MySQL import. Accepted values: [Offline]; Default value: Offline. |
| 131 | +location | westus | The Azure location for the source Azure Database for MySQL Flexible Server. |
| 132 | +name | test-flexible-server | Enter a unique name for your target Azure Database for MySQL Flexible Server. The server name can contain only lowercase letters, numbers, and the hyphen (-) character. It must contain from 3 to 63 characters. Note: This server is deployed in the same subscription, resource group, and region as the source. |
| 133 | +admin-user | adminuser | The username for the administrator sign-in for your target Azure Database for MySQL Flexible Server. It can't be **azure_superuser**, **admin**, **administrator**, **root**, **guest**, or **public**. |
| 134 | +admin-password | *password* | The administrator user's password for your target Azure Database for MySQL Flexible Server. It must contain between 8 and 128 characters. Your password must contain characters from three categories: English uppercase letters, English lowercase letters, numbers, and nonalphanumeric characters. |
| 135 | +sku-name|GP_Gen5_2|Enter the name of the pricing tier and compute configuration for your target Azure Database for MySQL Flexible Server. Follows the convention {pricing tier}*{compute generation}*{vCores} in shorthand. See the [pricing tiers](../flexible-server/concepts-service-tiers-storage.md#service-tiers-size-and-server-types) for more information. |
| 136 | +tier | Burstable | Compute tier of the target Azure Database for MySQL Flexible Server. Accepted values: Burstable, GeneralPurpose, MemoryOptimized; Default value: Burstable. |
| 137 | +public-access | 0.0.0.0 | Determines the public access for the target Azure Database for MySQL Flexible Server. Enter single or range of IP addresses to be included in the allowed list of IPs. IP address ranges must be dash-separated and not contain any spaces. Specifying 0.0.0.0 allows public access from any resources deployed within Azure to access your server. Setting it to "None" sets the server in public access mode but doesn't create a firewall rule. |
| 138 | +vnet | myVnet | Name or ID of a new or existing virtual network. If you want to use a vnet from different resource group or subscription, provide a resource ID. The name must be between 2 to 64 characters. The name must begin with a letter or number, end with a letter, number or underscore, and can contain only letters, numbers, underscores, periods, or hyphens. |
| 139 | +subnet | mySubnet | Name or resource ID of a new or existing subnet. If you want to use a subnet from different resource group or subscription, provide resource ID instead of name. Note that the subnet is delegated to flexibleServers. After delegation, this subnet can't be used for any other type of Azure resources. |
| 140 | +private-dns-zone | myserver.private.contoso.com | The name or ID of new or existing private dns zone. You can use the private dns zone from same resource group, different resource group, or different subscription. If you want to use a zone from different resource group or subscription, provide resource Id. CLI creates a new private dns zone within the same resource group as virtual network if not provided by users. |
| 141 | +key | key identifier of testKey | The resource ID of the primary keyvault key for data encryption. |
| 142 | +identity | testIdentity | The name or resource ID of the user assigned identity for data encryption. |
| 143 | +storage-size | 32 | The storage capacity of the target Azure Database for MySQL Flexible Server. The minimum is 20 GiB, and max is 16 TiB. |
| 144 | +tags | key=value | Provide the name of the Azure resource group. |
| 145 | +version | 5.7 | Server major version of the target Azure Database for MySQL Flexible Server. |
| 146 | +high-availability | ZoneRedundant | Enable (ZoneRedundant or SameZone) or disable the high availability feature for the target Azure Database for MySQL Flexible Server. Accepted values: Disabled, SameZone, ZoneRedundant; Default value: Disabled. |
| 147 | +zone | 1 | Availability zone into which to provision the resource. |
| 148 | +standby-zone | 3 | The availability zone information of the standby server when high Availability is enabled. |
| 149 | +storage-auto-grow | Enabled | Enable or disable auto grow of storage for the target Azure Database for MySQL Flexible Server. The default value is Enabled. Accepted values: Disabled, Enabled; Default value: Enabled. |
| 150 | +iops | 500 | Number of IOPS to be allocated for the target Azure Database for MySQL Flexible Server. You get a certain amount of free IOPS based on compute and storage provisioned. The default value for IOPS is free IOPS. To learn more about IOPS based on compute and storage, refer to IOPS in Azure Database for MySQL Flexible Server. |
| 151 | + |
| 152 | +## Migrate to Flexible Server with minimal downtime |
| 153 | + |
| 154 | +In order to perform an online migration after completing the initial seeding from backup file using MySQL import, you can configure data-in replication between the source and target by following steps [here](../flexible-server/how-to-data-in-replication.md?tabs=bash%2Ccommand-line). You can use the bin-log position captured while taking the backup file using Percona XtraBackup to set up Bin-log position based replication. |
| 155 | + |
| 156 | +## How long does MySQL Import take to migrate my Single Server instance? |
| 157 | + |
| 158 | +Benchmarked performance based on storage size. |
| 159 | + |
| 160 | + | Backup file Storage Size | MySQL Import time | |
| 161 | + | ------------- |:-------------:| |
| 162 | + | 1 GiB | 0 min 23 secs | |
| 163 | + | 10 GiB | 4 min 24 secs | |
| 164 | + | 100 GiB | 10 min 29 secs | |
| 165 | + | 500 GiB | 13 min 15 secs | |
| 166 | + | 1 TB | 22 min 56 secs | |
| 167 | + | 10 TB | 2 hrs 5 min 30 secs | |
| 168 | + |
| 169 | +As the storage size increases, the time required for data copying also increases, almost in a linear relationship. However, it's important to note that copy speed can be significantly impacted by network fluctuations. Therefore, the data provided here should be taken as a reference only. |
| 170 | + |
| 171 | +## Next steps |
| 172 | + |
| 173 | +* [Manage an Azure Database for MySQL - Flexible Server using the Azure portal](../flexible-server/how-to-manage-server-portal.md) |
0 commit comments