Evolvere gli schemi senza downtime
Aggiornerà un validator esistente su una collection attiva e scriverà script di migrazione per aggiornare i documenti al nuovo formato.
Evolvere gli schemi senza downtime è una lezione MongoDB Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento MongoDB Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso MongoDB Academy include 4 lezioni in totale.
Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.
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 enforcementQuick 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.
Domande Frequenti
La lezione «Evolvere gli schemi senza downtime» è gratuita?
Sì — il testo completo di «Evolvere gli schemi senza downtime» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso MongoDB Academy, passa a CoddyKit PRO. Il corso MongoDB Academy include 4 lezioni in totale.
Cosa imparerò in «Evolvere gli schemi senza downtime»?
Aggiornerà un validator esistente su una collection attiva e scriverà script di migrazione per aggiornare i documenti al nuovo formato. Eserciti MongoDB Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare MongoDB Academy?
Non è richiesta alcuna esperienza precedente. MongoDB Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.
Quanto tempo richiede la lezione «Evolvere gli schemi senza downtime»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione MongoDB Academy?
Sì. Ogni lezione MongoDB Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Aggiungere un validator a una collection
- Vincoli di tipo, obbligatorietà ed enum
- Livelli e azioni di validazione
- Evolvere gli schemi senza downtime