Marten Documentation

Marten is a .NET Transactional Document DB and Event Store built on top of PostgreSQL. It leverages PostgreSQL's JSON support and ACID compliance to provide a robust document database and an event-sourcing engine for building event-sourced systems.

Key capabilities include:

• Document Database: A full-fledged document store for .NET objects.
• Event Store: Tools to store events and streams, including support for projections to create read-side views.
• PostgreSQL Integration: Uses PostgreSQL as the underlying data store to benefit from its proven engine and JSON capabilities.

The StoreOptions object is the root configuration for a DocumentStore. Configuration for a specific document type is applied in a specific order, with later steps overriding earlier ones.

Order of Precedence (Lowest to Highest):

1. ConfigureMarten(DocumentMapping) method defined on the document type.
2. IDocumentPolicy registered on StoreOptions (applies to all document types).
3. MartenAttribute decorations on the document type or its members.
4. Explicit configuration via MartenRegistry (using StoreOptions.Schema).

To avoid confusion, Marten recommends choosing one consistent configuration style.

By default, Marten opens a database connection only immediately before an operation requiring one and closes it immediately after (returning it to the Npgsql pool). This allows IQuerySession or IDocumentSession objects to be used safely across multiple threads.

Exceptions where a connection becomes "sticky" (stays open for the duration of the session) include:

• Creating a session with an existing connection or transaction.
• Using serializable transaction isolation levels (e.g., via IDocumentStore.SerializableSessionAsync()).
• Enrolling in ambient transactions using SessionOptions.ForCurrentTransaction().
• Using explicit transaction boundaries.
• Accessing the session's underlying connection directly for user-defined querying.

Marten allows you to use PostgreSQL as a document database for .NET applications. Instead of mapping .NET types to flat relational tables using an ORM like EF Core, Marten uses JSON serialization to persist and load .NET objects (referred to as "documents") directly into PostgreSQL's JSONB data type.

This approach is ideal for systems with relatively self-contained entities and provides several benefits:

• Eliminates explicit ORM mapping: No need to define complex relational mappings.
• Schema flexibility: Entities can evolve without requiring heavy database migrations.
• Simplified lifecycle: Supports built-in database initialization and runtime migrations.

The Marten LINQ provider operates through several internal models that transform a .NET LINQ expression into a PostgreSQL query:

• MartenLinqQueryable<T>: The entry point implementation of IQueryable that users interact with. It holds the Expression tree.
• CollectionUsage: An intermediate model that organizes the raw Expression into logical steps like Select, Where, OrderBy, Take, Skip, SelectMany, and Include.
• Statement: A model (structured as a double-linked list) that knows how to generate the necessary SQL and read raw data into results. Complex queries involving Include(), SelectMany(), or Distinct() may require multiple statements.
• IQueryHandler: The execution model that uses the Statement to run the query and return results via an IMartenSession.

The Marten Async Daemon, responsible for background projections, supports two primary deployment modes:

1. Polling-Based Mode: A classic approach where the daemon polls for new events. It can use PostgreSQL advisory locks for leader election to manage active/standby nodes.
2. Messaging-Based Mode: Uses external messaging infrastructure (e.g., RabbitMQ, Azure Service Bus, Kafka) to gather events and connect them to running projection builders. This mode typically requires a centralized Distributor process to assign projection segments to different nodes.

Aggregate Projections in Marten combine groups of events to create a single aggregated document representing the state of those events. There are two primary types:

1. Single Stream Projections: Create a rolled-up view of all or a segment of events within a single event stream. These can be implemented using the SingleStreamProjection<TDoc, TId> base type or via a "self-aggregating" Snapshot approach using Create, Apply, and ShouldDelete methods.
2. Multi Stream Projections: Create a rolled-up view of a user-defined grouping of events across multiple streams (e.g., an accounting query model rolling up unpaid invoices by client). These are implemented by subclassing MultiStreamProjection<TDoc, TId>.

Projections can be implemented using conventional methods (the original Marten pattern) or explicit code (introduced in Marten 8.0).

When multi-tenancy is enabled, Marten associates every record with a tenant. If no tenant is explicitly specified (via session scoping, mapping policies, or method overloads), Marten defaults to the identifier defined in StorageConstants.DefaultTenantId, which has a constant value of *DEFAULT*.

• Non-tenanted schemas: If a schema is not configured as multi-tenanted (e.g., opts.Schema.For<User>()), documents are treated as non-tenanted and are accessible regardless of the session's tenant.
• Tenanted schemas: If a schema is configured as multi-tenanted (e.g., opts.Schema.For<Target>().MultiTenanted()), documents without an explicit tenant will be assigned to the *DEFAULT* tenant.