Command Line Tooling
WARNING
The usage of JasperFx commands shown in this document are only valid for applications bootstrapped with the generic host builder with Marten registered in the application's IoC container.
WARNING
When writing integration tests, make sure to enable host auto-start in your test setup:
JasperFxEnvironment.AutoStartHost = true;
or in Marten V7 or earlier:
OaktonEnvironment.AutoStartHost = true;
Without this setting, creating the test server will fail to bootstrap. See also Creating an Integration Test Harness
Through dependencies on the JasperFx and Weasel libraries, Marten has support for command line tools to apply or generate database migrations from the command line. Marten also has support for running or rebuilding projections from the command line. Lastly, Marten has a more recent command for some advanced Event Store management features that might be useful in deployment scenarios.
To use the expanded command line options to a .NET application, add this last line of code shown below to your Program.cs
:
var builder = WebApplication.CreateBuilder(args);
// Easiest to just do this right after creating builder
// Must be done before calling builder.Build() at least
builder.Host.ApplyJasperFxExtensions();
And finally, use JasperFx as the command line parser and executor by replacing App.Run()
as the last line of code in your Program.cs
file:
// Instead of App.Run(), use the app.RunJasperFxCommands(args)
// as the last line of your Program.cs file
return await app.RunJasperFxCommands(args);
In your command line in the project directory, you can run:
dotnet -- help
And you will be given a list of commands.
The available commands are:
Alias Description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
check-env Execute all environment checks against the application
codegen Utilities for working with JasperFx.CodeGeneration and JasperFx.RuntimeCompiler
db-apply Applies all outstanding changes to the database(s) based on the current configuration
db-assert Assert that the existing database(s) matches the current configuration
db-dump Dumps the entire DDL for the configured Marten database
db-list List all database(s) based on the current configuration
db-patch Evaluates the current configuration against the database and writes a patch and drop file if there are any differences
describe Writes out a description of your running application to either the console or a file
help List all the available commands
marten Advanced Marten operations to 'heal' event store projection issues or reset data
projections Asynchronous projection and projection rebuilds
resources Check, setup, or teardown stateful resources of this system
run Start and run this .Net application
storage Administer the Wolverine message storage
For any of the listed commands, you can run:
dotnet -- help [command]
To see more information about the use of that command.
Example Commands
Run these commands in your project's directory.
List Your Projections
dotnet run -- projections list
Rebuild Your Projections
To rebuild all of your projections:
dotnet run -- projections rebuild
To rebuild a single projection:
dotnet run -- projections -p Course rebuild
(where Course
is the name of the projection, from the list)
Creating a SQL Script from your Marten Database
dotnet run -- db-dump -d Marten ./marten.sql
Codegen
You can use the CLI to preview, generate, write, or test the code generation:
To Test Codegen:
dotnet run -- codegen test
To preview codegen:
dotnet run -- codegen preview
To write the codegen to your project (in the internal/codegen
directory):
dotnet run -- codegen write
Outside the Dotnet CLI
If you're not using the dotnet CLI yet, you'd just need to compile your new console application like you've always done and call the exe directly. If you're familiar with the *nix style of command-line interfaces ala Git, you should feel right at home with the command line usage in Marten.
For the sake of usability, let's say that you stick a file named "marten.cmd" (or the *nix shell file equivalent) at the root of your codebase like so:
dotnet run --project src/MyConsoleApp %*
All the example above does is delegate any arguments to your console application. Once you have that file, some sample usages are shown below:
Assert that the database matches the current database. This command will fail if there are differences
marten marten-assert --log log.txt
This command tries to update the database to reflect the application configuration
marten marten-apply --log log.txt
This dumps a single file named "database.sql" with all the DDL necessary to build the database to match the application configuration
marten marten-dump database.sql
This dumps the DDL to separate files per document type to a folder named "scripts"
marten marten-dump scripts --by-type
Create a patch file called "patch1.sql" and the corresponding rollback file "patch.drop.sql" if any differences are found between the application configuration and the database
marten marten-patch patch1.sql --drop patch1.drop.sql
In all cases, the commands expose usage help through "marten help [command]." Each of the commands also exposes a "--conn" (or "-c" if you prefer) flag to override the database connection string and a "--log" flag to record all the command output to a file.
Projections Support
See the Async Daemon documentation for more information about the newly improved projections
command.
Event Store Management or Resetting Data
Some of the operations on IDocumentStore.Advanced
are now available from the command line for easier usage within automated deployment scripts.
If you'll type out:
dotnet run -- help marten
You'll see this output:
marten - Advanced Marten operations to 'heal' event store projection issues or reset data
└── Advanced Marten operations to 'heal' event store projection issues or reset data
└── dotnet run -- marten
├── [-a, --advance]
├── [-c, --correct]
├── [-t, --tenant-id <tenantid>]
├── [-r, --reset]
├── [-v, --env-variable <environmentvariable>]
├── [-c, --contentroot <contentroot>]
├── [-a, --applicationname <applicationname>]
├── [-e, --environment <environment>]
├── [-v, --verbose]
├── [-l, --log-level Trace|Debug|Information|Warning|Error|Critical|None]
└── [--config:<prop> <value>]
Usage Description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[-a, --advance] Advance the high water mark to the highest detected point
[-c, --correct] Try to correct the event progression based on the event sequence after *some* database hiccups
[-t, --tenant-id <tenantid>] Limit the operation to a single tenant if specified
[-r, --reset] Reset all Marten data
[-v, --env-variable <environmentvariable>] Value in the form <KEY=VALUE> to set an environment variable for this process
[-c, --contentroot <contentroot>] Override the IHostEnvironment.ContentRoot
[-a, --applicationname <applicationname>] Override the IHostEnvironment.ApplicationName
[-e, --environment <environment>] Override the IHostEnvironment.EnvironmentName
[-v, --verbose] Write out much more information at startup and enables console logging
[-l, --log-level Trace|Debug|Information|Warning|Error|Critical|None] Override the log level
[--config:<prop> <value>] Overwrite individual configuration items