Polecat on SQL Server 2025: Production Spike Migration

For .NET teams utilizing Microsoft SQL Server, Polecat on SQL Server 2025 represents a significant advancement over document databases and Wolverine messaging. Migrating a production spike revealed critical insights into handling enterprise environments where SQL Server is a requirement. While PostgreSQL's Marten remains the gold standard for .NET document databases and event sourcing, SQL Server 2025 now enables high-performance document store capabilities with Polecat.

This migration highlighted distinct architectural refinements and runtime constraints between the two engines.

Key findings included:

1. Strict Asynchrony and DI Scope Trap: Polecat does not support synchronous LINQ enumeration; ToListAsync() must be used instead. Implementing IQuerySession with IAsyncDisposable is mandatory, as synchronous Scope creation fails on Dispose.

2. Narrower LINQ Expression Parser: Polecat's WhereClauseParser is stricter, requiring predicates to directly compare a concrete document member against a constant or value. Generic filter extensions using interface-constrained filters will throw BadLinqExpressionException. Refactoring these predicates to compare concrete document members will resolve this issue.

3. Batch Querying and IBatchedQueryable: Both libraries support session.CreateBatchQuery() for combining queries into a single database roundtrip. However, Polecat's IBatchedQueryable does not inherit from IQueryable and must be used with standalone async queries for paged or projected queries requiring OrderBy, Skip, Take, or Select.

4. API Surface and Architecture Differences: Polecat has modularized its namespace design, separating Async LINQ operators and batching types into distinct namespaces. Method signatures have been updated to include CancellationToken where applicable.