PCSM-382: Document skipping chunk pre-splitting in PCSM 1.1.0

docs/api.md

@@ -26,6 +26,7 @@ Starts the replication process.
 |-----------|------|----------|-------------|
 | `includeNamespaces` | string[] | No | List of namespaces to include in replication (for example, ["db.*", "db.collection"]) |
 | `excludeNamespaces` | string[] | No | List of namespaces to exclude from replication |
+| `cloneSkipPresplit` | boolean | No | Set to `true` to skip pre-splitting collections on the sharded target. {{pcsm.short}} still shards each collection with the source shard key. If you omit this field, {{pcsm.short}} uses the value from its startup configuration, which defaults to `false`. Available starting with version 1.1.0. See [Skip pre-splitting](sharding.md#skip-pre-splitting). |
 | `replNumWorkers` | int | No | Controls how many concurrent replication worker goroutines PCSM uses to apply DML (insert/update/replace/delete) events to the target cluster.|
 | `replChangeStreamBatchSize` | int | No | Sets the maximum number of change stream events PCSM will request and read from MongoDB per batch while streaming changes from the source cluster. |
 | `replEventQueueSize` | int | No | Controls the size of the internal event queue used by the replication subsystem. |

docs/install/parameters.md

@@ -41,6 +41,7 @@ Alternatively, you can define the following environment variables:
 | `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_CLONE_SKIP_PRESPLIT` | Set to `true` to skip pre-splitting collections on the sharded target before the initial clone. {{pcsm.short}} still shards each collection with the source shard key but keeps the initial chunk layout that MongoDB creates. Available starting with version 1.1.0. See [Skip pre-splitting](../sharding.md#skip-pre-splitting). | `false` |
 | `PCSM_CLONE_SEGMENT_SIZE` | Defines the segment size used during clone operations. Accepts values in bytes or with size suffixes such as `500MB` or `1GiB`. If not specified, PCSM automatically calculates the segment size based on collection size and available read workers. | `Auto` |
 | `PCSM_MONGODB_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` | 
 | `PCSM_REPL_NUM_WORKERS` | Controls how many concurrent replication worker goroutines PCSM uses to apply DML (insert/update/replace/delete) events to the target cluster. | `runtime.NumCPU()` |

docs/pcsm-commands.md

@@ -67,6 +67,7 @@ Available flags:
 | `--clone-num-read-workers` | Number of read workers that read collection segments from the source. Shared for all collections.|
 | `--clone-num-insert-workers` | Number of insert workers that write batches to the target. Shared for all collections.|
 | `--clone-segment-size` | Defines the size of each clone segment processed during the initial clone phase.|
+| `--clone-skip-presplit` | Skips pre-splitting collections on the sharded target. {{pcsm.short}} still shards each collection with the source shard key but keeps the initial chunk layout that MongoDB creates. Default: `false`. Available starting with version 1.1.0. See [Skip pre-splitting](sharding.md#skip-pre-splitting). |
 | `--repl-num-workers` | Controls how many concurrent replication worker goroutines PCSM uses to apply DML (insert/update/replace/delete) events to the target cluster.|
 | `--repl-change-stream-batch-size`| Sets the maximum number of change stream events PCSM will request and read from MongoDB per batch while streaming changes from the source cluster.|
 | `--repl-event-queue-size`| Controls the size of the internal event queue used by the replication subsystem.|

docs/sharding.md

@@ -8,7 +8,7 @@
 
 For a sharded source, {{pcsm.short}} connects to `mongos` instead of connecting directly to individual shard members. When the target is also sharded, {{pcsm.short}} connects to the target `mongos` as well. The source and target can have different numbers of shards.
 
-{{pcsm.short}} does not continuously replicate sharding metadata. For collections with a ranged shard key, it uses the source chunk boundaries to prepare the target before the initial clone begins. Changes to the chunk layout that occur later on the source are not replicated to the target.
+{{pcsm.short}} does not continuously replicate sharding metadata. By default, for collections with a ranged shard key, it uses the source chunk boundaries to prepare the target before the initial clone begins. You can [skip pre-splitting](#skip-pre-splitting) to keep the initial chunk layout created by MongoDB on the target. Changes to the chunk layout that occur later on the source are not replicated to the target.
 
 The primary shard assignment can also differ between the source and target clusters.
 
@@ -40,7 +40,7 @@
 
 During the initial sync, {{pcsm.short}} checks which collections are sharded on the source cluster and shards the corresponding collections on the target with the same shard key before copying their documents.
 
-For collections with a ranged shard key, {{pcsm.short}} uses the source chunk boundaries to pre-split the collection on the target before copying any documents. If the source and target have the same number of shards, PCSM preserves the source chunk ownership pattern. If the shard counts differ, PCSM uses the source boundaries and determines the chunk placement across the available target shards.
+By default, for collections with a ranged shard key, {{pcsm.short}} uses the source chunk boundaries to pre-split the collection on the target before copying any documents. If the source and target have the same number of shards, PCSM preserves the source chunk ownership pattern. If the shard counts differ, PCSM uses the source boundaries and determines the chunk placement across the available target shards.
 
 Collections with a hashed shard key keep the initial chunk layout created by MongoDB when `shardCollection` runs on the target.
 
@@ -50,7 +50,7 @@
 
 {{pcsm.full_name}} connects to the sharded source through a `mongos` instance. When the target is also sharded, {{pcsm.full_name}} connects to it through `mongos`. You do not need to disable the balancer on either sharded cluster before starting replication. The target balancer continues to operate normally and manages chunk distribution according to the target cluster's sharding configuration and balancer settings.
 
-For ranged shard keys, PCSM prepares the target using the source chunk boundaries before the clone begins. Chunk migrations, splits, and merges that occur later are not replicated between the clusters. Each cluster continues to manage its own chunk layout. See [Manage sharded cluster balancer :octicons-link-external-16:](https://www.mongodb.com/docs/manual/tutorial/manage-sharded-cluster-balancer/){:target="_blank"} in the MongoDB documentation.
+By default, for collections that use ranged sharding, {{pcsm.short}} pre-splits each collection on the target using the source chunk boundaries before the clone begins. After that, chunk migrations, splits, and merges aren't replicated between the clusters, and each cluster manages its own chunk layout. To learn how MongoDB balances chunks across shards, see [Manage sharded cluster balancer :octicons-link-external-16:](https://www.mongodb.com/docs/manual/tutorial/manage-sharded-cluster-balancer/){:target="_blank"} in the MongoDB documentation.
 
 ### If the pre-split fails
 
@@ -60,7 +60,7 @@
 
 !!! admonition "Version added: 1.0.0"
 
-During the initial sync, {{pcsm.short}} prepares the chunk distribution of a sharded collection before copying its documents. This happens automatically for every sharded collection, immediately after the collection is sharded on the target. There is no flag and nothing to configure.
+During the initial sync, {{pcsm.short}} prepares the chunk distribution of each sharded collection before copying its documents. For collections that use ranged sharding, pre-splitting runs right after {{pcsm.short}} shards the collection on the target. Starting with version 1.1.0, you can [skip pre-splitting](#skip-pre-splitting).
 
 For an empty collection with a ranged shard key, MongoDB initially creates a single chunk that covers the full shard key range. If the clone starts with this layout, writes can be concentrated on one shard and the target balancer may need to redistribute the data later. See [Data partitioning with chunks :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/sharding-data-partitioning/){:target="_blank"} in the MongoDB documentation.
 
@@ -71,6 +71,42 @@
 !!! note
     {{pcsm.short}} uses the source chunk layout to prepare the target before the clone. It does not keep the chunk layouts on the two clusters synchronized. Chunk migrations, splits, or merges that happen later on the source are not reproduced on the target. The layouts can therefore change independently as each cluster's balancer runs. This is expected and does not indicate a replication problem. See [Balancer operation](#balancer-operation).
 
+### Skip pre-splitting
+
+!!! admonition "Version added: 1.1.0"
+
+If the source has an uneven chunk distribution that you do not want to copy, you can skip pre-splitting on the target. {{pcsm.short}} still shards each target collection with the source shard key, but keeps the initial chunk layout created by MongoDB. The target balancer manages distribution according to its configuration and balancing thresholds.
+
+Use one of the following options when [starting replication](install/usage.md#start-the-replication):
+
+=== "Command line"
+
+    ```{.bash data-prompt="$"}
+    $ pcsm start --clone-skip-presplit
+    ```
+
+=== "HTTP API"
+
+    ```{.bash data-prompt="$"}
+    $ curl -X POST http://localhost:2242/start \
+        -H "Content-Type: application/json" \
+        --data '{"cloneSkipPresplit": true}'
+    ```
+
+=== "Environment variable"
+
+    ```{.bash data-prompt="$"}
+    $ export PCSM_CLONE_SKIP_PRESPLIT=true
+    $ pcsm start
+    ```
+
+The default is `false`, so pre-splitting stays enabled unless you skip it. To keep pre-splitting for a single run when `PCSM_CLONE_SKIP_PRESPLIT` is `true`, use `pcsm start --clone-skip-presplit=false` or set `cloneSkipPresplit` to `false` in the `/start` request.
+
+!!! note
+    Skipping pre-splitting doesn't guarantee that data is evenly distributed across shards during the initial clone. At first, writes can concentrate on a single shard while the balancer redistributes the data. For details, see [Data partitioning with chunks :octicons-link-external-16:](https://www.mongodb.com/docs/v8.0/core/sharding-data-partitioning/){:target="_blank"} in the MongoDB documentation and [Balancer operation](#balancer-operation). 
+
+    Collections with [hashed shard keys](#hashed-shard-keys) already use the initial chunk layout that MongoDB creates, so this option doesn't change how they're distributed.
+
 ### Same number of shards
 
 For a source collection with more than one chunk, if the source and target have the same number of shards, {{pcsm.short}} sorts the shard IDs in each cluster and pairs them by their position in the sorted lists. For example, the first source shard is paired with the first target shard, the second source shard with the second target shard, and so on.
@@ -141,4 +177,4 @@
 * [Configure authentication](install/authentication.md)
 * [Start replication](install/usage.md)
 * [Monitor replication status](install/usage.md#check-the-replication-status)
-* [Monitor PCSM performance with Percona Monitoring and Management](pmm-setup.md)
+* [Monitor PCSM performance with Percona Monitoring and Management](pmm-setup.md)

mkdocs-base.yml

@@ -164,7 +164,7 @@ nav:
      - Deployment architecture: architecture.md
      - compare.md
      - deployment.md
-     - sharding.md
+     - Sharding support: sharding.md
      - sharded-source-to-replica-set-target.md
      - limitations.md
   - Get started: