DEV Community: ONDŘEJ PODHORNÝ

SQL Server in Docker & .NET Aspire: Zero-Pollution Local Dev Experience

ONDŘEJ PODHORNÝ — Tue, 03 Nov 2026 11:57:01 +0000

Surprisingly many .NET developers still don't know SQL Server runs natively in Docker containers. Microsoft has officially supported SQL Server in optimized Linux containers for years — and paired with .NET Aspire, it eliminates host OS pollution and revolutionizes local developer experience.

For over a decade, the standard onboarding routine for a .NET developer working with SQL Server was downloading a multi-gigabyte installer, setting up a local SQL Server Express or Developer instance, and leaving behind dangling Windows services, registry keys, and shared DLL bloat.

Running SQL Server in Docker completely flips this model: instant local provisioning, zero machine pollution, and identical behavior on developer laptops and CI/CD runners.

Decision & Evaluation Matrix

Workload & Environment	Status	Practical Rationale & Architecture Impact
Local Dev & Onboarding	✅ Optimal	Zero installation friction. New devs run `docker run` or launch .NET Aspire and are coding in 60 seconds with no host pollution.
Automated CI/CD Pipelines	✅ Optimal	Spin up disposable database instances for each test job. Completely isolated state, 100% test reproducibility.
Ephemeral Feature Branches	✅ Optimal	Preview environments in Kubernetes or local Docker can spin up dedicated databases per pull request and tear them down on merge.
Heavy Production Workloads	⚠️ Evaluation	Fully supported on Linux/Kubernetes, but requires proper volume mount tuning (I/O latency) and standard commercial core licensing.

1. Quick Start: One-line Local Setup

A complete, fully functional SQL Server 2025 instance can be spun up on your machine in seconds without touching your host OS:

docker run \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=${SA_PASSWORD:-YourStrong@Password123}" \
  -p 1433:1433 \
  --name sqlserver \
  -d mcr.microsoft.com/mssql/server:2025-latest

Starts in Seconds: Microsoft's official Linux image ([mcr.microsoft.com/mssql/server:2025-latest](https://mcr.microsoft.com/mssql/server:2025-latest)) boots fast and contains the full database engine.
Port 1433: Standard connection port, accessible via SQL Server Management Studio (SSMS), Azure Data Studio, JetBrains Rider, or the VS Code MSSQL extension.
Dynamic SA Password: Reads ${SA_PASSWORD} if defined in your shell environment, with a safe fallback for local development.
Zero Host Contamination: Clean teardown; running docker rm -f sqlserver removes every trace of the database without residual registry keys or background services.

2. First-Class .NET Aspire Integration

While raw Docker commands or Docker Compose files work, .NET Aspire elevates containerized SQL Server into an orchestrated, zero-config development workflow.

In your Aspire AppHost project, you declare SQL Server as a managed resource:

var sqlserver = builder.AddSqlServer("sqlserver")
    .WithImageTag("2025-latest")
    .WithDataVolume("sqlserver-data")
    .WithLifetime(ContainerLifetime.Persistent);

var db = sqlserver.AddDatabase("appdb");

// Microservice gets connection string injected automatically
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(db);

Why Aspire Beats Raw Docker Compose

Auto-injected Secrets & Connections: No manual password management or connection strings in appsettings.Development.json. Aspire injects the connection string into dependent projects via environment variables.
Persistent Data Volume: With WithDataVolume("sqlserver-data") and WithLifetime(ContainerLifetime.Persistent), container restarts do not wipe your database tables or seed data.
Built-in Dashboard: Live resource logs, container health status, and OpenTelemetry metrics directly in the Aspire developer portal.
The True F5 Workflow: Hitting Run / Debug in your IDE automatically provisions the container, validates connection readiness, and boots your microservices in order.

3. The Trade-offs: Clear Upsides vs. Practical Catches

Containerizing SQL Server provides immense velocity, but engineering teams must understand the practical trade-offs:

The Clear Upsides

Instant Provisioning: Spin up fresh DBs in seconds for dev or CI integration tests.
Zero Host Contamination: Clean teardown; no registry keys, dangling Windows background services, or DLL bloat.
Reproducible CI/CD: Identical database engine behavior on developer laptops, Linux workstations, and GitHub Actions runners.

The Practical Catches

OS Architecture & I/O Overhead: When running Docker on Windows (WSL2) or macOS (Docker Desktop / Colima), SQL Server executes within a lightweight Linux VM. While memory and CPU execution are virtually native, I/O across host-mounted file systems can incur translation overhead. Always use Docker named volumes (e.g. sqlserver-data) rather than host directory bind mounts (-v /c/mydata:/var/opt/mssql/data) for optimal disk performance.
Licensing Realities: The official image defaults to Developer Edition, which is 100% free for development, testing, and staging (with full Enterprise Edition feature parity). But deploying that container to production or running live business workloads requires standard Microsoft core licenses (MSSQL_PID=Enterprise or MSSQL_PID=Standard).
Tooling Differences: Linux containers need Linux CLI commands (sqlcmd, systemd coredumps) for OS-level diagnostics rather than traditional Windows PerfMon or Windows Event Viewer.

Verdict

Running SQL Server in Docker with .NET Aspire is a total game-changer for developer experience, local isolation, and CI/CD pipelines. Installing gigabytes of SQL Server directly onto developer workstations should be considered obsolete.

Polecat on SQL Server 2025: Production Spike Migration

ONDŘEJ PODHORNÝ — Tue, 03 Nov 2026 11:52:48 +0000

For .NET teams tied to Microsoft SQL Server who want the developer velocity of document databases and Wolverine messaging, Polecat on SQL Server 2025 is a massive leap forward. Here is what we learned from migrating a production spike.

If your team is committed to PostgreSQL, Marten remains the gold standard of .NET document databases and event sourcing. But what about enterprise environments where SQL Server is mandatory? Until SQL Server 2025 introduced native binary JSON (JSON_TYPE, JSON indexes), running a high-performance document store on SQL Server felt like an uphill battle.

Polecat brings the Critter Stack document model directly to SQL Server 2025. In our production spike migration, it delivered where it counts. But moving between the two engines reveals distinct architectural refinements.

Spike Migration Matrix

Subsystem	Status	Spike Finding & Architecture Impact
SQL Server 2025 Aspire Host	✅ OK	Smooth local orchestration out of the box via .NET Aspire container images
WolverineFx.Polecat Outbox	✅ OK	Transactional outbox pattern and message dispatch swapped with zero friction
LINQ Query Suite	⚠️ Refactor	Predicates require concrete members; interface-constrained filters throw `BadLinqExpressionException`
DI Scopes (FastEndpoints)	⚠️ Refactor	Sessions implement only `IAsyncDisposable`; synchronous `CreateScope()` fails on `Dispose`
Batch Queries (`IBatchedQueryable`)	⚠️ Refactor	Does not inherit from `IQueryable`; `Skip`, `Take`, and `OrderBy` must run as standalone queries

While the matrix above highlights high-level audit results, the real insights emerged in the implementation details. Moving our production spike across database boundaries forced us to confront strict runtime constraints, query compilation subtleties, and architectural refinements between the two engines.

Here is the deep-dive into each technical finding and how we resolved it.

1. Strict Asynchrony & DI Synchronous Scope Trap

One of the most critical runtime differences between Marten and Polecat lies in lifecycle disposal and asynchrony.

Marten: Supported synchronous execution (.ToList()) and hybrid disposable sessions implementing both IDisposable and IAsyncDisposable.
Polecat: System.NotSupportedException — Polecat strictly does not support synchronous LINQ enumeration. You must use ToListAsync(...). Furthermore, IQuerySession and IDocumentSession implement only `IAsyncDisposable`.

// ❌ The Real-World Trap (FastEndpoints & ASP.NET DI):
// Synchronous scope creation fails on Dispose:
using var scope = app.Services.CreateScope();
var session = scope.ServiceProvider.GetRequiredService<IQuerySession>();
// Throws on scope exit:
// System.InvalidOperationException: 'QuerySession' type only implements IAsyncDisposable.

// ✓ Workaround / Fix:
// In hosted services and startup paths, transition to CreateAsyncScope:
await using var asyncScope = app.Services.CreateAsyncScope();
var asyncSession = asyncScope.ServiceProvider.GetRequiredService<IQuerySession>();

💡 Legacy disposal note: If you have legacy infrastructure or libraries calling synchronous Dispose(), wrap the session in a DispatchProxy forwarding Dispose() to DisposeAsync().GetAwaiter().GetResult().

2. Narrower LINQ Expression Parser (`BadLinqExpressionException`)

Marten’s LINQ provider has enjoyed over 10 years of edge-case normalization. Polecat’s WhereClauseParser is leaner and stricter: it requires predicates to directly compare a concrete document member against a constant or value.

// ❌ Generic filter extensions constrained by an interface:
public static IQueryable<T> ApplyScopeFilters<T>(this IQueryable<T> query, string tenant)
    where T : IScopeFilterable
{
    return query.Where(x => x.TenantId == tenant);
}
// Throws in Polecat:
// Polecat.Linq.BadLinqExpressionException: neither side resolves to a document member compared against a constant.

// ✓ Fix: Constrain to concrete base class or concrete overloads
public static IQueryable<T> ApplyScopeFilters<T>(this IQueryable<T> query, string tenant)
    where T : DocumentBase
{
    return query.Where(x => x.TenantId == tenant);
}

3. Batch Querying & `IBatchedQueryable<T>`

Both libraries provide session.CreateBatchQuery(), combining multiple independent queries into a single database roundtrip.

Marten (Mature): IBatchedQueryable<T> inherits from `IQueryable (Where, OrderBy, Skip, Take, Select, Stats`).
Polecat (Native-AOT Lean): IBatchedQueryable<T> does NOT inherit from `IQueryable`. It exposes a lean interface tailored strictly for batch retrieval:

public interface IBatchedQueryable<T>
{
    IBatchedQueryable<T> Where(Expression<Func<T, bool>> filter);
    Task<IReadOnlyList<T>> ToList();
    Task<int> Count();
    Task<bool> Any();
    Task<T?> FirstOrDefault();
}

Impact on Migration

Extension methods written on IQueryable<T> will not compile on batch.Query<T>(). Paged or projected queries requiring OrderBy, Skip, Take, or Select must run as standalone async queries outside the batch.

4. API Surface & Architecture Differences

Polecat modernizes several legacy patterns accumulated by Marten:

Namespace Separation

Marten: Extension methods like .ToListAsync() or CreateBatchQuery() lived in the monolithic root namespace.
Polecat: Modular namespace design:
Async LINQ operators live in using Polecat.Linq; (ToListAsync, FirstOrDefaultAsync).
Batching types live in using Polecat.Batching;.
Enum serialization and DDL types live in using Weasel.Core;.

Method Signatures & `CancellationToken`

Marten: Legacy convention where CancellationToken was frequently the first argument:

session.LoadManyAsync<T>(ct, id1, id2);

Polecat: Modern BCL style placing cancellation tokens at the end with default values:

session.LoadManyAsync<T>(ids, ct);

`System.Text.Json` Configuration

Marten: Configured via:

opts.UseSystemTextJsonForSerialization(EnumStorage.AsString, Casing.CamelCase, configure: ...);

Polecat: Configured via:

opts.ConfigureSerialization(EnumStorage.AsString, casing: Casing.CamelCase, configure: ...);

Startup Seeding (`IInitialData`)

Marten: marten.InitializeWith<MartenInitialData>() (Marten.Schema.IInitialData).
Polecat: opts.InitialData.Add(new PolecatInitialData()) (Polecat.IInitialData).
Detail in Polecat: AddPolecat unconditionally registers PolecatActivator (IHostedService), running InitialData seeders reliably on startup even without calling ApplyAllDatabaseChangesOnStartup().

5. What Was Our Own Code & Migration Debt?

The migration spike acted as an invaluable mirror, surfacing hidden technical debt that Marten's permissive nature had masked:

Transition to CreateAsyncScope(): Hosted background services and startup bootstrapping paths were updated from synchronous CreateScope() to provider.CreateAsyncScope() to properly dispose asynchronous database sessions.
Uncovered Hidden Synchronous LINQ Execution: Because Polecat throws System.NotSupportedException on sync enumeration, the spike immediately flagged legacy queries accidentally calling .ToList() instead of .ToListAsync().
Closure Null-Checks Inside Where Predicates: Polecat translates (key == null) into a SQL column comparison rather than evaluating it locally in C#:

// ❌ Fails: Polecat tries translating (key == null) into a SQL column comparison
var run = await session.Query<T>()
    .FirstOrDefaultAsync(p => p.OrganizationId == orgId && (key == null || p.Key == key), ct);

// ✓ Fix: Branch in C# before dispatching the query
var query = session.Query<T>().Where(p => p.OrganizationId == orgId);
if (!string.IsNullOrEmpty(key))
{
    query = query.Where(p => p.Key == key);
}
var run = await query.FirstOrDefaultAsync(ct);

Spike Verdict: Polecat is Production-Ready

Polecat is a real step forward for .NET teams tied to SQL Server 2025: native binary JSON, JSON indexes, and the Critter Stack (documents, Wolverine, schema generation) on an engine many enterprises already run.

In our production migration it delivered where it counts — indexing, async LINQ, and a straightforward Wolverine swap. If PostgreSQL is off the table, Polecat is the first credible document story on SQL Server without feeling like a hack.

EF Core vs Marten and Polecat

ONDŘEJ PODHORNÝ — Tue, 29 Sep 2026 22:07:05 +0000

EF Core is the .NET default long after the thing you are saving has stopped being a set of rows. An order with its lines, discounts, and address is one decision. The template still models it as a join.

I reach for EF Core when the model is rows: a line that is queried without its parent, a report that joins five tables, a schema another service already reads with SQL. I reach for a document when that order is loaded and saved as one unit. The second choice does not require a second database. Marten stores the document as JSONB in the PostgreSQL you already run. Polecat is that document model on SQL Server. EF Core stays for the tables that are actually relational.

The aggregate became a join

The symptoms show up before anyone argues about databases. Loading one order walks every relationship the screen might need. Include chains grow. AsSplitQuery appears because one query returned a cartesian product. The Fluent API in OnModelCreating holds the mapping the class no longer shows.

LoadOrderEfCore.cs

var order = await db.Orders
    .Include(o => o.Items)
        .ThenInclude(i => i.Discounts)
    .Include(o => o.ShippingAddress)
    .Include(o => o.StatusHistory)
    .AsSplitQuery()
    .SingleAsync(o => o.Id == orderId);

That query is honest about a relational model. It is a tax on a document. Early in a product, every new field on the aggregate wants a migration, and the migration is arguing with a schema the business has not settled. The mapping layer is there so the ORM can split a thing the domain keeps together.

ToJson puts an owned graph into a JSON column on that same row. The order is still a table, the mapping still lives in the model, and the change tracker still decides the save. The column got easier. The aggregate is still something the ORM assembled.

Why the default stays

Three habits, and they reinforce each other.

Official templates and most conference talks start from EF Core. It is familiar, it is staffable, and the ecosystem assumes it. Choosing it needs no meeting. Choosing anything else does.

Most of us were trained to normalize first. Third normal form is the right reflex for an invoice line that accounting will sum without the order, and for a ledger. Applied to an aggregate, it produces the Include chain above and calls that design.

The alternative people picture is another cluster. MongoDB or DynamoDB, a second backup story, a second failure domain, and a dual write between the document and the relational system that still has to exist. That trade is real when the document cluster is the product. It is the wrong trade when the only goal was to stop joining an order to itself.

One roundtrip, same engine

The document session loads the order by id, the domain decides, and one commit writes the document back. Marten does this on PostgreSQL. Polecat does this on SQL Server. The table is mt_doc_order. The body is JSONB, or JSON on SQL Server. There is no line-item table unless you create one.

LoadOrderDocument.cs

var order = await session.LoadAsync<Order>(orderId);

order.ApplyDiscount(coupon);

session.Store(order);
await session.SaveChangesAsync();

Store is the upsert. The rules for Insert, Update, indexes, and a lost update are the document guide. A stream of facts, when you need the history and not only the current order, is Marten Event Sourcing in Production.

	EF Core	Marten / Polecat
Model	Tables and JOINs	JSON document
Database	Your Postgres or SQL Server	Your Postgres or SQL Server
ACID across models	Yes. Relational only.	Yes. One transaction.
Aggregates	Includes and mapping	Natural and typed
Schema friction	Schema changes need a migration.	Low

"Low" is the document, not the database. A new property inside the JSON is not a new column. A computed index is cheap to add. A duplicated column, which a DateTime filter needs, is still a migration, and production applies it before the new code serves traffic. The friction that goes away is the migration for every field of an aggregate that is still changing shape.

Both columns say the same database because that is the point. You do not stand up MongoDB to get a document. Backups, restore drills, and the people who already run PostgreSQL or SQL Server stay the operational home. A dedicated document cluster still fits when the access pattern is an aggregation pipeline, sharding, and operators who already run it. Moving that workload onto Marten so the architecture diagram says Postgres trades a database the team knows for a JSONB schema that will not behave like that pipeline.

Both models, one instance

I do not throw EF Core away to adopt the document. One PostgreSQL or SQL Server instance holds both.

On one side, Marten or Polecat: the aggregates that are loaded and saved whole, one roundtrip by id, mt_doc_order. On the other, EF Core or Dapper: invoices, the general ledger, the report that joins tables, the legacy schema that already has a reader. A screen that wants five joins is telling you the data is relational. A command that loads one order to decide is telling you the data is a document.

The table's "one transaction" means those two writes can share the database transaction you already have. It does not mean a distributed transaction between PostgreSQL and a second cluster, and it does not mean every command should touch both models. On PostgreSQL, a Marten session and an EF Core context can enlist in the same transaction when one request truly writes both. That request is rarer than a diagram suggests. If every command needs both, the boundary is wrong. The enlistment is also specific to that engine. I am not going to pretend a PostgreSQL transaction sample is the Polecat and SQL Server wiring.

Polyglot, on this reading, is another model in the same engine. Strictly relational access stays on EF Core or Dapper. Time-series telemetry on PostgreSQL can be TimescaleDB beside Marten, still one cluster to back up. A second engine is a decision about operations, not a requirement of the document.

MediatR vs. Wolverine: Architecture, Ergonomics, and Feature Matrix

ONDŘEJ PODHORNÝ — Fri, 25 Sep 2026 13:49:10 +0000

MediatR taught .NET teams to keep HTTP away from business logic. Wolverine asks whether that boundary still needs a marker interface.

For years, MediatR has served as the default standard for implementing CQRS and in-process decoupling in .NET applications. It introduced clean boundary separation between HTTP controllers and business logic, providing an accessible, predictable structure for monolithic codebases.

As distributed requirements, event-driven architectures, and performance constraints have matured, the limitations of simple in-memory mediator patterns have become clearer. Wolverine, part of the Critter Stack ecosystem, approaches this challenge from a fundamentally different perspective: replacing interface ceremony with code generation and integrating messaging capabilities directly into the framework core.

This article breaks down the architectural, ergonomic, and operational differences between MediatR and Wolverine to evaluate when each tool makes sense.

Ergonomics: interface ceremony vs. pure POCOs

The structural difference is evident in handler and message definitions. MediatR enforces strict generic interfaces, whereas Wolverine relies on conventions and dynamic code generation to eliminate boilerplate.

MediatR: marker interfaces and rigid signatures

In MediatR, every command, query, and handler must implement specific interfaces:

// 1. Command requires marker interface
public record CreateOrder(string CustomerId, decimal Amount)
    : IRequest<OrderResult>;

// 2. Handler ceremony and constructor injection boilerplate
public class CreateOrderHandler : IRequestHandler<CreateOrder, OrderResult>
{
    private readonly ILogger<CreateOrderHandler> _logger;

    public CreateOrderHandler(ILogger<CreateOrderHandler> logger)
    {
        _logger = logger;
    }

    public Task<OrderResult> Handle(CreateOrder request, CancellationToken ct)
    {
        _logger.LogInformation("Processing order for {CustomerId}...", request.CustomerId);
        return Task.FromResult(new OrderResult(Guid.NewGuid()));
    }
}

This pattern introduces several architectural constraints:

Interface coupling. Commands and handlers are coupled to IRequest<T> and IRequestHandler<TRequest, TResponse>.
Constructor clutter. Dependencies require explicit constructor injection and private field assignments.
Forced asynchrony. Handlers must return Task<T> and accept a CancellationToken, even when handling pure in-memory, synchronous computations. This forces artificial state machines and allocations via Task.FromResult.

Wolverine: convention over ceremony

Wolverine strips away external interface constraints entirely:

  // 1. Clean, zero-interface C# POCO
  public record CreateOrder(string CustomerId, decimal Amount);

  // 2. Static class and direct method injection (no constructor DI)
  public static class CreateOrderHandler
  {
      public static OrderResult Handle(CreateOrder cmd, ILogger logger)
      {
          logger.LogInformation("Processing order for {CustomerId}...", cmd.CustomerId);
          return new OrderResult(Guid.NewGuid());
      }
  }

Key ergonomic differences:

Zero-interface messaging. Messages remain pure POCOs without framework references.
Method-level dependency injection. Handlers can be declared as static classes, with dependencies passed directly into the Handle method parameters alongside the command.
Flexible signatures. If an operation is synchronous, return the raw type directly. If a CancellationToken is needed, declare it; if not, omit it.

Comprehensive feature matrix

While MediatR focuses solely on in-process dispatching, Wolverine acts as both an in-memory mediator and an integration bus.

Feature	MediatR	Wolverine
Scope & Complexity	Minimal in-process mediator	Full messaging & integration bus
Team Onboarding & Ecosystem	🟢 De-facto industry standard	🟡 Emerging, convention-heavy
Coding Style	`IRequest`, Handlers	Zero-interface (POCO)
HTTP Endpoint Integration	❌ Minimal API / MVC only	✅ Wolverine.Http (zero MVC)
Cascading Messages	❌ Explicit dispatch calls	✅ Native return types
Transactional Outbox/Inbox	❌ External libraries	✅ EF Core, PG, SQL, Marten
Async Message Brokers	❌ In-process only	✅ RabbitMQ, Kafka, ASB, SQS
Retry & Dead Letter Queue	❌ Complex in behaviors	✅ Per-exception & circuit breakers
Stateful Sagas & Workflows	❌ Not supported	✅ First-class stateful sagas
OpenTelemetry & Tracing	❌ Custom pipeline	✅ Built-in natively
Native AOT / Cold Starts	🟢 Zero-overhead out-of-the-box	🟡 Requires code pre-generation
In-Memory Dispatch	⚡ Direct delegate invoke	Full message envelope context

Architectural scope: beyond in-process dispatch

MediatR stops at the process boundary. When requirements involve asynchronous background processing, external message queues, or reliable transaction boundaries, developers must build or integrate secondary frameworks (such as MassTransit or custom outbox implementations).

Wolverine bridges this gap by unifying local invocation and external messaging into a single abstraction model:

Cascading messages via return types. Handlers can return tuples, for example (OrderResult Result, OrderPlaced Event). Wolverine automatically sends the event downstream to message queues or outbox storage while returning the result to the direct caller, avoiding manual dispatcher calls.
Native transactional outbox. Ensures consistency between database writes and message broker dispatching natively, without third-party plugins.
Resilience and error handling. Wolverine provides declarative retry policies, fallback logic, and dead-letter queues configured per message or exception type.

Operational trade-offs

Choosing between these frameworks requires weighing specific architectural compromises:

Conventions vs. explicit types. MediatR’s explicit interface hierarchies make code navigation straightforward via standard IDE tools. Wolverine’s convention-based discovery requires developers to understand its method naming and parameter binding rules.
Startup performance and AOT. MediatR relies on standard DI service registration. Wolverine uses Lamar and runtime Roslyn compilation by default to maximize throughput. For environments requiring minimal cold-start latencies or Native AOT, teams must incorporate ahead-of-time code pre-generation into their build pipelines.
Adoption and maintenance. MediatR has an established track record and extensive documentation across the enterprise ecosystem. Wolverine offers modern ergonomics and broader built-in capabilities, but onboarding requires familiarity with convention-driven patterns.

Which should you choose?

Choose MediatR if your application is a modular monolith requiring strict in-memory command dispatching, explicit interface-driven navigation, and zero additional infrastructure dependencies.

Choose Wolverine if your application needs an integrated messaging pipeline with transactional outbox support, message broker integration, minimal ceremony, and declarative resilience built directly into the runtime.

These architectural trade-offs, combined with Marten as a document database on PostgreSQL, were the primary reason I decided to rebuild the backend of Codebase Pulse on top of the Critter Stack.