Evolución de esquemas y migraciones de documentos

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.

The cleanest pattern is to stamp every document with a schema_version integer. Beanie documents are Pydantic models, so you add it as a field with a default. New writes get the current version automatically; old documents that lack the field fall back to version 1 because Pydantic applies the default when the key is missing.

This is the same idea as a plain Python class with a version attribute.

Here is the Beanie model. Note three things:

• schema_version defaults to the current number for new documents.
• The old price field is kept as Optional so legacy docs still load.
• New fields are also Optional so a half-migrated collection never crashes a read.

Keeping deprecated fields Optional instead of deleting them outright is the key to zero-downtime: code must read both shapes for the whole transition window.

The least disruptive strategy is lazy migration: when you load a document, detect the old version and transform it in memory, persisting the upgrade only if you happen to save. This spreads the work across normal traffic with no big batch job.

The pure transform logic is just a function. Test it in isolation before wiring it into Beanie.

In an endpoint, fetch the Beanie document, apply the upgrade if needed, and save it back. Because the upgrade is idempotent (already-v2 docs are untouched), it is safe to run on every read.

This is framework code that depends on Beanie and a running MongoDB, so treat the transform helper as the testable part and keep the I/O thin.

Lazy migration leaves cold documents on the old shape forever. To fully retire field price, run an eager batch migration once: stream every old document, transform it, and write it back. Iterate over a query filter so you only touch unmigrated docs.

Always process in batches and use a filter like schema_version < 2 so a re-run resumes where it left off instead of redoing finished work.

Saving documents one by one is fine for thousands of rows, but for millions you want the database to do the work. MongoDB's aggregation-pipeline update can compute the new field server-side in a single command, avoiding a round trip per document.

Beanie exposes this through update with a raw pipeline. Multiplying price by 100 and setting currency happens inside Mongo.

Beanie ships a migration framework so you don't hand-roll scripts. You write a migration module with a Forward (and optional Backward) class containing functions decorated with @iterative_migration(). Beanie records applied migrations in a migrations collection, just like Alembic does for SQL.

• Run forward: beanie migrate -uri ... -db ... -p ./migrations
• Each function receives the old and new document instances.
• State is tracked so migrations apply exactly once.

This gives you ordered, repeatable, version-controlled schema changes.

Two changes look harmless but cause outages if rushed:

• Renaming a field: never rename in one step. Add the new field, dual-write both, backfill old docs, then drop the old field in a later release.
• Removing a field: deploy code that stops reading it first, then run a migration to $unset it.

The rule of thumb is the expand-and-contract pattern: expand the schema to support old and new at once, migrate the data, then contract by removing the old shape once no running code depends on it.

A common evolution is adding a brand-new field that older documents lack. For nullable convenience you give it an Optional default in the model, but to keep queries simple (e.g. filtering on is_active=True) you backfill a concrete default. This pure helper computes the patch dictionary you'd hand to MongoDB.

You learned how to evolve MongoDB document schemas with Beanie without taking the service down:

• Version documents with a schema_version field defaulted in the Pydantic model.
• Keep deprecated fields Optional so mixed-shape collections still load.
• Lazy migration upgrades documents on read; eager batch or bulk aggregation-pipeline updates fully retire old shapes.
• Use Beanie's @iterative_migration() framework for ordered, tracked, version-controlled migrations.
• Apply expand-and-contract: support old + new, migrate data, then remove the old shape only after no code depends on it.

These patterns let your data model grow alongside new features while users keep hitting the API uninterrupted.