Skip to content
Percona Software for MongoDB Documentation

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

Get help from Percona

Use Percona Link for MongoDB

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

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

Before you start

Your target MongoDB cluster may be empty or contain data. PLM replicates data from the source to the target but doesn’t manage the target’s data. If the target already has the same data as the source, PLM overwrites it. However, if the target contains different data, PLM doesn’t delete it during replication. This leads to inconsistencies between the source and target. To ensure consistency, manually delete any existing data from the target before starting replication.

Start the replication

Start the replication process between source and target clusters. PLM 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 the change streams to track the changes to your data on the source and replicate them to the target.

$ plm 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. Currently you can start the filtered replication only via the API. The ability to start it via the CLI will be added in future releases.

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. PLM stops the replication, saves the timestamp and enters the paused state. PLM uses the saved timestamp after you resume the replication.

$ plm pause

Send a POST request to the /pause endpoint:

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

Resume the replication

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

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

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

$ plm 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. PLM stops replication, creates the required indexes on the target, and stops. This is a one-time operation. You cannot restart the replicaton after you finalized it. If you run the start command, PLM will start the replication anew, with the initial sync. 

$ plm finalize

Send a POST request to the /finalize endpoint:

$ curl -X POST http://localhost:2242/finalize
Last update: June 5, 2025
Created: June 5, 2025