Schema Evolution and Document Migrations

In a FastAPI backend, your data model rarely stays frozen. New features mean new fields, renamed properties, and changed shapes. With a relational database you'd run an ALTER TABLE migration. MongoDB is schemaless at the storage layer, so nothing stops you from writing a new shape next to an old one.

• Old documents keep their original fields until you touch them.
• New documents follow the latest model.
• Your code must tolerate BOTH shapes during the transition.

This lesson shows how Beanie (the async ODM built on Motor + Pydantic) lets you version your documents and migrate collections without downtime.

Imagine a Product document that started with a single price float. Later you split it into price_cents (int) plus currency. After deploy, your collection holds a mix:

• Old docs: { "price": 19.99 }
• New docs: { "price_cents": 1999, "currency": "USD" }

If your Pydantic-backed model declares only the new fields as required, reading an old document raises a validation error. The core skill of schema evolution is making the model forgiving enough to load both, then upgrading data behind the scenes.