Merge pull request #23237 from WilliamDAssafMSFT/20220715-azure-sql-data-sync

20220715 elaborate permissions, synapse

Author: PRMerger19

azure-sql/database/scripts/sql-data-sync-sync-data-between-sql-databases-rest-api.md

@@ -25,7 +25,7 @@ This REST API example configures SQL Data Sync to sync data between multiple dat
 For an overview of SQL Data Sync, see [Sync data across multiple cloud and on-premises databases with SQL Data Sync in Azure](../sql-data-sync-data-sql-server-sql-database.md).
 
 > [!IMPORTANT]
-> SQL Data Sync does not support Azure SQL Managed Instance at this time.
+> SQL Data Sync does not support Azure SQL Managed Instance or Azure Synapse Analytics at this time.
 
 ## Create sync group
 

azure-sql/database/sql-data-sync-agent-overview.md

@@ -19,7 +19,7 @@ ms.date: 12/20/2018
 Sync data with SQL Server databases by installing and configuring the Data Sync Agent for SQL Data Sync in Azure. For more info about SQL Data Sync, see [Sync data across multiple cloud and on-premises databases with SQL Data Sync](sql-data-sync-data-sql-server-sql-database.md).
 
 > [!IMPORTANT]
-> SQL Data Sync does **not** support Azure SQL Managed Instance at this time.
+> SQL Data Sync does **not** support Azure SQL Managed Instance or Azure Synapse Analytics at this time.
 
 ## Download and install
 
@@ -70,7 +70,7 @@ To immediately invalidate or retire an agent, regenerate its key in the portal b
 If you want to run the local agent from a different computer than it is currently on, do the following things:
 
 1. Install the agent on desired computer.
-2. Log in to the SQL Data Sync portal and regenerate an agent key for the new agent.
+2. Sign in to the SQL Data Sync portal and regenerate an agent key for the new agent.
 3. Use the new agent's UI to submit the new agent key.
 4. Wait while the client agent downloads the list of on-premises databases that were registered earlier.
 5. Provide database credentials for all databases that display as unreachable. These databases must be reachable from the new computer on which the agent is installed.
@@ -81,7 +81,7 @@ In order to delete a Sync metadata database that has a Sync agent associated wit
 
 1. Select the Sync database. 
 2. Go to the **Sync to other databases** page.
-3. Select the Sync agent and click on **Delete**. 
+3. Select the Sync agent and select on **Delete**. 
 
 ## <a name="agent-tshoot"></a> Troubleshoot Data Sync Agent issues
 
@@ -161,7 +161,7 @@ You discover that the agent isn't running on a computer that hosts SQL Server. W
   1. In the **Password** box, enter your password.
   1. In the **Confirm Password** box, reenter your password.
   1. Select **Apply**, and then select **OK**.
-  1. In the **Services** window, right-click the **SQL Data Sync Agent** service, and then click **Start**.
+  1. In the **Services** window, right-click the **SQL Data Sync Agent** service, and then select **Start**.
   1. Close the **Services** window.
 
 ### <a name="agent-key"></a> I can't submit the agent key
@@ -330,7 +330,7 @@ For more info about SQL Data Sync, see the following articles:
         -  [Use PowerShell to sync between a database in Azure SQL Database and a database in a SQL Server instance](scripts/sql-data-sync-sync-data-between-azure-onprem.md)
 -   Best practices - [Best practices for Azure SQL Data Sync](sql-data-sync-best-practices.md)
 -   Monitor - [Monitor SQL Data Sync with Azure Monitor logs](./monitor-tune-overview.md)
--   Troubleshoot - [Troubleshoot issues with Azure SQL Data Sync]sql-data-sync-troubleshoot.md)
+-   Troubleshoot - [Troubleshoot issues with Azure SQL Data Sync](sql-data-sync-troubleshoot.md)
 -   Update the sync schema
     -   With Transact-SQL - [Automate replication of schema changes with SQL Data Sync in Azure](sql-data-sync-update-sync-schema.md)
     -   With PowerShell - [Use PowerShell to update the sync schema in an existing sync group](scripts/update-sync-schema-in-sync-group.md)

azure-sql/database/sql-data-sync-best-practices.md

@@ -9,7 +9,7 @@ ms.topic: conceptual
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: wiassaf, mathoma
-ms.date: 12/20/2018
+ms.date: 07/19/2022
 ---
 # Best practices for Azure SQL Data Sync 
 
@@ -20,25 +20,37 @@ This article describes best practices for Azure SQL Data Sync.
 For an overview of SQL Data Sync, see [Sync data across multiple cloud and on-premises databases with Azure SQL Data Sync](sql-data-sync-data-sql-server-sql-database.md).
 
 > [!IMPORTANT]
-> Azure SQL Data Sync does **not** support Azure SQL Managed Instance at this time.
+> Azure SQL Data Sync does **not** support Azure SQL Managed Instance or Azure Synapse Analytics at this time.
 
 ## <a name="security-and-reliability"></a> Security and reliability
 
 ### Client agent
 
 -   Install the client agent by using the least privileged user account that has network service access.  
 -   Install the client agent on a computer that isn't the SQL Server computer.  
--   Don't register an on-premises database with more than one agent.    
-    -   Avoid this even if you are syncing different tables for different sync groups.  
+-   Don't register an on-premises database with more than one agent.
+    -   Avoid this even if you're syncing different tables for different sync groups.  
     -   Registering an on-premises database with multiple client agents poses challenges when you delete one of the sync groups.
 
 ### Database accounts with least required privileges
 
--   **For sync setup**. Create/Alter Table; Alter Database; Create Procedure; Select/ Alter Schema; Create User-Defined Type.
+-   **For sync setup**: 
+    - SQL Server permissions: CREATE/ALTER TABLE, ALTER DATABASE, CREATE PROCEDURE, SELECT/ALTER SCHEMA, CREATE TYPE. These permissions are included (along with other permissions) in the built-in database role `ddl_admin`.
+    - At the resource group level, membership in the [SQL DB Contributor](/azure/role-based-access-control/built-in-roles#sql-db-contributor) role is necessary. For more information, see [Assign Azure roles using the Azure portal](/azure/role-based-access-control/role-assignments-portal). Membership in broader roles like Contributor or Owner work too, if already assigned.
+    - Permissions at the subscription level should not be needed, but could provide a simplified (though not *least required*) way to provide necessary permissions for multiple Azure Data Sync implementations in a subscription. An original, deprecated API required these [Azure RBAC permissions](/azure/role-based-access-control/resource-provider-operations), but should no longer be in use.
+        - "Microsoft.Sql/locations/syncMemberOperationResults/read"
+        - "Microsoft.Sql/locations/syncAgentOperationResults/read"
+        - "Microsoft.Sql/locations/syncGroupOperationResults/read"
 
--   **For ongoing sync**. Select/ Insert/ Update/ Delete on tables that are selected for syncing, and on sync metadata and tracking tables; Execute permission on stored procedures created by the service; Execute permission on user-defined table types.
+-   **For ongoing sync**. 
+    - SQL Server permissions: SELECT, INSERT, UPDATE, and DELETE permission on user tables that are selected for syncing. EXECUTE permission on user-defined table types.
+    - SQL Server permissions: SELECT, INSERT, UPDATE, and DELETE permission on sync metadata and system-created tracking tables. EXECUTE permission on stored procedures created by the service.
+        - The `DataSync` schema is used for system-created objects in the hub and member databases. 
+        - The `dss` and `TaskHosting` schemas are used for system-created objects in the sync metadata database.
 
--   **For deprovisioning**. Alter on tables part of sync; Select/ Delete on sync metadata tables; Control on sync tracking tables, stored procedures, and user-defined types.
+-   **For deprovisioning**. 
+    - SQL Server permissions: ALTER on all tables part of sync; SELECT and DELETE on sync metadata tables; CONTROL on sync tracking tables, stored procedures, and user-defined types.
+    - For cleanup, remove system-created objects in the `DataSync`, `dss`, and `TaskHosting` schemas.
 
 Azure SQL Database supports only a single set of credentials. To accomplish these tasks within this constraint, consider the following options:
 
@@ -223,7 +235,7 @@ If you have a complex schema to sync, you may encounter an "operation timeout" d
 
 #### Solution
 
-To mitigate this issue, please scale up your sync metadata database to have a higher SKU, such as S3. 
+To mitigate this issue, consider scaling up your sync metadata database resources. 
 
 ## Next steps
 For more information about SQL Data Sync, see:

azure-sql/database/sql-data-sync-data-sql-server-sql-database.md

@@ -13,14 +13,16 @@ ms.topic: conceptual
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: wiassaf, mathoma
-ms.date: 2/2/2022
+ms.date: 07/15/2022
 ---
 # What is SQL Data Sync for Azure?
 
+[!INCLUDE[appliesto-sqldb](../includes/appliesto-sqldb.md)]
+
 SQL Data Sync is a service built on Azure SQL Database that lets you synchronize the data you select bi-directionally across multiple databases, both on-premises and in the cloud. 
 
 > [!IMPORTANT]
-> Azure SQL Data Sync does not support Azure SQL Managed Instance at this time.
+> Azure SQL Data Sync does not support Azure SQL Managed Instance or Azure Synapse Analytics at this time.
 
 
 ## Overview 
@@ -31,7 +33,7 @@ Data Sync uses a hub and spoke topology to synchronize data. You define one of t
 
 - The **Hub Database** must be an Azure SQL Database.
 - The **member databases** can be either databases in Azure SQL Database or in instances of SQL Server.
-- The **Sync Metadata Database** contains the metadata and log for Data Sync. The Sync Metadata Database has to be an Azure SQL Database located in the same region as the Hub Database. The Sync Metadata Database is customer created and customer owned. You can only have one Sync Metadata Database per region and subscription. Sync Metadata Database cannot be deleted or renamed while sync groups or sync agents exist. Microsoft recommends to create a new, empty database for use as the Sync Metadata Database. Data Sync creates tables in this database and runs a frequent workload.
+- The **Sync Metadata Database** contains the metadata and log for Data Sync. The Sync Metadata Database has to be an Azure SQL Database located in the same region as the Hub Database. The Sync Metadata Database is customer created and customer owned. You can only have one Sync Metadata Database per region and subscription. Sync Metadata Database cannot be deleted or renamed while sync groups or sync agents exist. Microsoft recommends creating a new, empty database for use as the Sync Metadata Database. Data Sync creates tables in this database and runs a frequent workload.
 
 > [!NOTE]
 > If you're using an on premises database as a member database, you have to [install and configure a local sync agent](sql-data-sync-sql-server-configure.md#add-on-prem).
@@ -139,23 +141,24 @@ Provisioning and deprovisioning during sync group creation, update, and deletion
 
 - Snapshot isolation must be enabled for both Sync members and hub. For more info, see [Snapshot Isolation in SQL Server](/dotnet/framework/data/adonet/sql/snapshot-isolation-in-sql-server).
 
-- In order to use Data Sync private link, both the member and hub databases must be hosted in Azure (same or different regions), in the same cloud type (e.g. both in public cloud or both in government cloud). Additionally, to use private link, Microsoft.Network resource providers must be Registered for the subscriptions that host the hub and member servers. Lastly, you must manually approve the private link for Data Sync during the sync configuration, within the “Private endpoint connections” section in the Azure portal or through PowerShell. For more details on how to approve the private link, see [Set up SQL Data Sync](./sql-data-sync-sql-server-configure.md). Once you approve the service managed private endpoint, all communication between the sync service and the member/hub databases will happen over the private link. Existing sync groups can be updated to have this feature enabled.
+- In order to use Data Sync private link, both the member and hub databases must be hosted in Azure (same or different regions), in the same cloud type (for example, both in public cloud or both in government cloud). Additionally, to use private link, `Microsoft.Network` resource providers must be Registered for the subscriptions that host the hub and member servers. Lastly, you must manually approve the private link for Data Sync during the sync configuration, within the "Private endpoint connections" section in the Azure portal or through PowerShell. For more information on how to approve the private link, see [Set up SQL Data Sync](./sql-data-sync-sql-server-configure.md). Once you approve the service managed private endpoint, all communication between the sync service and the member/hub databases will happen over the private link. Existing sync groups can be updated to have this feature enabled.
 
 ### General limitations
 
 - A table can't have an identity column that isn't the primary key.
 - A primary key can't have the following data types: sql_variant, binary, varbinary, image, xml.
 - Be cautious when you use the following data types as a primary key, because the supported precision is only to the second: time, datetime, datetime2, datetimeoffset.
-- The names of objects (databases, tables, and columns) can't contain the printable characters period (.), left square bracket ([), or right square bracket (]).
-- A table name can't contain printable characters: ! " # $ % ' ( ) * + - space
+- The names of objects (databases, tables, and columns) can't contain the printable characters period (`.`), left square bracket (`[`), or right square bracket (`]`).
+- A table name can't contain printable characters: `! " # $ % ' ( ) * + -` or space.
 - Azure Active Directory authentication isn't supported.
-- If there are tables with the same name but different schema (for example, dbo.customers and sales.customers) only one of the tables can be added into sync.
-- Columns with User-Defined Data Types aren't supported
+- If there are tables with the same name but different schema (for example, `dbo.customers` and `sales.customers`) only one of the tables can be added into sync.
+- Columns with user-defined data types aren't supported.
 - Moving servers between different subscriptions isn't supported. 
-- If two primary keys are only different in case (e.g. Foo and foo), Data Sync won't support this scenario.
+- If two primary keys are only different in case (for example, `Foo` and `foo`), Data Sync won't support this scenario.
 - Truncating tables is not an operation supported by Data Sync (changes won't be tracked).
-- Using a Hyperscale database as a Hub or Sync Metadata database is not supported. However, a Hyperscale database can be a member database in a Data Sync topology.
+- Using an Azure SQL Hyperscale database as a Hub or Sync Metadata database is not supported. However, a Hyperscale database can be a member database in a Data Sync topology.
 - Memory-optimized tables are not supported.
+- Schema changes aren't automatically replicated. A custom solution can be created to [automate the replication of schema changes](./sql-data-sync-update-sync-schema.md).
 
 #### Unsupported data types
 
@@ -191,7 +194,7 @@ Data Sync can't sync read-only or system-generated columns. For example:
 > [!NOTE]
 > If you use Sync private link, these network requirements do not apply. 
 
-When the sync group is established, the Data Sync service needs to connect to the hub database. At the time when you establish the sync group, the Azure SQL server must have the following configuration in its `Firewalls and virtual networks` settings:
+When the sync group is established, the Data Sync service needs to connect to the hub database. When establishing the sync group, the Azure SQL server must have the following configuration in its `Firewalls and virtual networks` settings:
 
  * *Deny public network access* must be set to *Off*.
  * *Allow Azure services and resources to access this server* must be set to *Yes*, or you must create IP rules for the [IP addresses used by Data Sync service](network-access-controls-overview.md#data-sync).
@@ -230,9 +233,9 @@ Yes. You can configure sync between databases that belong to resource groups own
 - If the subscriptions belong to the same tenant and you have permission to all subscriptions, you can configure the sync group in the Azure portal.
 - Otherwise, you have to use PowerShell to add the sync members.
 
-### Can I setup Data Sync to sync between databases in SQL Database that belong to different clouds (like Azure Public Cloud and Azure China 21Vianet)
+### Can I set up Data Sync to sync between databases in SQL Database that belong to different clouds (like Azure Public Cloud and Azure China 21Vianet)
 
-Yes. You can setup sync between databases that belong to different clouds. You have to use PowerShell to add the sync members that belong to the different subscriptions.
+Yes. You can set up sync between databases that belong to different clouds. You have to use PowerShell to add the sync members that belong to the different subscriptions.
 
 ### Can I use Data Sync to seed data from my production database to an empty database, and then sync them
 

azure-sql/database/sql-data-sync-sql-server-configure.md

@@ -11,7 +11,7 @@ ms.topic: tutorial
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: wiassaf, mathoma
-ms.date: 01/14/2019
+ms.date: 07/16/2022
 ---
 # Tutorial: Set up SQL Data Sync between databases in Azure SQL Database and SQL Server
 [!INCLUDE[appliesto-sqldb](../includes/appliesto-sqldb.md)]
@@ -25,7 +25,7 @@ For an overview of SQL Data Sync, see [Sync data across cloud and on-premises da
 For PowerShell examples on how to configure SQL Data Sync, see [How to sync between databases in SQL Database](scripts/sql-data-sync-sync-data-between-sql-databases.md) or [between databases in Azure SQL Database and SQL Server](scripts/sql-data-sync-sync-data-between-azure-onprem.md)
 
 > [!IMPORTANT]
-> SQL Data Sync does **not** support Azure SQL Managed Instance at this time.
+> SQL Data Sync does **not** support Azure SQL Managed Instance or Azure Synapse Analytics at this time.
 
 ## Create sync group
 
@@ -223,9 +223,9 @@ When you change the data type of an existing column, Data Sync continues to work
 
 **How can I export and import a database with Data Sync?**
 
-After you export a database as a *.bacpac* file and import the file to create a database, do the following to use Data Sync in the new database:
+After you export a database as a `.bacpac` file and import the file to create a database, do the following to use Data Sync in the new database:
 
-1. Clean up the Data Sync objects and additional tables on the new database by using [this script](https://github.com/vitomaz-msft/DataSyncMetadataCleanup/blob/master/Data%20Sync%20complete%20cleanup.sql). The script deletes all the required Data Sync objects from the database.
+1. Clean up the Data Sync objects and additional tables on the new database by using [Data Sync complete cleanup.sql](https://github.com/vitomaz-msft/DataSyncMetadataCleanup/blob/master/Data%20Sync%20complete%20cleanup.sql). The script deletes all the required Data Sync objects from the database.
 1. Recreate the sync group with the new database. If you no longer need the old sync group, delete it.
 
 **Where can I find information on the client agent?**
@@ -238,7 +238,7 @@ Yes, you must manually approve the service managed private endpoint, in the Priv
 
 **Why do I get a firewall error when the Sync job is provisioning my Azure database?**
 
-This may happen because Azure resources are not allowed to access your server. Ensure that the firewall on the Azure database has "Allow Azure services and resources to access this server” setting set to "Yes".
+This may happen because Azure resources are not allowed to access your server. Ensure that the firewall on the Azure database has set "Allow Azure services and resources to access this server" to "Yes".
 
 
 ## Next steps