Getting Started ​

Prerequisites ​

Before starting, ensure the following prerequisites are met:

• Docker is installed. To learn why Docker is needed, see How Sable Works.
• The Sable dotnet tool is installed by running the following command:

dotnet tool install -g Sable.Cli

dotnet tool install -g Sable.Cli

See .NET Tools to learn more about how .NET tools work.

Application Configuration ​

This guide assumes you have experience with configuring Marten along with its command line tooling support in .NET projects. If that is not the case, please take a look at the following guides before proceeding:

• Getting Started With Marten
• Marten Command Line Tooling

Ok. Let's move on. We're going to integrate Sable into a new project. To learn how to integrate Sable into an exiting project, see Existing Project Integration after going through this guide. The process is similar, so everything learned here will be applicable for existing projects as well.

• Create a new project:

dotnet new webapi

dotnet new webapi

• Configure marten along with its command line tooling support.
• Add Sable integration support to the project:

dotnet add package Sable

dotnet add package Sable

Now the fun part. Replace whatever overload of AddMarten you're using with AddMartenWithSableSupport. That's all there is to it for the integration.

At this point, you should have a configuration that looks something like this:

using Marten;
using Oakton;
using Sable.Extensions;
using Sable.Samples.Core;
using Weasel.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Host.ApplyOaktonExtensions();
builder.Services.AddMartenWithSableSupport(_ =>
{
    var options = new StoreOptions();
    options.Connection(builder.Configuration["Databases:Books:BasicTier"]);
    options.DatabaseSchemaName = "books";
    options.AutoCreateSchemaObjects = AutoCreate.None;
    options.Schema.For<Book>()
        .Index(x => x.Contents);
    return options;
});

var app = builder.Build();
app.MapGet("/", () => "💪🏾");

return await app.RunOaktonCommands(args);

using Marten;
using Oakton;
using Sable.Extensions;
using Sable.Samples.Core;
using Weasel.Core;

var builder = WebApplication.CreateBuilder(args);
builder.Host.ApplyOaktonExtensions();
builder.Services.AddMartenWithSableSupport(_ =>
{
    var options = new StoreOptions();
    options.Connection(builder.Configuration["Databases:Books:BasicTier"]);
    options.DatabaseSchemaName = "books";
    options.AutoCreateSchemaObjects = AutoCreate.None;
    options.Schema.For<Book>()
        .Index(x => x.Contents);
    return options;
});

var app = builder.Build();
app.MapGet("/", () => "💪🏾");

return await app.RunOaktonCommands(args);

Initialize Migration Infrastructure ​

Ok. Now that your project is properly configured, what's next? In your project directory, run the following command:

sable init --database <database-name> --schema <schema-name>

sable init --database <database-name> --schema <schema-name>

The default values for the database and schema names are Marten and public, respectively. Marten is the name associated with the database for the default configuration. This is important when multiple databases are used in the same project.

Running the command above should have created some migration files in the ./sable/<database-name>/migrations directory.

Update Database ​

Now, to update the database, follow either one of the following strategies:

• Create a migration script that you can then apply manually:

sable migrations script --database <database-name>

sable migrations script --database <database-name>

Running the command above should have created a migration script in the ./sable/<database-name>/scripts directory. You can now take that script and apply it manually to your database.

• Point Sable to the database and have it run the migration it for you:

sable database update <connection-string> --database <database-name>

sable database update <connection-string> --database <database-name>

Running the command above should have applied the pending migrations to your database.

Add Migration ​

Ok. All good so far, but you just added a new index to a document and want to update the database. What do you do? Pretty simple. Just add a new migration:

sable migrations add <migration-name> --database <database-name>

sable migrations add <migration-name> --database <database-name>

Running the command above should have created a new migration file in the ./sable/<database-name>/migrations directory.

To apply that migration, just follow one of the database update strategies outlined above one more time.

What's Next? ​

• Want do see some more sample configurations? See Sample Configurations.

• You have a more complicated configuration with a multi-tenancy setup? See Multi-Tenancy Setup

• You have a more complicated configuration with multiple database references? See Multiple Database Setup

• Curious to know how Sable works? See How Sable Works