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.

Command lineHTTP API

$ 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.

Command lineHTTP API

$ 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.

Command lineHTTP API

$ 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.

Command lineHTTP API

$ 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:

Command lineHTTP API

$ 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.

Command lineHTTP API

$ 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.

Command lineHTTP API

$ pcsm finalize

Send a POST request to the /finalize endpoint:

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

Finalize after losing the source cluster

If the source cluster becomes unavailable after initial sync completes, you can still finalize replication and use the target cluster for reads and writes, as long as PCSM keeps running and the replication state is not failed. PCSM connects to the source cluster at startup, so it cannot start or restart while the source is unavailable. This applies to replica sets and sharded clusters.

The target might have missing data

Finalization can succeed even when the target is behind the source. Changes that did not reach PCSM before the outage can be missing from the target, even if replication appeared caught up. PCSM cannot verify that the target contains all changes made before the source became unavailable. Consider the impact of any missing changes on your application before using the target.

Before finalizing, check the replication status:

1. Check the replication status and confirm that initialSync.completed is true. You cannot finalize before initial sync completes.

2. Review lastReplicatedOpTime in the status response and compare it with the time the source became unavailable. Do not rely in this case on lagTimeSeconds which is calculated from the source cluster time.

   Neither value guarantees that the target contains all source changes.

3. Check whether replication was paused before the outage. Any changes made on the source during the pause can be missing from the target.

   For example, if replication was paused and the source received new writes before becoming unavailable, finalization can still succeed. Those writes can remain missing from the target.

To finalize replication:

1. Run pcsm finalize or send a POST request to /finalize, as shown above. PCSM first pauses replication and waits for queued writes to drain. If the request times out during the pause, finalization does not start. Wait until state is paused and run the command again. If state becomes failed, you cannot finalize.

2. Check finalization status until state is finalized and finalization.completed is true.

3. Review any unsuccessful indexes before using the target for reads and writes. With the source unavailable, PCSM cannot recheck incomplete or inconsistent indexes against the source. They stay in unsuccessfulIndexes even though finalization completes, so resolve them on the target yourself.

This behavior is also listed in Known limitations.

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 recreates failed indexes from their stored specifications. It rechecks incomplete and inconsistent indexes against the source and recreates them from the current source specification only if the index still exists on the source, is no longer building, and is consistent across source shards. Only indexes that remain unsuccessful are reported in the unsuccessfulIndexes array. With the source unavailable, PCSM cannot recheck incomplete or inconsistent indexes, so they remain in unsuccessfulIndexes even though finalization completes. 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: November 5, 2026
Created: November 5, 2026