MongoDB Academy · Lesson

Evolving Schemas Without Downtime

Learners will update an existing validator on a live collection and write migration scripts to backfill documents to the new shape.

Evolving Schemas Without Downtime is a free MongoDB Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Challenge of Schema Evolution

As your application grows, requirements change and your MongoDB schema must evolve. Unlike relational databases, you cannot run a blocking ALTER TABLE that locks the entire table during migration. MongoDB's flexibility means old and new document shapes can coexist in the same collection, which requires a deliberate migration strategy to keep the application working while the schema transitions.

Step 1: Update the Validator in Warn Mode

Begin every schema migration by updating the collection's validator to reflect the new schema, but with validationAction: 'warn'. This allows existing non-conforming documents to remain and be updated without errors while you measure how many documents need to be backfilled. New writes from updated application code will conform to the new schema.

// Add a new required field 'phoneNumber' to the validator
db.runCommand({
  collMod: 'users',
  validator: {
    $jsonSchema: {
      bsonType: 'object',
      required: ['name', 'email', 'phoneNumber'],
      properties: {
        name:        { bsonType: 'string' },
        email:       { bsonType: 'string' },
        phoneNumber: { bsonType: 'string' }
      }
    }
  },
  validationLevel: 'moderate',
  validationAction: 'warn'
});

Step 2: Update the Application Code

Deploy the updated application code that writes documents conforming to the new schema. New documents will now include the new fields. Old documents written before the schema change remain in the collection in their original shape. During this phase, your application code must handle both document shapes—for example, by providing a default value when the new field is absent.

// Application code that handles both old and new document shapes
async function getUserPhone(userId) {
  const user = await db.collection('users').findOne({ _id: userId });
  // Provide a fallback for documents written before the migration
  return user.phoneNumber || 'Not provided';
}

Step 3: Write a Backfill Migration Script

A backfill script iterates over all documents missing the new field and sets a default value. Run it in small batches to avoid locking resources or spiking server load. Use bulkWrite with ordered: false for efficiency, and track progress with logging so you can resume if interrupted.

// Backfill: set phoneNumber to '' for documents that lack it
const collection = db.collection('users');
const cursor = collection.find({ phoneNumber: { $exists: false } });

const batchSize = 500;
let batch = [];

for await (const doc of cursor) {
  batch.push({
    updateOne: {
      filter: { _id: doc._id },
      update: { $set: { phoneNumber: '' } }
    }
  });
  if (batch.length === batchSize) {
    await collection.bulkWrite(batch, { ordered: false });
    console.log('Processed', batchSize, 'docs');
    batch = [];
  }
}
if (batch.length) await collection.bulkWrite(batch, { ordered: false });
console.log('Backfill complete');

Step 4: Switch to Strict Error Mode

After the backfill is complete and you have verified that all documents conform to the new schema, switch validationLevel to strict and validationAction to error. From this point on, any write that violates the schema is rejected. Monitor the application for unexpected errors in the first hours after switching to catch any edge case that the backfill missed.

// Enable full enforcement after backfill is verified
db.runCommand({
  collMod: 'users',
  validationLevel: 'strict',
  validationAction: 'error'
});
console.log('Full schema enforcement enabled');

Renaming a Field Safely

To rename a field (e.g., fullName → name), first add name to new documents while the application still reads fullName as a fallback. Then backfill by copying fullName to name using $rename or $set. Finally, update the application to write and read only name, and remove fullName from old documents.

// Backfill: rename fullName to name for all existing documents
db.users.updateMany(
  { fullName: { $exists: true }, name: { $exists: false } },
  [{ $set: { name: '$fullName' } }, { $unset: 'fullName' }]
);

The Schema Versioning Pattern

For complex long-running migrations, add a schemaVersion field to every document. Application code checks this field and applies a transformation function for each older version before processing the document. New writes always include the latest schemaVersion. This gives you a controlled, auditable upgrade path and allows multiple schema generations to coexist indefinitely.

// Insert new document with schema version
db.products.insertOne({
  schemaVersion: 2,
  name: 'Widget Pro',
  priceUSD: 49.99,
  categories: ['electronics']
});

// Application transformer
function normalise(doc) {
  if (doc.schemaVersion === 1) {
    // v1 used 'price' instead of 'priceUSD'
    doc.priceUSD = doc.price;
    delete doc.price;
    doc.schemaVersion = 2;
  }
  return doc;
}

Adding a New Optional Field Safely

Adding a new optional field is the simplest schema evolution: update the validator's properties without adding it to required. Existing documents simply don't have the field, and the validator passes them because the field is not required. No backfill is necessary. New documents can include the field; application code reads it with a safe fallback default.

// Add optional 'avatarUrl' field to the validator
db.runCommand({
  collMod: 'users',
  validator: {
    $jsonSchema: {
      bsonType: 'object',
      required: ['name', 'email'],
      properties: {
        name:      { bsonType: 'string' },
        email:     { bsonType: 'string' },
        avatarUrl: { bsonType: 'string' }  // optional — no backfill needed
      }
    }
  }
});

Removing a Field From the Schema

To retire a field, first remove it from required if it was required, then deploy application code that no longer writes the field. Over time, new documents won't contain the field. You can optionally backfill by removing the field from all existing documents using $unset, but this is only necessary if the field wastes storage or causes confusion.

// Remove the deprecated 'legacyCode' field from all documents
db.products.updateMany(
  { legacyCode: { $exists: true } },
  { $unset: { legacyCode: '' } }
);

Zero-Downtime Migration Summary

The key insight for zero-downtime schema migration is that MongoDB allows mixed document shapes in the same collection. This means you never need to take the database offline to change the schema. The four-phase playbook—warn-mode validator, app code update, backfill, strict enforcement—decouples the schema change from the deployment and gives you full control over the transition timeline.

Verifying Migration Completeness

Before switching to strict mode, verify that zero documents are missing the required fields. A simple count query confirms completeness. If any documents are still non-conforming, run the backfill script again. This verification step prevents surprise validation errors after switching to error action.

// Verify no users are missing the new required field
const missing = await db.collection('users').countDocuments({
  phoneNumber: { $exists: false }
});
console.log('Documents missing phoneNumber:', missing);
// Should be 0 before enabling strict enforcement

Quick Check

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

Lesson Recap

In this lesson you learned: the four-phase migration playbook (warn → app update → backfill → strict) achieves zero downtime, the schema versioning pattern lets multiple document shapes coexist indefinitely, and verification before strict enforcement prevents surprise errors. Next up we explore projection and field selection to fetch only the fields your queries actually need.

Frequently asked questions

Is the “Evolving Schemas Without Downtime” lesson free?

Yes — the full text of “Evolving Schemas Without Downtime” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.

What will I learn in “Evolving Schemas Without Downtime”?

Learners will update an existing validator on a live collection and write migration scripts to backfill documents to the new shape. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start MongoDB Academy?

No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Evolving Schemas Without Downtime” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this MongoDB Academy lesson?

Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to MongoDB Academy