Sharding support in Percona ClusterSync for MongoDB (Technical Preview)¶

Technical Preview

Sharding support is available starting with Percona ClusterSync for MongoDB 0.7.0 and is currently in technical preview stage. We encourage you to try it out and share your feedback. This will help us improve the feature in future releases.

Percona ClusterSync for MongoDB supports replication between sharded MongoDB clusters, enabling you to migrate or synchronize data from one sharded deployment to another. This capability allows you to migrate sharded clusters with minimal downtime and synchronize data between sharded clusters for testing or development purposes.

Overview¶

The workflow for sharded clusters is similar to replica sets. See How Percona ClusterSync for MongoDB works for the complete workflow overview. The key difference is that PCSM connects to mongos instances on both the source and target clusters instead of replica set members.

Since PCSM connects through mongos, the cluster topology doesn’t matter. This means the source and target clusters can have different numbers of shards.

PCSM does not continuously replicate sharding metadata from the source to the target. For collections with a ranged shard key, it copies the initial chunk boundaries to the target before the clone starts. Any sharding metadata changes made after that are not replicated. The primary shard name for a collection may also differ between the source and target clusters. See Chunk distribution.

Prerequisites¶

Percona ClusterSync for MongoDB version 0.7.0 or later
Source and target clusters must be sharded MongoDB deployments
Both clusters must be running the same MongoDB version. Check Version requirements for more information about supported versions.

Connection string format¶

When connecting to sharded clusters, use the standard MongoDB connection string format but specify mongos hostname and port instead of replica set members:

mongodb://user:pwd@mongos-host:port/[authdb]?[options]

Since PCSM connects through mongos, you don’t need to specify individual shard members or config servers in the connection string. The mongos router handles routing to the appropriate shards.

For detailed information about authentication and connection string configuration, see Configure authentication in MongoDB.

Sharding-specific behavior¶

Initial sync preparation¶

Before starting the initial sync, PCSM checks which collections are sharded on the source cluster and creates corresponding sharded collections on the destination cluster. The sharding key is preserved from the source cluster. For ranged shard keys, PCSM also copies the initial chunk boundaries and ownership to the target; it does not replicate sharding metadata afterwards.

For a ranged shard key, PCSM then pre-splits the collection using the source chunk boundaries, immediately after it shards the collection on the target and before it copies any documents. Collections with a hashed shard key keep the layout that shardCollection creates. See Chunk distribution.

Balancer operation¶

Percona ClusterSync for MongoDB connects to source and target clusters via a mongos instance. Therefore, you do not need to disable the balancer on either the source or target cluster before starting replication. The target cluster’s balancer continues to operate normally and manages chunk distribution according to its own sharding configuration and balancer settings.

For ranged shard keys, the target also starts from the source chunk boundaries, which leaves the target balancer less data to move once the clone begins. Chunk migrations on either cluster are not replicated to the other, so both clusters keep managing their own layout throughout. See Manage sharded cluster balancer in the MongoDB documentation.

Chunk distribution¶

Version added: 0.10.0

When MongoDB shards an empty collection on a ranged shard key, it creates a single chunk covering the entire range of shard key values. See Data partitioning with chunks in the MongoDB documentation. A clone into that collection would therefore write to a single shard, and the target balancer would move the data afterwards.

PCSM therefore recreates the source chunk boundaries on the target before copying any documents. Clone writes follow the source layout instead of concentrating on one shard, which reduces how much the target balancer has to move afterwards.

This runs automatically for every collection with a ranged shard key, immediately after PCSM shards it on the target. There is no flag and nothing to configure. Collections with a hashed shard key are not pre-split.

Source collection	Target shards	Result on the target
Hashed shard key	Any number	The layout that `shardCollection` creates, unchanged.
Ranged shard key	Same number as the source	The same chunk boundaries and the same ownership pattern as the source.
Ranged shard key	Different number from the source	The same chunk boundaries, with chunks placed to even out the estimated data volume per shard.

Note

PCSM reads the source boundaries once, before the clone, and does not replicate sharding metadata afterwards. Later migrations, splits, merges, and resharding on the source have no effect on the target, so the two layouts drift apart as the balancers work. That is expected and does not indicate a replication problem.

Hashed shard keys¶

PCSM does not pre-split hashed collections, and does not need to. MongoDB already spreads the initial chunks evenly across the shards for a hashed shard key, so PCSM keeps that layout. See Hashed sharding in the MongoDB documentation.

Ranged shard keys¶

With the same number of shards on both sides, the target gets the source boundaries and the same ownership pattern. Shards are paired in sorted order, so a range does not necessarily land on the target shard whose name resembles its source shard.

With different shard counts, the boundaries still come from the source, but the largest chunks are placed first, each on whichever target shard holds the least data at that point. Every shard ends up owning chunks and holding roughly the same volume. The estimate carries across collections, so the large chunks of several collections do not all collect on one shard.

How the two cases look

Same number of shards
---------------------
Source: [MinKey, 100) -> src-a    Target: [MinKey, 100) -> tgt-a
        [100, MaxKey) -> src-b            [100, MaxKey) -> tgt-b

Different number of shards
--------------------------
Target shards: tgt-a, tgt-b
Source chunk sizes: 100 MB, 60 MB, 40 MB

100 MB -> tgt-a        Estimated result:
 60 MB -> tgt-b        tgt-a: 100 MB
 40 MB -> tgt-b        tgt-b: 100 MB

If the pre-split fails¶

A failed pre-split fails the clone for that instance, and there is no fallback to loading into an unsplit collection. Check the log for the reported failure, resolve it on the target cluster, then restart replication with pcsm resume --from-failure. See Resume the replication, Logging in Percona ClusterSync for MongoDB, and the Troubleshooting guide.

Check the layout on the target¶

Connect to the target mongos and look at how a replicated collection is spread:

db.getSiblingDB('<database>').getCollection('<collection>').getShardDistribution()

Look for data on every shard rather than an exact match with the source, since counts differ even immediately after the clone and keep changing as the balancer works. For chunk counts per shard across the cluster, use sh.status() .

Usage¶

The commands and API endpoints for sharded cluster replication are the same as for replica set replication. The workflow follows the same stages as replica set replication. See How Percona ClusterSync for MongoDB works for the complete workflow overview and Use Percona ClusterSync for MongoDB for detailed command instructions.

Next steps¶

Last update: September 8, 2026
Created: September 8, 2026