Tyto.Materializer.EntityFrameworkCore 0.0.1-alpha.47

Tyto.Materializer.EntityFrameworkCore

This package provides a robust IViewStore<TView, TKey> implementation using Entity Framework Core. It allows you to persist your read models as structured tables in a relational database (SQL Server, PostgreSQL, SQLite, etc.) while seamlessly integrating with EF Core's change tracking and native optimistic concurrency mechanisms.

🚀 Features

• Relational Persistence: Store your materialized views in SQL databases, enabling complex querying, filtering, and reporting capabilities outside of the event loop.
• Optimistic Concurrency: Leverages EF Core's native concurrency tokens (RowVersion / Timestamp) to prevent data overwrite during concurrent updates.
• Change Tracking: Efficiently updates only modified fields using EF Core's change tracker.
• Automatic Conventions: Includes helper methods to automatically configure Tyto types (like ProjectableVersion) within your DbContext.

📦 Installation

dotnet add package Tyto.Materializer.EntityFrameworkCore

⚡ Usage

Using this provider involves two steps: configuring your DbContext correctly and enabling the provider in your application startup.

1. Configure Your DbContext

Your EF Core DbContext must be configured to map your view entity. This includes defining a Primary Key and a Concurrency Token.

using Microsoft.EntityFrameworkCore;
using Tyto.Materializer;
using Tyto.Materializer.EntityFrameworkCore; // Required for conventions

public class MyAppContext : DbContext
{
    public DbSet<UserBalanceView> UserBalances { get; set; }

    public MyAppContext(DbContextOptions<MyAppContext> options) : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        
        // 1. Apply Tyto conventions
        // This automatically configures value converters for types like ProjectableVersion.
        modelBuilder.ApplyTytoMaterializerConventions();

        var view = modelBuilder.Entity<UserBalanceView>();

        // 2. CRITICAL: Define the primary key.
        // This property MUST match the key defined in .IdentifiedAs(...) configuration.
        // If they don't match, the provider will throw a safety exception at runtime.
        view.HasKey(v => v.UserId);

        // 3. CRITICAL: Configure the 'Version' property as a concurrency token.
        // This tells EF Core to include this column in the WHERE clause during updates
        // (e.g., UPDATE ... WHERE Id = x AND Version = y).
        view.Property(v => v.Version).IsConcurrencyToken();
    }
}

2. Register in Program.cs

Configure Tyto to use the EF Core provider for your specific view.

var builder = WebApplication.CreateBuilder(args);

// Standard EF Core Registration
builder.Services.AddDbContext<MyAppContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

// Tyto Configuration
builder.Services.AddTytoConfiguration(tyto => 
{
    tyto.AddMaterializer(materializer =>
    {
        materializer.ForView<UserBalanceView>()
            .IdentifiedAs<Guid>(c => c.From<UserCreated>(e => e.UserId))
            
            // Configure Storage
            // Parameters: <TDbContext, TView, TKey>
            .Store.UseEntityFrameworkCore<MyAppContext, UserBalanceView, Guid>();
            
            // Note: This replaces any previously configured store for this view.
    });
});

🔧 How It Works Internally

Runtime Validation

When the application starts, the EntityFrameworkCoreViewStore performs a safety check. It inspects your DbContext metadata to ensure:

1. The TView entity is registered in the context.
2. A Primary Key is defined and matches the key type expected by Tyto.
3. The Version property is explicitly configured as a Concurrency Token.

If any of these checks fail, it throws an InvalidOperationException immediately, preventing silent data consistency bugs.

Concurrency Handling

1. Read: Uses DbSet<T>.FindAsync to load the entity.
2. Write:
   • The SaveAsync method attaches the entity and sets the state to Modified.
   • It increments the Version property in memory.
   • It calls SaveChangesAsync.
   • EF Core generates an SQL statement like: UPDATE Views SET Bal = 100, Version = 2 WHERE Id = 1 AND Version = 1.
   • If no rows are affected (meaning the version in DB was not 1), EF Core throws DbUpdateConcurrencyException.
3. Retry: This provider catches that exception and re-throws it as a Tyto...ConcurrencyException, which triggers the core library's automatic retry policy (Reload → Re-project → Save).