Recently, I worked on an interesting Azure SQL Data Sync issue that I thought was worth sharing with the community.
The scenario looked straightforward at first: a database had been restored from another environment and was being configured as a Member database in a new Data Sync group. However, synchronization wasn’t working as expected.
The interesting part was not the new Sync Group itself. It was what the restored database had brought with it from its previous Data Sync configuration.
The scenario
The Member database was a restored copy of a database that had previously participated in another Azure SQL Data Sync group.
After the restored database was configured as a Member in the new environment, synchronization wasn’t working as expected.
During troubleshooting, another important clue emerged. The restored database still had a history with Azure SQL Data Sync, so we needed to determine whether metadata and generated objects from its previous configuration were still present.
This became one of the key areas of the investigation.
Understand the Data Sync architecture first
Before jumping into scripts, it’s important to clearly distinguish the three database roles involved in Azure SQL Data Sync:
- Hub Database: The central database containing the application data being synchronized.
- Member Database: A database that synchronizes with the Hub.
- Sync Metadata Database: A separate Azure SQL Database containing Data Sync metadata and logs.
Microsoft’s documentation explains that Data Sync follows a hub-and-spoke topology and that the Sync Metadata Database contains Data Sync metadata and logs.
This distinction became particularly important during this investigation because the initial diagnostic configuration wasn’t pointing to the expected Sync Metadata Database.
Troubleshooting approach
Here is the troubleshooting flow we followed.
Step 1: Run the Azure SQL Data Sync Health Checker
One of the first tools I recommend for this type of investigation is the public Azure SQL Data Sync Health Checker:
Azure SQL Data Sync Health Checker on GitHub [github.com]
The tool validates whether metadata associated with the Hub and Member is in place and compares the scopes against information in the Sync Metadata Database. Importantly, the Health Checker repository states that it performs validation without changing Data Sync or user objects.
The tool requires the relevant connection details for:
- Sync Metadata Database
- Hub Database
- Member Database
The GitHub repository contains the current script and execution instructions.
What we observed
In our investigation, the initial Health Checker output included messages similar to:
WARNING: dss schema IS MISSING!
WARNING: TaskHosting schema IS MISSING!
Invalid object name ‘dss.syncgroup’.
Invalid object name ‘dss.userdatabase’.
Those errors were important clues, but they needed to be interpreted together with the database roles.
Microsoft’s documentation states that the DataSync schema is used for system-created objects in Hub and Member databases, while the dss and TaskHosting schemas are used for system-created objects in the Sync Metadata Database.
That distinction helped us recognize that we first needed to validate which database was actually being supplied to the Health Checker as the Sync Metadata Database.
Lesson learned
Before treating a missing dss or TaskHosting schema as corruption, first make sure you’re actually connected to the Sync Metadata Database.
That simple validation can save a lot of investigation time.
Step 2: Check the Member database for Data Sync artifacts
Once we had clarified the topology, the investigation moved to the restored Member database.
Because this database had previously participated in Data Sync, we wanted to understand what Data Sync objects were still present.
One of the queries used during troubleshooting was:
SELECT name
FROM sys.tables
WHERE SCHEMA_NAME(schema_id) = ‘DataSync’
AND name NOT LIKE ‘%_tracking%’;
We also inspected:
SELECT *
FROM DataSync.schema_info_dss;
And, when checking the Member database’s Data Sync scope information:
SELECT *
FROM DataSync.scope_info_dss;
These checks helped us understand the Data Sync metadata state of the restored Member database and whether it still contained artifacts associated with its previous configuration.
Why this matters
Microsoft’s current Data Sync best-practices documentation confirms that the DataSync schema is used for system-created objects in Hub and Member databases.
So, when investigating a database restored from an environment where it previously participated in Data Sync, the DataSync schema is an important part of the investigation.
Step 3: Consider the history of the restored database
This was really the turning point in the investigation.
Instead of treating the database simply as a “new Member”, we started looking at it as:
A restored database that had previously been provisioned for another Data Sync configuration.
That’s an important difference.
When troubleshooting a restored database, ask early:
Was this database previously part of another Azure SQL Data Sync group?
If the answer is yes, the database’s previous Data Sync state should be considered during the investigation.
Step 4: Remove the Member before cleanup
In our scenario, the remediation sequence was essentially:
- Remove the restored database from the current Sync Group.
- Clean up the previous Data Sync metadata from the restored Member database.
- Re-add the database as a Member.
- Trigger synchronization again.
For the cleanup portion, we used the following publicly available repository:
SQL Data Sync Cleanup Scripts on GitHub [github.com]
The repository contains several scripts for different purposes, including:
- Data Sync complete cleanup.sql
- Data Sync cleanup hub or member.sql
- cleanup data sync object V2.sql
The specific complete-cleanup script is available here:
Data Sync complete cleanup.sql
Important warning about the cleanup script
Please do not treat this as a general-purpose Data Sync troubleshooting script.
The script itself contains a very clear warning. It immediately cleans Data Sync-related objects associated with the database and says it should be used only for the scenarios specified in the script, including when advised by the support team during a support request.
The repository also explains the different purposes of its cleanup scripts. For example, the complete-cleanup script has more restrictive usage guidance, while the Hub/Member cleanup and object cleanup scripts target different scenarios.
My recommendation: use the Health Checker and read-only diagnostic queries first. Do not jump directly to metadata cleanup without understanding the database topology and existing Data Sync configuration.
Step 5: Validate with one table
After cleaning up the previous Data Sync artifacts, we didn’t immediately assume that everything was resolved.
Instead, we validated with a controlled test.
A test table on the Member side was truncated, the synchronization was started again, and the table began synchronizing successfully.
That provided the confirmation we needed that the previous Data Sync state of the restored Member was an important part of the issue.
Root cause
The troubleshooting pointed to the fact that the restored Member database had previously participated in another Data Sync configuration and retained Data Sync-related metadata/artifacts from that previous state.
After cleaning up the old Data Sync state and reprovisioning the restored database as a Member, synchronization was successfully validated again.
The important lesson for me wasn’t simply the cleanup itself. It was recognizing that restoring a database does not necessarily mean you’re starting with a clean Data Sync state.
A practical troubleshooting flow
For similar scenarios, I would approach the investigation in this order:
- Confirm the architecture
Identify the:
- Hub Database
- Member Database
- Sync Metadata Database
- Run the Health Checker
Use:
Microsoft Azure SQL Data Sync Health Checker [github.com]
Review its output before making changes.
- Inspect the restored Member
Check whether Data Sync-related objects exist:
SELECT name
FROM sys.tables
WHERE SCHEMA_NAME(schema_id) = ‘DataSync’
AND name NOT LIKE ‘%_tracking%’;
Then, where applicable to the database’s current state, inspect:
SELECT *
FROM DataSync.schema_info_dss;
and:
SELECT *
FROM DataSync.scope_info_dss;
- Ask about the database history
Was the database:
- restored from another environment?
- previously a Data Sync Member?
- previously associated with another Sync Group?
That historical context can completely change the direction of the investigation.
- Consider cleanup only after understanding the environment
The public cleanup scripts are available here:
SQL Data Sync Cleanup Scripts [github.com]
These scripts make changes to Data Sync objects and should not be the first troubleshooting step.
- Validate using a controlled test
Once the environment has been correctly cleaned/reconfigured, validate synchronization on a controlled scope before assuming the entire configuration is healthy.
My key takeaways
This troubleshooting experience reinforced a few lessons for me.
- A restored database isn’t necessarily a clean Data Sync database
Restoring the application data doesn’t mean you should ignore the database’s previous synchronization configuration.
- Always distinguish Hub, Member, and Sync Metadata databases
This is especially important when interpreting Health Checker output.
The DataSync schema is associated with system-created objects in Hub and Member databases, while dss and TaskHosting are associated with system-created objects in the Sync Metadata Database.
- Use diagnostics before cleanup
The Azure SQL Data Sync Health Checker is designed to validate Data Sync metadata and objects without making changes.
That makes it a much better starting point than immediately removing objects.
- Database history matters
One of my favorite questions after this investigation is now:
“Was this database ever part of another Data Sync Group?”
It’s a simple question, but in restore or copy scenarios it can reveal an important part of the troubleshooting story.
- Be very careful with metadata cleanup
The public cleanup repository itself provides specific guidance about when each script should be used, and the complete-cleanup script includes an explicit warning before execution.
Always understand the environment and protect your data before performing destructive operations.
One more important consideration: SQL Data Sync retirement
There is also an important longer-term architecture consideration.
Microsoft currently documents that SQL Data Sync retires on September 30, 2027. Existing Sync Groups can continue operating until the retirement date, but Microsoft recommends migrating to alternative data replication and synchronization solutions before then.
So, while troubleshooting existing Data Sync environments remains necessary, organizations using the service should also begin considering their migration strategy.
References and useful tools
Microsoft documentation
Troubleshooting tools