Multi-Database Support
Workflow Engine ships persistence providers for six databases: SQL Server, PostgreSQL, MySQL, MongoDB, Oracle, and SQLite. Each provider implements IPersistenceProvider and supports automatic schema migration via RunMigrations(). Switching databases means changing the NuGet package and connection string - application code does not change. 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 provider implements the same IPersistenceProvider interface. Switching databases means changing the NuGet package and connection string - your application code does not change.
Each provider includes automatic schema management. Calling RunMigrations() on the runtime creates all required tables, indexes, and procedures. When you upgrade Workflow Engine, the same method detects the current schema version and applies only the pending migrations. You do not write migration scripts or track schema versions manually.
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 automatically. See the Persistence Providers page for installation steps.
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 - Call
RunMigrations()once during startup. Tables, indexes, and procedures are created automatically. Version upgrades apply only the migrations you need - no manual SQL scripting. - 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
IPersistenceProviderinterface is public. If your database is not among the six built-in options, implement the interface and register the custom provider with the runtime.
Who it is for
Evaluator (CEO, CTO, PM): Multi-database support means Workflow Engine fits into your existing infrastructure. If your organization runs PostgreSQL, use the PostgreSQL provider. If you are on SQL Server, use the SQL Server provider. The runtime does not dictate your database choice.
Developer: Install one NuGet package, register the provider, call RunMigrations(). 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. - Embedded or local deployment - A desktop application or single-server deployment uses SQLite for lightweight persistence with no database server setup. The provider runs as a file-based database.
- 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
IPersistenceProviderfor 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 IPersistenceProvider for your database and register it with the runtime | Full control over storage, same runtime API, manual maintenance of provider code |
Workflow Engine ships providers for the six most-requested databases. If you need a database not in this list, the IPersistenceProvider interface is public for custom implementations.
Frequently asked questions
Which databases does Workflow Engine support for persistence?
Six databases: SQL Server, PostgreSQL, MySQL, MongoDB, Oracle, and SQLite. Each has its own NuGet package and implements IPersistenceProvider. 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?
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. You do not need separate SQL scripts.
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. The IPersistenceProvider interface is public. Implement the required methods for your database and register the provider with WorkflowRuntime. All six built-in providers are open-source implementations you can use as reference.
Do I need a specific license for multi-database support?
No. The persistence providers are part of the core runtime and available in all editions. See Workflow Engine Editions for licensing details.