As your application grows and requirements change, it becomes crucial to adapt your database accordingly. In this blog, I will explain step by step method of writing migration scripts for MongoDB, and provide real-world examples to help you seamlessly manage your database transitions.

💡 Understanding Migration Scripts:

A migration script is a set of instructions written in code to transform data and schema from one state to another. In the context of MongoDB, it involves altering your database to accommodate changes such as adding new fields, modifying existing ones, or restructuring collections. Properly designed migration scripts ensure a smooth upgrade without losing data or causing application downtime.

✅ Planning Your Migration:

Before diving into writing migration scripts, planning is essential. Here are the steps to consider:

1. Identify Changes: List all the modifications you need to make to your database. These could include creating new collections, renaming fields, or migrating data to a new format.

2. Plan your migration strategy: Analyze your data and target schema changes to understand the scope and potential challenges. Decide whether you'll migrate the entire database in one go or opt for a phased approach to minimize risks.

3. Backup Your Data: As a precautionary measure, create a backup of your database before executing migration scripts. This step protects against accidental data loss.

👨‍💻 Writing Migration Scripts:

Now, let's see the process of writing migration scripts:

• Suppose we have a MongoDB collection named users with documents structured like this:

{
  _id: ObjectId("609e1696c8d15a2f4c6c7c7c"),
  name: "John Doe",
  email: "johndoe@example.com",
  age: 30
}

Now, we want to add a new field status to each document, indicating the user's account status.

db.users.updateMany({}, { $set: { status: "active" } });

The script uses the updateMany() method to add the status field with a default value of "active" to all existing documents.

• Let's say we decide to remove the age field from the users collection.

db.users.updateMany({}, { $unset: { age: "" } });

The updateMany() method with the $unset operator removes the age field from all documents in the users collection.

• Suppose we need to migrate the user data from the users collection to a new collection named user_details, keeping only the name and email fields.

db.users.find().forEach(function(user) {
    db.user_details.insert({
        name: user.name,
        email: user.email
    });
});

This script fetches each document from the users collection and inserts only the required fields into the user_details collection.

⚡️ Real-World Example:

Let's consider a scenario where you have developed a web application that manages an e-commerce platform. Your MongoDB database contains a collection called products with the following document structure:

{
  _id: ObjectId("61a2e154f487da77bf891234"),
  name: "Super Cool Widget",
  price: 1200,
  quantity_in_stock: 50,
  category: "Electronics",
  manufacturer: "TechCo Inc.",
  created_at: ISODate("2023-05-10T08:00:00Z")
}

Now, you want to add a new field called description to provide more information about each product. Additionally, you want to restructure the category field to an array of categories, as some products can belong to multiple categories now.

To achieve this, we need to write a migration script that accomplishes the following tasks:

1. Add the description field to each product document with a default value.

2. Convert the category field from a single string to an array of categories

Let's see how the migration script would look like for this scenario:

db.products.updateMany({}, [ 
  { 
    $set: { description: "This is an amazing product!" } 
  }, 
  { 
    $set: { category: ["$category"] } 
  }
]);

We use updateMany({}, [...]) to apply multiple update operations in one query, minimizing the number of interactions with the database. In the first update operation, we use $set to add the description field to all documents with the default value. Then, in the second step we use $set to convert category field to an array containing the same value.

⚠️ Applying Migration:

• Once your migration script is ready, test it thoroughly on a staging environment or a copy of your production database. Verify that the data transformation is accurate and that the script handles various scenarios gracefully.

• To apply the migration, follow these steps:

  1. Ensure your application is offline or in maintenance mode to prevent any write operations during migration.

  2. Run the migration script using the MongoDB shell or a tool like mongoose-migrate (if using Mongoose in Node.js).

  3. Verify that the migration was successful and the data is intact.

  4. Update your application code to work with the new database schema.

  5. Bring your application back online.

This is a simple illustration, yet this understanding can be applied to write even more complex migration scripts.

---

Thanks for reading :) If you found this blog helpful, don't hesitate to show your appreciation by giving it a like!