Merge pull request #217485 from WilliamDAssafMSFT/20221107-synapse-link-troubleshoot-aad

20221107 troubleshooting guides for Synapse Link

Author: BCS2022

articles/synapse-analytics/overview-faq.yml

@@ -70,7 +70,7 @@ sections:
           Azure Synapse Analytics currently supports Azure Synapse Link from Azure Cosmos DB to Synapse Apache Spark and serverless SQL pool. Azure Synapse Link for Apache Spark is GA. Synapse Link for serverless SQL pool is in preview. For more information, see [Azure Synapse Link for Azure Cosmos DB](../cosmos-db/synapse-link.md).
 
       - question: |
-          Is Azure Synapse Link to SQL Server 2022 generally available?
+          Is Azure Synapse Link for SQL Server 2022 generally available?
         answer: |
           Azure Synapse Link for SQL Server 2022 is in preview. For more information, see [What is Azure Synapse Link for SQL?](synapse-link/sql-synapse-link-overview.md).
 

articles/synapse-analytics/synapse-link/faq.yml

@@ -103,18 +103,18 @@ sections:
         answer: |
           A new change feed processor has been integrated into the Azure SQL Database and SQL Server 2022 engine to enable this functionality.
       - question: |
-          How do I rotate or change the SAS for the Landing Zone for Azure Synapse Link to SQL Server?
+          How do I rotate or change the SAS for the Landing Zone for Azure Synapse Link for SQL Server?
         answer: |
           If the SAS has expired for the user managed storage account for the Landing Zone, use [ALTER DATABASE SCOPED CREDENTIAL](/sql/t-sql/statements/alter-database-scoped-credential-transact-sql) to update the database credential for the new SAS. 
       - question: |
           What is the impact when a user removes the Azure Synapse workspace that contains an Azure Synapse Link to Azure SQL DB?
         answer: |
           If the Azure Synapse workspace is removed, Azure SQL DB will stop data replication from landing zone into Azure Synapse. The system stored procedure [sp_change_feed_drop_table_group](/sql/relational-databases/system-stored-procedures/sp-change-feed-drop-table-group) will be called automatically, and the storage account for the landing zone is managed and will be cleaned up automatically. If this fails, you may receive error 22739 from the SynapseGatewayClient in [sys.dm_change_feed_errors](/sql/relational-databases/system-dynamic-management-views/sys-dm-change-feed-errors). If this occurs, you can manually drop the changefeed table group with `sp_change_feed_drop_table_group`.
       - question: |
-          What is the impact when a user removes the Azure Synapse workspace that contains an Azure Synapse Link to SQL Server?
+          What is the impact when a user removes the Azure Synapse workspace that contains an Azure Synapse Link for SQL Server?
         answer: | 
           In SQL Server, since landing zone storage account is user managed, data will continue to be published to the landing zone. You should disable the Azure Synapse Link by dropping the relevant table groups with [sp_change_feed_drop_table_group](/sql/relational-databases/system-stored-procedures/sp-change-feed-drop-table-group), and manually remove the storage account for the landing zone.
       - question: |
-          What is the impact when a user intentionally removes the Azure Synapse Link landing zone for Azure Synapse Link to SQL Server?
+          What is the impact when a user intentionally removes the Azure Synapse Link landing zone for Azure Synapse Link for SQL Server?
         answer: | 
           In SQL Server, the landing zone storage account is user managed. If the landing zone storage account is no longer accessible, and there will be errors in the [sys.dm_change_feed_errors](/sql/relational-databases/system-dynamic-management-views/sys-dm-change-feed-errors). You should disable the Azure Synapse Link by dropping the relevant table groups with [sp_change_feed_drop_table_group](/sql/relational-databases/system-stored-procedures/sp-change-feed-drop-table-group).

articles/synapse-analytics/synapse-link/synapse-link-for-sql-known-issues.md

@@ -80,7 +80,7 @@ This is the list of known limitations for Azure Synapse Link for SQL.
 * Azure Synapse Link can't be enabled on the secondary database once a GeoDR failover has happened if the secondary database has a different name from the primary database.
 * If you enabled Azure Synapse Link for SQL on your database as a Microsoft Azure Active Directory (Azure AD) user, Point-in-time restore (PITR) will fail. PITR will only work when you enable Azure Synapse Link for SQL on your database as a SQL user.
 * If you create a database as an Azure AD user and enable Azure Synapse Link for SQL, a SQL authentication user (for example, even sysadmin role) won't be able to disable/make changes to Azure Synapse Link for SQL artifacts.  However, another Azure AD user will be able to enable/disable Azure Synapse Link for SQL on the same database. Similarly, if you create a database as an SQL authentication user, enabling/disabling Azure Synapse Link for SQL as an Azure AD user won't work.
-* When enabling Azure Synapse Link for SQL on your Azure SQL Database, you should ensure that aggressive log truncation is disabled.
+* While enabling Azure Synapse Link for SQL on Azure SQL Database or SQL Server, please be aware that the aggressive log truncation feature of Accelerated Database Recovery (ADR) is automatically disabled. This is because Azure Synapse Link for SQL accesses the database transaction log. This behavior is similar to Changed Data Capture (CDC). Active transactions will continue to hold the transaction log truncation until the transaction commits and Azure Synapse Link for SQL catches up, or transaction aborts. This might result in the transaction log filling up more than usual and should be monitored so that the transaction log does not fill.
 
 ### SQL Server 2022 only
 * Azure Synapse Link for SQL can't be enabled on databases that are transactional replication publishers or distributors.

articles/synapse-analytics/synapse-link/troubleshoot/media/troubleshoot-sql-database-failover/synapse-studio-edit-linked-service-system-assigned-managed-identity.png

@@ -0,0 +1,37 @@
+---
+title: Troubleshooting guide for Azure Synapse Link for Azure SQL Database and Azure Active Directory user impersonation
+description: Learn how to troubleshoot user impersonation issues with Azure Synapse Link for Azure SQL Database and Azure Active Directory 
+author: WilliamDAssafMSFT
+ms.author: wiassaf
+ms.reviewer: imotiwala 
+ms.service: synapse-analytics
+ms.topic: how-to
+ms.subservice: synapse-link
+ms.date: 11/09/2022
+---
+
+# Troubleshoot: Azure Synapse Link for Azure SQL Database and Azure Active Directory user impersonation
+
+This article is a guide to troubleshoot Azure Synapse Link for Azure SQL Database and Azure Active Directory (Azure AD) user impersonation. This article applies only to databases in Azure SQL Database. 
+
+## Symptom
+
+If you create database using a login connected to Microsoft Azure Active Directory and then try to perform Azure Synapse Link database operations signed in with any SQL Authenticated principal, you will receive error messages due to an impersonation failure. The following sample errors are all a symptom of the same problem.
+
+| Database Operation | Sample Error |
+|:--|:--|
+| sp_change_feed_enable_db, sp_change_feed_disable_db | `The error/state returned was 33171/1: 'Only active directory users can impersonate other active directory users.'. Use the action and error to determine the cause of the failure and resubmit the request.` |
+| Restore an Azure Synapse Link enabled database | `Non retriable error occurred while restoring backup with index 11 - 22729 Could not remove the metadata. The failure occurred when executing the command 'sp_MSchange_feed_ddl_database_triggers 'drop''. The error/state returned was 33171/1: 'Only active directory users can impersonate other active directory users.'. Use the action and error to determine the cause of the failure and resubmit the request. RESTORE DATABASE successfully processed 0 pages in 0.751 seconds (0.000 MB/sec). `|
+| Restore a blank database and then enable Azure Synapse Link | `The error returned was 33171: 'Only active directory users can impersonate other active directory users.'. Use the action and error to determine the cause of the failure and resubmit the request.` |
+
+## Resolution
+
+Sign in to the Azure SQL Database with an Azure AD database principal. It doesn't have to be the same Azure AD account that created the database. 
+
+## See also
+
+ - [Change data capture limitations](/sql/relational-databases/track-changes/about-change-data-capture-sql-server#limitations)
+
+## Next steps
+
+ - [Get started with Azure Synapse Link for Azure SQL Database](../connect-synapse-link-sql-database.md)

articles/synapse-analytics/synapse-link/troubleshoot/media/troubleshoot-sql-database-failover/synapse-studio-integrate-link-connection-refresh.png

@@ -0,0 +1,65 @@
+---
+title: Troubleshooting guide for Azure Synapse Link for Azure SQL Database after failover of an Azure SQL Database.
+description: Learn how to troubleshoot and configure Azure Synapse Link for Azure SQL Database after failover of an Azure SQL Database.
+author: WilliamDAssafMSFT
+ms.author: wiassaf
+ms.reviewer: imotiwala 
+ms.service: synapse-analytics
+ms.topic: how-to
+ms.subservice: synapse-link
+ms.date: 11/09/2022
+---
+
+# Troubleshoot: Azure Synapse Link for Azure SQL Database after failover of an Azure SQL Database
+
+This article is a guide to troubleshoot and configure Azure Synapse Link for Azure SQL Database after failover of an Azure SQL Database. This article applies only to databases in Azure SQL Database. 
+
+## Symptom
+
+For the safety of data, users may choose to set [auto-failover group](/sql/azure-sql/database/failover-group-add-single-database-tutorial) for Azure SQL Database. By setting failover group, users can group multiple geo-replicated databases that can protect a potential data loss. However, when Azure Synapse Link for Azure SQL Database has been started for the table in the Azure SQL Database and the database experiences failover, Synapse Link will be disabled in the backend even though its status is still displayed as running. 
+
+## Resolution
+
+You must stop Synapse Link manually and configure Synapse Link according to the new primary server's information so that it can continue to work normally.  
+
+1. Launch [Synapse Studio](https://web.azuresynapse.net).
+1. Open the **Integrate** hub.
+1. Select the Synapse Link whose database has failover occurred.
+1. Select the **Stop** button.
+
+    :::image type="content" source="media/troubleshoot-sql-database-failover/synapse-studio-stop-link-connection.png" alt-text="A screenshot of Synapse Studio. The Integrate hub is open and the Link Connection linkconnection1 is selected. The Stop button is highlighted." lightbox="media/troubleshoot-sql-database-failover/synapse-studio-stop-link-connection.png":::
+
+1. Open the **Manage** hub. Under **External connections**, select **Linked services**.
+1. In the list of **Linked services**, select the linked service whose database failed over.
+
+    :::image type="content" source="media/troubleshoot-sql-database-failover/synapse-studio-linked-services.png" alt-text="A screenshot of Synapse Studio. The Manage hub is open. In the list of Linked services, the AzureSqlDatabase1 linked service is highlighted." lightbox="media/troubleshoot-sql-database-failover/synapse-studio-linked-services.png":::
+
+1. You must reset the linked service connection string based on the new primary server after failover so that Synapse Link can connect to the new primary logical server's database. There are two options:
+    * Use [the auto-failover group read/write listener endpoint](/sql/azure-sql/managed-instance/auto-failover-group-configure-sql-mi#locate-listener-endpoint) and use the Synapse workspace's managed identity (SMI) to connect your Synapse workspace to the source database. Because of Read/Write listener endpoint that automatically maps to the new primary server after failover, so you only need to set it once. If failover occurs later, it will automatically use the fully-qualified domain name (FQDN) of the listener endpoint. Note that you still need to take action on every failover to update the Resource ID and Managed Identity ID for the new primary (see next step).
+    * After each failover, edit the linked service **Connection string** with the **Server name**, **Database name**, and authentication information for the new primary server. You can use a managed identity or SQL Authentication. 
+
+    The authentication account used to connect to the database, whether it be a managed identity or SQL Authenticated login to the Azure SQL Database, must have at least the CONTROL permission inside the database to perform the actions necessary for the linked service. The db_owner permission is similar to CONTROL.
+
+    To use the auto-failover group read/write listener endpoint:
+
+    :::image type="content" source="media/troubleshoot-sql-database-failover/synapse-studio-edit-linked-service-system-assigned-managed-identity.png" alt-text="Screenshot of the Azure Synapse Studio Edit linked service dialog. The FQDN of the read/write listener endpoint is entered manually." lightbox="media/troubleshoot-sql-database-failover/synapse-studio-edit-linked-service-system-assigned-managed-identity.png":::
+
+1. You must refresh the Resource ID and Managed Identity ID after every failover. Open the **Integrate** hub. Select your Synapse Link.
+1. The next step depends on the connection string you chose previously.
+    - If you choose to use the Read/Write listener endpoint for updating linked service connection string, you must update the **SQL logical server resource ID** and **Managed identity ID** corresponding to the new primary server manually. 
+    - If you provided the new primary server's connection information, select the **Refresh** button.
+    
+    :::image type="content" source="media/troubleshoot-sql-database-failover/synapse-studio-integrate-link-connection-refresh.png" alt-text="A screenshot of the Integrate hub of Synapse Studio. The Refresh button updates the SQL logical server resource ID and the managed identity ID." lightbox="media/troubleshoot-sql-database-failover/synapse-studio-integrate-link-connection-refresh.png":::
+
+1. Azure Synapse Link for Azure SQL Database currently cannot restart the synchronization from before the failover. Before restarting the Link connection, you must empty the target table in Azure Synapse if data is present. Or, check the option to **Drop and recreate table on target**, as seen in the following screenshot.
+
+    :::image type="content" source="media/troubleshoot-sql-database-failover/synapse-studio-start-drop-recreate-table-target.png" alt-text="A screenshot of the Integrate hub of Synapse Studio. The Drop and recreate table on target option is highlighted. The Start button is highlighted." lightbox="media/troubleshoot-sql-database-failover/synapse-studio-start-drop-recreate-table-target.png":::
+
+1. Finally, restart the Azure Synapse Link. On the **Integrate** hub and with the desired Link connection open, select the **Start** button.
+
+
+ 
+## Next steps
+
+ - [Tutorial: Add an Azure SQL Database to an auto-failover group](/sql/azure-sql/database/failover-group-add-single-database-tutorial)
+ - [Get started with Azure Synapse Link for Azure SQL Database](../connect-synapse-link-sql-database.md)