Just continuing a loose series about recent improvements in the big Marten 7.0 release:

• Revisioned Documents in Marten 7
• Marten 7 makes “Write Model” Projections Super
• Recent Critter Stack Multi-Tenancy Improvements (w/ Wolverine 2.0 too!)
• Resiliency and Low Level Improvements in Marten 7
• LINQ Query Improvements in Marten 7

As part of the big Marten 7 release a couple weeks ago, core team member Babu Annamalai made a huge contribution with a brand new model for making “partial” document updates that’s backed with native PostgreSQL operations. See Babu’s post Marten native partial updates – patching for much more information and details about everything that’s supported now.

Let’s put this into perspective with a quick sample. Here’s a simplistic Wolverine handler that updates a single member on a stored document:

 public static async Task Handle(ApproveInvoice command, IDocumentSession session)
    {
        // Load the invoice
        var invoice = await session.LoadAsync<Invoice>(command.InvoiceId);
        invoice.Approved = true;
        
        // Tell Marten to persist the new version
        session.Store(invoice);
        
        // Commit the one pending change
        await session.SaveChangesAsync();
    }

In the code above, I’m loading the whole document, changing one property, and committing the changes back to the database. Under the covers we’re making two round trips to the database, deserializing the starting state of the Invoice document, then serializing the end state of the Invoice document.

With the new patching support, let’s rewrite that handler to this:

 public static async Task Handle(ApproveInvoice command, IDocumentSession session)
    {
        // Tell Marten what to change
        session.Patch<Invoice>(command.InvoiceId).Set(x => x.Approved, true);

        // Commit the one pending change
        await session.SaveChangesAsync();
    }

In that second version, we’re doing a lot less work. There’s only one database call to overwrite the Approved value within the existing Invoice document. While it’s a nontrivial operation to reach inside the JSON in the database, we’re not having to do any serialization in memory.

Marten technically had this feature set already, but our older support depended on the PLv8 extension to PostgreSQL that’s more or less deprecated now. Babu’s work for Marten 7 brings this very important feature set back into play for the majority of users who don’t want to or can’t utilize the older PLv8 backed support.

Working inside of the LINQ provider code that’s ultimately interpreting C# code and trying to turn that into the most efficient Pgpsql code possible somehow makes me think about Alice in Wonderland where I’m definitely in the role of “Alice.”

Just continuing a loose series about recent improvements in the big Marten 7.0 release:

• Revisioned Documents in Marten 7
• Marten 7 makes “Write Model” Projections Super
• Recent Critter Stack Multi-Tenancy Improvements (w/ Wolverine 2.0 too!)
• Resiliency and Low Level Improvements in Marten 7

A major set of emphasis for the Marten 7 release was to address the large accretion of LINQ related issues with a mostly new LINQ provider subsystem. In terms of improvements or just changes, we:

• Completely removed the Remotion.Linq dependency (and the results of that are mixed so far)
• Reworked the SQL generation for child collection querying
• Greatly expanded the usage of .NET Dictionary types within LINQ queries
• Expanded the reach of Select() transformations quite a bit — and that code hadn’t been touched or improved in any substantial way since Marten 1.0. You can see the list of patterns that Marten now supports in the acceptance test code.
• Allowed for filtering of Include() queries, which has been a longstanding user “ask”

Child Collection Improvements

Alright, so back to the real problem. When Marten today encounters a LINQ query like this one:

var results = theSession.Query<Top>().Where(x =>
    x.Middles.Any(m => m.Color == Colors.Green && m.Bottoms.Any(b => b.Name == "Bill")));

Marten versions 4-6 had to generate a complicated SQL query using PostgreSQL Common Table Expressions to explode out the child collections into flat rows that can then be filtered to matching child rows, then finally uses a sub query filter on the original table to find the right rows. To translate, all that mumbo jumbo I said translates to “a big ass, slow query that doesn’t allow PostgreSQL to utilize its fancy GIN index support for faster JSONB querying.”

The Marten v7 support is smart enough to “know” when it can generate more efficient SQL for certain child collection filtering. In the case above, Marten v7 can use the PostgreSQL containment operator to utilize the GIN indexing support and just be simpler in general with SQL like this:

electd.id, d.data frompublic.mt_doc_top asd whereCAST(d.data ->> 'Middles'asjsonb) @> &1 LIMIT &2  &3: [{"Color":2,"Bottoms":[{"Name":"Bill"}]}]  

Another little micro-optimization we did for Marten V7 was to have as much SQL generation as possible use positional parameters (“&1”) as opposed to named parameters (“:p0”) that PostgreSQL itself expects to skip some SQL preprocessing in memory that we were forcing Npgsql to do for us earlier.

From early adopter feedback, some child collection queries in real systems have been a touch over an order of magnitude faster from V6 to V7 because of this change.

One more sample that I’m especially proud of. Let’s say you use this LINQ query:

var result = await theSession.Query<Root>()    
    .Where(r => r.ChildsLevel1.Count(c1 => c1.Name == "child-1.1") == 1)    
    .ToListAsync();

This one’s a little more complicated because you need to do a test of the number of matching child elements within a child collection. Again, Marten V6 will use a nasty and not terribly efficient common table expression approach to give you the right data. For Marten v7, we specifically asked the Marten user base if we could abandon support for any PostgreSQL versions lower than PostgreSQL 12 so we could use PostgreSQL’s JSONPath query support within our LINQ provider. That change got us to this SQL for the LINQ query from up above:

select d.id, d.data from public.mt_doc_root as d where jsonb_array_length(jsonb_path_query_array(d.data, '$.ChildsLevel1[*] ? (@.Name == $val1)', $1)) = $2
  &1: {"val1":"child-1.1"}
  &2: 1

That’s the child collection querying, which was absolutely a first class goal and time consuming task along the way.

Dictionary Queries

There was a large effort to improve Marten’s ability to query through Dictionary<TKey, TValue> members of a parent document type for V7 — which immediately led to plenty more user reported bugs we had to fix during the V7 pre-release cycle.

Here’a an example that’s now possible querying through Dictionary.ContainsKey():

        var results = await theSession
            .Query<Target>()
            
            // This is querying through a dictionary
            .Where(x => x.GuidDict.ContainsKey(guid))
            .ToListAsync();

And some SelectMany() action:

        var pairs = await theSession
            .Query<Target>()
            .SelectMany(x => x.StringDict.Keys)
            .ToListAsync();

And selecting the dictionary:

        var data = await theSession
            .Query<SelectDict>()
            .Select(x => x.Dict)
            .ToListAsync();

And querying through dictionary values:

        var values = await theSession.Query<Target>().SelectMany(x => x.StringDict.Values)
            .Where(x => x == "value2")
            .OrderBy(x => x)
            .ToListAsync();

Filtered Include

Marten’s Include() functionality is an important way to improve system performance by fetching related documents in one database round trip. Many folks through the years have asked for a way to limit the number of “included” documents returned in these queries by specifying a Where() filter against the included document type. That very functionality landed in Marten V7 with this syntax shown below from our testing code:

        var holders = await theSession.Query<TargetHolder>()
            // Limit the fetched Target documents from the Include()
            // by specifying a filter on Target documents
            .Include<Target>(x => x.TargetId, x => list.Add(x), t => t.Color == Colors.Blue)
            .ToListAsync();

Summary

While there are still some regression bugs coming in from the LINQ provider work (but they’re getting way more “edge case-y” and “WTH *would* you do that?”), I’m feeling good about the LINQ provider subsystem in Marten as a better foundation for us moving forward.

And for the appropriate coding soundtrack for me when I need to duck into the LINQ provider code in Marten to fix bugs:

Just continuing a loose series about recent improvements in the big Marten 7.0 release:

• Revisioned Documents in Marten 7
• Marten 7 makes “Write Model” Projections Super
• Recent Critter Stack Multi-Tenancy Improvements (w/ Wolverine 2.0 too!)
• Resiliency and Low Level Improvements in Marten 7 (this post)

I hate to tell you all this, but sometimes there’s going to be occasional hiccups with your system in production. Just sticking with using Marten and its connectivity to PostgreSQL under the covers, you could easily have:

• Occasional network issues that cause transactions to fail
• A database could be temporarily too busy and throw exceptions
• Concurrency issues from trying to write to the same rows in the underlying database (Marten isn’t particularly prone to this, but I needed another example)

These typical transient errors happen, but that doesn’t mean that the operation that just failed couldn’t happily succeed if you just retried it in a little bit. To that end, Marten 7 replaced our previous homegrown resiliency approach (that didn’t really work anyway) with a reliance on the popular Polly library.

The default settings for Marten are shown below:

// Default Polly setup
var strategy = new ResiliencePipelineBuilder().AddRetry(new()
{
    ShouldHandle = new PredicateBuilder().Handle<NpgsqlException>().Handle<MartenCommandException>().Handle<EventLoaderException>(),
    MaxRetryAttempts = 3,
    Delay = TimeSpan.FromMilliseconds(50),
    BackoffType = DelayBackoffType.Exponential
}).Build();

The Marten docs here will tell you how to customize these policies at your discretion.

To put this into context, if you call IDocumentSession.SaveChangesAsync() to commit a unit of work, and there’s an exception that matches the criteria shown above, Polly will re-execute the queued operations from scratch with a brand new connection so the retry can succeed after the database or network has settled down.

Moreover, we followed the Polly recommendations on performance to utilize “static Lambdas” within the Marten internals to reduced the number of object allocations within Marten 7’s execution pipeline compared to the Marten 6 and earlier pipeline. It’s kind of ugly code, but you can see where and how we used Polly in QuerySession.Execution.cs.

Another big change for Marten 7 was how Marten is going to manage database connection lifecycles inside of Marten sessions. Prior to Marten 7, Marten sessions would open a database connection and keep it open until the session was ultimately disposed. This decision was originally made to optimize the integration between Marten and Dapper when Marten’s functionality was very limited.

Now though, Marten will only open a database connection within a session immediately before any operation that involves a database connection, and close that connection immediately after the operation is over (really just returning the underlying connection to the connection pool managed by Npgsql). With this change, it is now safe to run read-only queries through IQuerySession (or lightweight IDocumentSession) objects in multiple threads. That should make Marten be more effective within Hot Chocolate integrations:

• Marten sessions can actually be thread safe so that you can let the default IoC registration behavior for Marten sessions happily work within Hot Chocolate requests where it wants to parallelize queries
• Marten usage will be far, far less prone to connection leaks when developers create sessions without disposing them properly

And even if you’re not using Hot Chocolate at all, Marten 7 will be more parsimonious over all with how it uses database connections which should help with scalability of your system — and definitely will help with cloud hosting options that charge by the number of database connections used!

Final Thoughts

In the past month or so I’ve had more interaction with developers than usual who are highly suspicious of open source tooling and especially of alternative open source tooling in .NET that isn’t directly supported by Microsoft. It’s a fair point to some degree, because “Google/Bing-bility” is a highly underrated quality of a development tool. Some of that fear was thinking that the responsible developers behind a non mainstream tool are just going to get tired of it and abandon it on a whim when a shinier object comes around so it’s not even worth the time to care about those alternatives from the “cool kids.”

What I would like to point out with Marten in particular is that it’s nearly a decade old as a project (the document db features in Marten actually predate CosmosDb in .NET world) and still very active and growing. The work in this post is all about making fine grained refinements to the core project and I would hope demonstrate a dedication on the part of the whole community toward continuously improving Marten for serious work. In other words, I think development shops can absolutely feel confident in placing a technical bet on Marten.

A new feature in the big Marten 7.0 release this weekend is an alternative to add numeric revisions to a document as a way of enforcing optimistic concurrency checks.

First off, from Martin Fowler’s seminal Patterns of Enterprise Application Architecture (which is just visible to me on my book case across the room as I write this even though it’s 20 years old now), an Optimistic Offline Lock is:

Prevents conflicts between concurrent business transactions by detecting a conflict and rolling back the transaction.

David Rice

In a simple usage, let’s say we’re building some kind of system to make reservations for restaurants. Logically, we’d have a document named Reservation, and we’ve decided that we want to use the numeric revisioning on this document. That document type could look something like this:

// By implementing the IRevisioned
// interface, we're telling Marten to 
// use numeric revisioning with this 
// document type and keep the version number
// on the Version property
public class Reservation: IRevisioned
{
    public Guid Id { get; set; }

    // other properties

    public int Version { get; set; }
}

Now, let’s see this in action just a little bit:

    public static async Task try_revisioning(IDocumentSession session, Reservation reservation)
    {
        // This will create a new document with Version = 1
        session.Insert(reservation);

        // "Store" is an upsert, but if the revisioned document
        // is all new, the Version = 1 after changes are committed
        session.Store(reservation);

        // If Store() is called on an existing document
        // this will just assign the next revision
        session.Store(reservation);

        // *This* operation will enforce the optimistic concurrency
        // The supplied revision number should be the *new* revision number,
        // but will be rejected with a ConcurrencyException when SaveChanges() is
        // called if the version
        // in the database is equal or greater than the supplied revision
        session.UpdateRevision(reservation, 3);

        // This operation will update the document if the supplied revision
        // number is greater than the known database version when
        // SaveChanges() is called, but will do nothing if the known database
        // version is equal to or greater than the supplied revision
        session.TryUpdateRevision(reservation, 3);

        // Any checks happen only here
        await session.SaveChangesAsync();
    }

Summary

In the end, this is another alternative to the older Guid based version tracking that Marten has supported since 1.0. I don’t know about you, but I can certainly read and understand an integer much more easily than a random string of letters, numbers, and dashes.

In reality though, this feature was specifically built as a prerequisite to some serious improvements to the asynchronous projection support in Marten. Time and ambition permitting, the next Marten 7.0 blog post will show how Marten can support the strongly consistent “write model” projections you need for command processing while also being performant and allowing for zero downtime projection rebuilds.