Step By Step

This is a high-level overview of the steps necessary to migrate your database with dsync while minimizing downtime.

Prepare for the migration

Make sure both source and destination databases are accessible from the host where you are planning to run the dsync process. For best performance, run dsync on a host with minimal network latency to the source and the destination. If both databases are in the same geographical region (e.g. US Central), it's best to provision a VM there for dsync.

For MongoDB Atlas and Azure Cosmos DB destinations, we recommend provisioning higher throughput to avoid timeouts during the initial bulk data copy. Additionally, we recommend enabling server-side retries for Azure Cosmos DB destinations, at least for the duration of the migration.

Step 1. Start

Start the dsync process and let it run until it progresses through the initial data copy and the changestream. When the reported events lag is close to 0, the destination is caught up with the source.

Step 2. Prepare your application or service for cutover

While dsync is still running, stop the writes on the source and let the lag go fully to 0. When the "change stream events" counter is no longer growing, the source and destination are in sync.

Note on deletes emulation in Cosmos DB

If you're using Cosmos DB deletes emulation for a Cosmos DB source, it's possible that there's a pending delete detection cycle. A simple restart of the dsync process will force the deletes cycle to happen.

Step 3. Validate the data

Stop the dsync process and restart it with --verify while keeping all other options same.

If dsync reports a validation error, you will need to check the log file for details.

Step 4. Restart your application or service

Your data has been fully migrated, congratulations! Now you can stop the dsync process, repoint your services to the new database and resume normal operation.