Configuration

FCQRS starts from an embedded Akka.NET configuration and merges application configuration over it. This page lists the defaults, FCQRS runtime keys, persistence providers, and the settings required to move from one local process to a cluster.

Minimal configuration

Fcqrs.connect supplies the persistence provider and connection string. An empty IConfiguration accepts the rest of the embedded defaults:

open FCQRS.FSharp

let connection = Fcqrs.connect FCQRS.Actor.DBType.Sqlite "Data Source=app.db;"

// An empty IConfiguration accepts the embedded Akka.NET defaults.
let config = Microsoft.Extensions.Configuration.ConfigurationBuilder().Build()
let loggerFactory = Microsoft.Extensions.Logging.LoggerFactory.Create(fun _ -> ())

let api = Fcqrs.actor config loggerFactory (Some connection) "MyCluster"

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFcqrs(
    connectionString: "Data Source=app.db;",
    clusterName: "MyCluster");

The supported DBType values are listed in Configure the database. The C# host-builder overload creates the same setup with SQLite.

What the defaults set up for you

The embedded configuration provides:

• a SQL journal for persisted events;
• a SQL read journal consumed by projections;
• a SQL snapshot store;
• automatic persistence-table initialization;
• FCQRS and Akka.NET serializers;
• the Akka.NET cluster actor provider and distributed pub/sub;
• cluster sharding with remembered entities;
• a localhost transport on a dynamic port;
• a one-node cluster formed by joining the process to itself.

The query journal polls for new events every 100 ms by default. Those persistence-plugin settings may be overridden with HOCON.

FCQRS runtime keys

The .NET configuration path uses colons. The equivalent HOCON path uses nested objects.

The two timeout keys share one unit rule: a bare number means seconds. command-timeout also accepts HOCON durations such as 500ms or 1m (beware: a bare number would mean milliseconds to HOCON's duration parser — FCQRS parses bare numbers as seconds deliberately, matching saga-start-timeout). The command timeout is an idle timeout: receiving a non-matching event on the same correlation topic restarts it. Correlation topics are quiet in practice, but it is not a hard deadline. The same key bounds the projection wait in the F# facade's sendAwaiting: a projection that suppresses the matching notification raises TimeoutException instead of hanging the caller.

The notification buffer is not a durable queue. Notifications without an active subscriber may be dropped, which is correct for the request-scoped read-your-writes mechanism.

The saga-start handshake is synchronous, so each concurrent start holds the thread its aggregate runs on until the starter acknowledges. The saga starter therefore raises the CLR thread pool's minimum worker count to cover the handshakes it has outstanding, up to max-worker-threads. A minimum is a floor rather than a reservation: threads are created only as work demands them, so raising the ceiling costs nothing until a burst of saga starts arrives. The floor is captured once per process and only ever raised, never lowered or restored.

max-worker-threads is a real limit, not a tuning hint. Past it, saga-start handshakes time out and fail-fast the process, exactly as they did before the floor was adaptive. On a 12-core machine at the default ceiling, 1000 simultaneous saga starts across distinct aggregate instances complete and 1500 do not. The starter logs a warning the first time demand exceeds the ceiling, and an error if the runtime refuses the raise outright (a lower process maximum). Values below the captured baseline are ignored — the floor is never lowered. This bounds concurrent saga starts, not command throughput: commands to one aggregate serialize through one entity. See Sagas: durable coordination for why the handshake blocks.

Snapshot policy resolves in this order:

1. the aggregate or saga's Every n or NoSnapshots setting;
2. the C# builder's WithDefaultSnapshotPolicy value;
3. config:akka:persistence:snapshot-version-count;
4. the fallback value 30.

See Deferring, snapshots, and passivation before tuning the cadence. A snapshot changes replay cost, not the events that define recoverable state.

Set config:akka:scheduler to FCQRS's ObservingScheduler only in tests that control delayed saga commands with a virtual clock.

Overriding with HOCON

Application configuration is added after the embedded HOCON, so matching application keys win. The example below overrides the three SQLite persistence stores explicitly:

config {
  connection-string = "Data Source=app.db;"
  akka {
    persistence {
      journal.sql {
        connection-string = ${config.connection-string}
        provider-name = "SQLite.MS"
        auto-initialize = true
      }
      query.journal.sql {
        connection-string = ${config.connection-string}
        provider-name = "SQLite.MS"
        auto-initialize = true
      }
      snapshot-store.sql {
        connection-string = ${config.connection-string}
        provider-name = "SQLite.MS"
        auto-initialize = true
      }
    }
  }
}

Load the file with ConfigurationBuilder().AddHoconFile("config.hocon").Build() and pass the result to Fcqrs.actor, or add the same keys through another IConfiguration provider.

When overriding the database provider, change the journal, query journal, and snapshot store together. Pointing them at different databases is possible but changes backup, recovery, and availability behaviour and should be an explicit design choice.

Logging and diagnostics

FCQRS emits a message-flow log through ILogger and spans through ActivitySource. Configure payload visibility before handling sensitive data. Observe your system lists the categories, source names, switches, and fatal-flush hook.

Akka.NET internal logging defaults to OFF; FCQRS application-flow logs still use the supplied ILoggerFactory. Enable Akka.NET internals with builder.WithAkkaLogging(AkkaLogLevel.Info) from the hosting builder, or set config:akka:loglevel in your IConfiguration.

Scaling to a cluster

The default node listens on localhost and joins itself. A multi-node deployment must override the remote hostname and port and configure seed-node discovery or another Akka.NET bootstrap mechanism. Every node must reach the shared journal and use compatible serializers and event contracts.

Cluster sharding routes an aggregate or saga id to its current node, so domain definitions do not change. Before deploying several nodes, verify rolling-version compatibility, shared storage, node discovery, coordinated shutdown, and monitoring for cluster membership and unreachable nodes.

The production tutorial provides the operational checklist.