Add a New Property in Cosmos DB (Existing millions of data) Without Downtime

 

Scenario

You have a Cosmos DB collection with 1 million records, and you need to introduce a new property (e.g., Discount). Your goal is to add this new field without causing downtime, meaning that both the old and new data should work for clients during the transition period.

Step 1: Understand Cosmos DB is Schema-less

Cosmos DB is a NoSQL database, meaning it doesn't enforce a strict schema. Each document (record) can have a different structure. This gives you flexibility in adding or modifying fields without requiring an actual schema migration, unlike relational databases.

In Cosmos DB:

• Old records can remain as they are (without the new field).
• New records can be added with the new field.

Your task is to handle this evolution in the application code without downtime.

Step 2: Update Your Application Model (Add the New Field)

You need to modify your application’s data model (e.g., C# class) to include the new field (Discount).

public class Product
{
    public string Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    
    // Add the new field (Version2)
    public string Version2 { get; set; }  // New field, initially null for old records
}

• Old records will not have the Version2 field.
• New records will have the Version2 field.

Key Point:

• Backward Compatibility: Ensure that your code can handle the case where Version2 is null for old records.

Step 3: Modify Read and Write Logic in Your Application

Now, you need to ensure that your application works seamlessly with both old and new data (some records have Version2, and some don’t). Update the read and write logic in your application to handle both scenarios.

Read Logic (Backward Compatibility):

When reading from Cosmos DB, check whether the Version2 field exists.

public async Task<Product> GetProductAsync(string id)
{
    var product = await cosmosDbClient.GetItemAsync<Product>(id);

    // Check if the new field (Version2) is present
    if (string.IsNullOrEmpty(product.Version2))
    {
        // Old record, handle accordingly
        Console.WriteLine("Using old data format, without Version2.");
    }
    else
    {
        // New record, handle Version2 logic
        Console.WriteLine("Using new data format with Version2.");
    }

    return product;
}

Write Logic (Ensure New Records Include Version2):

When writing new records or updating existing records, ensure that the Version2 field is included in the new data.

public async Task SaveProductAsync(Product product)
{
    // Ensure Version2 is populated for new or updated records
    product.Version2 = "some_value_for_version2";
    
    await cosmosDbClient.UpsertItemAsync(product.Id, product);  // Upsert to create or update the document
}

Key Point:

• This step ensures that your application handles old and new records differently but works seamlessly with both.

Step 4: Gradually Migrate Old Data (Without Downtime)

You can choose one of two methods to gradually populate the Version2 field for the existing 1 million records, without taking your system down.

Option 1: Lazy Update on Read

• Whenever a record is read by any client, check if the Version2 field is missing.
• If it's missing, populate the field and update the record in Cosmos DB at the same time.

This way, over time, as records are accessed, they will be updated to include Version2.

public async Task<Product> GetAndUpdateProductAsync(string id)
{
    var product = await cosmosDbClient.GetItemAsync<Product>(id);

    // Check if the new field (Version2) is missing
    if (string.IsNullOrEmpty(product.Version2))
    {
        // Populate the new field
        product.Version2 = "default_value";  // Compute this based on your logic
        
        // Update the record in Cosmos DB with the new field
        await cosmosDbClient.UpdateItemAsync(product.Id, product);
    }

    return product;
}

This lazy update approach ensures that records are updated incrementally, without needing to run a massive migration upfront.

Never miss new posts by subscribe

Powered by

Option 2: Background Migration Job

• You can write a background process (or a scheduled job) that iterates through the records in Cosmos DB and updates them with the new Version2 field.
• The job should run in small batches to avoid overwhelming the system.

public async Task MigrateOldDataAsync()
{
    var items = await cosmosDbClient.GetItemsAsync<Product>(); // Fetch all records

    foreach (var product in items)
    {
        if (string.IsNullOrEmpty(product.Version2))
        {
            // Populate Version2 for old data
            product.Version2 = "default_value";  // Use your business logic to set this

            // Update the document in Cosmos DB
            await cosmosDbClient.UpdateItemAsync(product.Id, product);
        }
    }
}

• Run the migration during off-peak hours to minimize performance impact on live clients.
• This way, you are migrating the data in batches without taking down your application.

Key Point:

• No Downtime: Both options (lazy update or background migration) ensure that old records are gradually migrated without affecting live clients.

Step 5: Monitor and Ensure Consistency

Monitor the migration process to ensure that the Version2 field is being added to old records as expected. You can log progress and handle errors as part of the migration job.

• Check how many records have been updated with the new field over time.
• Indexing: Cosmos DB automatically indexes all properties, including the new field, which helps with efficient querying.

Step 6: Update Client Applications (If Needed)

If your clients are expected to use the new Version2 field, make sure they are updated once the migration is largely complete.

You can use API versioning or feature flags to control when the new field is exposed to clients, ensuring they are not affected by the migration.

Never miss new posts by subscribe

Powered by

Summary: Zero Downtime Strategy

Here’s a recap of the steps to introduce the new field in Cosmos DB without downtime:

1. Add the new field (Version2) to your data model without altering the existing structure.
2. Update the read and write logic to handle both old (no Version2) and new records (with Version2).
3. Gradually populate the new field:
   • Option 1: Lazy update on read: Add the field when records are accessed.
   • Option 2: Run a background migration job: Update old records in batches during low traffic times.
4. Ensure backward compatibility: Your application should work with both old and new data formats throughout the migration process.
5. Monitor and update clients: Once the migration is largely complete, update your client applications to start using the new field.

By following this step-by-step approach, you can evolve your data schema in Cosmos DB without downtime, ensuring both your application and clients continue working smoothly.