{"id":15187215,"url":"https://github.com/jasperfx/marten","last_synced_at":"2026-04-02T18:27:45.687Z","repository":{"id":37885087,"uuid":"44125268","full_name":"JasperFx/marten","owner":"JasperFx","description":".NET Transactional Document DB and Event Store on PostgreSQL","archived":false,"fork":false,"pushed_at":"2025-05-06T16:17:02.000Z","size":34224,"stargazers_count":3126,"open_issues_count":77,"forks_count":485,"subscribers_count":74,"default_branch":"master","last_synced_at":"2025-05-06T16:50:47.591Z","etag":null,"topics":["document-database","documentdb","dotnet","event-sourcing","eventsourcing","marten","plv8","postgres"],"latest_commit_sha":null,"homepage":"https://martendb.io","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JasperFx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["JasperFx"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-10-12T18:11:12.000Z","updated_at":"2025-05-05T03:42:38.000Z","dependencies_parsed_at":"2024-03-27T04:25:56.351Z","dependency_job_id":"f03860d0-272f-4825-9f0c-01f9cbcfe76f","html_url":"https://github.com/JasperFx/marten","commit_stats":{"total_commits":5097,"total_committers":256,"mean_commits":19.91015625,"dds":0.5275652344516382,"last_synced_commit":"6d67030243e13bb4ea564d383e0f9d850654fd6d"},"previous_names":[],"tags_count":187,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasperFx%2Fmarten","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasperFx%2Fmarten/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasperFx%2Fmarten/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasperFx%2Fmarten/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JasperFx","download_url":"https://codeload.github.com/JasperFx/marten/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254020639,"owners_count":22000756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-database","documentdb","dotnet","event-sourcing","eventsourcing","marten","plv8","postgres"],"created_at":"2024-09-27T18:04:39.235Z","updated_at":"2026-04-02T18:27:45.662Z","avatar_url":"https://github.com/JasperFx.png","language":"C#","readme":"# Marten\n\n## .NET Transactional Document DB and Event Store on PostgreSQL\n\n[![Discord](https://img.shields.io/discord/1074998995086225460?color=blue\u0026label=Chat%20on%20Discord)](https://discord.gg/WMxrvegf8H)\n![Twitter Follow](https://img.shields.io/twitter/follow/marten_lib?logo=Twitter\u0026style=flat-square)\n[![Windows Build Status](https://ci.appveyor.com/api/projects/status/va5br63j7sbx74cm/branch/master?svg=true)](https://ci.appveyor.com/project/jasper-ci/marten/branch/master)\n[![Linux Build status](https://dev.azure.com/jasperfx-marten/marten/_apis/build/status/marten?branchName=master)](https://dev.azure.com/jasperfx-marten/marten/_build/latest?definitionId=1\u0026branchName=master)\n[![Nuget Package](https://badgen.net/nuget/v/marten)](https://www.nuget.org/packages/Marten/)\n[![Nuget](https://img.shields.io/nuget/dt/marten)](https://www.nuget.org/packages/Marten/)\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/f052d5a7-1f49-4aa7-91f6-cba415988d14\" alt=\"marten logo\" width=\"70%\"\u003e\n\u003c/div\u003e\n\nThe Marten library provides .NET developers with the ability to use the proven [PostgreSQL database engine](http://www.postgresql.org/) and its [fantastic JSON support](https://web.archive.org/web/20230127180328/https://www.compose.com/articles/is-postgresql-your-next-json-database/) as a fully fledged [document database](https://en.wikipedia.org/wiki/Document-oriented_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.\n\nMarten also provides .NET developers with an ACID-compliant event store with user-defined projections against event streams.\n\nAccess docs [here](https://martendb.io/). For any of your queries including the whole of Critter stack, join our [Discord channel](https://discord.gg/WMxrvegf8H) and it is the best way to reach us quickly. You can also raise questions/queries via [GitHub Discussions](https://github.com/JasperFx/marten/discussions) as well.\n\n## Support Plans\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://www.jasperfx.net/logo.png\" alt=\"JasperFx logo\" width=\"70%\"\u003e\n\u003c/div\u003e\n\nWhile Marten is open source, [JasperFx Software offers paid support and consulting contracts](https://jasperfx.net/support-plans/) for Marten.\n\n## Help us keep working on this project 💚\n\n[Become a Sponsor on GitHub](https://github.com/sponsors/JasperFX) by sponsoring monthly or one time.\n\n### Past Sponsors\n\n\u003cp align=\"left\"\u003e\n    \u003ca href=\"https://aws.amazon.com/dotnet\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n    \u003cpicture\u003e\n      \u003csource srcset=\"https://martendb.io/dotnet-aws.png\" media=\"(prefers-color-scheme: dark)\" height=\"72px\" alt=\".NET on AWS\" /\u003e\n      \u003cimg src=\"https://martendb.io/dotnet-aws.png\" height=\"72px\" alt=\".NET on AWS\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Working with the Code\n\nBefore getting started you will need the following in your environment:\n\n### 1. .NET SDK 8.0+\n\nAvailable [here](https://dotnet.microsoft.com/download)\n\n### 2. PostgreSQL 13 or above database\n\nThe 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:\n`docker-compose up`\nor\n`dotnet run --framework net6.0 -- init-db`\nat the command line to spin up a Postgresql database withThe default Marten test configuration tries to find this database if no\nPostgreSQL database connection string is explicitly configured following the steps below:\n\n### Native Partial Updates/Patching\n\nMarten supports native patching since v7.x. you can refer to [patching api](https://martendb.io/documents/partial-updates-patching.html) for more details.\n\n### PLV8\n\nIf you'd like to use [PLV8 Patching Api](https://martendb.io/documents/plv8.html#the-patching-api) you need to enable the PLV8 extension inside of PostgreSQL for running JavaScript stored procedures for the nascent projection support.\n\nNote 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](https://martendb.io/documents/partial-updates-patching.html#patching-api) for more details.\n\nEnsure the following:\n\n- The login you are using to connect to your database is a member of the `postgres` role\n- 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](http://www.npgsql.org/doc/connection-string-parameters.html) for more information about PostgreSQL connection strings ).\n\n_Help with PSQL/PLV8_\n\n- On Windows, see [this link](http://www.postgresonline.com/journal/archives/360-PLV8-binaries-for-PostgreSQL-9.5-windows-both-32-bit-and-64-bit.html) for pre-built binaries of PLV8\n- On *nix, check [marten-local-db](https://github.com/eouw0o83hf/marten-local-db) for a Docker based PostgreSQL instance including PLV8.\n\n### Test Config Customization\n\nSome 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:\n\n```bash\nPOSTGRES_IMAGE=postgres:15.3-alpine docker compose up\n```\n\nTests 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.)\n\n```shell\npostgresql_version=15.3\n```\n\nOnce you have the codebase and the connection string file, run the [build command](https://github.com/JasperFx/marten#build-commands) or use the dotnet CLI to restore and build the solution.\n\nYou are now ready to contribute to Marten.\n\nSee more in [Contribution Guidelines](CONTRIBUTING.md).\n\n### Tooling\n\n* Unit Tests rely on [xUnit](http://xunit.github.io/) and [Shouldly](https://github.com/shouldly/shouldly)\n* [Bullseye](https://github.com/adamralph/bullseye) is used for build automation.\n* [Node.js](https://nodejs.org/en/) runs our Mocha specs.\n* [Storyteller](http://storyteller.github.io) for some of the data intensive automated tests\n\n### Build Commands\n\n| Description                         | Windows Commandline      | PowerShell               | Linux Shell             | DotNet CLI                                                |\n|-------------------------------------|--------------------------|--------------------------|-------------------------|-----------------------------------------------------------|\n| Run restore, build and test         | `build.cmd`              | `build.ps1`              | `build.sh`              | `dotnet build src\\Marten.sln`                             |\n| Run all tests including mocha tests | `build.cmd test`         | `build.ps1 test`         | `build.sh test`         | `dotnet run --project build/build.csproj -- test`         |\n| Run just mocha tests                | `build.cmd mocha`        | `build.ps1 mocha`        | `build.sh mocha`        | `dotnet run --project build/build.csproj -- mocha`        |\n| Run StoryTeller tests               | `build.cmd storyteller`  | `build.ps1 storyteller`  | `build.sh storyteller`  | `dotnet run --project build/build.csproj -- storyteller`  |\n| Open StoryTeller editor             | `build.cmd open_st`      | `build.ps1 open_st`      | `build.sh open_st`      | `dotnet run --project build/build.csproj -- open_st`      |\n| Run docs website locally            | `build.cmd docs`         | `build.ps1 docs`         | `build.sh docs`         | `dotnet run --project build/build.csproj -- docs`         |\n| Publish docs                        | `build.cmd publish-docs` | `build.ps1 publish-docs` | `build.sh publish-docs` | `dotnet run --project build/build.csproj -- publish-docs` |\n| Run benchmarks                      | `build.cmd benchmarks`   | `build.ps1 benchmarks`   | `build.sh benchmarks`   | `dotnet run --project build/build.csproj -- benchmarks`   |\n\n\u003e Note: You should have a running Postgres instance while running unit tests or StoryTeller tests.\n\n### xUnit.Net Specs\n\nThe tests for the main library are now broken into three testing projects:\n\n1. `CoreTests` -- basic services like retries, schema management basics\n1. `DocumentDbTests` -- anything specific to the document database features of Marten\n1. `EventSourcingTests` -- anything specific to the event sourcing features of Marten\n\nTo aid in integration testing, Marten.Testing has a couple reusable base classes that can be use\nto make integration testing through Postgresql be more efficient and allow the xUnit.Net tests\nto run in parallel for better throughput.\n\n- `IntegrationContext` -- if most of the tests will use an out of the box configuration\n  (i.e., no fluent interface configuration of any document types), use this base type. Warning though,\n  this context type will **not** clean out the main `public` database schema between runs,\n  but will delete any existing data\n- `DestructiveIntegrationContext` -- similar to `IntegrationContext`, but will wipe out any and all\n  Postgresql schema objects in the `public` schema between tests. Use this sparingly please.\n- `OneOffConfigurationsContext` -- if a test suite will need to frequently re-configure\n  the `DocumentStore`, this context is appropriate. You do *not* need to decorate any of these\n  test classes with the `[Collection]` attribute. This fixture will use an isolated schema using the name of the\n  test fixture type as the schema name\n- `BugIntegrationContext` -- the test harnesses for bugs tend to require custom `DocumentStore`\n  configuration, and this context is a specialization of `OneOffConfigurationsContext` for\n  the *bugs* schema.\n- `StoreFixture` and `StoreContext` are helpful if a series of tests use the same custom\n  `DocumentStore` configuration. You'd need to write a subclass of `StoreFixture`, then use\n  `StoreContext\u003cYourNewStoreFixture\u003e` as the base class to share the `DocumentStore` between\n  test runs with xUnit.Net's shared context (`IClassFixture\u003cT\u003e`)\n\n### Mocha Specs\n\nRefer 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\nin a watched mode with growl turned on.\n\n\u003e Note: remember to run `npm install`\n\n### Storyteller Specs\n\nRefer to build commands section to look up the commands to open the StoryTeller editor or run the StoryTeller specs.\n\n### Current Build Matrix\n\n| CI              | .NET | Postgres  |        plv8        | Serializer | \n|-----------------|:----:|:---------:|:------------------:|:----------:|\n| GitHub Actions  |  8   |   12.8    | :white_check_mark: |    STJ     | \n| GitHub Actions  |  8   | 15-alpine |        :x:         | Newtonsoft | \n| GitHub Actions  |  7   |   12.8    | :white_check_mark: |  JSON.NET  | \n| GitHub Actions  |  7   |  latest   |        :x:         |    STJ     | \n| Azure Pipelines |  6   |   12.8    | :white_check_mark: |  JSON.NET  | \n| Azure Pipelines |  6   |   12.8    | :white_check_mark: |    STJ     | \n| Azure Pipelines |  6   | 15-alpine |        :x:         |    STJ     | \n| Azure Pipelines |  6   |  latest   |        :x:         | Newtonsoft | \n\n## Documentation\n\nAll 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.\n\n### v4.x and above\n\n[VitePress](https://vitepress.vuejs.org/) is used as documentation tool. Along with this, [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets) is used for adding code snippets to docs from source code and [Algolia DocSearch](https://docsearch.algolia.com/) is used for searching the docs via the search box.\n\nThe 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.\n\nTo add code samples/snippets from the tests in docs, follow the steps below:\n\nUse C# named regions to mark a code block as described in the sample below\n\n```csharp\n#region sample_my-snippet\n// code sample/snippet\n// ...\n#endregion\n```\n\nAll 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 kebab case for the identifiers with words in lower case.\n\nUse the below to include the code snippet in a docs page\n\n\u003cpre\u003e\n\u0026#60;!-- snippet: sample_my-snippet --\u003e\n\u0026#60;!-- endSnippet --\u003e\n\u003c/pre\u003e\n\nNote 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.\n\nFew gotchas:\n\n- Any changes to the code snippets will need to done in the source code. Do not edit/update any of the auto-generated inline code snippet directly in the Markdown files.\n- The latest snippet are always pulled into the docs while we publish the docs. Hence do not worry about the inline code snippet in Markdown file getting out of sync with the snippet in source code.\n\n### v3.x\n\n[stdocs](https://www.nuget.org/packages/dotnet-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](https://github.com/JasperFx/marten/tree/3.14). To run the documentation website locally with auto-refresh, refer to the build commands section above.\n\nIf you wish to insert code samples/snippet to a documentation page from the tests, wrap the code you wish to insert with\n`// SAMPLE: name-of-sample` and `// ENDSAMPLE`.\nThen to insert that code to the documentation, add `\u003c[sample:name-of-sample]\u003e`.\n\n\u003e Note: content is published to the `gh-pages` branch of this repository. Refer to build commands section to lookup the command for publishing docs.\n\n## License\n\nCopyright © Jeremy D. Miller, Babu Annamalai, Oskar Dudycz, Joona-Pekka Kokko and contributors.\n\nMarten is provided as-is under the MIT license. For more information see [LICENSE](LICENSE).\n\n## Code of Conduct\n\nThis project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/) to clarify expected behavior in our community.\n","funding_links":["https://github.com/sponsors/JasperFx","https://github.com/sponsors/JasperFX"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasperfx%2Fmarten","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasperfx%2Fmarten","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasperfx%2Fmarten/lists"}