percona/percona-clustersync-mongodb repository overview

⁠Percona ClusterSync for MongoDB

Percona ClusterSync for MongoDB (PCSM) is an open-source binary process that replicates data between MongoDB deployments in real time until you manually finalize it. You can also make a one-time data migration from the source to the target with zero downtime.

Key features include:

• Data clone: Transfer existing data from a source MongoDB to a target MongoDB deployment.
• Real-time replication: Percona ClusterSync for MongoDB uses MongoDB change streams⁠ to track changes in your source cluster and replicate them to target in real time.
• Namespace filtering: Specify which databases and collections to include or exclude.
• Automatic index management: Ensure necessary indexes are created on the target.
• HTTP API: Start, finalize, pause, resume, and check replication status via HTTP endpoints.

⁠Supported MongoDB topologies:

• Replica Set to Replica Set: The source and target replica sets can have different numbers of nodes.
• Sharded cluster to Sharded cluster: The source and target sharded clusters can have different numbers of shards.

⁠MongoDB version requirements

• You can synchronize Percona Server for MongoDB or MongoDB Community/Enterprise Advanced/Atlas within the same major versions - 6.0 to 6.0, 7.0 to 7.0, 8.0 to 8.0
• Minimal supported MongoDB versions are: 6.0.17, 7.0.13, 8.0.0

For more information and related downloads for Percona ClusterSync for MongoDB® and other Percona products, please visit http://www.percona.com⁠.

Read Product Documentation⁠

⁠Percona ClusterSync for MongoDB Docker Images

Percona ClusterSync for MongoDB Docker images are created and maintained by the Percona team.

Images are updated when new releases are published.

⁠How to Use the Images

⁠Prerequisites

1. You need to either deploy MongoDB or Percona Server for MongoDB as your source and target clusters, or use existing deployments. Both clusters can run in Docker containers, on virtual machines, or in cloud environments.

2. The PCSM container must be able to reach all nodes in both source and target MongoDB clusters over the network. This includes:

   • All replica set members that can become primary
   • The mongos nodes in source and target clusters

3. Create users in both source and target clusters with appropriate permissions for authentication.

   This is the example command:

   db.getSiblingDB("admin").createUser({
     user: "source",
     pwd: "mys3cretpAss",
     roles: ["backup", "clusterMonitor", "readAnyDatabase"]
   });'
   

   Copy

4. Your source cluster has some data to verify the replication.

⁠Start Percona ClusterSync for MongoDB

1. Start Percona ClusterSync for MongoDB container. You can specify connection strings using environment variables or command-line flags:

   • Using environment variables:

     Use the PCSM_SOURCE_URI and PCSM_TARGET_URI environment variables:

     docker run --name <container-name> --network <mymongo> -d \
     -e PCSM_SOURCE_URI="mongodb://<source-user>:<source-password>@psmdb-source:27017" \
     -e PCSM_TARGET_URI="mongodb://<target-user>:<target-password>@psmdb-target:27017" \
     percona/percona-clustersync-mongodb:<tag>
     

     Copy

   • Using the command line flags:

     Pass the --source and --target flags directly:

     docker run --name <container-name> --network <mymongo> \ 
     -d percona/percona-clustersync-mongodb:<tag> \
     --source "mongodb://<source-user>:<source-password>@psmdb-source:27017" \
     --target "mongodb://<target-user>:<target-password>@psmdb-target:27017"
     

     Copy

     Replace <source-user>:<source-password> and <target-user>:<target-password> with the credentials of the users you created for pcsm process in the source and target clusters.

   Where:

   • container-name is the name you want to assign to your container,
   • PCSM_SOURCE_URI and PCSM_TARGET_URI are environment variables and --source and --target are command line flags for MongoDB Connection URI⁠ strings used to connect to source and target MongoDB clusters.
   • (optional) mymongo is the network where the source and target clusters are running if deployed in Docker, and
   • tag is the tag specifying the version and architecture you need. See the list above for relevant tags, or look at the full list of tags⁠.

2. Check the initial status of PCSM. Replace with the name of your container:

   docker exec -it <container-name> pcsm status
   

   Copy

   The status should be idle, indicating PCSM is ready to accept requests.

⁠Run Percona ClusterSync for MongoDB

Replace pcsm1 with the name of your container in the following commands:

1. Start the replication process:

   docker exec -it pcsm1 pcsm start
   

   Copy

2. Monitor replication by checking the status:

   docker exec -it pcsm1 pcsm status
   

   Copy

3. View logs to monitor activity:

   docker logs -f pcsm1
   

   Copy

⁠User Feedback

We welcome your feedback!