Rediger

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 in single-database link mode.

To migrate multiple databases together through one link, you can extend an existing Always On availability group or create a new one. For this workflow, see Extend an Always On availability group to Azure SQL Managed Instance.

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

Note

You can now migrate your SQL Server instance enabled by Azure Arc to Azure SQL Managed Instance directly through the Azure portal. For more information, see Migrate to Azure SQL Managed Instance.

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 your workloads with a read-only database replica 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.
  • You can migrate multiple databases by using a separate link for each database in single-database link mode, or one link for an availability group in multiple-database link mode.
  • The only true online migration to the Business Critical service tier.

Note

In single-database link mode, you can migrate one database per link and establish multiple links from the same SQL Server instance to SQL Managed Instance. To replicate an existing Always On availability group with multiple databases through one link, use multiple-database link mode. Review the AG extension requirements before configuring the link.

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.

You can't migrate SQL Managed Instance databases encrypted with service-managed TDE keys to SQL Server. To migrate an encrypted database to SQL Server, the database must use a customer-managed key, and the destination SQL Server instance must have access to the same key. For more information, see Set up SQL Server TDE with Azure Key Vault.

Prerequisites

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

Assess and discover

As part of pre-migration, discover your existing data sources, assess migration feasibility, and identify any blocking issues that might prevent your migration. If you already completed these steps, skip this section.

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 you discover data sources, assess any on-premises SQL Server instances that you can migrate to Azure SQL Managed Instance to identify migration blockers or compatibility issues.

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.

If you want to retain reverse failover capabilities, your SQL Server version must match the update policy on your managed instance. For example, provision your managed instance with the SQL Server 2022 update policy for SQL Server 2022, or the SQL Server 2025 update policy for SQL Server 2025. The Always-up-to-date update policy on your managed instance doesn't support reverse failover to SQL Server. For more information, see Update policy and Reverse a migration.

After you create your target SQL managed instance, configure a link between SQL Server and Azure SQL Managed Instance. Use single-database link mode to replicate one database per link, or multiple-database link mode to replicate all databases in a SQL Server Always On availability group through a single Managed Instance link.

First, prepare your environment, including preparing your databases. For single-database link mode, configure a link by using SQL Server Management Studio (SSMS) or scripts. Multiple-database link mode isn't enabled by default; for requirements and steps to enable and configure it, see Extend an Always On availability group to Azure SQL Managed Instance.

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

You can migrate multiple databases by using either single-database or multiple-database link mode. Single-database link mode replicates one database per link, so each database requires a separate link. Multiple-database link mode replicates all databases in a SQL Server Always On availability group through a single Managed Instance link on supported SQL Server versions and cumulative updates.

In single-database link mode, 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.

In multiple-database link mode, the seeding and failover process is managed automatically, so you don't need to manually migrate a limited number of databases at a time as you do in single-database link mode. For requirements and configuration steps, see Extend an Always On availability group to Azure SQL Managed Instance.

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.

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 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, the disabled setting is transferred with the database. You can't enable Service Broker yourself on the migrated database. This is a per-database setting, so other databases on the managed instance aren't affected.

To prevent this issue, 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, contact Microsoft Support to enable it on the migrated database. Alternatively, you can resolve the issue yourself by enabling Service Broker on the source SQL Server database, and then re-migrating the database to SQL Managed Instance.

To use the link:

To learn more about the link:

For other replication and migration scenarios, consider: