diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d75bd23..4569537 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,18 @@ # Contributing guide -Welcome to Percona Link for MongoDB documentation! +Welcome to Percona ClusterSync for MongoDB documentation! We're glad that you would like to become a Percona community member and participate in keeping open source open. -Percona Link for MongoDB is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It supports cloning data, replicating changes, and managing collections and indexes. +Percona ClusterSync for MongoDB is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It supports cloning data, replicating changes, and managing collections and indexes. -This repository contains the source file for PLM documentation and this document explains how you can contribute to it. +This repository contains the source file for PCSM documentation and this document explains how you can contribute to it. -If you'd like to submit a PLM code patch, follow the [Contributing section in PLM's code repository](https://github.com/percona/percona-link-mongodb/blob/main/README.md#contributing). +If you'd like to submit a PCSM code patch, follow the [Contributing section in PCSM's code repository](https://github.com/percona/percona-clustersync-mongodb/blob/main/README.md#contributing). ## Contributing to documentation -Percona Backup for MongoDB documentation is written in [Markdown] language, so you can +Percona ClusterSync for MongoDB documentation is written in [Markdown] language, so you can [edit it online via GitHub](#edit-documentation-online-via-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally). Before you start, learn what [git], [MkDocs] and [Docker] are and what [Markdown] is and how to write it. For your convenience, there's also a cheat sheet to help you with the syntax. @@ -21,7 +21,7 @@ The doc files are in the `docs` directory. ### Edit documentation online via GitHub -1. Click the **Edit this page** icon next to the page title. The source `.md` file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. +1. Click the **Edit this page**. The source `.md` file of the page opens in GitHub editor in your browser. If you haven't worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. 2. Edit the page. You can check your changes on the **Preview** tab. @@ -44,13 +44,13 @@ The steps are the following: 2. Clone the repository on your machine: ```sh -git clone git@github.com:/plm-docs.git +git clone git@github.com:/pcsm-docs.git ``` -3. Change the directory to ``pbm-docs`` and add the remote upstream repository: +1. Change the directory to `pcsm-docs` and add the remote upstream repository: ```sh -git remote add upstream git@github.com:percona/plm-docs.git +git remote add upstream git@github.com:percona/pcsm-docs.git ``` 4. Pull the latest changes from upstream @@ -74,32 +74,9 @@ git checkout -b ### Building the documentation -To verify how your changes look, generate the static site with the documentation. This process is called *building*. You can do it in these ways: +To verify how your changes look, generate the static site with the documentation. This process is called *building*. -- [Use Docker](#use-docker) -- [Install MkDocs and build locally](#install-sphinx-and-build-locally) - -#### Use Docker - -1. [Get Docker](https://docs.docker.com/get-docker/) -2. We use [our Docker image](https://hub.docker.com/repository/docker/perconalab/pmm-doc-md) to build documentation. Run the following command: - -```sh -docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -``` - If Docker can't find the image locally, it first downloads the image, and then runs it to build the documentation. - -3. Go to the ``site`` directory and open the ``index.html`` file to see the documentation. - -If you want to see the changes as you edit the docs, use this command instead: - -```sh -docker run --rm -v $(pwd):/docs -p 8000:8000 perconalab/pmm-doc-md mkdocs serve --dev-addr=0.0.0.0:8000 -``` - -Wait until you see `INFO - Start detecting changes`, then enter `0.0.0.0:8000` in the browser's address bar. The documentation automatically reloads after you save the changes in source files. - -#### Install MkDocs and build locally +#### Preconditions 1. Install [Python]. @@ -109,37 +86,29 @@ Wait until you see `INFO - Start detecting changes`, then enter `0.0.0.0:800 pip install -r requirements.txt ``` -3. Build the site: +#### Build the site + +1. To build the site, run: ```sh mkdocs build ``` -4. Open `site/index.html` +2. Open `site/index.html` + +#### Live preview -Or, to run the built-in web server: +To view your changes as you make them, run the following command: ```sh mkdocs serve ``` -#### PDF - -To create the PDF version of the documentation, use the following command: - -* With Docker: - - ```sh - docker run --rm -v $(pwd):/docs -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml - ``` - -* Without: +Paste the in your browser and you will see the documentation. The page reloads automatically as you make changes. - ```sh - ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml - ``` +#### PDF -The PDF is in `site/_pdf`. +To build the PDF documentation, open the `site/print_page.html` in your browser. Save it as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format. ## After your pull request is merged diff --git a/README.MD b/README.MD index 99065c8..7ff082e 100644 --- a/README.MD +++ b/README.MD @@ -1,16 +1,16 @@ -# Percona Link for MongoDB documentation +# Percona ClusterSync for MongoDB documentation -Welcome to Percona Link for MongoDB documentation! +Welcome to Percona ClusterSync for MongoDB documentation! ## Overview -Percona Link for MongoDB is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It supports cloning data, replicating changes, and managing collections and indexes. +Percona ClusterSync for MongoDB is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It supports cloning data, replicating changes, and managing collections and indexes. -Percona Link for MongoDB requires replica set deployments of Percona Server for MongoDB and MongoDB. You must [convert your standalone instance](https://www.mongodb.com/docs/manual/tutorial/convert-standalone-to-replica-set/#std-label-server-replica-set-deploy-convert) to a single-node replica set to use Percona Link for MongoDB. +Percona ClusterSync for MongoDB requires replica set deployments of Percona Server for MongoDB and MongoDB. You must [convert your standalone instance](https://www.mongodb.com/docs/manual/tutorial/convert-standalone-to-replica-set/#std-label-server-replica-set-deploy-convert) to a single-node replica set to use Percona ClusterSync for MongoDB. -Percona Link for MongoDB code is [here](https://github.com/percona/percona-link-mongodb). +Percona ClusterSync for MongoDB code is [here](https://github.com/percona/percona-clustersync-mongodb). -This repository contains the source files for [Percona Link for MongoDB documentation](https://github.com/Percona-Lab/plm-docs). The documentation is written in [Markdown markup language](https://daringfireball.net/projects/markdown/) and is created using [MkDocs Documentation Generator](https://www.mkdocs.org/). +This repository contains the source files for [Percona ClusterSync for MongoDB documentation](https://github.com/percona/pcsm-docs). The documentation is written in [Markdown markup language](https://daringfireball.net/projects/markdown/) and is created using [MkDocs Documentation Generator](https://www.mkdocs.org/). ## Contributing diff --git a/_resource/overrides/main.html b/_resource/overrides/main.html index f03ed46..cdfa3e1 100644 --- a/_resource/overrides/main.html +++ b/_resource/overrides/main.html @@ -7,7 +7,7 @@ {% extends "base.html" %} {% block announce %} -

The version 0.6.0 of Percona Link for MongoDB is the technical preview. We encourage you to test Percona Link for MongoDB and give your feedback. +

The version 0.6.0 of Percona ClusterSync for MongoDB is the technical preview. We encourage you to test Percona ClusterSync for MongoDB and give your feedback. This will help us improve the product in the future. {% endblock %} @@ -27,8 +27,8 @@ {% endif %} - - + + @@ -48,7 +48,7 @@
{# Commenting out Download PDF button diff --git a/_resource/overrides/partials/banner.html b/_resource/overrides/partials/banner.html index b13a25b..2589f31 100644 --- a/_resource/overrides/partials/banner.html +++ b/_resource/overrides/partials/banner.html @@ -4,6 +4,6 @@

-Get help from Percona +Get help from Percona
diff --git a/docs/about-docs.md b/docs/about-docs.md index 8922fb1..60f2ccb 100644 --- a/docs/about-docs.md +++ b/docs/about-docs.md @@ -1,17 +1,17 @@ -# About {{plm.full_name}} documentation +# About {{pcsm.full_name}} documentation -This documentation provides comprehensive information about the features and operation guide for {{plm.full_name}} ({{plm.short}}). Reference materials on {{plm.short}} commands and configuration file options are also available here. +This documentation provides comprehensive information about the features and operation guide for {{pcsm.full_name}} ({{pcsm.short}}). Reference materials on {{pcsm.short}} commands and configuration file options are also available here. ## Versions -We recommend you to run the latest version of {{plm.short}} to receive all bug fixes and benefit from the new features. For this reason, the documentation always reflects the latest {{plm.short}} version. +We recommend you to run the latest version of {{pcsm.short}} to receive all bug fixes and benefit from the new features. For this reason, the documentation always reflects the latest {{pcsm.short}} version. To track feature changes, an additional version indication is added where a feature appeared or a change was introduced. Please also take a look at the release notes for detailed information. ## Report an issue or request a change -To report an issue with the documentation, leave your feedback using the widget at the bottom of the page or open a ticket in [{{plm.full_name}} Jira project :octicons-link-external-16:](https://perconadev.atlassian.net/jira/software/c/projects/PLM/issues). +To report an issue with the documentation, leave your feedback using the widget at the bottom of the page or open a ticket in [{{pcsm.full_name}} Jira project :octicons-link-external-16:](https://perconadev.atlassian.net/jira/software/c/projects/PLM/issues). ## How to contribute -Thank you for willing to contribute to {{plm.full_name}} project. Please check the [Contribution guidelines](reference/contributing.md) for instructions. +Thank you for willing to contribute to {{pcsm.full_name}} project. Please check the [Contribution guidelines](reference/contributing.md) for instructions. diff --git a/docs/api.md b/docs/api.md index 32e0894..fe6ba86 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,8 +1,8 @@ -# {{plm.full_name}} HTTP API documentation +# {{pcsm.full_name}} HTTP API documentation ## Quick start guide -To get started with {{plm.full_name}} API: +To get started with {{pcsm.full_name}} API: 1. Ensure the service is running on `http://localhost:2242` 2. Use the `/start` endpoint to begin replication @@ -126,7 +126,7 @@ Example: ### GET /status -The /status endpoint provides the current state of the Percona Link for MongoDB replication process, including its progress, lag, and event processing details. +The /status endpoint provides the current state of the Percona ClusterSync for MongoDB replication process, including its progress, lag, and event processing details. #### Request diff --git a/docs/compare.md b/docs/compare.md index ef56dda..996f27a 100644 --- a/docs/compare.md +++ b/docs/compare.md @@ -1,15 +1,15 @@ # Comparing Percona software for MongoDB solutions -Percona Software for MongoDB offers a variety of tools for different purposes. Below is a comparison of Percona Link for MongoDB with other Percona tools: +Percona Software for MongoDB offers a variety of tools for different purposes. Below is a comparison of Percona ClusterSync for MongoDB with other Percona tools: ## Primary purpose | Tool | Primary Purpose | Best Use Cases | | --- | --- | --- | -| Percona Link for MongoDB | Real-time replication and zero-downtime migration | - Live migration between MongoDB deployments
- Zero-downtime migration to Percona Server for MongoDB
- Active-passive deployment | +| Percona ClusterSync for MongoDB | Real-time replication and zero-downtime migration | - Live migration between MongoDB deployments
- Zero-downtime migration to Percona Server for MongoDB
- Active-passive deployment | | [Percona Backup for MongoDB (PBM)](https://docs.percona.com/percona-backup-mongodb/index.html) | Backup and restore solution with guaranteed data consistency | - Backup strategy implementation
- Point-in-time recovery
- Disaster recovery | -[Supported MongoDB deployments for PLM :material-arrow-right:](deployment.md){.md-button} \ No newline at end of file +[Supported MongoDB deployments for PCSM :material-arrow-right:](deployment.md){.md-button} \ No newline at end of file diff --git a/docs/copyright.md b/docs/copyright.md index 462d379..f892c2b 100644 --- a/docs/copyright.md +++ b/docs/copyright.md @@ -2,5 +2,5 @@ ## Documentation licensing -{{plm.full_name}} documentation is (C){{year}} Percona LLC and/or its affiliates +{{pcsm.full_name}} documentation is (C){{year}} Percona LLC and/or its affiliates and is distributed under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/) license. diff --git a/docs/deployment.md b/docs/deployment.md index aff2e6c..b845461 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,10 +1,22 @@ # Supported MongoDB deployments -* Percona Link for MongoDB supports only Replica Set to Replica Set synchronization. The source and target replica sets can have different number of nodes. +{{pcsm.full_name}} supports the following deployment topologies: + +* **Replica Set to Replica Set**: The source and target replica sets can have different numbers of nodes. +* **Sharded cluster to Sharded cluster**: The source and target sharded clusters can have different numbers of shards. This functionality is in tech preview stage. See [Sharding support in {{pcsm.full_name}}](sharding.md) for details. + +## Version requirements + * You can synchronize Percona Server for MongoDB or MongoDB Community/Enterprise Advanced/Atlas within the same major versions - 6.0 to 6.0, 7.0 to 7.0, 8.0 to 8.0 -* Percona Link for MongoDB is supported on both ARM64 and x86_64 architectures. * Minimal supported MongoDB versions are: 6.0.17, 7.0.13, 8.0.0 -* You can connect the following MongoDB deployments: + +## Supported architectures + +* {{pcsm.full_name}} is supported on both ARM64 and x86_64 architectures. + +## Supported MongoDB deployments + +You can connect the following MongoDB deployments: | Source | Target | | --- | --- | diff --git a/docs/faq.md b/docs/faq.md index 07f2e88..fbce204 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,8 +1,8 @@ # FAQ -## What are the typical use cases for {{plm.full_name}}? +## What are the typical use cases for {{pcsm.full_name}}? -{{plm.full_name}} is a data migration tool that you can use for various use cases. Among them are: +{{pcsm.full_name}} is a data migration tool that you can use for various use cases. Among them are: - Migration from MongoDB Atlas or MongoDB Enterprise to Percona Server for MongoDB. - Cluster synchronization across environments, such as staging to production. @@ -18,27 +18,27 @@ Check [Supported deployments](deployment.md) to learn more. ## Can I sync from Atlas to a self-hosted Percona Server for MongoDB? -Yes. {{plm.full_name}} is explicitly built to support Atlas to Percona Software migrations with minimal effort. +Yes. {{pcsm.full_name}} is explicitly built to support Atlas to Percona Software migrations with minimal effort. -## Does {{plm.full_name}} require a replica set on the source or target? +## Does {{pcsm.full_name}} require a replica set on the source or target? Yes. Both the source and target must be replica sets. Sharded clusters are not yet supported, but planned. -## Does {{plm.full_name}} support bidirectional sync? +## Does {{pcsm.full_name}} support bidirectional sync? -No. {{plm.full_name}} currently supports one-way synchronization only (source → target). However, you can re-run Percona {{plm.full_name}} with a reversed connection strings to do the other direction sync. +No. {{pcsm.full_name}} currently supports one-way synchronization only (source → target). However, you can re-run Percona {{pcsm.full_name}} with a reversed connection strings to do the other direction sync. ## Is there a way to monitor sync progress? -Yes. {{plm.full_name}} provides Prometheus metrics exposed at the `/metrics` endpoint and provides detailed logging for sync status, lag, and errors. See how you can [configure monitoring with PMM](pmm-setup.md). You can also use a monitoring tool of your choice. +Yes. {{pcsm.full_name}} provides Prometheus metrics exposed at the `/metrics` endpoint and provides detailed logging for sync status, lag, and errors. See how you can [configure monitoring with PMM](pmm-setup.md). You can also use a monitoring tool of your choice. ## Can I filter which databases or collections to sync? -Yes. {{plm.full_name}} allows you to include/exclude filters for specific databases or collections. You can do it both via the API and using the CLI. To learn more, see [PLM usage](install/usage.md#start-the-filtered-replication). +Yes. {{pcsm.full_name}} allows you to include/exclude filters for specific databases or collections. You can do it both via the API and using the CLI. To learn more, see [PCSM usage](install/usage.md#start-the-filtered-replication). -## How does {{plm.full_name}} handle failures? +## How does {{pcsm.full_name}} handle failures? -{{plm.full_name}} is designed with resilience in mind: +{{pcsm.full_name}} is designed with resilience in mind: - It supports automatic retries on transient errors. - It uses checkpointing to resume from the last known sync point after restart. diff --git a/docs/get-help.md b/docs/get-help.md index 28bef97..65001a0 100644 --- a/docs/get-help.md +++ b/docs/get-help.md @@ -1,6 +1,6 @@ # Get help from Percona -Our documentation guides are packed with information, but they can't cover everything you need to know about {{plm.full_name}}. They also won't cover every scenario you might come across. Don't be afraid to try things out and ask questions when you get stuck. +Our documentation guides are packed with information, but they can't cover everything you need to know about {{pcsm.full_name}}. They also won't cover every scenario you might come across. Don't be afraid to try things out and ask questions when you get stuck. ## Percona's Community Forum diff --git a/docs/index.md b/docs/index.md index 9fdb942..00d43a3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,34 +1,34 @@ -# {{plm.full_name}} documentation +# {{pcsm.full_name}} documentation !!! note "" - This is the documentation for the latest release, **{{plm.short}} {{release}}** ([Release Notes](release-notes/{{release}}.md)). + This is the documentation for the latest release, **{{pcsm.short}} {{release}}** ([Release Notes](release-notes/{{release}}.md)). ---8<-- "plm-description.md" +--8<-- "pcsm-description.md" [Get started :material-arrow-right:](installation.md){.md-button} -[How {{plm.full_name}} works :material-arrow-right:](intro.md){.md-button} +[How {{pcsm.full_name}} works :material-arrow-right:](intro.md){.md-button} ## Features * **Data clone**: Transfer existing data from a source MongoDB to a target MongoDB deployment. -* **Real-time replication**: {{plm.full_name}} uses MongoDB [change streams :octicons-link-external-16:](https://mongodb.com/docs/manual/changeStreams/) to track changes in your source cluster and replicate them to target in real time. +* **Real-time replication**: {{pcsm.full_name}} uses MongoDB [change streams :octicons-link-external-16:](https://mongodb.com/docs/manual/changeStreams/) to track changes in your source cluster and replicate them to target in real time. * **Namespace filtering**: Specify which databases and collections to include or exclude. * **Automatic index management**: Ensure necessary indexes are created on the target. * **HTTP API**: Start, finalize, pause, resume, and check replication status via HTTP endpoints. -## Why you need PLM +## Why you need PCSM -Benefit from {{plm.full_name}} in the following use cases: +Benefit from {{pcsm.full_name}} in the following use cases: * **Disaster recovery**: - {{plm.short}} enables you to maintain a secondary cluster as a backup. In case of a failure in the primary cluster, the secondary cluster can take over, ensuring minimal downtime. + {{pcsm.short}} enables you to maintain a secondary cluster as a backup. In case of a failure in the primary cluster, the secondary cluster can take over, ensuring minimal downtime. * **Data migration**: - {{plm.short}} simplifies the process of migrating data between clusters, whether you're upgrading to a new MongoDB version, moving to a different vendor, or transitioning from cloud to on-premises. + {{pcsm.short}} simplifies the process of migrating data between clusters, whether you're upgrading to a new MongoDB version, moving to a different vendor, or transitioning from cloud to on-premises. * **Global data distribution** diff --git a/docs/install/authentication.md b/docs/install/authentication.md index 0365585..91eb3dc 100644 --- a/docs/install/authentication.md +++ b/docs/install/authentication.md @@ -1,6 +1,6 @@ # Configure authentication in MongoDB -{{plm.full_name}} uses the authentication and authorization subsystem of MongoDB. This means that to authenticate {{plm.full_name}}, you need to: +{{pcsm.full_name}} uses the authentication and authorization subsystem of MongoDB. This means that to authenticate {{pcsm.full_name}}, you need to: * [Create users in source and target cluster](#create-users) * [Set a valid MongoDB connection string URI for source and target cluster](#set-mongodb-connection-string-uri) @@ -32,35 +32,35 @@ You need to create users in both source and target clusters. You will use these ## Set MongoDB connection string URI -{{plm.full_name}} authenticates in source and target clusters using the MongoDB Connection string URI. It has the following format: +{{pcsm.full_name}} authenticates in source and target clusters using the MongoDB Connection string URI. It has the following format: ``` mongodb://user:pwd@host1:port1,host2:port2,host3:port3/[authdb]?[options] ``` -To connect PLM to source and target MongoDB clusters, specify the MongoDB Connection string URI for the `PLM_SOURCE_URI` and `PLM_TARGET_URI` environment variables in its environment file. +To connect PCSM to source and target MongoDB clusters, specify the MongoDB Connection string URI for the `PCSM_SOURCE_URI` and `PCSM_TARGET_URI` environment variables in its environment file. -When you [install PLM from repositories](repos.md), the environment file is created for you. You can find it at the following path: +When you [install PCSM from repositories](repos.md), the environment file is created for you. You can find it at the following path: -* for Debian and Ubuntu: `/etc/default/plm` -* for RHEL and derivatives: `/etc/sysconfig/plm` +* for Debian and Ubuntu: `/etc/default/pcsm` +* for RHEL and derivatives: `/etc/sysconfig/pcsm` ### Example environment file ```{.text .no-copy} -PLM_SOURCE_URI="mongodb://source:mys3cretpAssword@mysource1:27017,mysource2:27017,mysource3:27017/" -PLM_TARGET_URI="mongodb://target:tops3cr3t@mytarget1:27017,mytarget2:27017,mytarget3:27017/" +PCSM_SOURCE_URI="mongodb://source:mys3cretpAssword@mysource1:27017,mysource2:27017,mysource3:27017/" +PCSM_TARGET_URI="mongodb://target:tops3cr3t@mytarget1:27017,mytarget2:27017,mytarget3:27017/" ``` ### Passwords with special characters -If the password includes special characters like `#`, `@`, `/` and so on, you must convert these characters using the [percent-encoding mechanism](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) when passing them to Percona Link for MongoDB. For example, the password `secret#pwd` should be passed as `secret%23pwd`. +If the password includes special characters like `#`, `@`, `/` and so on, you must convert these characters using the [percent-encoding mechanism](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) when passing them to Percona ClusterSync for MongoDB. For example, the password `secret#pwd` should be passed as `secret%23pwd`. ### MongoDB connection string options You can pass additional connection options to the MongoDB connection string. The string of options begins with the question mark (`?`). -{{plm.full_name}} accepts the following authentication and TLS-related options: +{{pcsm.full_name}} accepts the following authentication and TLS-related options: | Option | Description | |--------|-------------| @@ -81,4 +81,4 @@ You can pass additional connection options to the MongoDB connection string. The ## Next steps -[Start PLM :material-arrow-right: ](start-plm.md){.md-button} \ No newline at end of file +[Start PCSM :material-arrow-right: ](start-pcsm.md){.md-button} \ No newline at end of file diff --git a/docs/install/parameters.md b/docs/install/parameters.md index ffcba5e..7ec5e2e 100644 --- a/docs/install/parameters.md +++ b/docs/install/parameters.md @@ -1,6 +1,6 @@ -# Percona Link for MongoDB startup configuration +# Percona ClusterSync for MongoDB startup configuration -When [starting the `plm` process](start-plm.md), you can use the following options: +When [starting the `pcsm` process](start-pcsm.md), you can use the following options: - `--port`: The port on which the server will listen (default: 2242) - `--source`: The MongoDB connection string for the source cluster @@ -12,7 +12,7 @@ When [starting the `plm` process](start-plm.md), you can use the following optio Example: ```{.bash data-prompt="$"} -$ plm \ +$ pcsm \ --source \ --target \ --port 2242 \ @@ -26,9 +26,10 @@ Alternatively, you can define the following environment variables: | Variable | Description | Default | |----------|-------------|---------| -| `PLM_SOURCE_URI` | MongoDB connection string for the source cluster | - | -| `PLM_TARGET_URI` | MongoDB connection string for the target cluster | - | -| `PLM_PORT` | Server port number | `2242` | -| `PLM_CLONE_NUM_PARALLEL_COLLECTIONS` | Number of collections cloned in parallel | `2` | -| `PLM_CLONE_NUM_READ_WORKERS` | Number of read workers for cloning | `NumCPU / 4` | -| `PLM_CLONE_NUM_INSERT_WORKERS` | Number of insert workers for cloning | `NumCPU * 4` | +| `PCSM_SOURCE_URI` | MongoDB connection string for the source cluster | - | +| `PCSM_TARGET_URI` | MongoDB connection string for the target cluster | - | +| `PCSM_PORT` | Server port number | `2242` | +| `PCSM_CLONE_NUM_PARALLEL_COLLECTIONS` | Number of collections cloned in parallel | `2` | +| `PCSM_CLONE_NUM_READ_WORKERS` | Number of read workers for cloning | `NumCPU / 4` | +| `PCSM_CLONE_NUM_INSERT_WORKERS` | Number of insert workers for cloning | `NumCPU * 4` | +| `PCSM_MONGODB_CLI_OPERATION_TIMEOUT` | Maximum time to wait before timing out MongoDB client operations such as insert, update, delete. If the timeout is reached, the operation will fail. | `5m` | diff --git a/docs/install/repos.md b/docs/install/repos.md index 3a4582a..5cf8249 100644 --- a/docs/install/repos.md +++ b/docs/install/repos.md @@ -1,6 +1,6 @@ -# Install {{plm.full_name}} from Percona repositories +# Install {{pcsm.full_name}} from Percona repositories -To install the software from Percona repositories means to subscribe to them. Percona provides the [`percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/index.html) repository management tool. It automatically enables the required repository so that you can install and update both {{plm.full_name}} packages and required dependencies smoothly. +To install the software from Percona repositories means to subscribe to them. Percona provides the [`percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/index.html) repository management tool. It automatically enables the required repository so that you can install and update both {{pcsm.full_name}} packages and required dependencies smoothly. ## Before you start @@ -10,7 +10,7 @@ Check the following resources: * [known limitations](../limitations.md) * [supported operating systems :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-support-lifecycle#mongodb). -Data migration is a resource-intensive task. Therefore, we recommend installing PLM on the instance closest to the target to reduce the network lag as much as possible.s +Data migration is a resource-intensive task. Therefore, we recommend installing PCSM on the instance closest to the target to reduce the network lag as much as possible.s ## Procedure @@ -25,13 +25,13 @@ Data migration is a resource-intensive task. Therefore, we recommend installing 2. Enable the repository ```{.bash data-prompt="$"} - $ sudo percona-release enable plm release + $ sudo percona-release enable pcsm release ``` 3. Install the package: ```{.bash data-prompt="$"} - $ sudo apt install percona-link-mongodb + $ sudo apt install percona-clustersync-mongodb ``` === ":material-redhat: On RHEL and derivatives" @@ -43,13 +43,13 @@ Data migration is a resource-intensive task. Therefore, we recommend installing 2. Enable the repository ```{.bash data-prompt="$"} - $ sudo percona-release enable plm release + $ sudo percona-release enable pcsm release ``` 3. Install the package: ```{.bash data-prompt="$"} - $ sudo yum install percona-link-mongodb + $ sudo yum install percona-clustersync-mongodb ``` === ":fontawesome-brands-amazon: On Amazon Linux 2023" @@ -61,16 +61,16 @@ Data migration is a resource-intensive task. Therefore, we recommend installing 2. Enable the repository ```{.bash data-prompt="$"} - $ sudo percona-release enable plm release + $ sudo percona-release enable pcsm release ``` 3. Install the package: ```{.bash data-prompt="$"} - $ sudo yum install percona-link-mongodb + $ sudo yum install percona-clustersync-mongodb ``` -Congratulations! You have successfully installed {{plm.full_name}}. Now you must connect it to source and target MongoDB deployments. +Congratulations! You have successfully installed {{pcsm.full_name}}. Now you must connect it to source and target MongoDB deployments. ## Next steps diff --git a/docs/install/source.md b/docs/install/source.md index 68abb91..17ffe57 100644 --- a/docs/install/source.md +++ b/docs/install/source.md @@ -6,7 +6,7 @@ Check the [system requirements](../system-requirements.md) and [known limitatio ## Prerequisites -To build {{plm.full_name}} from source, you need the following: +To build {{pcsm.full_name}} from source, you need the following: - Go 1.24 or later. [Install and set up Go tools :octicons-link-external-16:](https://golang.org/doc/install)x - make @@ -14,14 +14,14 @@ To build {{plm.full_name}} from source, you need the following: ## Build steps -Here's how to build {{plm.full_name}}: +Here's how to build {{pcsm.full_name}}: {.power-number} -1. Clone the repository and change directory to `plm`: +1. Clone the repository and change directory to `pcsm`: ```{.bash data-prompt="$"} - git clone https://github.com/percona/percona-link-mongodb.git - $ cd plm + git clone https://github.com/percona/percona-clustersync-mongodb.git + $ cd pcsm ``` 2. Build the project using the Makefile: @@ -30,15 +30,15 @@ Here's how to build {{plm.full_name}}: $ make build ``` - Alternatively, you can install {{plm.short}} from the cloned repo using `go install`: + Alternatively, you can install {{pcsm.short}} from the cloned repo using `go install`: ```{.bash data-prompt="$"} $ go install . ``` - This installs `plm` into your `GOBIN` directory. + This installs `pcsm` into your `GOBIN` directory. -3. Add `GOBIN` to your `PATH`. This makes `plm` a global command in your terminal. +3. Add `GOBIN` to your `PATH`. This makes `pcsm` a global command in your terminal. ## Next steps diff --git a/docs/install/start-pcsm.md b/docs/install/start-pcsm.md new file mode 100644 index 0000000..a0f0697 --- /dev/null +++ b/docs/install/start-pcsm.md @@ -0,0 +1,60 @@ +# Start Percona ClusterSync for MongoDB + +Start {{pcsm.full_name}}. + +=== ":material-console: Using `systemd`" + + We recommend to use the packaged service scripts to run `pcsm`. + + ```{.bash data-prompt="$"} + $ sudo systemctl start pcsm + ``` + + Check the status with this command: + + ```{.bash data-prompt="$"} + $ sudo systemctl status pcsm + ``` + +=== ":fontawesome-solid-user-gear: Manually" + + You can start PCSM manually. This option is the way you start {{pcsm.full_name}} if you installed it [from source code](source.md) + + Run Percona ClusterSync for MongoDB with the following command **if you haven't defined MongoDB connection string URI before**: + + ```{.bash data-prompt="$"} + $ nohup pcsm --source --target --no-color > percona-clustersync-mongodb.log 2>&1 & + ``` + + Alternatively, you can use environment variables: + + ```{.bash data-prompt="$"} + $ export SOURCE_URI= + $ export TARGET_URI= + $ nohup pcsm --no-color > percona-clustersync-mongodb.log 2>&1 & + ``` + +See [Percona ClusterSync for MongoDB startup configuration](parameters.md) for all available options. + + +## How to see {{pcsm.full_name}} logs + +With the packaged `systemd` service, the log output to `stdout` is captured by +systemd's default redirection to `systemd-journald`. You can view it with this +command: + +```{.bash data-prompt="$"} +$ sudo journalctl -u pcsm.service +``` + +See `man journalctl` for useful options such as `--lines`, `--follow`, etc. + + +If you started `pcsm` manually, see the file you redirected `stdout` and `stderr` to. + + +## Next steps + +Congratulations! you have successfully installed and connected PCSM to your source and target MongoDB. Now you have it up and running and you are ready to use it. + +[Use {{pcsm.full_name}} :material-arrow-right:](usage.md){.md-button} \ No newline at end of file diff --git a/docs/install/start-plm.md b/docs/install/start-plm.md deleted file mode 100644 index e510eb1..0000000 --- a/docs/install/start-plm.md +++ /dev/null @@ -1,60 +0,0 @@ -# Start Percona Link for MongoDB - -Start {{plm.full_name}}. - -=== ":material-console: Using `systemd`" - - We recommend to use the packaged service scripts to run `plm`. - - ```{.bash data-prompt="$"} - $ sudo systemctl start plm - ``` - - Check the status with this command: - - ```{.bash data-prompt="$"} - $ sudo systemctl status plm - ``` - -=== ":fontawesome-solid-user-gear: Manually" - - You can start PLM manually. This option is the way you start {{plm.full_name}} if you installed it [from source code](source.md) - - Run Percona Link for MongoDB with the following command **if you haven't defined MongoDB connection string URI before**: - - ```{.bash data-prompt="$"} - $ nohup plm --source --target --no-color > percona-link-mongodb.log 2>&1 & - ``` - - Alternatively, you can use environment variables: - - ```{.bash data-prompt="$"} - $ export SOURCE_URI= - $ export TARGET_URI= - $ nohup plm --no-color > percona-link-mongodb.log 2>&1 & - ``` - -See [Percona Link for MongoDB startup configuration](parameters.md) for all available options. - - -## How to see {{plm.full_name}} logs - -With the packaged `systemd` service, the log output to `stdout` is captured by -systemd’s default redirection to `systemd-journald`. You can view it with this -command: - -```{.bash data-prompt="$"} -$ sudo journalctl -u plm.service -``` - -See `man journalctl` for useful options such as `--lines`, `--follow`, etc. - - -If you started `plm` manually, see the file you redirected `stdout` and `stderr` to. - - -## Next steps - -Congratulations! you have successfully installed and connected PLM to your source and target MongoDB. Now you have it up and running and you are ready to use it. - -[Use {{plm.full_name}} :material-arrow-right:](usage.md){.md-button} \ No newline at end of file diff --git a/docs/install/usage.md b/docs/install/usage.md index 4077834..1a9fc1c 100644 --- a/docs/install/usage.md +++ b/docs/install/usage.md @@ -1,23 +1,23 @@ -# Use {{plm.full_name}} +# Use {{pcsm.full_name}} -{{plm.full_name}} doesn't automatically start data replication after the startup. It has the `idle` status indicating that it is ready to accept requests. +{{pcsm.full_name}} 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 {{plm.full_name}} using the command-line interface or via the HTTP API. Read more about [PLM API](../api.md). +You can interact with {{pcsm.full_name}} using the command-line interface or via the HTTP API. Read more about [PCSM API](../api.md). ## 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. +Your target MongoDB cluster may be empty or contain data. PCSM 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, PCSM overwrites it. However, if the target contains different data, PCSM 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. +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 the [change streams :octicons-link-external-16:](https://www.mongodb.com/docs/manual/changeStreams/) to track the changes to your data on the source and replicate them to the target. === "Command line" ```{.bash data-prompt="$"} - $ plm start + $ pcsm start ``` ??? example "Expected output" @@ -46,7 +46,7 @@ To include or exclude a specific database and all collections it includes, pass === "Command line" ```{.bash data-prompt="$"} - $ plm start \ + $ pcsm start \ --include-namespaces="db1.collection1,db2.collection2" \ --exclude-namespaces="db3.collection3" ``` @@ -72,12 +72,12 @@ To include or exclude a specific database and all collections it includes, pass ## 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](#resume-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](#resume-the-replication). === "Command line" ```{.bash data-prompt="$"} - $ plm pause + $ pcsm pause ``` === "HTTP API" @@ -90,12 +90,12 @@ You can pause the replication at any moment. PLM stops the replication, saves th ## 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. +Resume the replication. PCSM 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. === "Command line" ```{.bash data-prompt="$"} - $ plm resume + $ pcsm resume ``` === "HTTP API" @@ -111,7 +111,7 @@ The replication may fail for some reason, like lost connectivity or the like. In === "Command line" ```{.bash data-prompt="$"} - $ plm resume --from-failure + $ pcsm resume --from-failure ``` === "HTTP API" @@ -132,7 +132,7 @@ Check the current status of the replication process. === "Command line" ```{.bash data-prompt="$"} - $ plm status + $ pcsm status ``` === "HTTP API" @@ -145,12 +145,12 @@ Check the current status of the replication process. # 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. +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 replicaton after you finalized it. If you run the `start` command, PCSM will start the replication anew, with the initial sync. === "Command line" ```{.bash data-prompt="$"} - $ plm finalize + $ pcsm finalize ``` === "HTTP API" diff --git a/docs/installation.md b/docs/installation.md index 8240988..a71325a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,14 +1,14 @@ # Quickstart guide ---8<-- "plm-description.md" +--8<-- "pcsm-description.md" ## Tutorials -We recommend installing PLM via the package manager of your operating system for a convenient and quick way to try the software first. For other installation options, navigate to the corresponding tutorial. +We recommend installing PCSM via the package manager of your operating system for a convenient and quick way to try the software first. For other installation options, navigate to the corresponding tutorial. === ":octicons-terminal-16: Package manager" - Use the package manager of your operating system to install {{plm.full_name}}: + Use the package manager of your operating system to install {{pcsm.full_name}}: * `apt` - for Debian and Ubuntu Linux * `yum` - for Red Hat Enterprise Linux and compatible Linux derivatives @@ -18,7 +18,7 @@ We recommend installing PLM via the package manager of your operating system for === ":octicons-file-code-16: Build from source" - Have a full control over the installation by building {{plm.short}} from source code. + Have a full control over the installation by building {{pcsm.short}} from source code. Check the guide below for step-by-step instructions. @@ -26,6 +26,6 @@ We recommend installing PLM via the package manager of your operating system for ## Next steps -[Use {{plm.full_name}} :material-arrow-right:](install/usage.md){.md-button} +[Use {{pcsm.full_name}} :material-arrow-right:](install/usage.md){.md-button} diff --git a/docs/intro.md b/docs/intro.md index 8facf5d..b4ff6ce 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,35 +1,35 @@ -# How {{plm.full_name}} works +# How {{pcsm.full_name}} works -{{plm.full_name}} (PLM) is a binary process that replicates data between MongoDB deployments in real time until you manually finalize it. You can also make a one-time data migration from the source to the target with zero downtime. +{{pcsm.full_name}} (PCSM) is a binary process that replicates data between MongoDB deployments in real time until you manually finalize it. You can also make a one-time data migration from the source to the target with zero downtime. -You operate with {{plm.full_name}} using the [set of commands](plm-commands.md) or [API calls](api.md). Depending on the request it receives, {{plm.full_name}} has several states as shown in the following diagram: +You operate with {{pcsm.full_name}} using the [set of commands](pcsm-commands.md) or [API calls](api.md). Depending on the request it receives, {{pcsm.full_name}} has several states as shown in the following diagram: -![PLM states](_images/state-transition-flow.jpg) +![PCSM states](_images/state-transition-flow.jpg) -* **Idle**: PLM is up and running but not migrating data -* **Running**: PLM is replicating data from the source to the target. PLM enters the running state when you start and resume the replication -* **Paused**: PLM is not running and data is not replicated -* **Finalizing**: PLM stops the replication and is doing final checks, creates indexes +* **Idle**: PCSM is up and running but not migrating data +* **Running**: PCSM is replicating data from the source to the target. PCSM enters the running state when you start and resume the replication +* **Paused**: PCSM is not running and data is not replicated +* **Finalizing**: PCSM stops the replication and is doing final checks, creates indexes * **Finalized**: all checks are complete, data replication is stopped -* **Failed**: PLM encountered an error +* **Failed**: PCSM encountered an error ## Usage scenario -Now, let's use the data migration from MongoDB Atlas to Percona Server for MongoDB as an example to understand how PLM works. +Now, let's use the data migration from MongoDB Atlas to Percona Server for MongoDB as an example to understand how PCSM works. You run a MongoDB Atlas 8.0.8 deployed as a replica set. You need to migrate to Percona Server for MongoDB 8.0.8-3, also a replica set. You have a strict requirement to migrate with zero downtime; therefore, using logical backups with [Percona Backup for MongoDB :octicons-link-external-16:](https://docs.percona.com/percona-backup-mongodb/features/logical.html) is a no-go. -A solution is to use Percona Link for MongoDB. MongoDB Atlas is your source. An empty Percona Server for MongoDB replica set is your target. Data migration is a resource-intensive task. Therefore, we recommend installing PLM closest to the target to reduce the network lag as much as possible. +A solution is to use Percona ClusterSync for MongoDB. MongoDB Atlas is your source. An empty Percona Server for MongoDB replica set is your target. Data migration is a resource-intensive task. Therefore, we recommend installing PCSM closest to the target to reduce the network lag as much as possible. -Create users for PLM in both MongoDB deployments. Start and connect PLM to your source and target using these user credentials. Now you are ready to start the migration. +Create users for PCSM in both MongoDB deployments. Start and connect PCSM to your source and target using these user credentials. Now you are ready to start the migration. -To start the migration, call the `start` command. 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. +To start the migration, call the `start` command. 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. -After the initial data sync, PLM monitors changes in the source and replicates them to the target at runtime. You don't have to stop your source deployment, it operates as usual, accepting client requests. PLM uses [change streams :octicons-link-external-16:](https://www.mongodb.com/docs/manual/changeStreams/) to track the changes to your data and replicate them to the target. +After the initial data sync, PCSM monitors changes in the source and replicates them to the target at runtime. You don't have to stop your source deployment, it operates as usual, accepting client requests. PCSM uses [change streams :octicons-link-external-16:](https://www.mongodb.com/docs/manual/changeStreams/) to track the changes to your data and replicate them to the target. -You can `pause` the replication and `resume` it later. When paused, PLM saves the timestamp when it stops the replication. After you resume PLM, it copies the changes from the saved timestamp and continues real-time replication. +You can `pause` the replication and `resume` it later. When paused, PCSM saves the timestamp when it stops the replication. After you resume PCSM, it copies the changes from the saved timestamp and continues real-time replication. -You can track the migration status in logs and using the `status` command. When the data migration is complete, call the `finalize` command. This makes PLM finalize the replication, create the required indexes on the target, and stop. Note that finalizing is a one-time operation. If you try to start PLM again, it will start data copy anew. +You can track the migration status in logs and using the `status` command. When the data migration is complete, call the `finalize` command. This makes PCSM finalize the replication, create the required indexes on the target, and stop. Note that finalizing is a one-time operation. If you try to start PCSM again, it will start data copy anew. Afterwards, you will only need to switch your clients to connect to Percona Server for MongoDB. @@ -44,6 +44,6 @@ Specify what namespaces - databases and collections - to include and/or exclude ## Next steps -Ready to try out PLM? +Ready to try out PCSM? [Quickstart](installation.md){.md-button} diff --git a/docs/limitations.md b/docs/limitations.md index 1c96aa6..b52bb0b 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -4,13 +4,13 @@ author: Radoslaw Szulgo --- # Known issues and limitations -This page lists known limitations for using Percona Link for MongoDB +This page lists known limitations for using Percona ClusterSync for MongoDB ## Versions and topology * Sharded clusters are not supported * MongoDB versions that reached End-of-Life are not supported -* PLM connects only to the primary node in the replica set. You cannot force connection to secondary members using the [directConnection :octicons-link-external-16:](https://www.mongodb.com/docs/manual/reference/connection-string/#connection-string-formats) option. This option is ignored. +* PCSM connects only to the primary node in the replica set. You cannot force connection to secondary members using the [directConnection :octicons-link-external-16:](https://www.mongodb.com/docs/manual/reference/connection-string/#connection-string-formats) option. This option is ignored. ## Data types diff --git a/docs/logging.md b/docs/logging.md index f358005..39f3095 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -1,10 +1,10 @@ -# Logging in Percona Link for MongoDB +# Logging in Percona ClusterSync for MongoDB -Percona Link for MongoDB (PLM) provides a flexible logging system to help you monitor its operations, diagnose issues, and integrate with log management systems. You can control the log verbosity, format, and appearance using command-line flags. +Percona ClusterSync for MongoDB (PCSM) provides a flexible logging system to help you monitor its operations, diagnose issues, and integrate with log management systems. You can control the log verbosity, format, and appearance using command-line flags. ## Configuration -You configure logging when the `plm` process starts. The following flags are available: +You configure logging when the `pcsm` process starts. The following flags are available: | Flag | Description | Default | |---------------|---------------------------------------------------|---------| @@ -25,15 +25,15 @@ The `--log-level` flag controls the minimum level of messages that will be recor **Example:** -To see detailed debugging messages, start `plm` with: +To see detailed debugging messages, start `pcsm` with: ```bash -plm --source --target --log-level=debug +pcsm --source --target --log-level=debug ``` ### Log format -PLM can output logs in two formats: human-readable text (default) and structured JSON. +PCSM can output logs in two formats: human-readable text (default) and structured JSON. #### Text format (default) @@ -49,7 +49,7 @@ By default, logs are printed to the console in a color-coded, human-readable for You can disable the colorization with the `--no-color` flag. This is useful when redirecting log output to a file. ```sh -plm --source --target --no-color > plm.log +pcsm --source --target --no-color > pcsm.log ``` #### JSON format diff --git a/docs/oplog-sizing.md b/docs/oplog-sizing.md index 12dfeea..8914e5c 100644 --- a/docs/oplog-sizing.md +++ b/docs/oplog-sizing.md @@ -1,10 +1,10 @@ -# Oplog sizing for Percona Link for MongoDB +# Oplog sizing for Percona ClusterSync for MongoDB -Percona Link for MongoDB synchronizes data between MongoDB replica sets using change streams. For the sync to complete successfully, the required operations must remain in the source's oplog until they are applied. If operations expire from the oplog before being processed, the sync will fail. +Percona ClusterSync for MongoDB synchronizes data between MongoDB replica sets using change streams. For the sync to complete successfully, the required operations must remain in the source's oplog until they are applied. If operations expire from the oplog before being processed, the sync will fail. ## Source cluster oplog requirements -After the initial data copy, PLM applies ongoing changes using the oplog from the source cluster. If the oplog window is too short, PLM may fall behind and lose access to required changes. To avoid this, increase the oplog retention window using the `replSetResizeOplog` command. +After the initial data copy, PCSM applies ongoing changes using the oplog from the source cluster. If the oplog window is too short, PCSM may fall behind and lose access to required changes. To avoid this, increase the oplog retention window using the `replSetResizeOplog` command. This is especially important when: @@ -21,7 +21,7 @@ The destination cluster must have enough space to store both the full dataset an ## Track the data sync progress -During the initial data clone, PLM clones data and then applies oplog entries on top. You track the sync progress and fine-tune PLM. Here's how: +During the initial data clone, PCSM clones data and then applies oplog entries on top. You track the sync progress and fine-tune PCSM. Here's how: ### Extend the oplog window if the lag approaches its limit @@ -33,12 +33,12 @@ During the initial data clone, PLM clones data and then applies oplog entries on The value you get is the minimum oplog window, in seconds. -2. Compare this value to the current sync lag using the `PLM status` command and the `lagTime` field. If the `lagTime` approaches the oplog window, extend the window using the `replSetResizeOplog` with a higher `minRetentionHours` value. +2. Compare this value to the current sync lag using the `PCSM status` command and the `lagTime` field. If the `lagTime` approaches the oplog window, extend the window using the `replSetResizeOplog` with a higher `minRetentionHours` value. ### Improve the sync performance to reduce lag If the oplog is large enough but the lag is still high, optimize performance by: -- Running PLM closer to the destination to reduce network latency -- Increasing CPU and memory on PLM host +- Running PCSM closer to the destination to reduce network latency +- Increasing CPU and memory on PCSM host - Using faster hardware on the destination to improve write performance \ No newline at end of file diff --git a/docs/plm-commands.md b/docs/pcsm-commands.md similarity index 68% rename from docs/plm-commands.md rename to docs/pcsm-commands.md index c584ea0..b28416f 100644 --- a/docs/plm-commands.md +++ b/docs/pcsm-commands.md @@ -1,17 +1,17 @@ -# {{plm.full_name}} commands +# {{pcsm.full_name}} commands ## Overview -Percona Link for MongoDB is a replication tool for MongoDB clusters. It provides commands to manage and monitor the replication process between source and target MongoDB clusters. +Percona ClusterSync for MongoDB is a replication tool for MongoDB clusters. It provides commands to manage and monitor the replication process between source and target MongoDB clusters. ## Commands ### version -Display the current version of Percona Link for MongoDB. +Display the current version of Percona ClusterSync for MongoDB. ```{.bash data-prompt="$"$} -$ plm version +$ pcsm version ``` ### status @@ -19,7 +19,7 @@ $ plm version Get the status of the replication process. ```{.bash data-prompt="$"$} -$ plm status +$ pcsm status ``` ### start @@ -27,13 +27,13 @@ $ plm status Starts cluster replication. ```{.bash data-prompt="$"$} -$ plm start +$ pcsm start ``` To start a filtered replication, pass the namespaces (databases and collections) that you want to include/exclude from replication. ```{.bash data-prompt="$"} -$ plm start \ +$ pcsm start \ --include-namespaces="db1.collection1,db2.collection2" \ --exclude-namespaces="db3.collection3" ``` @@ -51,10 +51,10 @@ Available flags: ### reset -Resets the `PLM` state and deletes the metadata collections from target deployment. After the command execution, you must restart the `PLM` service and start the data replication from scratch. Read more about the flow in [Troubleshooting guide](troubleshooting.md) +Resets the `PCSM` state and deletes the metadata collections from target deployment. After the command execution, you must restart the `PCSM` service and start the data replication from scratch. Read more about the flow in [Troubleshooting guide](troubleshooting.md) ```{.bash data-prompt="$"$} -$ plm reset --target +$ pcsm reset --target ``` ### finalize @@ -62,7 +62,7 @@ $ plm reset --target Finalize cluster replication. ```{.bash data-prompt="$"$} -$ plm finalize +$ pcsm finalize ``` ### pause @@ -70,7 +70,7 @@ $ plm finalize Pause cluster replication. ```{.bash data-prompt="$"$} -$ plm pause +$ pcsm pause ``` ### resume @@ -78,7 +78,7 @@ $ plm pause Resume cluster replication. ```{.bash data-prompt="$"$} -$ plm resume +$ pcsm resume ``` Available flags: diff --git a/docs/pmm-setup.md b/docs/pmm-setup.md index 6532d5f..b668eb0 100644 --- a/docs/pmm-setup.md +++ b/docs/pmm-setup.md @@ -1,12 +1,12 @@ # Set up observability with Percona Monitoring and Management -{{plm.full_name}} exports Prometheus metrics enabling you to monitor the replication performance including the number of processed events, data transfer sizes, document counts, and batch processing times. These metrics are available at the `/metrics` endpoint. +{{pcsm.full_name}} exports Prometheus metrics enabling you to monitor the replication performance including the number of processed events, data transfer sizes, document counts, and batch processing times. These metrics are available at the `/metrics` endpoint. [Available metrics](#available-metrics){.md-button} You can use any monitoring tool of your choice to collect and analyze these metrics. We recommend and provide instructions for setting up observability with [Percona Monitoring and Management (PMM)](https://docs.percona.com/percona-monitoring-and-management/3/index.html). -{{plm.full_name}} is natively integrated with PMM for automated monitoring of replication performance with data visualization on dashboards. This comprehensive monitoring helps you optimize replication performance and quickly identify any potential issues during the replication process. +{{pcsm.full_name}} is natively integrated with PMM for automated monitoring of replication performance with data visualization on dashboards. This comprehensive monitoring helps you optimize replication performance and quickly identify any potential issues during the replication process. PMM is the server-client solution. The PMM Client collects the metrics and sends them to the PMM Server. PMM Server displays these metrics on dashboards in a user-friendly way. @@ -15,11 +15,11 @@ PMM Server and PMM Client are installed separately. ## Prerequisites 1. You must have PMM server up and running. You can run PMM Server as a Docker image, install it a virtual appliance, or on an AWS instance. Follow the [Quickstart quide :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/3/quickstart/quickstart.html) to start PMM Server in a Docker container. For other installation options, see [PMM Documentation :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/3/install-pmm/install-pmm-server/index.html) -2. Ensure PMM server and PLM can communicate with each other over the network. +2. Ensure PMM server and PCSM can communicate with each other over the network. ## Install PMM Client -1. You must install PMM Client on the same instance where {{plm.full_name}} is running. Refer to the [installation instructions :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/3/install-pmm/install-pmm-client/index.html) suitable for your deployment +1. You must install PMM Client on the same instance where {{pcsm.full_name}} is running. Refer to the [installation instructions :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/3/install-pmm/install-pmm-client/index.html) suitable for your deployment 2. Register the client node in PMM Server. Replace the `admin:admin` with your PMM Server credentials and the `X.X.X.X` with the PMM Server IP address in the following command: ```{.bash data-prompt="$"} @@ -38,12 +38,12 @@ PMM Server and PMM Client are installed separately. pmm-agent is running. ``` -## Configure monitoring for PLM +## Configure monitoring for PCSM -To enable metrics collection, add PLM as an external service to PMM server, Run the following command: +To enable metrics collection, add PCSM as an external service to PMM server, Run the following command: ```{.bash data-prompt="$"} -$ pmm-admin add external --service-name=plm_test --listen-port=2242 --metrics-path=metrics --scheme=http +$ pmm-admin add external --service-name=pcsm_test --listen-port=2242 --metrics-path=metrics --scheme=http ``` ??? example "Expected output" @@ -51,22 +51,22 @@ $ pmm-admin add external --service-name=plm_test --listen-port=2242 --metrics-pa ```{.text .no-copy} External Service added. Service ID : 0b3460d9-4173-4ff8-adcd-105883a4ef56 - Service name: plm_test + Service name: pcsm_test Group : external ``` -Now PMM Client collects the metrics for PLM. +Now PMM Client collects the metrics for PCSM. ## Create a dashboard -To view PLM metrics, configure a dashboard in PMM Server. Here's how: +To view PCSM metrics, configure a dashboard in PMM Server. Here's how: 1. Log in to PMM Server 2. From the main menu, select **Dashboards** and click **New** 3. Select **Import a dashboard** 4. Copy the following metrics file in the **Import via dashboard JSON model** window and click **Load** - ??? admonition "PLM Metrics file" + ??? admonition "PCSM Metrics file" ```json { @@ -590,7 +590,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: "options": { "mode": "exclude", "names": [ - "plm" + "pcsm" ], "prefix": "All except:", "readOnly": true @@ -636,7 +636,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: }, "editorMode": "code", "exemplar": false, - "expr": "rate(round(go_goroutines{node_name=\"plm\"}[1m]))", + "expr": "rate(round(go_goroutines{node_name=\"pcsm\"}[1m]))", "instant": false, "legendFormat": "{{node_name}}", "range": true, @@ -712,7 +712,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: "options": { "mode": "exclude", "names": [ - "plm" + "pcsm" ], "prefix": "All except:", "readOnly": true @@ -758,7 +758,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: }, "editorMode": "code", "exemplar": false, - "expr": "rate(round(go_threads{node_name=\"plm\"}[1m]))", + "expr": "rate(round(go_threads{node_name=\"pcsm\"}[1m]))", "instant": false, "legendFormat": "{{node_name}}", "range": true, @@ -835,7 +835,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: "options": { "mode": "exclude", "names": [ - "plm" + "pcsm" ], "prefix": "All except:", "readOnly": true @@ -881,7 +881,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: }, "editorMode": "code", "exemplar": false, - "expr": "go_memstats_alloc_bytes{node_name=\"plm\"} / 1024 / 1024", + "expr": "go_memstats_alloc_bytes{node_name=\"pcsm\"} / 1024 / 1024", "instant": false, "legendFormat": "{{node_name}}", "range": true, @@ -904,7 +904,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: }, "timepicker": {}, "timezone": "browser", - "title": "Percona Link for MongoDB", + "title": "Percona ClusterSync for MongoDB", "uid": "aegcuit193shse", "version": 8, "weekStart": "" @@ -915,7 +915,7 @@ To view PLM metrics, configure a dashboard in PMM Server. Here's how: ## Available metrics -You can collect and view the following PLM metrics at the `/metrics` endpoint: +You can collect and view the following PCSM metrics at the `/metrics` endpoint: | Metric name | Description | |-------------|-------------| diff --git a/docs/reference/contributing.md b/docs/reference/contributing.md deleted file mode 100644 index 0e08548..0000000 --- a/docs/reference/contributing.md +++ /dev/null @@ -1,65 +0,0 @@ -# Contribution guidelines - -We're glad that you would like to become a Percona community member and participate in keeping open source open. - -There are many ways how you can contribute: - -* [Submit bug reports or feature requests](#submit-bug-reports-or-feature-requests) -* [Submit a code patch](#submit-a-code-patch) -* [Contribute to documentation](#contribute-to-documentation) - -# Submit bug reports or feature requests - -If you find a bug in {{plm.full_name}}, you can submit a report to the [JIRA issue tracker](https://jira.percona.com/projects/PLM) for {{plm.full_name}}. - -Start by searching the open tickets for a similar report. If you find that -someone else has already reported your problem, then you can upvote that report -to increase its visibility. - -If there is no existing report, submit a report following these steps: - - -1. Sign in to [JIRA issue tracker](https://jira.percona.com/projects/PLM). You will need to create an account if you do not have one. - -2. In the *Summary*, *Description*, *Steps To Reproduce*, *Affects Version* fields -describe the problem you have detected. - -As a general rule of thumb, try to create bug reports that are: - - -* *Reproducible*: Describe the steps to reproduce the problem. - - -* *Specific*: Include the version of Percona Backup for MongoDB, your environment, and so on. - - -* *Unique*: Check if there already exists a JIRA ticket to describe -the problem. - - -* *Scoped to a Single Bug*: Report only one bug in one JIRA ticket. - -## Submit a code patch - -If you'd like to submit a code patch, follow the [Contributing guide in {{plm.short}} code repository](https://github.com/percona/percona-link-mongodb/blob/main/README.md#contributing). - -## Contribute to documentation - -### Edit documentation online via GitHub - -1. Click the **Edit this page** icon next to the page title. The source `.md` file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. - -2. Edit the page. You can check your changes on the **Preview** tab. - -3. Commit your changes. - - - In the *Commit changes* section, describe your changes. - - Select the **Create a new branch for this commit and start a pull request** option - - Click **Propose changes**. - -4. GitHub creates a branch and a commit for your changes. It loads a new page on which you can open a pull request to Percona. The page shows the base branch - the one you offer your changes for, your commit message and a diff - a visual representation of your changes against the original page. This allows you to make a last-minute review. When you are ready, click the **Create pull request** button. -5. Someone from our team reviews the pull request and if everything is correct, merges it into the documentation. Then it gets published on the site. - -### Edit documentation locally - -If you wish to have full control over the documentation process, follow the [Contributing to documentation guide](https://github.com/Percona-Lab/plm-docs/blob/main/CONTRIBUTING.md). diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 7aaab5c..e4c63c7 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -26,7 +26,7 @@ The process of applying changes that occurred during the cloning period to ensur ## Cluster replication -The process of copying user data, collections, views, and indexes from a primary (source) cluster to a secondary (target) cluster. Initiated by POST /start command, it transitions PLM status to running, and completes when the PLM status becomes finalized. +The process of copying user data, collections, views, and indexes from a primary (source) cluster to a secondary (target) cluster. Initiated by POST /start command, it transitions PCSM status to running, and completes when the PCSM status becomes finalized. ## Collection @@ -56,7 +56,7 @@ A critical process that converts temporary changes into their original form from ## Initial sync -Initial sync is the process of copying all data from a source to a target system. In MongoDB, this occurs when a new node joins a replica set, where it copies all databases, collections, and indexes from an existing member. In the context of Percona Link for MongoDB (PLM), initial sync is the first phase of data migration where all existing data is copied from the source cluster to the target cluster. Then PLM applies the changes that occurred to data since the initial sync start. +Initial sync is the process of copying all data from a source to a target system. In MongoDB, this occurs when a new node joins a replica set, where it copies all databases, collections, and indexes from an existing member. In the context of Percona ClusterSync for MongoDB (PCSM), initial sync is the first phase of data migration where all existing data is copied from the source cluster to the target cluster. Then PCSM applies the changes that occurred to data since the initial sync start. ## Isolation diff --git a/docs/release-notes.md b/docs/release-notes.md index d3a1733..fc207eb 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,5 +1,10 @@ -# {{plm.full_name}} release notes +# {{pcsm.full_name}} release notes + +!!! note "" + + Starting with version 0.7.0, Percona Link for MongoDB has been rebranded as Percona ClusterSync. Any mentions of Percona Link for MongoDB in earlier release notes now refer to this product. + -* [{{plm.full_name}} 0.6.0 ({{date.v0_6_0}})](release-notes/0.6.0.md) +* [Percona Link for MongoDB 0.6.0 ({{date.v0_6_0}})](release-notes/0.6.0.md) -* [{{plm.full_name}} 0.5.0 ({{date.v0_5_0}})](release-notes/0.5.0.md) \ No newline at end of file +* [Percona Link for MongoDB 0.5.0 ({{date.v0_5_0}})](release-notes/0.5.0.md) diff --git a/docs/release-notes/0.5.0.md b/docs/release-notes/0.5.0.md index e9fce6f..263c84f 100644 --- a/docs/release-notes/0.5.0.md +++ b/docs/release-notes/0.5.0.md @@ -1,6 +1,6 @@ -# {{ plm.full_name }} 0.5.0 ({{ date.v0_5_0 }}) +# Percona Link for MongoDB 0.5.0 ({{ date.v0_5_0 }}) -We are pleased to announce the Minimum Viable Product (MVP) release of {{ plm.full_name }} (PLM). This new powerful and open-source tool addresses one of the challenging tasks DBAs have: migration of mission-critical MongoDB deployments with minimized downtime and ensured data consistency. {{ plm.full_name }} aims to simplify this process, being a solution for zero-downtime data migration and real-time replication between MongoDB deployments that are either Percona Server for MongoDB instances, MongoDB Community/Advanced versions, or even cloud-based Atlas clusters. +We are pleased to announce the Minimum Viable Product (MVP) release of Percona Link for MongoDB (PLM). This new powerful and open-source tool addresses one of the challenging tasks DBAs have: migration of mission-critical MongoDB deployments with minimized downtime and ensured data consistency. Percona Link for MongoDB aims to simplify this process, being a solution for zero-downtime data migration and real-time replication between MongoDB deployments that are either Percona Server for MongoDB instances, MongoDB Community/Advanced versions, or even cloud-based Atlas clusters. This release focuses on core capabilities providing a solid foundation for your migration needs. We're counting on your expertise and feedback to help us shape its future. @@ -9,8 +9,8 @@ This release focuses on core capabilities providing a solid foundation for your This release features the following core capabilities: * **Data clone**: Full data copy with parallel processing and batch operations -* **Real-time replication**: {{ plm.short }} uses [change streams :octicons-link-external-16:](https://www.mongodb.com/docs/manual/changeStreams/) to capture and replicate data changes in real-time, keeping your target synchronized with the source -* **Guaranteed event ordering and consistency**: {{ plm.short }} applies changes to the target in the same order they occurred on the source, maintaining data integrity. +* **Real-time replication**: PLM uses [change streams :octicons-link-external-16:](https://www.mongodb.com/docs/manual/changeStreams/) to capture and replicate data changes in real-time, keeping your target synchronized with the source +* **Guaranteed event ordering and consistency**: PLM applies changes to the target in the same order they occurred on the source, maintaining data integrity. * **Data and index integrity**: Support for all index types, including TTL. * **Transaction support**: Basic handling for multi-document transactions. * **Standardized secure connections** via standard MongoDB connection strings with SASL authentication for secure communication. @@ -18,11 +18,11 @@ This release features the following core capabilities: * **Simple management**: Basic CLI commands for start, pause, resume, finalize, and status monitoring * **HTTP API**: Start, finalize, pause, resume, and check replication status via HTTP endpoints. * **Detailed logging**: Comprehensive logging enables you to monitor the migration process and assists in troubleshooting. -* **Observability**: {{ plm.short }} provides basic Prometheus metrics available for collection via PMM or any other monitoring tool of your choice. +* **Observability**: PLM provides basic Prometheus metrics available for collection via PMM or any other monitoring tool of your choice. ## Supported versions and deployments -{{ plm.full_name }} is available for replica set to replica set synchronization within the same major MongoDB versions (6.0 to 6.0, 7.0 to 7.0, 8.0 to 8.0). +Percona Link for MongoDB is available for replica set to replica set synchronization within the same major MongoDB versions (6.0 to 6.0, 7.0 to 7.0, 8.0 to 8.0). Minimum patch versions: 6.0.17, 7.0.13, 8.0.0 respectively. @@ -30,11 +30,11 @@ Check other [limitations](../limitations.md) ## Get started -Check out our [installation guide](../install/source.md) and follow the step-by-step instructions to get started with {{ plm.short }}. The tool is designed to be straightforward to set up and use, even for those new to MongoDB migration tools. +Check out our [installation guide](../install/source.md) and follow the step-by-step instructions to get started with PLM. The tool is designed to be straightforward to set up and use, even for those new to MongoDB migration tools. ## Join us in shaping the future of Percona Link for MongoDB! -This MVP release is just the beginning. Your real-world experience and feedback are invaluable as we evolve Percona Link for MongoDB. We encourage you to explore {{ plm.short }} for your non-production migration scenarios and share your insights: +This MVP release is just the beginning. Your real-world experience and feedback are invaluable as we evolve Percona Link for MongoDB. We encourage you to explore PLM for your non-production migration scenarios and share your insights: * What challenges did it solve for you? * What features would you like to see next? diff --git a/docs/release-notes/0.6.0.md b/docs/release-notes/0.6.0.md index e570f06..a34edf7 100644 --- a/docs/release-notes/0.6.0.md +++ b/docs/release-notes/0.6.0.md @@ -1,8 +1,10 @@ -# {{ plm.full_name }} 0.6.0 ({{ date.v0_6_0 }}) (Technical preview) +# Percona Link for MongoDB 0.6.0 ({{ date.v0_6_0 }}) (Technical preview) -We are excited to announce the first public release of {{ plm.full_name }} (PLM). It is in technical preview stage. We encourage you to test it and give us your feedback. This will help us improve the product in future. +We are excited to announce the first public release of Percona Link for MongoDB (PLM). It is in technical preview stage. We encourage you to test it and give us your feedback. This will help us improve the product in future. ---8<-- "plm-description.md" +Percona Link for MongoDB (PLM) is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It enables you to migrate from MongoDB Atlas or MongoDB Enterprise Edition to Percona Server for MongoDB with zero downtime. Check [Supported MongoDB deployments](../deployment.md). + +Percona Link for MongoDB (PLM) supports cloning data, replicating changes, and managing collections and indexes. [Get started with PLM](../installation.md){.md-button} diff --git a/docs/system-requirements.md b/docs/system-requirements.md index 3711427..9939bdf 100644 --- a/docs/system-requirements.md +++ b/docs/system-requirements.md @@ -2,11 +2,11 @@ * At least 1GB RAM is required to operate successfully. * At least 2 logical CPU cores are recommended to reduce the 100% CPU saturation risk during the synchronization period -* {{plm.short}} process must be able to connect to all replica set nodes that could become a new primary. In non-sharded replica set deployments, this means connecting to all the nodes that could become a new primary node. To become a primary, a node must meet the following criteria: +* {{pcsm.short}} process must be able to connect to all replica set nodes that could become a new primary. In non-sharded replica set deployments, this means connecting to all the nodes that could become a new primary node. To become a primary, a node must meet the following criteria: * have `priority` greater than `0` and must be able to vote (`votes`: 1) * is not an arbiter (`arbiterOnly: false`) * is not hidden (`hidden: false`) * is not delayed -Note that networking issues like connection to the remote backup storage can also affect {{plm.short}} performance. +Note that networking issues like connection to the remote backup storage can also affect {{pcsm.short}} performance. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b63ebb2..6530b12 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,10 +1,10 @@ # Troubleshooting guide -This guide helps you recover {{plm.full_name}} after an unexpected interruption, whether it occurs during initial data clone or real-time replication. +This guide helps you recover {{pcsm.full_name}} after an unexpected interruption, whether it occurs during initial data clone or real-time replication. -## Recover PLM during initial data clone +## Recover PCSM during initial data clone -{{plm.full_name}} can interrupt because of various reasons. For example, it is restarted, abnormally exits or loses connection to the source or destination cluster for an extended time. In any of these cases you must restart the initial data clone. +{{pcsm.full_name}} can interrupt because of various reasons. For example, it is restarted, abnormally exits or loses connection to the source or destination cluster for an extended time. In any of these cases you must restart the initial data clone. ### Symptoms @@ -14,70 +14,70 @@ After subsequently starting the service, you may see such messages: ```{.text .no-copy} 2025-06-02 21:25:38.927 INF Found Recovery Data. Recovering... s=recovery - Error: new server: recover Percona Link for MongoDB: recover: cannot resume: replication is not started or not resuming from failure - 2025-06-02 21:25:38.929 FTL error="new server: recover Percona Link for MongoDB: recover: cannot resume: replication is not started or not resuming from failure" + Error: new server: recover Percona ClusterSync for MongoDB: recover: cannot resume: replication is not started or not resuming from failure + 2025-06-02 21:25:38.929 FTL error="new server: recover Percona ClusterSync for MongoDB: recover: cannot resume: replication is not started or not resuming from failure" ``` ### Recovery steps -To recover PLM, do the following: +To recover PCSM, do the following: {.power-number} -1. Stop the `plm` service: +1. Stop the `pcsm` service: ```{.bash data-prompt="$"} - $ sudo systemctl stop plm + $ sudo systemctl stop pcsm ``` -2. Reset the PLM state with the following command and pass the connection string URL to the target deployment: +2. Reset the PCSM state with the following command and pass the connection string URL to the target deployment: ```{.bash data-prompt="$"} - $ plm reset --target + $ pcsm reset --target ``` The command does the following: * Connects to the target MongoDB deployment * Deletes the metadata collections - * Restores the `plm` service from the `failed` state + * Restores the `pcsm` service from the `failed` state -3. Restart `plm` +3. Restart `pcsm` ```{.bash data-prompt="$"} - $ sudo systemctl start plm + $ sudo systemctl start pcsm ``` 4. Start data replication from scratch: ```{.bash data-prompt="$"} - $ plm start + $ pcsm start ``` -## Recover PLM during real-time replication +## Recover PCSM during real-time replication -PLM can successfully complete the initial data clone and then interrupt unexpectedly, during the real-time replication. The recovery steps differ depending on how PLM stopped. +PCSM can successfully complete the initial data clone and then interrupt unexpectedly, during the real-time replication. The recovery steps differ depending on how PCSM stopped. ### Unexpected shutdown -If PLM exits abnormally or is stopped unexpectedly, restart the `plm` service. This is typically sufficient as PLM resumes replication automatically from the last saved checkpoint. +If PCSM exits abnormally or is stopped unexpectedly, restart the `pcsm` service. This is typically sufficient as PCSM resumes replication automatically from the last saved checkpoint. ??? example "Example logs" ```{.text .no-copy} - 2025-06-02 21:32:04.592 INF Starting Cluster Replication s=plm + 2025-06-02 21:32:04.592 INF Starting Cluster Replication s=pcsm 2025-06-02 21:32:04.592 DBG Change Replication is resuming s=repl 2025-06-02 21:32:04.592 INF Change Replication resumed op_ts=[1748887947,1] s=repl 2025-06-02 21:32:04.594 DBG Checkpoint saved s=checkpointing ``` -### Replication fails while PLM is running +### Replication fails while PCSM is running -The `plm` process is active but the replication may fail due to a temporary connection issue or other reasons. After you resolve the reason of failure (restore the connection), follow these steps to recover PLM: +The `pcsm` process is active but the replication may fail due to a temporary connection issue or other reasons. After you resolve the reason of failure (restore the connection), follow these steps to recover PCSM: 1. Check current replication status: ```{.bash data-prompt="$"} - $ plm status + $ pcsm status ``` ??? example "Sample output" @@ -103,13 +103,13 @@ The `plm` process is active but the replication may fail due to a temporary conn 2. Resume the replication from the last successful checkpoint: ```{.bash data-prompt="$"} - $ plm resume --from-failure + $ pcsm resume --from-failure ``` 3. Confirm that the replication has resumed: ```{.bash data-prompt="$"} - plm status + pcsm status ``` ??? example "Sample output after successful resume" @@ -134,4 +134,4 @@ The `plm` process is active but the replication may fail due to a temporary conn !!! note - If replication still fails after using the `plm resume --from-failure`, even after you restored the connectivity, the target cluster availability or any other underlying issue, you'll need to start over. Refer to the [Recover PLM during initial data clone](#recover-plm-during-initial-data-clone) section and reset the PLM state to begin replication from scratch. + If replication still fails after using the `pcsm resume --from-failure`, even after you restored the connectivity, the target cluster availability or any other underlying issue, you'll need to start over. Refer to the [Recover PCSM during initial data clone](#recover-pcsm-during-initial-data-clone) section and reset the PCSM state to begin replication from scratch. diff --git a/mkdocs-base.yml b/mkdocs-base.yml index c38a203..81fa4f5 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -1,6 +1,6 @@ # MkDocs configuration for builds with material theme -site_name: Percona Link for MongoDB +site_name: Percona ClusterSync for MongoDB site_description: documentation site_author: Percona LLC copyright: > @@ -127,7 +127,7 @@ plugins: enabled: !ENV [ENABLED_GIT_REVISION_DATE, True] git-committers: enabled: !ENV [CI, false] - repository: percona/plm-docs + repository: percona/pcsm-docs branch: "main" tags: {} glightbox: {} @@ -158,11 +158,12 @@ not_in_nav: | nav: - Home: index.md - get-help.md - - About Percona Link for MongoDB: - - How PLM works: intro.md + - About Percona ClusterSync for MongoDB: + - How PCSM works: intro.md - compare.md - deployment.md - limitations.md + - sharding.md - Get started: - Quickstart: installation.md - System requirements: system-requirements.md @@ -170,13 +171,13 @@ nav: - From repositories: install/repos.md - Build from source: install/source.md - 2. Configure authentication: install/authentication.md - - 3. Start PLM: install/start-plm.md + - 3. Start PCSM: install/start-pcsm.md - install/parameters.md - - Use PLM: + - Use PCSM: - Usage: install/usage.md - pqs.md - - PLM commands: plm-commands.md - - PLM HTTP API: api.md + - PCSM commands: pcsm-commands.md + - PCSM HTTP API: api.md - Troubleshooting and debugging: - Troubleshooting guide: troubleshooting.md - oplog-sizing.md @@ -184,12 +185,12 @@ nav: - pmm-setup.md - FAQ: faq.md - Release notes: - - release-notes.md + - Release notes index: release-notes.md - 0.6.0: release-notes/0.6.0.md - 0.5.0: release-notes/0.5.0.md - Reference: - Glossary: reference/glossary.md - - reference/contributing.md + - Contributing: "https://github.com/percona/pcsm-docs/blob/main/CONTRIBUTING.md" - About documentation: about-docs.md - Legal: - Copyright and licensing: copyright.md diff --git a/snippets/pcsm-description.md b/snippets/pcsm-description.md new file mode 100644 index 0000000..bce5644 --- /dev/null +++ b/snippets/pcsm-description.md @@ -0,0 +1,3 @@ +Percona ClusterSync for MongoDB (PCSM) is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It enables you to migrate from MongoDB Atlas or MongoDB Enterprise Edition to Percona Server for MongoDB with zero downtime. Check [Supported MongoDB deployments](../deployment.md). + +Percona ClusterSync for MongoDB (PCSM) supports cloning data, replicating changes, and managing collections and indexes. \ No newline at end of file diff --git a/snippets/plm-description.md b/snippets/plm-description.md deleted file mode 100644 index b2d5d3f..0000000 --- a/snippets/plm-description.md +++ /dev/null @@ -1,3 +0,0 @@ -Percona Link for MongoDB (PLM) is a tool for replicating data from a source MongoDB cluster to a target MongoDB cluster. It enables you to migrate from MongoDB Atlas or MongoDB Enterprise Edition to Percona Server for MongoDB with zero downtime. Check [Supported MongoDB deployments](../deployment.md). - -Percona Link for MongoDB (PLM) supports cloning data, replicating changes, and managing collections and indexes. \ No newline at end of file diff --git a/variables.yml b/variables.yml index f731f63..055a5a0 100644 --- a/variables.yml +++ b/variables.yml @@ -8,6 +8,6 @@ date: v0_6_0: '2025-09-04' v0_5_0: '2025-06-04' -plm: - full_name: 'Percona Link for MongoDB' - short: 'PLM' \ No newline at end of file +pcsm: + full_name: 'Percona ClusterSync for MongoDB' + short: 'PCSM' \ No newline at end of file