Add migration tips for MI link - replication lag, error 1412, and failover improvements (#36985)

* Migration tips

* Apply suggestions from PR review

Grammar fix.

---------

Co-authored-by: Anna Huff <v-annahuff@microsoft.com>

Author: MashaMSFT

azure-sql/managed-instance/doc-changes-updates-known-issues.md

@@ -27,6 +27,7 @@ This article lists the currently known issues with [Azure SQL Managed Instance](
 | [Unable to use accelerated database recovery after migrating to SQL Managed Instance](#unable-to-use-accelerated-database-recovery-after-migrating-to-sql-managed-instance) | March 2026 | Has workaround | |
 | [Misleading error message when connecting to a read replica using invalid credentials](#misleading-error-message-when-connecting-to-a-read-replica-using-invalid-credentials) | February 2026 |No resolution| |
 | [Modifying backup retention period for the free offer](#modifying-backup-retention-period-for-the-free-offer) | June 2025 | Has workaround | |
+| [Error 1412 when creating a Managed Instance link](#error-1412-when-creating-a-managed-instance-link) | May 2025 | Has workaround | |
 | [Login to read-secondary failed due to long wait on "HADR_DATABASE_WAIT_FOR_TRANSITION_TO_VERSIONING"](#login-to-read-secondary-failed-due-to-long-wait-on-hadr_database_wait_for_transition_to_versioning) | April 2025 | Has workaround | |
 | [Interim guidance on 2024 time zone updates for Paraguay](#interim-guidance-on-2024-time-zone-updates-for-paraguay) | March 2025 | Resolved | February 2026 |
 | [Error 8992 when running DBCC CHECKDB on a SQL Server database that originated from SQL Managed Instance](#error-8992-when-running-dbcc-checkdb-on-a-sql-server-database-that-originated-from-sql-managed-instance) | March 2025 | Has workaround | |
@@ -65,7 +66,6 @@ This article lists the currently known issues with [Azure SQL Managed Instance](
 
 [!INCLUDE [known-issues-after-migration](../includes/sql-managed-instance/known-issues-after-migration.md)]
 
-
 ### Modifying backup retention period for the free offer
 
 You can only modify the backup retention policy of your databases in the free SQL managed instance by using [REST API](/rest/api/sql/managed-backup-short-term-retention-policies), [PowerShell](/powershell/module/az.sql/set-azsqlinstancedatabasebackupshorttermretentionpolicy), and [Azure CLI](/cli/azure/sql/midb/short-term-retention-policy) commands. You can't modify the backup retention policy through the [Azure portal](https://portal.azure.com).
@@ -93,6 +93,14 @@ To work around the issue, first drop the index, or the table with the index, fro
 > [!CAUTION]  
 > If you create a partitioned index on a table after dropping an index as described in this scenario, the table becomes inaccessible.
 
+### Error 1412 when creating a Managed Instance link
+
+When you first create a [link](managed-instance-link-feature-overview.md), the first part of the process seeds a full backup of the database from the primary replica to the secondary replica. After seeding of the full backup completes, the link starts to replicate data by applying the differential data from the primary replica to the secondary replica. This process continues indefinitely until a failover command is issued, or the link is removed.
+
+If a transaction log backup occurs on the primary replica during initial seeding of the full backup, the transaction log truncates. Creating the link fails with error 1412 since the data in the transaction log necessary for initial seeding is no longer available.
+
+If you see error 1412 in the SQL Server error log on Azure SQL Managed Instance, then you must [drop](managed-instance-link-configure-how-to-ssms.md#drop-a-link) and recreate the link. To preemptively avoid this issue, pause transaction log backups during the initial seeding phase. If transaction log backups are necessary during the initial seeding phase, then begin an open transaction to prevent log truncation. For more information, review [Error 1412 when creating a Managed Instance link](managed-instance-link-troubleshoot-how-to.md#error-1412) in the troubleshooting guide for the link feature.
+
 ### List of long-term backups in Azure portal shows backup files for active and deleted databases with the same name
 
 Long-term backups can be listed and managed on Azure portal page for an Azure SQL Managed Instance on the *Backups* tab. The page lists active or deleted databases, basic information about their long-term backups, and link for managing backups. When you select the *Manage* link, a new side pane opens with list of backups. Due to an issue with the filtering logic, the list shows backups for both active database and deleted databases with the same name. This requires a special attention when selecting backups for deletion, to avoid deleting backups for a wrong database.
@@ -271,7 +279,7 @@ Error logs that are available in SQL Managed Instance aren't persisted, and thei
 
 **(Resolved in February 2026)**
 
-On October 14, 2024, the Paraguayan government announced a permanent change to the time zone policy. Paraguay now remains on Daylight Saving Time (DST) year-round, effectively adopting UTC-3 as its standard time. As a result, clocks did not advance by 60 minutes at 12:00 a.m. on March 23, 2025, as previously scheduled. This change affects the Paraguay Standard time zone. Microsoft has released related [Windows updates in February and March 2025](https://techcommunity.microsoft.com/blog/dstblog/paraguay-2025-time-zone-update-now-available/4386720). SQL managed instances using the affected time zone reflect this change, and align to to the new UTC-3 offset.
+On October 14, 2024, the Paraguayan government announced a permanent change to the time zone policy. Paraguay now remains on Daylight Saving Time (DST) year-round, effectively adopting UTC-3 as its standard time. As a result, clocks did not advance by 60 minutes at 12:00 a.m. on March 23, 2025, as previously scheduled. This change affects the Paraguay Standard time zone. Microsoft has released related [Windows updates in February and March 2025](https://techcommunity.microsoft.com/blog/dstblog/paraguay-2025-time-zone-update-now-available/4386720). SQL managed instances using the affected time zone reflect this change, and align to the new UTC-3 offset.
 
 ### Changing the connection type doesn't affect connections through the failover group endpoint
 

azure-sql/managed-instance/managed-instance-link-best-practices.md

@@ -65,6 +65,37 @@ You can monitor the performance of replication by checking the redo queue size o
 
 If the redo queue size is consistently high, consider increasing resources on the secondary replica.
 
+## Monitor replication lag
+
+Monitoring replication lag helps you determine the speed of which the secondary replica synchronizes with the primary replica. A large discrepancy indicates that the secondary replica is having trouble keeping up with the primary replica, which is typically caused by slow network throughput in the link between the two instances, mismatched resource allocation between the two replicas, or by an excessively high workload on the primary replica.
+
+Monitoring replication lag is especially important when performing a planned failover, which requires the secondary replica to be fully synchronized with the primary replica before the failover can be executed. If replication lag is high, the failover might take longer to complete, and in some cases, it might even fail.
+
+Use the following T-SQL query on both SQL Server and SQL Managed Instance to monitor replication lag between the replicas:
+
+```sql
+-- 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
+```
+
 ## Rotate certificate
 
 You might need to manually rotate the certificate used to secure the database mirroring endpoint on SQL Server. Since the service manages and automatically rotates the certificate used to secure the database mirroring endpoint on SQL Managed Instance, you don't need to manually rotate it. 

azure-sql/managed-instance/managed-instance-link-configure-how-to-scripts.md

@@ -94,7 +94,9 @@ As you run scripts from this user guide, it's important not to mistake SQL Serve
 
 ## Set up database recovery and backup
 
-If SQL Server is your initial primary, then databases that will be replicated via the link must be in the full recovery model and have at least one backup.  Since Azure SQL Managed Instance takes backups automatically, skip this step if SQL Managed Instance is your initial primary. 
+If SQL Server is your initial primary, then databases that will be replicated via the link must be in the full recovery model and have at least one backup.  Since Azure SQL Managed Instance takes backups automatically, skip this step if SQL Managed Instance is your initial primary.
+
+When you create a link, the initial seeding between the primary and secondary replicas happens by taking a full backup of the database on the primary replica, transferring it to the secondary replica, and restoring it there. When you take the full backup, we recommend that you use the `WITH CHECKSUM` option to ensure that the backup is valid and doesn't have any corruption. For more information, see [BACKUP (Transact-SQL)](/sql/t-sql/statements/backup-transact-sql).
 
 Run the following code on SQL Server for all databases you wish to replicate. Replace `<DatabaseName>` with your actual database name.
 

azure-sql/managed-instance/managed-instance-link-configure-how-to-ssms.md

@@ -73,12 +73,15 @@ For Azure SQL Managed Instance, you need to be a member of the [SQL Managed Inst
 
 If SQL Server is your initial primary, you need to create a backup of your database. Since Azure SQL Managed Instance takes backups automatically, skip this step if SQL Managed Instance is your initial primary. 
 
+When you create a link, the initial seeding between the primary and secondary replicas happens by taking a full backup of the database on the primary replica, transferring it to the secondary replica, and restoring it there. When you take the full backup, we recommend that you use the `WITH CHECKSUM` option to ensure that the backup is valid and doesn't have any corruption. For more information, see [BACKUP (Transact-SQL)](/sql/t-sql/statements/backup-transact-sql).
+
 Use SSMS to back up your database on SQL Server. Follow these steps:
 
 1. Connect to your SQL Server in SQL Server Management Studio (SSMS). 
 1. In **Object Explorer**, right-click the database, hover over **Tasks**, and then choose **Back up**. 
 1. Choose **Full** for backup type. 
 1. Ensure the **Back up to** option has the backup path to a disk with sufficient free storage space available. 
+1. (Optional but recommended) On the **Media Options** tab, check the box for **Perform checksum before writing to media** to have SQL Server verify the integrity of the backup after it's created.
 1. Select **OK** to complete the full backup. 
 
 For more information, see [Create a Full Database Backup](/sql/relational-databases/backup-restore/create-a-full-database-backup-sql-server).

azure-sql/managed-instance/managed-instance-link-failover-how-to.md

@@ -31,6 +31,37 @@ To fail over your databases to your secondary replica through the link, you need
 
 If you're ready to fail over your database to the secondary replica, first stop any application workloads on the primary replica during your maintenance hours. This enables database replication to catch up on the secondary so you can fail over to the secondary without data loss. Ensure your applications aren't committing transactions to the primary before failing over. 
 
+## Check replication lag
+
+It's important that the secondary replica catches up to the primary replica before performing a planned 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:
+
+```sql
+-- 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 the 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 improving link network throughput between the two instances, or increasing resource capacity on the secondary replica.
+
 ## Fail over a database
 
 You can fail over a linked database by using Transact-SQL (T-SQL),  SQL Server Management Studio, or PowerShell. 
@@ -93,7 +124,7 @@ If you chose to maintain the link for SQL Server 2022, the secondary becomes the
 If you're on SQL Server 2019 and earlier versions, or if you chose to drop the link for SQL Server 2022, the link is dropped and no longer exists after failover completes. The source database and target database on each replica can both execute a read/write workload. They're completely independent. 
 
 > [!IMPORTANT]
-> After successful fail over to SQL Managed Instance, manually repoint your application(s) connection string to the SQL managed instance FQDN to complete the migration or fail over process and continue running in Azure.
+> After successful failover to SQL Managed Instance, manually repoint your application(s) connection string to the SQL managed instance FQDN to complete the migration or fail over process and continue running in Azure.
 
 ### [PowerShell](#tab/powershell)
 
@@ -245,7 +276,7 @@ Remove-AzSqlInstanceLink -ResourceGroupName $ResourceGroup |
 When failover succeeds, the link is dropped and no longer exists. The SQL Server database and SQL Managed Instance database can both execute read/write workloads as they're now completely independent. 
 
 > [!IMPORTANT]
-> After successful fail over to SQL Managed Instance, manually repoint your application(s) connection string to the SQL managed instance FQDN to complete the migration or fail over process and continue running in Azure.
+> After successful failover to SQL Managed Instance, manually repoint your application(s) connection string to the SQL managed instance FQDN to complete the migration or fail over process and continue running in Azure.
 
 After the link is dropped, you can keep the availability group on SQL Server, but you must drop the _distributed_ availability group to remove link metadata from SQL Server. This additional step is only necessary when failing over by using PowerShell since SSMS performs this action for you. 
 
@@ -266,6 +297,10 @@ GO
 > [!IMPORTANT]
 > After executing a planned failover, the replication mode is set to asynchronous.
 
+## Fail over multiple databases
+
+If you plan to fail over multiple databases from instances on the same server, for optimal performance and predictability, fail over 8 databases per instance at a time. For example, if you have 10 instances with 32 linked databases each, fail over 8 databases at a time from each instance, and repeat the process until all databases are failed over.
+
 ## View database after failover
 
 For SQL Server 2022, if you chose to maintain the link, you can check that the distributed availability group exists under **Availability Groups** in **Object Explorer** in SQL Server Management Studio. 

azure-sql/managed-instance/managed-instance-link-migrate.md

@@ -73,15 +73,52 @@ After you've assessed your existing environment, and determined the appropriate
 
 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](managed-instance-link-preparation.md) and then configure a link by using [SQL Server Management Studio (SSMS)](managed-instance-link-configure-how-to-ssms.md) or [scripts](managed-instance-link-configure-how-to-scripts.md).
 
+## 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:
+
+```sql
+-- 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.
-1. Validate all data has made it over to the secondary database on SQL Managed Instance.
+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.
+1. Validate all data has made it over to the secondary database on SQL Managed Instance. Check [replication lag](#check-replication-lag) to ensure the secondary replica is caught up with the primary replica.
 1. [Fail over the link](managed-instance-link-failover-how-to.md) to the secondary SQL managed instance by choosing **Planned failover**.
-1. (For SQL Server 2022 migrations) Check the box to **Remove link after successful failover** to ensure that failover is one way, and the link is removed.
+1. (Optionally) Check the box to **Remove link after successful failover** to ensure that failover is one way, and the link is removed. 
+1. (Optionally) If you're on a supported SQL Server version with a matching SQL Managed Instance [update policy](update-policy.md), you can keep the link after failover to reverse a migration if needed. Check the [reverse a migration section](#reverse-a-migration) for specific version details.
 1. Cut over the application to connect to the SQL managed instance endpoint.
+1. (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