Marten

.NET Transactional Document DB and Event Store on PostgreSQL

<div align="center"> <img src="https://github.com/user-attachments/assets/f052d5a7-1f49-4aa7-91f6-cba415988d14" alt="marten logo" width="70%"> </div>

The Marten library provides .NET developers with the ability to use the proven PostgreSQL database engine and its fantastic JSON support as a fully fledged document database. The Marten team believes that a document database has far reaching benefits for developer productivity over relational databases with or without an ORM tool.

Marten also provides .NET developers with an ACID-compliant event store with user-defined projections against event streams.

Access docs here. For any of your queries including the whole of Critter stack, join our Discord channel and it is the best way to reach us quickly. You can also raise questions/queries via GitHub Discussions as well.

Support Plans

<div align="center"> <img src="https://www.jasperfx.net/logo.png" alt="JasperFx logo" width="70%"> </div>

While Marten is open source, JasperFx Software offers paid support and consulting contracts for Marten.

Help us keep working on this project 💚

Become a Sponsor on GitHub by sponsoring monthly or one time.

Past Sponsors

<p align="left"> <a href="https://aws.amazon.com/dotnet" target="_blank" rel="noopener noreferrer"> <picture> <source srcset="https://martendb.io/dotnet-aws.png" media="(prefers-color-scheme: dark)" height="72px" alt=".NET on AWS" /> <img src="https://martendb.io/dotnet-aws.png" height="72px" alt=".NET on AWS" /> </picture> </a> </p>

Working with the Code

Before getting started you will need the following in your environment:

1. .NET SDK 8.0+

Available here

2. PostgreSQL 13 or above database

The fastest possible way to develop with Marten is to run PostgreSQL in a Docker container. Assuming that you have Docker running on your local box, type: docker-compose up or dotnet run --framework net6.0 -- init-db at the command line to spin up a Postgresql database withThe default Marten test configuration tries to find this database if no PostgreSQL database connection string is explicitly configured following the steps below:

Native Partial Updates/Patching

Marten supports native patching since v7.x. you can refer to patching api for more details.

PLV8

If you'd like to use PLV8 Patching Api you need to enable the PLV8 extension inside of PostgreSQL for running JavaScript stored procedures for the nascent projection support.

Note that PLV8 patching will be deprecated in future versions and native patching is the drop in replacement for it. You can easily migrate to native patching, refer here for more details.

Ensure the following:

• The login you are using to connect to your database is a member of the postgres role
• An environment variable of marten_testing_database is set to the connection string for the database you want to use as a testbed. (See the Npgsql documentation for more information about PostgreSQL connection strings ).

Help with PSQL/PLV8

• On Windows, see this link for pre-built binaries of PLV8
• On *nix, check marten-local-db for a Docker based PostgreSQL instance including PLV8.

Test Config Customization

Some of our tests are run against a particular PostgreSQL version. If you'd like to run different database versions, you can do it by setting POSTGRES_IMAGE env variables, for instance:

POSTGRES_IMAGE=postgres:15.3-alpine docker compose up

Tests explorer should be able to detect database version automatically, but if it's not able to do it, you can enforce it by setting postgresql_version to a specific one (e.g.)

postgresql_version=15.3

Once you have the codebase and the connection string file, run the build command or use the dotnet CLI to restore and build the solution.

You are now ready to contribute to Marten.

See more in Contribution Guidelines.

Tooling

• Unit Tests rely on xUnit and Shouldly
• Bullseye is used for build automation.
• Node.js runs our Mocha specs.
• Storyteller for some of the data intensive automated tests

Build Commands

| Description | Windows Commandline | PowerShell | Linux Shell | DotNet CLI | |-------------------------------------|--------------------------|--------------------------|-------------------------|-----------------------------------------------------------| | Run restore, build and test | build.cmd | build.ps1 | build.sh | dotnet build src\Marten.sln | | Run all tests including mocha tests | build.cmd test | build.ps1 test | build.sh test | dotnet run --project build/build.csproj -- test | | Run just mocha tests | build.cmd mocha | build.ps1 mocha | build.sh mocha | dotnet run --project build/build.csproj -- mocha | | Run StoryTeller tests | build.cmd storyteller | build.ps1 storyteller | build.sh storyteller | dotnet run --project build/build.csproj -- storyteller | | Open StoryTeller editor | build.cmd open_st | build.ps1 open_st | build.sh open_st | dotnet run --project build/build.csproj -- open_st | | Run docs website locally | build.cmd docs | build.ps1 docs | build.sh docs | dotnet run --project build/build.csproj -- docs | | Publish docs | build.cmd publish-docs | build.ps1 publish-docs | build.sh publish-docs | dotnet run --project build/build.csproj -- publish-docs | | Run benchmarks | build.cmd benchmarks | build.ps1 benchmarks | build.sh benchmarks | dotnet run --project build/build.csproj -- benchmarks |

Note: You should have a running Postgres instance while running unit tests or StoryTeller tests.

xUnit.Net Specs

The tests for the main library are now broken into three testing projects:

1. CoreTests -- basic services like retries, schema management basics
2. DocumentDbTests -- anything specific to the document database features of Marten
3. EventSourcingTests -- anything specific to the event sourcing features of Marten

To aid in integration testing, Marten.Testing has a couple reusable base classes that can be use to make integration testing through Postgresql be more efficient and allow the xUnit.Net tests to run in parallel for better throughput.

• IntegrationContext -- if most of the tests will use an out of the box configuration (i.e., no fluent interface configuration of any document types), use this base type. Warning though, this context type will not clean out the main public database schema between runs, but will delete any existing data
• DestructiveIntegrationContext -- similar to IntegrationContext, but will wipe out any and all Postgresql schema objects in the public schema between tests. Use this sparingly please.
• OneOffConfigurationsContext -- if a test suite will need to frequently re-configure the DocumentStore, this context is appropriate. You do not need to decorate any of these test classes with the [Collection] attribute. This fixture will use an isolated schema using the name of the test fixture type as the schema name
• BugIntegrationContext -- the test harnesses for bugs tend to require custom DocumentStore configuration, and this context is a specialization of OneOffConfigurationsContext for the bugs schema.
• StoreFixture and StoreContext are helpful if a series of tests use the same custom DocumentStore configuration. You'd need to write a subclass of StoreFixture, then use StoreContext<YourNewStoreFixture> as the base class to share the DocumentStore between test runs with xUnit.Net's shared context (IClassFixture<T>)

Mocha Specs

Refer