Skip to content
Branch: master
Go to file
Code

Latest commit

Tobias Schaffner authored and oskardudycz committed 33df6b0 Jun 24, 2020

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Marten

.NET Transactional Document DB and Event Store on PostgreSQL

Join the chat at https://gitter.im/JasperFx/Marten Twitter Follow Windows Build Status Linux Build status Nuget Package

marten logo

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)

Available here

2. .NET Framework 4.6.1 Developer Pack

Available here

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:

You need to enable the PLV8 extension inside of PostgreSQL for running JavaScript stored procedures for the nascent projection support.

Ensure the following:

  • The login you are using to connect to your database is a member of the postgres role
  • 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 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.

Tooling

Build Commands

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 -p martenbuild.csproj -- test
Run just mocha tests build.cmd mocha build.ps1 mocha build.sh mocha dotnet run -p martenbuild.csproj -- mocha
Run StoryTeller tests build.cmd storyteller build.ps1 storyteller build.sh storyteller dotnet run -p martenbuild.csproj -- storyteller
Open StoryTeller editor build.cmd open_st build.ps1 open_st build.sh open_st dotnet run -p martenbuild.csproj -- open_st
Run documentation website locally build.cmd docs build.ps1 docs build.sh docs dotnet run -p martenbuild.csproj -- docs
Publish docs build.cmd publish-docs build.ps1 publish-docs build.sh publish-docs dotnet run -p martenbuild.csproj -- publish-docs
Run benchmarks build.cmd benchmarks build.ps1 benchmarks build.sh benchmarks dotnet run -p martenbuild.csproj -- benchmarks

Note: You should have a running Postgres instance while running unit tests or StoryTeller tests.

xUnit.Net Specs

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 public database 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 public schema 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 DocumentStore configuration, and this context is a specialization of OneOffConfigurationsContext for the bugs schema.
  • StoreFixture and StoreContext are helpful if a series of tests use the same custom DocumentStore configuration. You'd need to write a subclass of StoreFixture, then use StoreContext<YourNewStoreFixture> as the base class to share the DocumentStore between test runs with xUnit.Net's shared context (IClassFixture<T>)

Mocha Specs

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

Storyteller Specs

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

Documentation

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

License

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 has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.

.NET Foundation

This project is supported by the .NET Foundation .

You can’t perform that action at this time.