Updated readme. Stop balancer prior to index creation to avoid deadlocks.

Author: daniel-percona

cmd/docStreamer/main.go

@@ -519,6 +519,18 @@ func createAllDeferredIndexes(ctx context.Context, docdbURI, mongoURI string, st
 	}
 	defer targetClient.Disconnect(ctx)
 
+	logging.PrintStep("Stopping MongoDB Balancer to prevent index build deadlocks...", 0)
+	indexer.StopBalancer(ctx, targetClient)
+
+	// Use defer to ENSURE the balancer is restarted when this function exits,
+	// even if an error occurs or the context is cancelled.
+	defer func() {
+		logging.PrintStep("Restarting MongoDB Balancer...", 0)
+		// We use context.Background() here because if the user cancelled the operation,
+		// the original 'ctx' is dead, and the balancer restart command would fail.
+		indexer.StartBalancer(context.Background(), targetClient)
+	}()
+
 	collectionsToMigrate, err := discover.DiscoverCollections(ctx, discClient)
 	if err != nil {
 		return err
@@ -535,13 +547,19 @@ func createAllDeferredIndexes(ctx context.Context, docdbURI, mongoURI string, st
 	statusMgr.SetIndexingProgress(true, "Preparing...", 0, totalColls, false)
 
 	for i, collInfo := range collsWithIndexes {
+		if ctx.Err() != nil {
+			logging.PrintWarning("Index creation aborted due to shutdown.", 0)
+			return ctx.Err()
+		}
+
 		statusMgr.SetIndexingProgress(true, collInfo.Namespace, i, totalColls, false)
 		targetColl := targetClient.Database(collInfo.DB).Collection(collInfo.Coll)
 
 		logging.PrintStep(fmt.Sprintf("[%s] Checking %d source indexes...", collInfo.Namespace, len(collInfo.Indexes)), 0)
 
 		if err := indexer.FinalizeIndexes(ctx, targetColl, collInfo.Indexes, collInfo.Namespace, includeTTL); err != nil {
 			logging.PrintError(fmt.Sprintf("[%s] Failed to finalize indexes: %v", collInfo.Namespace, err), 0)
+			return err
 		}
 	}
 
@@ -852,7 +870,7 @@ func runMigrationProcess(cmd *cobra.Command, args []string) {
 			os.Exit(1)
 		}
 		logging.PrintPhase("FINALIZE", "Creating deferred indexes...")
-		if err := createAllDeferredIndexes(context.Background(), docdbURI, mongoURI, statusManager, true); err != nil {
+		if err := createAllDeferredIndexes(ctx, docdbURI, mongoURI, statusManager, true); err != nil {
 			logging.PrintError(fmt.Sprintf("Index creation failed: %v", err), 0)
 			os.Exit(1)
 		}
@@ -932,6 +950,8 @@ func runMigrationProcess(cmd *cobra.Command, args []string) {
 		w.Write([]byte(`{"status": "finalization started"}`))
 
 		logging.PrintPhase("FINALIZE", "Stopping CDC to begin finalization...")
+		statusManager.SetState("finalizing", "Stopping CDC to begin finalization")
+		statusManager.Persist(context.Background())
 		triggerFinalize.Store(true) // Flip the switch to trigger finalization
 		cancel()                    // Tell CDC to stop safely
 	})
@@ -1121,6 +1141,8 @@ func runMigrationProcess(cmd *cobra.Command, args []string) {
 
 	if triggerFinalize.Load() {
 		logging.PrintPhase("FINALIZE", "CDC safely drained. Creating deferred indexes...")
+		statusManager.SetState("finalizing", "Creating deferred indexes")
+		statusManager.Persist(context.Background())
 		if err := createAllDeferredIndexes(context.Background(), docdbURI, mongoURI, statusManager, true); err != nil {
 			logging.PrintError(fmt.Sprintf("Index creation failed: %v", err), 0)
 		} else {

readme.md

@@ -833,7 +833,7 @@ Percona docStreamer also has an API that allows you to perform certain status an
 
 ### Logs
 
-Percona docStreamer generates three separate logs, each of the logs location and name can be configured via [config.yaml](./config.yaml):
+Percona docStreamer generates separate logs, each of the logs location and name can be configured via [config.yaml](./config.yaml):
 
 1. Application Log (`logs/docStreamer.log`): Tracks the overall application status and any errors encountered.
 2. Full Load Log (`logs/full_load.log`): Dedicated to the initial full synchronization process. This log, together with the status endpoint, helps you monitor the progress of the initial sync.
@@ -1291,4 +1291,9 @@ By default, docStreamer safely defers TTL index creation. The safest and recomme
 
 When you run the `docStreamer finalize` command, docStreamer safely stops the CDC stream and **automatically builds your TTL indexes** (along with any other deferred indexes). Because the data stream is stopped, this ensures your target has an exact, 1:1 match of the source data before it begins autonomously managing document expiration. 
 
-*(Alternatively, you can choose to manually create TTL indexes on the destination cluster after the migration is fully complete.)*
+*(Alternatively, you can choose to manually create TTL indexes on the destination cluster after the migration is fully complete.)*
+
+
+# Disclaimer
+
+This code is not supported by Percona. It has been provided as a community contribution and is not covered under any Percona services agreement.