Skip to content
Percona Software for MongoDB Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Use Percona ClusterSync for MongoDB

Percona ClusterSync for MongoDB doesn’t automatically start data replication after startup. It has the idle status indicating that it is ready to accept requests.

Understanding the workflow

For an overview of how PCSM works and the replication workflow stages, see How Percona ClusterSync for MongoDB works.

You can interact with Percona ClusterSync for MongoDB using the command-line interface or via the HTTP API. Read more about PCSM HTTP API.

For command-line subcommands, responses are written to stdout while logs and errors are written to stderr. For details on capturing command output, see Logging.

Target collections are overwritten on start

When you start replication (for example, using pcsm start or the /start API endpoint), PCSM drops and recreates the collections selected for replication on the target, overwriting any existing data in those collections. Databases and collections that are not selected for replication remain untouched.

Start the replication

Start the replication process between source and target clusters. PCSM starts copying the data from the source to the target. First it does the initial sync by cloning the data and then applying all the changes that happened since the clone start.

Then it uses change streams to track changes on the source and replicate them to the target.

$ pcsm start
Expected output 
{
  "ok": true
}

Send a POST request to the /start endpoint:

$ curl -X POST http://localhost:2242/start

Start the filtered replication

You can replicate the whole dataset or specific namespaces - databases and collections. You can specify what namespaces to include and/or exclude from the replication.

To include or exclude a specific database and all collections it includes, pass it in the format mydb.*.

When both include and exclude filters are used, the exclude filter takes precedence. For instance, if you include all collections in the mydb database but exclude mydb.users, PCSM will replicate all collections from mydb except mydb.users.

$ pcsm start \ 
--include-namespaces="db1.collection1,db2.collection2" \
--exclude-namespaces="db3.collection3"
Expected output 
{
  "ok": true
}

Send a POST request to the /start endpoint:

$ curl -X POST http://localhost:2242/start -d '{
    "includeNamespaces": ["db1.collection1", "db2.collection2"],
    "excludeNamespaces": ["db3.collection3"]
}'

Pause the replication

You can pause the replication at any moment. PCSM stops the replication, saves the timestamp, and enters the paused state. PCSM uses the saved timestamp after you resume the replication.

$ pcsm pause

Send a POST request to the /pause endpoint:

$ curl -X POST http://localhost:2242/pause

Resume the replication

Resume the replication. PCSM changes the state to running and copies the changes that occurred from the timestamp it saved when you paused the replication. Then it continues monitoring data changes and replicating them in real time. 

$ pcsm resume

Send a POST request to the /resume endpoint:

$ curl -X POST http://localhost:2242/resume

The replication may fail for some reason, like lost connectivity or the like. In this case you can resume replication by adding the --from-failure flag to the resume command:

$ pcsm resume --from-failure

Send a POST request to the /resume endpoint:

$ curl -X POST http://localhost:2242/resume -d '{
    "fromFailure": true
}'

Check the replication status

Check the current status of the replication process.

$ pcsm status

Send a GET request to the /status endpoint:

$ curl http://localhost:2242/status

Finalize the replication

When you no longer need / want to replicate data, finalize the replication. PCSM stops replication, creates the required indexes on the target, and stops. This is a one-time operation. You cannot restart the replication after you finalized it. If you run the start command, PCSM will start the replication anew, with the initial sync. 

$ pcsm finalize

Send a POST request to the /finalize endpoint:

$ curl -X POST http://localhost:2242/finalize

Check finalization status

You can use the /status endpoint to monitor finalization progress and inspect the outcome after it completes.

During finalization, /status indicates that finalization is in progress. After it completes, /status reports the finalization result, including whether any index builds were unsuccessful.

For general /status endpoint details, see the PCSM HTTP API. The example below shows the finalization-specific fields returned after finalization completes.

Example: Finalization completed with one failed index 
{
  "ok": true,
  "state": "finalized",
  "info": "Finalized",
  "lagTimeSeconds": 0,
  "eventsRead": 1234,
  "eventsApplied": 1234,
  "initialSync": {
    "completed": true,
    "cloneCompleted": true,
    "clonedSizeBytes": 1073741824
  },
  "finalization": {
    "completed": true,
    "startedAt": "2026-05-07T10:30:00Z",
    "completedAt": "2026-05-07T10:30:42Z",
    "unsuccessfulIndexes": [
      {
        "namespace": "mydb.users",
        "indexName": "email_unique_idx",
        "type": "failed",
        "reason": "recreate index mydb.users.email_unique_idx: duplicate key error",
        "keys": {"email": 1}
      }
    ]
  }
}

The unsuccessfulIndexes array will not appear if there are no unsuccessful indexes.

Unsuccessful indexes

The unsuccessfulIndexes array lists indexes that could not be finalized successfully on the target cluster. During finalization, PCSM retries the creation of failed and incomplete indexes, while inconsistent indexes are skipped. Only indexes that remain unsuccessful after these retry attempts are reported in the unsuccessfulIndexes array. Each entry contains:

Field Type Description
namespace string The MongoDB namespace containing the index, in database.collection format.
indexName string The index name as registered in the data store.
type string Machine-readable problem category.
keys object Key specification: field names mapped to their sort order or index type.
reason string Human-readable explanation of what was observed during this finalize attempt.

The type field can contain the following values:

Type Reason What it means
failed MongoDB error message (not stable) The index build was attempted and encountered an error and could not be completed successfully. As a result, the index is not available in a usable state on the target cluster.
incomplete MongoDB error message (not stable) The index could not be successfully recreated during the finalization phase. PCSM reports the index as incomplete, and the reason contains the error message returned by MongoDB during the failed recreation attempt.
inconsistent index is missing on one or more source shards Indexes that exist on some shards but are missing on others.
Last update: June 17, 2026
Created: June 17, 2026