Event Store Schema Objects #

Overriding the Schema #

By default, the event store database objects are created in the default schema for the active IDocumentStore. If you wish, you can segregate the event store objects into a separate schema with this syntax:

var store = DocumentStore.For(_ =>
{
    _.Connection("some connection string");

    // Places all the Event Store schema objects
    // into the "events" schema
    _.Events.DatabaseSchemaName = "events";
});

^{snippet source | anchor}

Database Tables #

The events are stored in the mt_events table, with these columns:

• seq_id - A sequential identifier that acts as the primary key
• id - A Guid value uniquely identifying the event across databases
• stream_id - A foreign key to the event stream that contains the event
• version - A numerical version of the event's position within its event stream
• data - The actual event data stored as JSONB
• type - A string identifier for the event type that's derived from the event type name. For example, events of type IssueResolved would be identified as "issue_resolved." The type column exists so that Marten can be effectively used without the underlying JSON serializer having to embed type metadata.
• timestamp - A database timestamp written by the database when events are committed.
• tenant_id - Identifies the tenancy of the event
• mt_dotnet_type - The full name of the underlying event type, including assembly name, e.g. "Marten.Testing.Events.IssueResolved, Marten.Testing"

The "Async Daemon" projection supports keys off of the sequential id, but we retained the Guid id field for backward compatibility and to retain a potential way to uniquely identify events across databases.

In addition, there are a couple other metadata tables you'll see in your schema:

• mt_streams - Metadata about each event stream
• mt_event_progression - A durable record about the progress of each async projection through the event store

A couple functions that Marten uses internally:

• mt_append_event - Writes event data to the mt_events and mt_streams tables
• mt_mark_event_progression - Updates the mt_event_progression table

And lastly, there's a document type called DeadLetterEvent that Marten adds automatically to record information about "dead letter events" that are repeatedly erroring in the async daemon and are being skipped in accordance with the error handling policies in your application's Marten configuration.

Event Metadata in Code #

Hopefully, it's relatively clear how the fields in mt_events map to the IEvent interface in Marten:

/// <summary>
///     A reference to the stream that contains
///     this event
/// </summary>
public Guid StreamId { get; set; }

/// <summary>
///     A reference to the stream if the stream
///     identifier mode is AsString
/// </summary>
public string? StreamKey { get; set; }

/// <summary>
///     An alternative Guid identifier to identify
///     events across databases
/// </summary>
public Guid Id { get; set; }

/// <summary>
///     An event's version position within its event stream
/// </summary>
public long Version { get; set; }

/// <summary>
///     A global sequential number identifying the Event
/// </summary>
public long Sequence { get; set; }

/// <summary>
///     The UTC time that this event was originally captured
/// </summary>
public DateTimeOffset Timestamp { get; set; }

public string TenantId { get; set; } = Tenancy.DefaultTenantId;

/// <summary>
/// Optional metadata describing the causation id
/// </summary>
public string? CausationId { get; set; }

/// <summary>
/// Optional metadata describing the correlation id
/// </summary>
public string? CorrelationId { get; set; }

/// <summary>
/// This is meant to be lazy created, and can be null
/// </summary>
public Dictionary<string, object>? Headers { get; set; }

^{snippet source | anchor}

The full event data is available on EventStream and IEvent objects immediately after committing a transaction that involves event capture. See diagnostics and instrumentation for more information on capturing event data in the instrumentation hooks.