.NET Transactional Document DB and Event Store on PostgreSQL
MIT License
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 and v3.x docs here.
While Marten is open source, JasperFx Software offers paid support and consulting contracts for Marten.
Become a Sponsor on GitHub by sponsoring monthly or one time.
Before getting started you will need the following in your environment:
Available here
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:
If you'd like to use Patching Api you need to enable the PLV8 extension inside of PostgreSQL for running JavaScript stored procedures for the nascent projection support.
Ensure the following:
postgres
rolemarten_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
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.
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.
The tests for the main library are now broken into three testing projects:
CoreTests
-- basic services like retries, schema management basicsDocumentDbTests
-- anything specific to the document database features of MartenEventSourcingTests
-- anything specific to the event sourcing features of MartenTo 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 configurationpublic
database schema between runs,DestructiveIntegrationContext
-- similar to IntegrationContext
, but will wipe out any and allpublic
schema between tests. Use this sparingly please.OneOffConfigurationsContext
-- if a test suite will need to frequently re-configureDocumentStore
, this context is appropriate. You do not need to decorate any of these[Collection]
attribute. This fixture will use an isolated schema using the name of theBugIntegrationContext
-- the test harnesses for bugs tend to require custom DocumentStore
OneOffConfigurationsContext
forStoreFixture
and StoreContext
are helpful if a series of tests use the same customDocumentStore
configuration. You'd need to write a subclass of StoreFixture
, then useStoreContext<YourNewStoreFixture>
as the base class to share the DocumentStore
betweenIClassFixture<T>
)Refer to the build commands section to look up the commands to run Mocha tests. There is also npm run tdd
to run the mocha specifications
in a watched mode with growl turned on.
Note: remember to run
npm install
Refer to build commands section to look up the commands to open the StoryTeller editor or run the StoryTeller specs.
CI | .NET | Postgres | plv8 | Serializer |
---|---|---|---|---|
GitHub Actions | 8 | 12.8 | ✅ | STJ |
GitHub Actions | 8 | 15-alpine | ❌ | Newtonsoft |
GitHub Actions | 7 | 12.8 | ✅ | JSON.NET |
GitHub Actions | 7 | latest | ❌ | STJ |
Azure Pipelines | 6 | 12.8 | ✅ | JSON.NET |
Azure Pipelines | 6 | 12.8 | ✅ | STJ |
Azure Pipelines | 6 | 15-alpine | ❌ | STJ |
Azure Pipelines | 6 | latest | ❌ | Newtonsoft |
All the documentation is written in Markdown and the docs are published as a static site hosted in Netlify. v4.x and v3.x use different documentation tools hence are detailed below in separate sub-sections.
VitePress is used as documentation tool. Along with this, MarkdownSnippets is used for adding code snippets to docs from source code and Algolia DocSearch is used for searching the docs via the search box.
The documentation content is the Markdown files in the /docs
directory directly under the project root. To run the docs locally use npm run docs
with auto-refresh on any changes.
To add code samples/snippets from the tests in docs, follow the steps below:
Use C# named regions to mark a code block as described in the sample below
#region sample_my_snippet
// code sample/snippet
// ...
#endregion
All code snippet identifier starts with sample_
as a convention to clearly identify that the region block corresponds to a sample code/snippet used in docs. Recommend to use snake case for the identifiers with words in lower case.
Use the below to include the code snippet in a docs page
Note that when you run the docs locally, the above placeholder block in the Markdown file will get updated inline with the actual code snippet from the source code. Please commit the changes with the auto-generated inline code snippet as-is after you preview the docs page. This helps with easier change tracking when you send PR's.
Few gotchas:
stdocs is used as documentation tool. The documentation content is the markdown files in the /documentation
directory directly under the project root. Any updates to v3.x docs will need to done in 3.14 branch. To run the documentation website locally with auto-refresh, refer to the build commands section above.
If you wish to insert code samples/snippet to a documentation page from the tests, wrap the code you wish to insert with
// SAMPLE: name-of-sample
and // ENDSAMPLE
.
Then to insert that code to the documentation, add <[sample:name-of-sample]>
.
Note: content is published to the
gh-pages
branch of this repository. Refer to build commands section to lookup the command for publishing docs.
Copyright © Jeremy D. Miller, Babu Annamalai, Oskar Dudycz, Joona-Pekka Kokko and contributors.
Marten is provided as-is under the MIT license. For more information see LICENSE.
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community.