Ewolucja schematów bez przestojów
Zaktualizują Państwo istniejący walidator w działającej kolekcji i napiszą skrypty migracyjne uzupełniające dokumenty do nowego kształtu.
Ewolucja schematów bez przestojów to bezpłatna lekcja MongoDB Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej MongoDB Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs MongoDB Academy zawiera 4 lekcji w sumie.
Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.
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.
Często zadawane pytania
Czy lekcja „Ewolucja schematów bez przestojów” jest bezpłatna?
Tak — pełny tekst „Ewolucja schematów bez przestojów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu MongoDB Academy, przejdź na CoddyKit PRO. Kurs MongoDB Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Ewolucja schematów bez przestojów”?
Zaktualizują Państwo istniejący walidator w działającej kolekcji i napiszą skrypty migracyjne uzupełniające dokumenty do nowego kształtu. Ćwiczysz MongoDB Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć MongoDB Academy?
Nie wymagamy żadnego doświadczenia. MongoDB Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.
Ile czasu zajmuje lekcja „Ewolucja schematów bez przestojów”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji MongoDB Academy?
Tak. Każda lekcja MongoDB Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Dodawanie walidatora do kolekcji
- Ograniczenia typu, wymaganych pól i enum
- Poziomy i działania walidacji
- Ewolucja schematów bez przestojów