Edit

Share via

Use PowerShell to update the sync schema in an existing sync group

  • Article

Applies to: Azure SQL Database

Important

SQL Data Sync will be retired on 30 September 2027. Consider migrating to alternative data replication/synchronization solutions.

This Azure PowerShell example updates the sync schema in an existing SQL Data Sync sync group. When you're syncing multiple tables, this script helps you to update the sync schema efficiently. This example demonstrates the use of the UpdateSyncSchema script, which is available on GitHub as UpdateSyncSchema.ps1.

If you don't have an Azure subscription, create an Azure free account before you begin.

Note

This article uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Screenshot that shows how to launch Cloud Shell in a new window.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Screenshot that shows the Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

If you choose to install and use PowerShell locally, this tutorial requires Az PowerShell 1.4.0 or later. If you need to upgrade, see Install Azure PowerShell module. If you are running PowerShell locally, you also need to run Connect-AzAccount to create a connection with Azure.

For an overview of SQL Data Sync, see What is SQL Data Sync for Azure?

SQL Data Sync does not support Azure SQL Managed Instance or Azure Synapse Analytics.

Examples

Add all tables to the sync schema

The following example refreshes the database schema and adds all valid tables in the hub database to the sync schema.

UpdateSyncSchema.ps1 -SubscriptionId <subscriptionId> -ResourceGroupName <resourceGroupName> -ServerName <serverName> -DatabaseName <databaseName> `
    -SyncGroupName <syncGroupName> -RefreshDatabaseSchema $true -AddAllTables $true

Add and remove tables and columns

The following example adds [dbo].[Table1] and [dbo].[Table2].[Column1] to the sync schema and removes [dbo].[Table3].

UpdateSyncSchema.ps1 -SubscriptionId <subscriptionId> -ResourceGroupName <resourceGroupName> -ServerName <serverName> -DatabaseName <databaseName> `
    -SyncGroupName <syncGroupName> -TablesAndColumnsToAdd "[dbo].[Table1],[dbo].[Table2].[Column1]" -TablesAndColumnsToRemove "[dbo].[Table3]"

Script parameters

The UpdateSyncSchema script has the following parameters:

Parameter Notes
$subscriptionId The subscription where the sync group is created.
$resourceGroupName The resource group where the sync group is created.
$serverName The server name of the hub database.
$databaseName The hub database name.
$syncGroupName The sync group name.
$memberName Specify the member name if you want to load the database schema from the sync member instead of from the hub database. If you want to load the database schema from the hub, leave this parameter empty.
$timeoutInSeconds Timeout when the script refreshes database schema. Default is 900 seconds.
$refreshDatabaseSchema Specify whether the script needs to refresh the database schema. If your database schema changed from the previous configuration (for example, if you added a new table or anew column), you need to refresh the schema before you reconfigure it. Default is false.
$addAllTables If this value is true, all valid tables and columns are added to the sync schema. The values of $TablesAndColumnsToAdd and $TablesAndColumnsToRemove are ignored.
$tablesAndColumnsToAdd Specify tables or columns to be added to the sync schema. Each table or column name needs to be fully delimited with the schema name. For example: [dbo].[Table1], [dbo].[Table2].[Column1]. Multiple table or column names can be specified and separated by a comma (,).
$tablesAndColumnsToRemove Specify tables or columns to be removed from the sync schema. Each table or column name needs to be fully delimited with schema name. For example: [dbo].[Table1], [dbo].[Table2].[Column1]. Multiple table or column names can be specified and separated by a comma (,).

Script explanation

The UpdateSyncSchema script uses the following commands. Each command in the table links to command-specific documentation.

Command Notes
Get-AzSqlSyncGroup Returns information about a sync group.
Update-AzSqlSyncGroup Updates a sync group.
Get-AzSqlSyncMember Returns information about a sync member.
Get-AzSqlSyncSchema Returns information about a sync schema.
Update-AzSqlSyncSchema Updates a sync schema.

Related content

For more information about Azure PowerShell, see Azure PowerShell documentation.

Additional SQL Database PowerShell script samples can be found in Azure SQL Database PowerShell scripts.

For more information about SQL Data Sync, see:

For more information about SQL Database, see: