Sable ⚡

Database Migration Management Tool for Marten

Sable (Martes zibellina) is a species of marten.

Menu

• Quick Start
• Documentation
• Contributions
• License
• Code of Conduct
• Security Policy

Quick Start

Prerequisites

Before starting, ensure the following prerequisites are met:

• Docker is installed.
• The Sable .NET tool is installed by running the following command:

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 together 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
• Command Line Tooling in Marten

Now we're going to integrate Sable into a new project.

• Create a new project:

dotnet new webapi

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

dotnet add package Sable

Now for the fun part. Replace whatever overload of AddMarten you're using with AddMartenWithSableSupport. That's all it takes to complete 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);

Initialize Migration Infrastructure

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

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, especially when multiple databases are used in the same project.

Running the command above should also 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 stategies:

• Create a migration script that you can apply manually:

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.

OR

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

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

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

Add Migration

Okay. Everything is good so far, but you just added a new index to a document and want to update the database. What do you do? That's pretty simple. Just add a new migration:

sable migrations add AddIndexOnName --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.

Documentation

To learn more, check out the documentation.

Contributions

We ❤️ contributions.

Have you had a good experience with this project? Why not share some love and contribute code, or just let us know about any issues you had with it?

We welcome issue reports here; be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.

Before sending a Pull Request, please make sure you read our Contribution Guidelines.

License

Please read the LICENSE file.

Code of Conduct

This project has adopted a Code of Conduct. If you have any concerns about the Code, or behavior which you have experienced in the project, please contact us at [email protected].

Security Policy

• Security Policy

If you believe you have identified a security vulnerability in this project, you may submit a private vulnerability disclosure.

Please do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until we've had an opportunity to review and address them.

If you have any questions or concerns, please send an email to the Bloomberg OSPO at [email protected].

---