0Pricing
FastAPI Backend Development Bootcamp · Lekcja

Ewolucja schematu i migracje dokumentów

Wersjonuj schematy dokumentów i migruj istniejące kolekcje bez przestojów wraz z rozwojem modelu danych.

Ewolucja schematu i migracje dokumentów to bezpłatna lekcja FastAPI Backend Development Bootcamp 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 FastAPI Backend Development Bootcamp, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs FastAPI Backend Development Bootcamp zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Why Schemas Evolve

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.

The Mixed-Shape Problem

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.

Track a Schema Version

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.

class ProductDoc:
    CURRENT_VERSION = 2

    def __init__(self, data):
        self.schema_version = data.get("schema_version", 1)
        self.data = data

    def needs_migration(self):
        return self.schema_version < self.CURRENT_VERSION


old = ProductDoc({"price": 19.99})
new = ProductDoc({"price_cents": 1999, "schema_version": 2})
print(old.schema_version, old.needs_migration())
print(new.schema_version, new.needs_migration())

A Versioned Beanie Document

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.

from typing import Optional
from beanie import Document


class Product(Document):
    schema_version: int = 2
    name: str
    # legacy (v1)
    price: Optional[float] = None
    # current (v2)
    price_cents: Optional[int] = None
    currency: Optional[str] = None

    class Settings:
        name = "products"

Upgrade on Read (Lazy Migration)

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.

def upgrade_product(doc: dict) -> dict:
    version = doc.get("schema_version", 1)
    if version < 2:
        # v1 -> v2: float dollars to integer cents + currency
        if doc.get("price") is not None:
            doc["price_cents"] = round(doc["price"] * 100)
            doc["currency"] = "USD"
        doc.pop("price", None)
        doc["schema_version"] = 2
    return doc


print(upgrade_product({"name": "Pen", "price": 19.99}))
print(upgrade_product({"name": "Pad", "price_cents": 500,
                       "currency": "USD", "schema_version": 2}))

Wiring Lazy Upgrade into FastAPI

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.

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/products/{product_id}")
async def get_product(product_id: str):
    product = await Product.get(product_id)
    if product is None:
        raise HTTPException(status_code=404, detail="Not found")
    if product.schema_version < 2 and product.price is not None:
        product.price_cents = round(product.price * 100)
        product.currency = "USD"
        product.price = None
        product.schema_version = 2
        await product.save()
    return product

Eager Migration with a Batch Script

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.

async def migrate_products():
    cursor = Product.find(Product.schema_version < 2)
    migrated = 0
    async for product in cursor:
        if product.price is not None:
            product.price_cents = round(product.price * 100)
            product.currency = "USD"
            product.price = None
        product.schema_version = 2
        await product.save()
        migrated += 1
    print(f"Migrated {migrated} products")

Bulk Update for Speed

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.

async def bulk_migrate_products():
    await Product.find(Product.schema_version < 2).update(
        [
            {
                "$set": {
                    "price_cents": {
                        "$round": [{"$multiply": ["$price", 100]}, 0]
                    },
                    "currency": "USD",
                    "schema_version": 2,
                }
            },
            {"$unset": "price"},
        ]
    )

Beanie's Built-in Migrations

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.

from beanie import Document, iterative_migration


class OldProduct(Document):
    price: float

    class Settings:
        name = "products"


class NewProduct(Document):
    price_cents: int
    currency: str

    class Settings:
        name = "products"


class Forward:
    @iterative_migration()
    async def split_price(self, input_document: OldProduct,
                          output_document: NewProduct):
        output_document.price_cents = round(input_document.price * 100)
        output_document.currency = "USD"

Renaming and Removing Fields Safely

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 Default-Backfill Helper

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.

def backfill_defaults(doc: dict, defaults: dict) -> dict:
    patch = {}
    for key, value in defaults.items():
        if key not in doc or doc[key] is None:
            patch[key] = value
    return patch


existing = {"name": "Widget", "price_cents": 1999}
defaults = {"is_active": True, "currency": "USD"}
print(backfill_defaults(existing, defaults))
# {'is_active': True, 'currency': 'USD'}

Checkpoint: Choosing a Strategy

Test your understanding of zero-downtime migration order.

Recap

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.

Często zadawane pytania

Czy lekcja „Ewolucja schematu i migracje dokumentów” jest bezpłatna?

Tak — pełny tekst „Ewolucja schematu i migracje dokumentó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 FastAPI Backend Development Bootcamp, przejdź na CoddyKit PRO. Kurs FastAPI Backend Development Bootcamp zawiera 4 lekcji w sumie.

Co nauczysz się w „Ewolucja schematu i migracje dokumentów”?

Wersjonuj schematy dokumentów i migruj istniejące kolekcje bez przestojów wraz z rozwojem modelu danych. Ćwiczysz FastAPI Backend Development Bootcamp 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ąć FastAPI Backend Development Bootcamp?

Nie wymagamy żadnego doświadczenia. FastAPI Backend Development Bootcamp 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 schematu i migracje dokumentó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 FastAPI Backend Development Bootcamp?

Tak. Każda lekcja FastAPI Backend Development Bootcamp 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

  1. Asynchroniczny dostęp do MongoDB za pomocą Motor
  2. Modelowanie dokumentów za pomocą Beanie ODM
  3. Potoki agregacji i złożone zapytania
  4. Ewolucja schematu i migracje dokumentów
← Powrót do FastAPI Backend Development Bootcamp