EF Core vs Marten and Polecat: Choosing a .NET Persistence Model
EF Core vs Marten and Polecat is a choice between a traditional ORM, a document database built on Postgres, and a newer PostgreSQL plugin that aims to replace both. This article explains the key differences between these three .NET persistence models so you can decide which fits your project’s data shape, transaction needs, and team experience.
What Each Option Actually Is
EF Core (Entity Framework Core) is Microsoft’s object-relational mapper. It maps your C# classes to relational tables with SQL Server, PostgreSQL, SQLite, and others. You define DbContext and entity classes, and EF Core generates SQL for queries, inserts, updates, and deletes. It supports migrations, LINQ queries, and change tracking.
Marten is a .NET library that turns PostgreSQL into a document database. You store your .NET objects as JSON documents in a table, and Marten provides LINQ queries, unit-of-work, event sourcing, and projections. It uses PostgreSQL’s JSONB type and GIN indexes for querying.
Polecat is a newer PostgreSQL plugin for .NET that provides a document-oriented API with a schema-free approach. It stores data as JSONB and offers a query API, but it is less mature and has a smaller community than the other two.
How the Data Model Differs
The biggest difference is how you shape your data. EF Core works best with normalized relational data: separate tables for customers, orders, and order lines, with foreign keys and joins. You design a schema, create migrations, and write queries that span multiple tables.
Marten and Polecat work with aggregates. You store a whole aggregate (for example, an order with its line items) as one JSON document. There are no joins; you load the entire document, modify it, and save it back. This fits Domain-Driven Design and microservices where each service owns its data.
If your data is highly relational with many many-to-many relationships and ad-hoc reporting, EF Core is the natural fit. If your data is hierarchical or you frequently change the shape of your entities, a document model like Marten or Polecat avoids migration pain.
Query Capabilities and Performance
EF Core translates LINQ queries to SQL. You can do complex joins, grouping, aggregations, and raw SQL when needed. The query pipeline is mature and well-optimized, but complex queries can generate verbose SQL, and you must be careful about N+1 problems and eager loading.
Marten also provides LINQ queries, but they operate on JSONB documents. It supports many common operations: equality, range, contains, and even full-text search. However, queries that would be simple joins in SQL require either denormalized data or projections. For example, to show a list of orders with customer names, you either store the customer name in the order document or maintain a separate read model.
Polecat’s query API is more limited. It supports basic filtering and projection, but complex queries and joins are not available. Performance-wise, JSONB with GIN indexes is fast for document lookups, but relational queries with proper indexes often outperform JSONB for heavy analytical workloads.
Transactions and Consistency
EF Core gives you full ACID transactions across multiple tables. You can update a customer and their orders in one transaction, and if anything fails, everything rolls back. This is critical for financial systems, inventory, and any domain where partial updates are unacceptable.
Marten also supports PostgreSQL transactions, but because you store aggregates as single documents, you rarely need multi-table transactions. The unit of work saves the entire aggregate atomically. However, if you need to update two different aggregates in one transaction, Marten supports that too, as long as both are saved in the same session.
Polecat follows the same single-document transaction model. It does not offer the same level of cross-document transactional guarantees as EF Core, and its transaction support is less documented. If you need strong consistency across multiple entities, EF Core is the safer choice.
Migrations and Schema Evolution
EF Core has a robust migration system. You create a migration from your model changes, and it generates SQL to alter tables, add columns, and create indexes. This is essential for relational schemas that evolve over time.
Marten does not use migrations for your document structure. You change your C# class, and the new shape is saved as JSONB. Old documents that lack new fields will have null values, which can cause issues if you don’t handle missing properties. Marten provides patch mechanisms and schema validation to help, but you own the data migration logic.
Polecat is similar: schema-free, no migrations. This is a double-edged sword. It makes development fast, but production data may contain multiple shapes, and you need to write code to handle versioning. If your team is disciplined about backward compatibility, document databases work well. If not, you will face runtime errors from missing fields.
Event Sourcing and Advanced Features
Marten has a distinctive advantage: built-in event sourcing. You can append events to a stream, and Marten stores them as an append-only log. You can then project those events into read models. This is a powerful pattern for audit trails, temporal queries, and systems that need to rebuild state. EF Core does not have built-in event sourcing; you would implement it yourself with tables and triggers.
Polecat does not offer event sourcing. It focuses on simple document storage and retrieval. If event sourcing is a requirement, Marten is the clear winner among the three.
Marten also supports optimistic concurrency with versioned documents, and it integrates with PostgreSQL’s full-text search. EF Core has none of these out of the box, though you can add them with extra libraries.
Team Experience and Ecosystem
EF Core is the default choice for most .NET developers. It has extensive documentation, thousands of Stack Overflow answers, and a huge ecosystem of extensions. Most developers have used it, and hiring is easier.
Marten has a smaller but dedicated community. Its documentation is good, and it is used in production by many companies. The learning curve is moderate: you need to understand document modeling and the differences from relational thinking.
Polecat is very new. It has minimal documentation, few community resources, and an API that may change. It is not recommended for production projects unless you are willing to contribute to the project and handle breaking changes.
How to Choose
Start with EF Core unless you have a specific reason not to. It is the safest, most versatile choice for relational data, transactions, and reporting. Choose Marten if you want document storage with event sourcing, or if your domain naturally fits aggregates and you want to avoid join-heavy queries. Avoid Polecat for now unless you are evaluating it for a proof of concept and understand its early-stage nature.
Consider a hybrid approach: use EF Core for relational parts of your system (billing, reports) and Marten for document-oriented parts (carts, profiles). Both can share the same PostgreSQL database. This gives you the strengths of each without committing to one model everywhere.
Frequently Asked Questions
Can I use EF Core and Marten together in the same project?
Yes. They can coexist in one application and even share the same PostgreSQL database. Use EF Core for relational tables and Marten for documents. Just be careful about transactions: a transaction spanning both would require careful coordination, so keep them separate where possible.
Is Marten slower than EF Core?
Not necessarily. For single-aggregate operations, Marten is often faster because it reads and writes one JSON document instead of joining multiple tables. For complex analytical queries across many records, EF Core with proper indexes is usually faster. Test with your actual workload.
Does Polecat support SQL queries?
Polecat is a document API over PostgreSQL, so you can always drop down to raw SQL through Npgsql if needed. But its built-in query API does not support joins or complex SQL. You would write custom SQL for those cases.
Which one is best for microservices?
Marten is often recommended for microservices because it encourages aggregate-based design and provides event sourcing out of the box. EF Core works too, but you must be disciplined about bounded contexts and avoid cross-service joins. Polecat is too immature for most microservice production use.
Do I need to write migrations with Marten?
No, not for your document structure. Marten stores JSONB, so adding a property to a class does not require a schema change. However, you may need to update indexes or add patches for existing data. You are responsible for handling old documents that lack new fields.
Is Polecat production-ready?
As of now, Polecat is an early-stage project. It lacks the documentation, testing, and community support needed for most production systems. If you need a document database in .NET today, Marten is a safer choice.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.