Multi-Database Support
Workflow Engine ships persistence providers for SQL Server, PostgreSQL, MySQL, MongoDB, Oracle, and SQLite, each a separate NuGet package. The five SQL providers create and upgrade their schema through RunMigrations(); the MongoDB provider has no migrations and needs its indexes created once. Choose the database before the first production deployment: switching providers after process instances exist is not supported. A persistence provider is required for the runtime to function.
Workflow Engine requires a database to run. Every process instance, timer, scheme definition, and history record is stored in a persistence provider. The choice is not whether to use a database - it is which database to use. The runtime survives restarts, multiple servers coordinate through the same database, and you pick the database your organization already manages. For example, an organization standardized on PostgreSQL installs the PostgreSQL provider, calls RunMigrations() to create the schema, and the runtime begins persisting instances, timers, and history - without writing a single migration script.
What it is
Think of a universal power adapter. It has the same plug on one end (your application) and interchangeable connectors on the other end (the database). Multi-database support works the same way: WorkflowRuntime talks to a provider interface, and the provider translates those calls into native SQL (or document queries) for your chosen database.
Workflow Engine ships providers for six databases: SQL Server, PostgreSQL, MySQL, MongoDB, Oracle, and SQLite. Each provider is a separate NuGet package - you install only the one for your database. Every built-in provider implements IWorkflowProvider, which combines runtime data persistence with XML scheme persistence and generation. Switching databases means changing the NuGet package and connection string - your application code does not change.
The five SQL providers include schema management. RunMigrations() creates the tables, indexes, and procedures and, after an upgrade, applies only the pending migrations. The MongoDB provider has no migrations: it creates its collections and lock records on first start, and its indexes come from a script.
For developers: Install the NuGet package for your database. The package IDs follow the pattern WorkflowEngine.NETCore-ProviderFor{Name} - for example, WorkflowEngine.NETCore-ProviderForMSSQL or WorkflowEngine.NETCore-ProviderForPostgreSQL. Register the provider with WorkflowRuntime, call RunMigrations(), and the schema is created for SQL providers.
Why it matters
Multi-database support delivers these outcomes:
- Choose your existing database - Use the database your operations team already manages. No need to introduce a new database platform just for workflow state. Every provider speaks the same interface; switching requires only package and connection string changes.
- Automatic schema management for SQL providers - Call
RunMigrations()once during startup. Tables, indexes, and procedures are created automatically, and version upgrades apply only the migrations you need. MongoDB has no migrations. - Clustering enabled - The persistence provider is the shared state that lets multiple
WorkflowRuntimeinstances coordinate as a cluster. Each instance reads and writes through the same database, distributing timer execution and respecting instance locks. - Extensible to unsupported databases - The provider interfaces are public. If your database is not among the six built-in options, implement
IWorkflowProviderand register the custom provider with the runtime.
Who it is for
Developer: Install one NuGet package, register the provider, and call RunMigrations() for a SQL provider. Application code uses the same WorkflowRuntime API regardless of which database is underneath.
Enterprise architect: The provider layer enforces a consistent data contract across all supported databases. Five of the six providers (SQL Server, PostgreSQL, MySQL, Oracle, SQLite) implement IMigratable for managed schema evolution. The MongoDB provider uses a document model with the same schema contract.
When to use it
Use a persistence provider in every Workflow Engine deployment - a provider is required for the runtime to function. The choice is which database to use. Typical scenarios:
- Standardize on your existing database - Your organization runs PostgreSQL for all application data. Install the PostgreSQL provider, call
RunMigrations(), and use the same database infrastructure for workflow state. No new database platform required. - Evaluation and local development - SQLite needs no database server, which suits a trial or a developer machine. It is not recommended for production workloads.
- Clustered production deployment - Multiple application servers run Workflow Engine in a cluster. All instances connect to the same SQL Server or PostgreSQL database, using the persistence provider as the coordination layer for timers and instance locks.
- Custom or unsupported database - Your organization uses a database not in the six built-in providers. Implement
IWorkflowProviderfor your database and register the custom class withWorkflowRuntime. The runtime treats it identically to a built-in provider.
How it compares
The table below compares Workflow Engine's persistence provider approach with alternatives for managing workflow state.
| Approach | What it requires | Result |
|---|---|---|
| Built-in persistence providers | Install one NuGet package, register the provider, call RunMigrations() | Automatic schema management, clustering support, same API across all six databases |
| Custom persistence provider | Implement IWorkflowProvider for your database and use it with WorkflowBuilder and WorkflowRuntime | Full control over storage, same runtime API, manual maintenance of provider code |
Workflow Engine ships providers for six databases. If you need a database not in this list, implement the public IWorkflowProvider interface.
Frequently asked questions
Which databases does Workflow Engine support for persistence?
Six databases: SQL Server, PostgreSQL, MySQL, MongoDB, Oracle, and SQLite. Each package provides a class that implements IWorkflowProvider. The NuGet package IDs use the format WorkflowEngine.NETCore-ProviderFor{Name}.
Can I switch databases while process instances are running?
No. Switching the persistence provider after process instances exist is not supported. Each provider stores runtime data in its native format, and there is no cross-provider migration tool. Choose your database before the first production deployment.
Does the provider create database tables automatically?
For SQL providers, yes. The runtime's RunMigrations() method creates all required tables, indexes, and procedures during startup. On subsequent runs, it detects the current schema version and applies only pending migration steps. MongoDB has no migrations: create its indexes with indexes.js, as the setup steps above show.
Can I use a different database for different runtime instances?
Yes. Each WorkflowRuntime instance is configured with one persistence provider. You can configure different instances with different providers - for example, a development instance with SQLite and a production instance with PostgreSQL - by changing the provider registration and connection string.
Can I implement a custom provider for an unsupported database?
Yes. Implement IWorkflowProvider for your database and register the provider with WorkflowRuntime. The source of the six built-in providers is in the Providers folder of the optimajet/WorkflowEngine.NET repository and can serve as a reference.
Do I need a specific license for multi-database support?
No. The persistence providers are part of the core runtime, so no license adds or removes them, and Workflow Engine Free has them too. See Workflow Engine Editions for licensing details.