Skip to main content

RavenDB

RavenDB is a document-database provider. It supports both the Master database and Agent transport layers.

Install​

dotnet add package JobMaster.RavenDb

Configuration​

builder.Services.AddJobMasterCluster(config =>
{
    config.ClusterId("My-Cluster")
          .UseRavenDb("Urls=http://localhost:8080;Database=JobMaster");

    config.AddAgentConnectionConfig("RavenDb-1")
          .UseRavenDb("Urls=http://localhost:8080;Database=JobMaster");
});

The connection string is RavenDB's own Urls/Database shape, not an ADO-style string: Urls=<url1>,<url2>;Database=<name> (comma-separate multiple URLs for a multi-node cluster).

Options​

UseRavenDb takes the same optional parameters on both the master and agent overloads (document expiration is master-only):

config.UseRavenDb(
    "Urls=https://localhost:8080;Database=JobMaster",
    certificate: myClientCertificate,
    collectionPrefix: "myapp_jm_",
    enableDocumentExpiration: true,
    documentExpirationFrequency: TimeSpan.FromHours(2),
    requestTimeout: TimeSpan.FromSeconds(30),
    pooledConnectionLifetime: TimeSpan.FromMinutes(5),
    pooledConnectionIdleTimeout: TimeSpan.FromMinutes(2));

Client certificate authentication​

For secured RavenDB clusters, pass an already-loaded certificate — it can't be expressed as plain text in the connection string:

config.UseRavenDb(
    "Urls=https://localhost:8080;Database=JobMaster",
    certificate: new X509Certificate2("client.pfx", "password"));

Collection prefix​

By default, JobMaster creates collections with the JM_ prefix, to avoid colliding with unrelated data if the database is shared. Override it with collectionPrefix. This isn't for separating multiple clusters — the compound document ID (which embeds ClusterId) already does that.

Document expiration​

enableDocumentExpiration opts the master database into RavenDB's native document-expiration background job. It's a housekeeping extra, not required for correctness — JobMaster's own background sweeps already clean up what they need to on their own schedule, independent of this setting. Off by default because it's a database-wide RavenDB setting, not scoped to JobMaster's own collections, and could conflict with an operator already managing expiration for other data in a shared database.

documentExpirationFrequency controls how often that sweep runs once enabled (default: 1 hour).

Connection tuning: requestTimeout, pooledConnectionLifetime, pooledConnectionIdleTimeout​

Three options for tuning RavenDB's HTTP behavior under load, all optional and left unset by default (RavenDB.Client's / .NET's own defaults apply):

  • requestTimeout — overrides RavenDB.Client's own default HTTP request timeout for every operation on this connection. Left unset, RavenDB.Client falls back to a very generous 12-hour ceiling, not a meaningful per-request timeout in practice.
  • pooledConnectionLifetime — forces the underlying HTTP connection pool to proactively recycle a connection after this long, regardless of activity. Left unset, .NET never proactively recycles a pooled connection, which can let one sit idle long enough for the server to have already closed its end — surfacing as a client-side "Connection reset by peer" on next reuse. If you see that error under sustained load, this is the setting most likely to help.
  • pooledConnectionIdleTimeout — closes a pooled connection that's been idle this long.
netstandard2.0

pooledConnectionLifetime/pooledConnectionIdleTimeout have no effect when running on netstandard2.0 — the underlying SocketsHttpHandler APIs they rely on aren't available on that target framework, so they're silently ignored there. requestTimeout works on both target frameworks.

JSON configuration​

Via ConfigFromJson, the same options are available under connectionOptions:

{
  "repoType": "RavenDB",
  "connectionString": "Urls=http://localhost:8080;Database=JobMaster",
  "connectionOptions": {
    "certificateFile": "client.pfx",
    "certificatePassword": "secret",
    "collectionPrefix": "myapp_jm_",
    "enableDocumentExpiration": "true",
    "documentExpirationFrequencySeconds": "7200",
    "requestTimeoutMs": "30000",
    "pooledConnectionLifetimeMs": "300000",
    "pooledConnectionIdleTimeoutMs": "120000"
  }
}

certificateFile/certificatePassword, collectionPrefix, and requestTimeoutMs/pooledConnectionLifetimeMs/pooledConnectionIdleTimeoutMs are available on both master and agent connections. enableDocumentExpiration/documentExpirationFrequencySeconds are master-only — setting them on an agent connection throws at startup.