Repository files navigation

The Marten library provides .NET developers with the ability to use the provenPostgreSQL database engine and itsfantastic JSON support as a fully fledgeddocument 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 docshere and v3.x docshere.

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:

Availablehere

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 upordotnet run --framework net6.0 -- init-dbat the command line to spin up a Postgresql database withThe default Marten test configuration tries to find this database if noPostgreSQL database connection string is explicitly configured following the steps below:

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

If you'd like to usePLV8 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, referhere for more details.

Ensure the following:

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

Help with PSQL/PLV8

• On Windows, seethis link for pre-built binaries of PLV8
• On *nix, checkmarten-local-db for a Docker based PostgreSQL instance including 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 settingPOSTGRES_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 settingpostgresql_version to a specific one (e.g.)

postgresql_version=15.3

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

You are now ready to contribute to Marten.

See more inContribution Guidelines.

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

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:

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 useto make integration testing through Postgresql be more efficient and allow the xUnit.Net teststo 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 willnot clean out the mainpublic database schema between runs,but will delete any existing data
• DestructiveIntegrationContext -- similar toIntegrationContext, but will wipe out any and allPostgresql schema objects in thepublic schema between tests. Use this sparingly please.
• OneOffConfigurationsContext -- if a test suite will need to frequently re-configuretheDocumentStore, this context is appropriate. You donot need to decorate any of thesetest classes with the[Collection] attribute. This fixture will use an isolated schema using the name of thetest fixture type as the schema name
• BugIntegrationContext -- the test harnesses for bugs tend to require customDocumentStoreconfiguration, and this context is a specialization ofOneOffConfigurationsContext forthebugs schema.
• StoreFixture andStoreContext are helpful if a series of tests use the same customDocumentStore configuration. You'd need to write a subclass ofStoreFixture, then useStoreContext<YourNewStoreFixture> as the base class to share theDocumentStore betweentest runs with xUnit.Net's shared context (IClassFixture<T>)

Refer to the build commands section to look up the commands to run Mocha tests. There is alsonpm run tdd to run the mocha specificationsin a watched mode with growl turned on.

Note: remember to runnpm install

Refer to build commands section to look up the commands to open the StoryTeller editor or run the StoryTeller specs.

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 andAlgolia 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 usenpm 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 withsample_ 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

<!-- snippet: sample_my_snippet --><!-- endSnippet -->

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:

• 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.
• 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.

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 in3.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 thegh-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 seeLICENSE.

This project has adopted the code of conduct defined by theContributor Covenant to clarify expected behavior in our community.