Configuration Options

DurableStack configuration lives under the DurableStack section.

Use ConnectionStrings only if your app prefers storing database connection strings there, then copy/bind those values into DurableStack:Postgres:ConnectionString (or the provider equivalent) in your startup logic.

Top-level options (DurableStack:*)

• StorageProvider: backing store selection (InMemory, Postgres, SqlServer, Sqlite, MySql). Default: InMemory.
• WorkerName: unique worker identity used for leasing and diagnostics. Default: "{HOSTNAME-or-machine}-{processId}".
• DatabaseTablePrefix: optional prefix for durable database objects. Default: null.
• PollIntervalSeconds: worker polling cadence in seconds (<= 0 resets to default). Default: 5.
• PollJitterEnabled: enables poll jitter for claim loops. Default: true.
• PollJitterRatio: jitter ratio used for poll timing when poll jitter is enabled. Default: 0.2.
• BatchSize: max runs leased per poll cycle. Default: 50.
• LeaseDurationSeconds: lease TTL in seconds (<= 0 resets to default). Default: 30.
• RetryDelay: base retry delay (TimeSpan format in config binding). Default: 00:00:05.
• RetryMaxDelay: maximum retry backoff (TimeSpan format in config binding). Default: 01:00:00.
• RetryJitterEnabled: enables retry jitter. Default: false.
• RetryJitterRatio: jitter ratio used when jitter is enabled. Default: 0.2.
• JobActivation: job activation mode (ScopedPerExecution, RootProvider). Default: ScopedPerExecution.

Provider connection options

Set the matching section for the selected StorageProvider:

• Postgres:ConnectionString (default: "")
• SqlServer:ConnectionString (default: "")
• Sqlite:ConnectionString (default: "")
• MySql:ConnectionString (default: "")

If a durable provider is selected and the corresponding connection string is empty, startup throws.

Recurring options (DurableStack:Recurring:*)

• CatchUpPolicy: missed-slot behavior (SkipMissed, CatchUp). Default: SkipMissed.

Registration sync (DurableStack:Recurring:RegistrationSync:*)

• ExistingJobBehavior: when recurring definitions already exist in storage (KeepDatabase, UpdateFromCode). Default: KeepDatabase.
• OrphanedJobBehavior: when a DB recurring definition no longer exists in code (Disable, Ignore). Default: Disable.

Retention options (DurableStack:Retention:*)

• Enabled: enables terminal-run cleanup. Default: true.
• RunRetentionSeconds: run retention window in seconds. Default: null (effective default is 3600 for in-memory, 86400 for durable stores).
• SweepIntervalSeconds: cleanup sweep cadence in seconds (<= 0 resets to default). Default: 300.
• DeleteBatchSize: max rows deleted per sweep batch (<= 0 resets to default). Default: 1000.

Job registration options (DurableStack:JobRegistration:*)

• AutoDiscoverJobsFromAssembly: auto-register public IDurableJob/IDurableJob<TArgs> classes from the app assembly. Default: true.

Eventing options (DurableStack:Eventing:*)

• TenantId: tenant ID for hosted ingestion auth. Default: null.
• ClientSecret: client secret for hosted ingestion auth. Default: null.
• IngestionApiBaseUrl: ingestion API base URL. Default: https://api.durablestack.com.
• IngestionPath: ingestion API path. Default: /v1/events/batch.
• IngestionMaxBatchSize: max events per post. Default: 100.
• IngestionMaxRequestBodyBytes: max request body size. Default: 1000000.
• IngestionMaxRetryAttempts: max retries for failed ingestion posts. Default: 5.
• IngestionFlushIntervalSeconds: flush cadence in seconds (<= 0 resets to default). Default: 5.
• IncludeErrorDetail: includes captured error details in event payloads. Default: false.
• MaxErrorDetailLength: max captured error-detail length (<= 0 resets to default). Default: 4096.

Event ingestion is automatically enabled when both TenantId and ClientSecret are set. When enabled, the runtime includes runtime information in posted ingestion data.

Example

{
  "DurableStack": {
    "StorageProvider": "Postgres",
    "WorkerName": "orders-api-1",
    "DatabaseTablePrefix": "prod_",
    "PollIntervalSeconds": 5,
    "BatchSize": 50,
    "LeaseDurationSeconds": 30,
    "RetryDelay": "00:00:05",
    "RetryMaxDelay": "01:00:00",
    "PollJitterEnabled": true,
    "PollJitterRatio": 0.2,
    "RetryJitterEnabled": false,
    "RetryJitterRatio": 0.2,
    "JobActivation": "ScopedPerExecution",
    "Postgres": {
      "ConnectionString": "Host=localhost;Port=5432;Database=durable_stack;Username=postgres;Password=postgres"
    },
    "Recurring": {
      "CatchUpPolicy": "SkipMissed",
      "RegistrationSync": {
        "ExistingJobBehavior": "KeepDatabase",
        "OrphanedJobBehavior": "Disable"
      }
    },
    "Retention": {
      "Enabled": true,
      "RunRetentionSeconds": 86400,
      "SweepIntervalSeconds": 300,
      "DeleteBatchSize": 1000
    },
    "JobRegistration": {
      "AutoDiscoverJobsFromAssembly": true
    },
    "Eventing": {
      "TenantId": "tenant_...",
      "ClientSecret": "secret_...",
      "IngestionApiBaseUrl": "https://api.durablestack.com",
      "IngestionPath": "/v1/events/batch",
      "IngestionMaxBatchSize": 100,
      "IngestionMaxRequestBodyBytes": 1000000,
      "IngestionMaxRetryAttempts": 5,
      "IngestionFlushIntervalSeconds": 5,
      "IncludeErrorDetail": false,
      "MaxErrorDetailLength": 4096
    }
  }
}