Key Parameters That Speed Up Percona ClusterSync for MongoDB
Percona has published a detailed guide to tuning Percona ClusterSync for MongoDB (PCSM), a synchronization tool that copies data from a source MongoDB cluster to a target cluster. The blog post, written by Ivan Groenewold and Adnan Supic and published on October 1, 2026, explains which parameters matter for the two phases of the sync process and suggests starting values for testing. PCSM first creates a consistent starting point by cloning existing collections and indexes, while at the same time capturing source changes through MongoDB change streams, a real-time feed of database operations. Once the initial copy is complete, PCSM applies those captured changes until the target catches up with the source. The latest architectural changes introduce several new parameters to improve initial clone speed and continuous replication throughput.
The authors advise tuning gradually and watching source and target CPU, disk, and network usage, connection counts, and replication lag after each change. They recommend using Percona Monitoring and Management (PMM), a monitoring tool, to identify bottlenecks, and to keep an eye on the same metrics for the host running PCSM. This measured approach prevents a tuning change from saturating storage or connections.
The initial cloning phase is mainly affected by collection parallelism, read and insert workers, segment size, and read batch size. These values are configured when starting the PCSM process. Collection parallelism is controlled by clone-num-parallel-collections, which defaults to 2, a conservative setting that limits how many collections are cloned at the same time. Percona recommends increasing it when the source has many collections and when both source and target have spare CPU and disk capacity. A reasonable starting point is 4 parallel collections per CPU core, then testing higher values as long as the target is not saturated. Excessive parallelism will increase disk contention and connection usage.
The clone phase also uses clone-num-read-workers and clone-num-insert-workers. The default for read workers is max(NumCPU/4, 1), and the default for insert workers is NumCPU multiplied by 2. Read workers fetch documents from the source, while insert workers write batches to the target. Increase read workers when source reads limit throughput. Increase insert workers when the target has available write capacity and insert queues are building up. Because target indexes are maintained during clone inserts, extra insert workers can increase write contention. The authors caution against increasing both aggressively at the same time. If target CPU or disk latency increases without a matching throughput gain, reduce insert concurrency. PCSM also exposes queue-depth metrics in PMM for continuous replication, including percona_clustersync_mongodb_repl_event_queue_size, percona_clustersync_mongodb_repl_worker_event_queue_size, and percona_clustersync_mongodb_repl_worker_bulk_queue_size.
Continuous replication is mainly affected by worker count, change-stream batch size, queue sizes, bulk size, flush interval, and bulk-write mode. The number of replication workers is set with repl-num-workers, which defaults to the number of CPUs. The guide suggests increasing this when worker queues grow and the target still has available CPU, storage, and connections; a useful test value is twice the number of CPUs. However, more workers will not improve throughput for high-contention workloads, such as operations targeting the same set of documents, because events for the same document remain processed in order on a single worker at a time.
The change-stream batch size is controlled by repl-change-stream-batch-size, with a default of 10,000 events. Larger values reduce round trips to the change stream during sustained workloads. The authors suggest experimenting with 20,000 or 50,000 events, but warn that larger batches use more memory and may increase burst latency.
Two queue parameters, repl-event-queue-size and repl-worker-queue-size, both default to 5,000 events. They absorb temporary bursts between change-stream reading, event routing, and target writes. Test values such as 10,000 or 25,000 when queues fill briefly during write stalls. Larger queues do not improve sustained throughput if the target is permanently slower than the source, and the worker queue is allocated per worker, so its memory impact increases with repl-num-workers.
The bulk write size and flush interval are set with repl-bulk-ops-size and repl-worker-flush-interval. The default bulk size is 5,000 operations and the default flush interval is 1 second. For higher throughput, Percona recommends testing repl-bulk-ops-size=10000 and repl-worker-flush-interval=2s. Larger bulks reduce MongoDB command overhead but may increase replication latency. For lower latency, use a shorter flush interval, such as 100ms to 500ms. Actual bulks are still limited by MongoDB's wire-message size, so large documents may reach the byte limit before the configured operation count.
The asynchronous bulk queue is set with repl-worker-bulk-queue-size, which defaults to 3 and controls how many completed bulks can wait behind an in-flight write. The authors suggest testing 5 or 10 when target writes are slower than event processing. Increasing this value keeps workers busy but also increases memory usage and may allow replication lag to grow when the target cannot keep up.
Another knob is use-collection-bulk-write, which is false by default. By default a single bulk write can contain operations for multiple databases and collections. Setting it to true groups operations by namespace instead, and may improve workloads spread across many collections. PCSM may select collection-level writes automatically for target versions without client-level bulk-write support.
PCSM supports the MongoDB URI option maxPoolSize. If omitted, the driver default is 100 connections per client. The guide gives an example URI of mongodb://target-host/?maxPoolSize=300. Connection-pool sizing becomes important when increasing clone or replication workers. Start with a moderate explicit value and increase it only when workers are waiting for connections. Avoid unlimited pools unless there is a specific reason to remove the limit.
Compression can be tuned separately for source and target connections with source-client-compressors and target-client-compressors. The default preference is snappy, zstd, zlib. PCSM matches the order in which MongoDB negotiates compressors by default. Typically snappy is used because it has the lowest overhead, but its compression is not as good as zstd or zlib. Teams optimizing for the least possible network bandwidth usage may try the other compressors.