What is the 'Schema Versioning' pattern?

Question

Accepted Answer

The Schema Versioning pattern addresses the challenge of evolving database schemas over time without requiring application downtime or immediate, large-scale migrations . Unlike traditional relational databases that often require rigid schema changes and potentially lengthy migration windows, MongoDB's flexible document model allows different document structures to coexist in the same collection . The Schema Versioning pattern formalizes this capability by adding a `schema_version` field to documents, enabling applications to identify and appropriately handle documents from different schema iterations . // Original schema (version 1)
{
  _id: 123,
  galactic_id: 123,
  name: "Anakin Skywalker",
  phone: "503-555-0000"
}

// Updated schema (version 2) with nested contact_method
{
  _id: 123,
  galactic_id: 123,
  name: "Darth Vader",
  contact_method: {
    work: "503-555-0210",
    home: "503-555-0220",
    twitter: "@realdarthvader",
    skype: "AlwaysWithYou"
  },
  schema_version: "2"
}

// Application logic handling different versions
const doc = db.users.findOne({ galactic_id: 123 });

if (!doc.schema_version) {
  // Handle original schema (version 1)
  renderPhone(doc.phone);
} else if (doc.schema_version === "2") {
  // Handle updated schema
  renderContactMethods(doc.contact_method);
} When implementing this pattern, you add a `schema_version` field to documents the first time you modify your schema . Documents using the new schema receive a version number (typically 2 for the first update), which increments with subsequent schema changes. Your application code checks this field to determine how to process each document, routing old and new documents to appropriate handler functions . This approach allows you to maintain backward compatibility while gradually introducing schema improvements. Application downtime is not an option for migrations  Updating all documents to a new schema may take hours, days, or weeks to complete  You need to maintain backward compatibility while evolving your data model  Different services or deployment phases require different document structures in the same collection  Updating documents to the new schema version is not a strict requirement  The Schema Versioning pattern requires careful consideration of query patterns. When fields move to different locations (e.g., from top-level `work` to nested `contactInfo.work`), queries must check all possible locations using `$or` conditions . Similarly, updates need conditional logic based on `schema_version` to modify the correct fields . This can also affect indexes—if the same logical field appears at different paths in different document versions, you may need multiple indexes to support efficient queries .

What is the 'Schema Versioning' pattern?

The Schema Versioning pattern is a MongoDB design approach that allows multiple versions of a schema to coexist in the same collection by adding a version field, enabling gradual migrations and backward compatibility without downtime.

What is the 'Schema Versioning' pattern?

The Schema Versioning pattern is a MongoDB design approach that allows multiple versions of a schema to coexist in the same collection by adding a version field, enabling gradual migrations and backward compatibility without downtime.

Scenario Questions

Follow-up Questions