Use the blob migration tool

Abstract

Migrate blobs from SQL Database to Azure Storage.

You use the blob migration tool to help migrate blobs from SQL Database to Azure Storage. During the migration process, there is zero downtime and blobs are not automatically deleted from the SQL Database. However, it is good practice to back up your current data before beginning migration.

Before you can use the Blob migration tool for Sitecore instances you must:

  • Install Sitecore 9.3 or later

Ensure you have the following PowerShell scripts; the Azure Blob Storage module uses them to help migrate blobs from the SQL Database to Azure Storage. You can find the scripts in the web applications for Content Management (CM) and Content Delivery (CD), in the AppData/Migration folder:

  • Invoke-Migration.ps1 - use this script to migrate the blobs from SQL Database to Azure Storage. Refer to the following example and table of parameters when using this script.

    .\Invoke-Migration.ps1 -SqlDBConnectionNames @("master", "web") -AzureBlobConnectionName "azureblob" -BlobContainerName "blobcontainer" -Force *>&1 | Tee-Object -FilePath Invoke-Migration.log
    Table 2. Invoke-Migration.ps1

    Parameters

    Description

    SqlDBConnectionNames

    The names of the Sitecore SQL Database connection strings that migrate blobs from SQL Database to Azure Blob Storage.

    AzureBlobConnectionName

    The name of the Azure Blob Storage connection string.

    BlobContainerName

    The name of the destination blob container that must exist in Azure Storage.

    ConnectionStringsConfigFileRelativePath

    (Optional) The path relative to the configuration file of the Sitecore connection strings . The default value is:

    ..\..\App_Config\ConnectionStrings.Config



  • Revert-Migration.ps1 - use this script to revert the migration of blobs from the SQL Database to Azure Storage. Refer to the following example and table of parameters when using this script.

    .\Revert-Migration.ps1 -SqlDBConnectionNames @("master", "web") -AzureBlobConnectionName "azureblob" -BlobContainerName "blobcontainer" -Force *>&1 | Tee-Object -FilePath Revert-Migration.log
    Table 3. Revert-Migration.ps1

    Parameters

    Description

    SqlDBConnectionNames

    The names of the Sitecore SQL Database connection strings that migrate blobs from the SQL Database to Azure Blob Storage.

    AzureBlobConnectionName

    The name of the Azure Blob Storage connection string.

    BlobContainerName

    The name of the destination blob container that must exist in Azure Storage.

    ConnectionStringsConfigFileRelativePath

    (Optional) The path relative to the configuration file of the Sitecore connection strings. The default value is:

    ..\..\App_Config\ConnectionStrings.Config



Before you begin migration, remove any unused blobs by running the Database Cleanup wizard, (this saves time and resources during the migration process). To estimate the time it will take to migrate a large volume of blobs, refer to the Migration scripts performance table.

Note

Migration scripts do not delete blobs from SQL Database, they only copy the blobs into Azure Storage.

To begin migration:

  1. Ensure you have configured the Microsoft Azure Storage Blob Provider as your default provider.

  2. Go to the CM AppData/Migration folder.

  3. Run the Invoke-Migration.ps1 script, (if there are any failures, re-run the script).

  4. When the script successfully completes, check the Azure Blob Storage container to verify the number of blobs and size of the container are correct.

  5. Run the Sitecore CM and CD applications to ensure that everything functions as it did when it was with SQL Blobs. Specifically check:

    • The contents view correctly.

    • You can still edit the contents.

    • You can download the contents.

  6. To ensure in-memory media items point to the correct blob storage account after migration completes:

    • After running the migration script, clear the Sitecore cache using the /sitecore/admin/cache.aspx page.

  7. After a successful migration, confirm all of the data has been correctly copied into Azure Storage and the contents render correctly.

  8. Clean the blobs from SQL Database: in the Admin role, run the Cleanup database Admin wizard.

If the migration did not run as expected, or if you want to use SQL Database again, you can revert the migration.

To revert the migration:

  1. Set the default provider to Classic SQL Blob Provider (classic).

  2. Go to the CM AppData/Migration folder.

  3. Run the Revert-Migration.ps1 script.

  4. To ensure in-memory media items point to the correct blob storage account after the revert migration completes:

    • After running the revert migration script, clear the Sitecore cache using the /sitecore/admin/cache.aspx page.

Note

During the migration process new blobs might be created. Reverting migration copies all new blobs that were created in Azure Storage.

The options and process to migrate blobs from the SQL Database to Azure Storage are quite flexible:

  • If, for some reason, the migration scripts fail during migration, you can rerun the scripts to continue the migration. The scripts resume running from the last known state.

  • The migration scripts automatically retry when a transient error occurs while blobs are uploading to Azure Storage.

  • You can run the migration scripts from a variety of places: