Migrating to Pydantic 2.0: Beanie for MongoDB

Episode Deep Dive

Guest Introduction and Background

Roman Right: Roman is the creator and maintainer of Beanie, an async ODM (object document mapper) that works with MongoDB and Pydantic. He originally began this project as a fun experiment to integrate Python’s async features with MongoDB (via Motor) and Pydantic for data validation and modeling. Over time, Beanie grew into a production-worthy tool embraced by many developers. Roman has lived in several countries, including Germany, and has recently moved to the United States.

What to Know If You're New to Python

If you’re just getting started and want to follow this conversation about Pydantic, MongoDB, and async Python, some foundational Python knowledge helps.

Key Points and Takeaways

1) Migrating from Pydantic v1 to v2 in Beanie

Beanie is deeply integrated with Pydantic, so migrating from v1 to v2 was a major overhaul. Roman shared that while Pydantic mostly maintained backward compatibility at the public API level, the underlying internals—especially around validation and forward references—changed considerably, requiring careful updates and testing. Once complete, the result was significant speed improvements and a more modern configuration system.

• Links and Tools
  • Beanie: github.com/roman-right/beanie
  • Pydantic: docs.pydantic.dev

2) Performance Boosts with Rust-based Pydantic Core

One of the biggest wins in Pydantic v2 is its new Rust-based validation engine. Pydantic’s performance gains are especially notable for large or deeply nested documents. Even though Beanie’s main bottleneck tends to be I/O with MongoDB, the new core can yield up to a 2x speedup for complex data structures.

• Links and Tools
  • Pydantic v2 Announcement: blog.pydantic.dev/blog/pydantic-v2
  • Motor (async MongoDB driver): motor.readthedocs.io

3) Deep Internals and Forward References

A big challenge for frameworks that rely on Pydantic is resolving type hints—especially when two classes reference each other. Previously, Pydantic’s Python-based reflection made it easier to peek at references. Now, the Rust-based approach means some details got hidden away. Roman ended up implementing his own forward-reference resolver for Beanie’s advanced features like document linking and inheritance.

• Links and Tools
  • FastAPI’s GitHub (inspiration on how to handle forward refs)

4) Lazy Parsing vs. Full Validation

Beanie once relied heavily on a lazy parsing model to avoid slowing down apps fetching thousands of documents. But now, Pydantic v2’s faster validation often makes lazy parsing less necessary. However, for extreme high-load use cases with massive data sets, lazy parsing can still be beneficial.

• Links and Tools
  • Beanie Docs on Lazy Parsing

5) Document Inheritance in MongoDB

Beanie supports storing multiple classes in one MongoDB collection using class inheritance. For example, a “Vehicle” base class can have “Car” or “Bicycle” subclasses all living in the same collection, each automatically storing an identifier for the subclass type. This design allows flexible queries over the full set or just a specific subtype.

• Links and Tools
  • Beanie Inheritance Example

6) Indexes and Optimizing MongoDB Performance

Even though Pydantic v2 delivers big performance boosts, indexing in MongoDB remains a critical factor. Many times, performance problems have nothing to do with Python or Pydantic overhead but rather suboptimal or missing indexes. Beanie allows specifying indexes, so you can speed up queries significantly.

• Links and Tools
  • MongoDB Indexing Docs

7) Using Locust for Load Testing

To measure real performance improvements before and after the upgrade, the guest mentioned using Locust. Locust helps simulate large numbers of users hitting a web endpoint, letting you see how your app scales under load with both Pydantic v1 and v2.

• Links and Tools
  • Locust

8) Combining Async Python, FastAPI, and Beanie

Many Beanie users run it alongside FastAPI to handle both the inbound/outbound requests and database operations. Since FastAPI is also built on Pydantic, upgrading both FastAPI and Beanie to the new version of Pydantic can lead to a “double acceleration” effect: faster request validation and faster document parsing.

• Links and Tools
  • FastAPI

Interesting Quotes and Stories

• Roman on Beanie’s origins: “I just wanted to play with async and Pydantic. Suddenly, people started filing issues, asking for features, and I realized I’d made an open-source project.”
• On Pydantic v2’s speed: “It’s not often you get such a major speedup in your app by just upgrading a library—sometimes two times faster.”
• On the move to Rust under the hood: “I wondered how they’d do all that Python logic in Rust, but it’s super impressive to see.”

Key Definitions and Terms

• ODM (Object Document Mapper): Like an ORM, but for document databases such as MongoDB. It maps Python objects to documents and collections.
• Forward Reference: A type hint referring to a class that isn’t yet defined in the code at parse time, often used when classes reference each other.
• Aggregation Framework (MongoDB): A pipeline-based approach to transform and analyze data in MongoDB rather than retrieving all documents to Python first.
• Async / await: Python syntax for concurrent code execution, especially useful when you wait on I/O or external APIs, such as database calls.

Learning Resources

Here are some deeper resources to expand on what you learned in this episode:

• MongoDB with Async Python: For hands-on practice with Beanie, Pydantic, FastAPI, and async.
• Full Web Apps with FastAPI: Build powerful HTML-based apps using FastAPI and its Pydantic underpinnings.

Overall Takeaway

Migrating from Pydantic v1 to v2 can be challenging for projects deeply tied to its internals, as Roman discovered with Beanie. However, once updated, teams benefit from a major performance boost, cleaner interfaces, and more robust validation. This episode highlights that even in Python’s dynamic ecosystem, carefully designed upgrades and open-source collaboration make next-level improvements possible without rewriting your entire stack.