.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.
Working with the Code
Before getting started you will need the following in your environment:
1. .NET Core SDK 3.1 (or higher)
2. .NET Framework 4.6.1 Developer Pack
3. PostgreSQL 9.5 or above database with PLV8
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
dotnet run -- init-db at the command line to spin up a Postgresql database with
PLv8 enabled and configured in the database. The default Marten test configuration tries to find this database if no
PostgreSQL database connection string is explicitly configured following the steps below:
Ensure the following:
- The login you are using to connect to your database is a member of the
- An environment variable of
marten_testing_databaseis 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.
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.
- 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
|Description||Windows Commandline||PowerShell||Linux Shell||DotNet CLI|
|Run restore, build and test||
|Run all tests including mocha tests||
|Run just mocha tests||
|Run StoryTeller tests||
|Open StoryTeller editor||
|Run documentation website locally||
Note: You should have a running Postgres instance while running unit tests or StoryTeller tests.
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
publicdatabase 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
publicschema between tests. Use this sparingly please.
OneOffConfigurationsContext-- if a test suite will need to frequently re-configure the
DocumentStore, this context is appropriate. You will need to decorate any of these test classes with the
[Collection]attribute, typically using the schema name for the collection name as a convention
BugIntegrationContext-- the test harnesses for bugs tend to require custom
DocumentStoreconfiguration, and this context is a specialization of
OneOffConfigurationsContextfor the bugs schema.
StoreContextare helpful if a series of tests use the same custom
DocumentStoreconfiguration. You'd need to write a subclass of
StoreFixture, then use
StoreContext<YourNewStoreFixture>as the base class to share the
DocumentStorebetween test runs with xUnit.Net's shared context (
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
Refer to build commands section to look up the commands to open the StoryTeller editor or run the StoryTeller specs.
The documentation content is the markdown files in the
/documentation directory directly under the project root. To run the documentation website locally with auto-refresh, refer to the build commands section above.
If you wish to insert code samples to a documentation page from the tests, wrap the code you wish to insert with
// SAMPLE: name-of-sample and
Then to insert that code to the documentation, add
Note: content is published to the
gh-pagesbranch of this repository. Refer to build commands section to lookup the command for publishing docs.
Copyright © .NET Foundation, 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.
Code of Conduct
This project is supported by the .NET Foundation .