Mongo DB support for Hangfire
Jonas Gottschau Jonas Gottschau
Jonas Gottschau and Jonas Gottschau Merge branch '0.5.13'
# Conflicts:
#	ChangeLog.md
#	src/Hangfire.Mongo/Hangfire.Mongo.csproj
Latest commit 508db7f Dec 13, 2018

README.md

Hangfire.Mongo

Build status Nuget version Nuget downloads GitHub license

MongoDB support for Hangfire library. By using this library you can store all jobs information in MongoDB.

Installation

To install Hangfire MongoDB Storage, run the following command in the Nuget Package Manager Console:

PM> Install-Package Hangfire.Mongo

Usage

public void Configuration(IAppBuilder app)
{
    GlobalConfiguration.Configuration.UseMongoStorage("<connection string>", "<database name>");

    app.UseHangfireServer();
    app.UseHangfireDashboard();
}

For example:

public void Configuration(IAppBuilder app)
{
    GlobalConfiguration.Configuration.UseMongoStorage("mongodb://localhost", "ApplicationDatabase");

    app.UseHangfireServer();
    app.UseHangfireDashboard();
}

Custom collections prefix

To use custom prefix for collections names specify it on Hangfire setup:

public void Configuration(IAppBuilder app)
{
    GlobalConfiguration.Configuration.UseMongoStorage("<connection string>", "<database name>",
        new MongoStorageOptions { Prefix = "custom" } );

    app.UseHangfireServer();
    app.UseHangfireDashboard();
}

Custom Mongo DB settings

To use custom Mongo DB connection settings you can use MongoClientSettings object from Mongo DB driver package. In this case just use it instead of passing connection string when you configure your storage.

public void Configuration(IAppBuilder app)
{
    GlobalConfiguration.Configuration.UseMongoStorage(new MongoClientSettings()
            {
                // ...
                IPv6 = true
            }, "ApplicationDatabase");

    app.UseHangfireServer();
    app.UseHangfireDashboard();
}

Naming Convention

Hangfire.Mongo will ignore any naming conventions configured by your application. E.g. if your application use camel casing like this:

  var camelCaseConventionPack = new ConventionPack { new CamelCaseElementNameConvention() };
  ConventionRegistry.Register("CamelCase", camelCaseConventionPack, type => true);

it will be ignored by Hangfire.Mongo and Pascal Case will be used instead. Of cause only for Hangfire specific collections.

Migration

We sometimes introduce breaking changes in the schema. For this reason we have introduced migration. Three migration strategies exists.

  • None

    This is the default migration strategy. It will throw an InvalidOperationException never letting you get up and running if there is a schema version mismatch. So it forces you to decide what migration strategy is best for you and at the same time keeps your data safe.

  • Drop

    This will simply just drop your existing Hangfire.Mongo database and update the schema version. No fuzz and ready to start from scratch. It is the perfect strategy if you e.g. enque all your jobs at startup.

  • Migrate

    This will migrate your database from one schema version to the next until the required schema version is reached. Chances are that not all data can be migrated, why some loss of data might occur. Please use with caution and thougoughly test before deploying to production. We are not responsible for data loss.

    NOTE: Only forward migration is supported. If you need to revert to a previous schema version, you need to manually drop or restore the previous database.

public void Configuration(IAppBuilder app)
{
    var migrationOptions = new MongoMigrationOptions
    {
        Strategy = MongoMigrationStrategy.Migrate,
        BackupStrategy = MongoBackupStrategy.Collections
    };
    var storageOptions = new MongoStorageOptions
    {
        // ...
        MigrationOptions = migrationOptions
    };
    GlobalConfiguration.Configuration.UseMongoStorage("<connection string>", "<database name>", storageOptions);

    app.UseHangfireServer();
    app.UseHangfireDashboard();
}

Migration Backup

By default a backup is made before attempting to migrate. You can backup Hangfire collections by "cloning" each collection to the same database. Or you can chose to copy the entire database. Alternatively you can just skip the backup. The backup can be customized using MongoMigrationOptions. NOTE: This software is made by humans in our sparetime - we do our best but will not be held responsible for any data loss.

Contributors

License

Hangfire.Mongo is released under the MIT License.