Persistence and signals

The engine keeps instances, tasks, task events, runtime state, signals, dead letters, stored definitions and the Designated Workflow ledger in one store. This page describes the two stores, PostgreSQL and MongoDB, the signal drivers that wake the signal pump, and running several nodes on one store.

Choosing a store

PostgreSQLMongoDB
PackageStellaOps.Workflow.DataStore.PostgreSQL (in StellaOps.Workflow)StellaOps.Workflow.DataStore.MongoDB
WorkflowBackend:ProviderPostgres (the default)Mongo
ConnectionSTELLAOPS_POSTGRES_WORKFLOW_CONNECTIONConnectionStrings:WorkflowMongo
SchemaThe workflow schema, created at startThe collections, created at first use
Native signal wake-upLISTEN/NOTIFYChange streams

Register the store library after the engine. Each store library registers itself only when WorkflowBackend:Provider names it, so a host can register both and choose by configuration:

/// <summary>
/// Both store libraries are registered; WorkflowBackend:Provider ("Postgres" or "Mongo") decides which
/// one takes effect, so one build serves either store.
/// </summary>
public static IServiceCollection AddWorkflowStores(this IServiceCollection services, IConfiguration configuration)
{
    services.AddWorkflowEngineCoreServices(configuration);
    services.AddWorkflowPostgresDataStore(configuration);
    services.AddWorkflowMongoDataStore(configuration);
    services.ValidateWorkflowProviderRegistrations(configuration);
    return services;
}

PostgreSQL

Connection

The store reads its connection string from one key, STELLAOPS_POSTGRES_WORKFLOW_CONNECTION, from any configuration source. Without it the host stops at start with an error that names the key; there is no fallback to ConnectionStrings.

STELLAOPS_POSTGRES_WORKFLOW_CONNECTION="Host=db.contoso.example;Port=5432;Database=workflow;Username=workflow_app;Password=<password>;SSL Mode=VerifyFull"

Pool settings are in WorkflowBackend:Postgres (MinPoolSize 1, MaxPoolSize 100, Pooling, ConnectionIdleLifetimeSeconds 300, ApplicationName stellaops-workflow).

Schema and permissions

At start, the store applies its schema script: it creates the workflow schema, its tables and a workflow.schema_migrations table that records the applied script. The schema name and the table names are fixed.

PhaseThe role needs
First startCREATE on the database (to create the schema), or ownership of a workflow schema that an administrator created for it
Every startOwnership of the workflow schema, so the script can check and extend it
RunningRead and write on the tables of the workflow schema

To keep schema changes with your database administrator, turn the startup migration off and apply the script yourself:

/// <summary>The schema script is applied by the database administrator, not by the host.</summary>
public static IServiceCollection AddWorkflowStoreWithManagedSchema(this IServiceCollection services, IConfiguration configuration)
{
    services.AddWorkflowEngineCoreServices(configuration);
    services.AddWorkflowPostgresDataStore(configuration, options => options.ApplyMigrationsOnStartup = false);
    return services;
}

The script is embedded in the StellaOps.Workflow.Persistence assembly as StellaOps.Workflow.Persistence.Migrations.001_workflow_schema.sql. It is idempotent (CREATE ... IF NOT EXISTS). Apply the script of the package version you install before you start that version.

Tables

ClassTablesLifetime
Operational stateInstances, tasks, task events, runtime states, and the durable-execution tablesPurged by the retention job after completion (Operations)
Source of truthDefinitions, definition audit, signal queue, dead letters, wake outbox, host locks, the first-seen ledgerChanged only by the operation the row describes; never deleted by age

The first-seen ledger (wf_first_seen_workflows) is insert-only: a trigger refuses updates and deletes.

MongoDB

{
  "WorkflowBackend": {
    "Provider": "Mongo",
    "Mongo": { "DatabaseName": "workflow" }
  },
  "ConnectionStrings": {
    "WorkflowMongo": "mongodb://workflow-app:<password>@mongo-1.contoso.example,mongo-2.contoso.example/?replicaSet=rs0&tls=true"
  }
}

Signals and the signal pump

A step that waits leaves a signal in the store: a timer, a task deadline, an external signal, the end of a child workflow, or the start of a ContinueWith workflow. The signal pump (AddWorkflowEngineHostedServices) claims due signals and resumes their instances. Timers, external signals and task deadlines run on the Stella.Engine runtime provider, the default (Hosting).

SettingDefaultEffect
WorkflowEngine:MaxConcurrentSignalHandlersprocessor countPump workers per node
WorkflowAq:MaxDeliveryAttempts10Attempts before a signal is dead-lettered
WorkflowBackend:Postgres:BlockingWaitSeconds30The longest wait of a worker for a wake-up before it checks the store again
WorkflowBackend:Postgres:ClaimTimeoutSeconds60The claim lease; a claim not completed within it becomes claimable again
WorkflowBackend:Mongo:BlockingWaitSeconds, ClaimTimeoutSeconds30, 60The same two settings for the MongoDB store

A signal is processed at least once. A signal whose wait is gone, a duplicate for example, is ignored, so a duplicate never applies twice; a signal that is applied again runs the steps after its wait again, service calls included. A signal whose processing keeps failing is moved to the dead letters after MaxDeliveryAttempts (Operations). The store keeps the delivery count with the signal and raises it at each claim, so the limit counts every delivery on every node, before and after a restart; a replayed dead letter starts again from zero.

Signal drivers

The signal driver wakes the pump workers when a signal becomes due, so that they do not wait for BlockingWaitSeconds.

WorkflowSignalDriver:ProviderWake-upUse
Native (default)PostgreSQL LISTEN/NOTIFY, or MongoDB change streamsOne store, any number of nodes
RedisA Redis channelMany nodes when the database should not carry the notifications

With Redis, the signals stay in the store; only the wake-up travels through Redis. The host provides the Redis connection, and AddWorkflowRedisSignaling registers everything else:

/// <summary>
/// Redis carries the wake-up notifications between nodes (WorkflowSignalDriver:Provider = "Redis"); the
/// signals themselves stay in the store. The host provides the Redis connection; the driver announces
/// each stored signal on the Redis channel once the store's transaction commits.
/// </summary>
public static IServiceCollection AddWorkflowRedisWakeUps(this IServiceCollection services, IConfiguration configuration)
{
    services.AddSingleton<IConnectionMultiplexer>(_ =>
        ConnectionMultiplexer.Connect(configuration["Redis:Configuration"]
            ?? throw new InvalidOperationException("Set Redis:Configuration.")));
    services.AddWorkflowRedisSignaling(configuration);
    return services;
}
{
  "WorkflowSignalDriver": {
    "Provider": "Redis",
    "Redis": { "ChannelName": "contoso:workflow:signals", "BlockingWaitSeconds": 30 }
  },
  "Redis": { "Configuration": "redis.contoso.example:6380,ssl=true,password=<password>" }
}

The driver announces each stored signal on the Redis channel once the store’s transaction commits, so a waiting pump worker claims it at once. A worker that receives no announcement looks at the store again after BlockingWaitSeconds (default 30). A timer is announced when it is scheduled, not when it falls due, so a due timer can start up to BlockingWaitSeconds late; lower the value when timers must be prompt.

Several nodes

Any number of nodes can share one store:

Pitfalls