Marten

Migration Guide

Key Changes in 4.0.0

V4 was a very large release for Marten, and basically every subsystem was touched at some point. When you are upgrading from V2/3 to V4 -- and even earlier alphas or RC releases of 4.0 -- you will need to run a database migration as part of your migration to V4.

Other key, breaking changes:

  • All schema management methods, including assertions on the schema, are now asynchronous. We had to do this for Npgsql connection multiplexing.
  • The compiled query syntax changed
  • The event store support has quite a few additions
  • Projections in Marten have moved to an all new programming model. Some of it is at least similar, but read the documentation on projection types before moving a Marten application over
  • The async daemon was completely rewritten, and is now about to run in application clusters and handle multi-tenancy
  • A few diagnostic methods moved within the API
  • Document types need to be public now, and Marten will alert you if document types are not public
  • The dynamic code in Marten moved to a runtime code generation model. If this is causing you any issues with cold start times or memory usage due to Roslyn misbehaving (this is not consistent), there is the new "generate ahead model" as a workaround.
  • If an application bootstraps Marten through the IServiceCollection.AddMarten() extension methods, the default logging in Marten is through the standard ILogger of the application

Key Changes in 3.0.0

Main goal of this release was to accommodate the Npgsql 4.* dependency.

Besides the usage of Npgsql 4, our biggest change was making the default schema object creation mode to CreateOrUpdate. Meaning that Marten even in its default mode will not drop any existing tables, even in development mode. You can still opt into the full "sure, I’ll blow away a table and start over if it’s incompatible" mode, but we felt like this option was safer after a few user problems were reported with the previous rules. See schema migration and patches for more information.

We also aligned usage of EnumStorage. Previously, Enum duplicated fields was always stored as varchar. Now it's using setting from JsonSerializer options - so by default it's integer. We felt that it's not consistent to have different default setting for Enums stored in json and in duplicated fields.

See full list of the fixed issues on GitHub.

You can also read more in Jeremy's blog post from.

Migration from 2.*

  • To keep Marten fully rebuilding your schema (so to allow Marten drop tables) set store options to:
AutoCreateSchemaObjects = AutoCreate.All
  • To keep enum fields being stored as varchar set store options to:
DuplicatedFieldEnumStorage = EnumStorage.AsString;

DuplicatedFieldUseTimestampWithoutTimeZoneForDateTime = false;