Schema versioning strategies in MongoDB

Introduction

Schema versioning helps keep track of changes in your database structure over time. It makes sure your app works well even when the data format changes.

When you add new fields to documents but want old data to stay usable.

When you change the type or format of existing fields in your documents.

When you want to migrate data safely without losing information.

When multiple versions of your app use the same database with different data needs.

When you want to track which version of the schema each document follows.

Syntax

MongoDB

No fixed syntax, but common patterns include:

1. Add a 'schemaVersion' field to each document.
2. Use migration scripts to update documents from old versions to new.
3. Use conditional logic in your app to handle different schema versions.

Example:
{
  _id: ObjectId(...),
  name: "Alice",
  age: 30,
  schemaVersion: 2
}

Adding a schemaVersion field helps identify the document's format.

Migration scripts update old documents to the latest schema.

Examples

Document with schema version 1, simple structure.

MongoDB

{
  _id: ObjectId("507f1f77bcf86cd799439011"),
  name: "John",
  schemaVersion: 1
}

Document updated to schema version 2 with new fields.

MongoDB

{
  _id: ObjectId("507f1f77bcf86cd799439012"),
  fullName: "John Doe",
  age: 28,
  schemaVersion: 2
}

Script to migrate documents from version 1 to version 2.

MongoDB

// Migration script example
const updateToV2 = async (db) => {
  await db.collection('users').updateMany(
    { schemaVersion: 1 },
    { $set: { age: 0, schemaVersion: 2 }, $rename: { name: 'fullName' } }
  );
};

Sample Program

This example inserts two user documents with different schema versions and then retrieves them.

MongoDB

// Sample MongoDB commands to show schema versioning
// Insert documents with different schema versions
use testdb;

// Insert version 1 document
db.users.insertOne({ name: "Alice", schemaVersion: 1 });

// Insert version 2 document
db.users.insertOne({ fullName: "Bob Smith", age: 25, schemaVersion: 2 });

// Find all documents
const allUsers = db.users.find().toArray();
allUsers;

Important Notes

Always keep the schemaVersion field updated when changing document structure.

Test migration scripts on a copy of your data before running in production.

Use your application code to handle different schema versions gracefully.

Summary

Schema versioning tracks changes in document structure over time.

Use a schemaVersion field and migration scripts to manage updates.

This helps keep your app stable and your data consistent.

Practice

1. What is the main purpose of adding a schemaVersion field in MongoDB documents?

easy

A. To track changes in the document structure over time

B. To improve query performance automatically

C. To encrypt the document data

D. To store user authentication details

Solution

1. Step 1: Understand schemaVersion role

   The schemaVersion field is used to mark which version of the document structure is currently in use.

2. Step 2: Identify its purpose in schema versioning

   This helps developers know what format the data is in and apply necessary migrations when the schema changes.

3. Final Answer:

   To track changes in the document structure over time -> Option A

4. Quick Check:

   schemaVersion tracks structure changes = C [OK]

Hint: Remember schemaVersion marks document format version [OK]

Common Mistakes:

• Thinking schemaVersion improves query speed
• Confusing schemaVersion with encryption
• Assuming schemaVersion stores user info

2. Which of the following is the correct way to add a schemaVersion field with value 2 to a MongoDB document using an update query?

easy

A. db.collection.updateOne({ _id: id }, { $push: { schemaVersion: 2 } })

B. db.collection.updateOne({ _id: id }, { schemaVersion: 2 })

C. db.collection.updateOne({ _id: id }, { $set: { schemaVersion: 2 } })

D. db.collection.updateOne({ _id: id }, { $inc: { schemaVersion: 2 } })

Solution

1. Step 1: Recall MongoDB update syntax

   To set or update a field, use the $set operator with the new value.

2. Step 2: Check each option

   db.collection.updateOne({ _id: id }, { $set: { schemaVersion: 2 } }) correctly uses $set to assign schemaVersion: 2. Bare object updates lack an update operator (invalid), $push is for arrays, and $inc increments numbers.

3. Final Answer:

   db.collection.updateOne({ _id: id }, { $set: { schemaVersion: 2 } }) -> Option C

4. Quick Check:

   Use $set to update fields = A [OK]

Hint: Use $set to add or update fields in MongoDB [OK]

Common Mistakes:

• Forgetting to use $set operator
• Using $push for non-array fields
• Using $inc to set a fixed value

3. Given the following documents in a collection:

{ "_id": 1, "name": "Alice", "schemaVersion": 1 }

{ "_id": 2, "name": "Bob", "schemaVersion": 2 }

What will be the result of this query?

db.collection.find({ schemaVersion: { $lt: 2 } })

medium

A. [{ "_id": 1, "name": "Alice", "schemaVersion": 1 }, { "_id": 2, "name": "Bob", "schemaVersion": 2 }]

B. [{ "_id": 2, "name": "Bob", "schemaVersion": 2 }]

C. []

D. [{ "_id": 1, "name": "Alice", "schemaVersion": 1 }]

Solution

1. Step 1: Understand the query condition

   The query filters documents where schemaVersion is less than 2.

2. Step 2: Check each document against condition

   Document with schemaVersion 1 matches (1 < 2). Document with 2 does not (2 is not less than 2).

3. Final Answer:

   [{ "_id": 1, "name": "Alice", "schemaVersion": 1 }] -> Option D

4. Quick Check:

   schemaVersion < 2 returns only version 1 docs = D [OK]

Hint: Check numeric conditions carefully in queries [OK]

Common Mistakes:

• Including documents with schemaVersion equal to 2
• Returning empty result incorrectly
• Confusing $lt with $lte operator

4. You have a migration script to update documents from schemaVersion 1 to 2. The script uses:

db.collection.updateMany({ schemaVersion: 1 }, { $set: { schemaVersion: 2, newField: true } })

But after running, some documents still show schemaVersion 1. What is a likely cause?

medium

A. Documents were missing the schemaVersion field

B. The update query syntax is incorrect

C. The updateMany command does not support $set

D. The migration script ran on the wrong collection

Solution

1. Step 1: Analyze the update query filter

   The filter matches documents where schemaVersion equals 1 exactly.

2. Step 2: Consider documents missing the field

   If some documents lack the schemaVersion field, they won't match the filter and won't be updated.

3. Final Answer:

   Documents were missing the schemaVersion field -> Option A

4. Quick Check:

   Missing field means no match = B [OK]

Hint: Check if all docs have the field before filtering [OK]

Common Mistakes:

• Assuming updateMany syntax is wrong
• Believing $set is unsupported in updateMany
• Not verifying the collection name

5. You want to migrate documents from multiple schema versions to the latest version 3. Your current documents have schemaVersion 1 or 2. Which strategy best ensures all documents are updated correctly?

hard

A. Directly update all documents with version 1 or 2 to version 3 in one step

B. Run separate migration scripts: first update version 1 to 2, then update version 2 to 3

C. Delete all documents with version less than 3 and insert new ones

D. Ignore schemaVersion and update documents randomly

Solution

1. Step 1: Understand incremental migrations

   Updating schema versions step-by-step ensures each migration applies necessary changes safely.

2. Step 2: Evaluate options

   Run separate migration scripts: first update version 1 to 2, then update version 2 to 3 runs migrations in order: 1 to 2, then 2 to 3, preserving data integrity. Directly update all documents with version 1 or 2 to version 3 in one step risks skipping intermediate changes. Delete all documents with version less than 3 and insert new ones loses data. Ignore schemaVersion and update documents randomly is unsafe.

3. Final Answer:

   Run separate migration scripts: first update version 1 to 2, then update version 2 to 3 -> Option B

4. Quick Check:

   Incremental migrations keep data safe = A [OK]

Hint: Migrate stepwise through versions, not skipping steps [OK]

Common Mistakes:

• Trying to skip intermediate schema versions
• Deleting data instead of migrating
• Ignoring schemaVersion field