Migrate with the link - Azure SQL Managed Instance

Applies to: Azure SQL Managed Instance

This article teaches you to migrate your SQL Server database to Azure SQL Managed Instance by using the Managed Instance link.

For a detailed migration guide, review Migrate to Azure SQL Managed Instance. To compare migration tools, review Compare LRS with Managed Instance link.

Overview

The Managed Instance link enables migration from SQL Server hosted anywhere, to Azure SQL Managed Instance. The link uses Always On availability group technology to replicate changes nearly in real time from the primary SQL Server instance to the secondary SQL Managed Instance. The link provides the only truly online migration option between SQL Server and Azure SQL Managed Instance, since the only downtime is cutting over to the target SQL managed instance.

Migrating with the link gives you:

• The ability to test read only workloads on SQL Managed Instance before you finalize the migration to Azure.
• The ability to keep the link and migration running for as long as you need, weeks and even months at a time.
• Near real-time replication of data that provides the fastest available data replication to Azure.
• The most minimum downtime migration compared to all other solutions available today.
• Instantaneous cutover to the target SQL Managed Instance.
• The ability to migrate anytime you're ready.
• The ability to migrate single or multiple databases from a single or multiple SQL Server instances to the same or multiple SQL managed instances in Azure.
• The only true online migration to the Business Critical service tier.

Cutover behavior

Cutover behavior depends on the version of SQL Server you're migrating from and the update policy of your target SQL Managed Instance:

• For SQL Server 2016 to SQL Server 2019, cutover to SQL Managed Instance drops the link.
• For SQL Server 2022 or later versions cutover to SQL Managed Instance can either drop the link or keep the link based on your choice during failover. If you choose to keep the link, and your SQL managed instance is configured with a matching update policy, you can reverse migrate back to SQL Server if needed.

For migration, removing the link is the recommended option. If you choose to keep the link but later decide to remove it, wait for Azure to complete the first full backup of the database after failover before removing the link. This step ensures the database is healthy and fully functional on SQL Managed Instance. It also helps avoid a rare known issue where the database can become temporarily unavailable after a server restart if the link is removed too early. For more information, see Database becomes unavailable after server restart following MI link failover.

Reverse a migration

Reverse migration back to SQL Server from Azure SQL Managed Instance might be supported depending on the update policy of your SQL managed instance. For example:

• SQL Server 2022 update policy: Databases from instances configured with the SQL Server 2022 update policy can be restored back to SQL Server 2022 instances.
• SQL Server 2025 update policy: Databases from instances configured with the SQL Server 2025 update policy can be restored back to SQL Server 2025 instances.
• Always-up-to-date update policy: Databases from instances configured with the Always-up-to-date update policy can't be restored back to SQL Server.

If your source SQL Server version is earlier than SQL Server 2022, reverse migration isn't possible. When you migrate your database to SQL Managed Instance, it undergoes an internal upgrade to a newer database version that isn't compatible with earlier SQL Server versions. Reverse migration database compatibility is only available when SQL Managed Instance is configured with the corresponding update policy.

Prerequisites

To use the link with Azure SQL Managed Instance for migration, you need the following prerequisites:

• An active Azure subscription. If you don't have one, create a free account.
• Supported version of SQL Server with the required service update installed.

Assess and discover

After you've verified that your source environment is supported, start with the pre-migration stage. Discover all of the existing data sources, assess migration feasibility, and identify any blocking issues that might prevent your migration. In the Discover phase, scan the network to identify all SQL Server instances and features used by your organization.

You can use the following tools to discover SQL sources in your environment:

• SQL Server enabled by Azure Arc: SQL Server enabled by Azure Arc automatically produces an assessment for migration to Azure, simplifying the discovery process and readiness assessment for migration.
• Azure Migrate to assess migration suitability of on-premises servers, perform performance-based sizing, and provide cost estimations for running them in Azure.
• Microsoft Assessment and Planning Toolkit (the "MAP Toolkit") to assess your current IT infrastructure. The toolkit provides a powerful inventory, assessment, and reporting tool to simplify the migration planning process.

After data sources have been discovered, assess any on-premises SQL Server instances that can be migrated to Azure SQL Managed Instance to identify migration blockers or compatibility issues.

You can use the migration readiness assessment to assess your source SQL Server instance.

For detailed guidance, review pre-migration.

Create target instance

After you've assessed your existing environment, and determined the appropriate service tier and hardware configuration for your target SQL managed instance, deploy your target instance by using the Azure portal, PowerShell or the Azure CLI.

Configure link

After your target SQL managed instance is created, configure a link between the database on your SQL Server instance and Azure SQL Managed Instance. First, prepare your environment and then configure a link by using SQL Server Management Studio (SSMS) or scripts.

Check replication lag

It's important that the secondary replica catches up to the primary replica before performing a planned migration failover. Planned failover can time out and fail if the secondary replica lags far behind the primary replica.

Use the following T-SQL query on both SQL Server and SQL Managed Instance to monitor replication lag between the replicas:

-- Execute on SQL Server and SQL Managed Instance 
USE master
DECLARE @link_name varchar(max) = '<DAGname>'
SELECT
   ag.name [Link name], 
   ars1.role_desc [Link role],
   ars2.connected_state_desc [Link connected state],
   ars2.synchronization_health_desc [Link sync health],
   drs.secondary_lag_seconds [Link replication latency (seconds)]
FROM
   sys.availability_groups ag 
   JOIN sys.dm_hadr_availability_replica_states ars1
   ON ag.group_id = ars1.group_id
   JOIN sys.dm_hadr_availability_replica_states ars2
   ON ag.group_id = ars2.group_id
   JOIN sys.dm_hadr_database_replica_states drs
   ON ars2.replica_id = drs.replica_id
WHERE 
   ag.is_distributed = 1 AND ag.name = @link_name AND ars1.is_local = 1 AND ars2.is_local = 0
GO

If replication lag is high, wait for the secondary replica to catch up with the primary replica. You might need to perform additional troubleshooting steps if the lag persists, such as pausing workloads on the primary replica, improving link network throughput between the two instances, or increasing resource capacity on the secondary replica. The easiest way to stop workloads on a SQL Server primary replica is to cut application connections to the instance.

Migrate multiple databases

If you plan to migrate multiple databases from instances on the same server, for optimal performance and predictability, migrate 8 databases per instance at a time. For example, if you have 10 instances with 32 linked databases each, migrate 8 databases at a time from each instance by using planned failovers, and repeat the process until all databases are migrated.

Data sync and cutover

After your link is established, and you're ready to migrate, follow these steps (typically during a maintenance window):

1. Stop the workload on the primary SQL Server database so the secondary database on SQL Managed Instance catches up. The easiest way to stop workloads on a SQL Server primary replica is to cut application connections to the instance.
2. Validate all data has made it over to the secondary database on SQL Managed Instance. Check replication lag to ensure the secondary replica is caught up with the primary replica.
3. Fail over the link to the secondary SQL managed instance by choosing Planned failover.
4. (Optionally) Check the box to Remove link after successful failover to ensure that failover is one way, and the link is removed.
5. (Optionally) If you're on a supported SQL Server version with a matching SQL Managed Instance update policy, you can keep the link after failover to reverse a migration if needed. Check the reverse a migration section for specific version details.
6. Cut over the application to connect to the SQL managed instance endpoint.
7. (Optionally) If you didn't choose to remove the link during failover, you can remove the link after cutover once you no longer need it.

Validate migration

After you've cut over to the SQL managed instance target, monitor your application, test performance and remediate any issues.

For details, review post-migration.

Known issues with migration

Review the following known issues related to migration with the link.

Database becomes unavailable after server restart following MI link failover

In rare circumstances, your database might become temporarily unavailable on SQL Managed Instance after a server restart following the failover of the link. This known issue occurs when you drop a link before Azure completes a full backup of the database after initial failover to SQL Managed Instance.

The database automatically recovers after Microsoft's intervention, but this recovery can take some time.

To avoid this problem, don't drop the link until the first full backup finishes after failover from SQL Server to SQL Managed Instance. For more information, see Database unavailable after server restart.

Restore operation failures after migrating to SQL Managed Instance

If you migrate a database to Azure SQL Managed Instance from SQL Server 2019 and later versions with accelerated database recovery enabled, but configured with the persistent version store (PVS) set to something other than the PRIMARY file group, you can experience restore operation failures on the target SQL managed instance.

To work around this issue, make sure you set the persistent version store (PVS) to PRIMARY on the source SQL Server database before you migrate it to SQL Managed Instance. If you already migrated the database without setting the PVS to PRIMARY, you can set it on the source SQL Server database, and then re-migrate the database to SQL Managed Instance.

Unable to use accelerated database recovery after migrating to SQL Managed Instance

Starting with SQL Server 2019, if you migrate a database to Azure SQL Managed Instance, and the source database has accelerated database recovery disabled, you can't use accelerated database recovery on the target SQL managed instance.

To work around this issue, make sure you enable accelerated database recovery on the source SQL Server database before you migrate it to SQL Managed Instance. If you already migrated the database without enabling accelerated database recovery, you can enable it on the source SQL Server database, and then re-migrate the database to SQL managed instance.

SQL Server 2017 and earlier versions don't support accelerated database recovery, so this issue doesn't apply to databases migrated from those versions of SQL Server.

Unable to use Service Broker after migrating to SQL Managed Instance

If you migrate a database to Azure SQL Managed Instance, and Service Broker is disabled on the source database, you can't use Service Broker on the target SQL managed instance.

To work around this problem, make sure you enable Service Broker on the source SQL Server database before you migrate it to SQL Managed Instance. If you already migrated the database without enabling Service Broker, you can enable it on the source SQL Server database, and then re-migrate the database to SQL Managed Instance.

Related content

To use the link:

• Prepare your environment for a link
• Configure link with SSMS
• Configure link with scripts
• Fail over link
• Managed Instance link best practices

To learn more about the link:

• Overview of the Managed Instance link
• Disaster recovery with Managed Instance link

For other replication and migration scenarios, consider:

• Transactional replication with Azure SQL Managed Instance
• Overview of Log Replay Service with Azure SQL Managed Instance
• Compare LRS with Managed Instance link