Marten

.NET Transactional Document DB and Event Store on PostgreSQL

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

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

Working with the Code

Prerequisites

• .NET SDK 9.0 and 10.0 — the libraries and test projects multi-target net9.0;net10.0
• Docker (recommended) or your own PostgreSQL 13+ server
• Node.js 22+ — only needed to work on the documentation website

The build is driven by Nuke (build/build.cs). build.sh, build.ps1 and build.cmd are thin wrappers, so any target below can be run as ./build.sh <target> on Linux/macOS, .\build.ps1 <target> in PowerShell, or build.cmd <target> on Windows.

./build.sh compile     # restore and build src/Marten.slnx (the default target)

PostgreSQL

Marten supports PostgreSQL 13 or later; the async daemon relies on pg_current_snapshot(), which first shipped in 13.

The quickest way to get a test database is the Docker Compose file at the repository root:

docker compose up -d          # or: ./build.sh init-db  (starts it and waits until it is ready)

docker-compose.yml builds its image from docker/postgres/Dockerfile, which layers PostGIS 3 and pgvector onto the official postgres:17 image, so the Marten.PostGIS and Marten.PgVector test projects have the extensions they need. Both packages are multi-arch, so this builds natively on Apple-silicon machines. It listens on port 5432 with the postgres/postgres login and a marten_testing database. ./build.sh rebuild-db tears the container down and starts it again.

A few suites need something other than the standard database:

Suite	Database
Marten.TimescaleDB	docker compose -f docker-compose.timescaledb.yml up -d (TimescaleDB on port 5433 — point marten_testing_database at it)
MultiHostTests	docker compose -f src/MultiHostTests/docker-compose.yaml up -d (primary/standby pair on ports 5440/5441)

PLV8 is no longer part of developing Marten — the patching API it once backed has been replaced by native partial updates, and neither the compose image nor CI installs the extension. Older applications that still depend on it can use the separate Marten.PLv8 package.

Test configuration

By default the tests connect to:

Host=localhost;Port=5432;Database=marten_testing;Username=postgres;password=postgres

To use a different server or PostgreSQL version, set environment variables rather than editing the compose file:

Variable	Purpose
marten_testing_database	Connection string for the test database (the login needs the postgres role)
DEFAULT_SERIALIZER	Newtonsoft (default) or SystemTextJson
DISABLE_TEST_PARALLELIZATION	true to run test collections serially, as CI does

Running the tests

The test suites use xUnit.net v3 and Shouldly, and are split across many test projects under src/. There is one build target per test project:

This is the beginning of the README. Read the rest at the original. Read the full README ↗