# Persistence

Persistence connects Workflow Engine to a database through separate contracts for runtime process data and workflow scheme
data. [Workflow Runtime](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/) uses
`IPersistenceProvider` for [process instances](https://docs.workflowengine.io/get-started/concepts/process-instance/), statuses,
persisted [parameters](https://docs.workflowengine.io/get-started/concepts/parameter/), [timers](https://docs.workflowengine.io/get-started/concepts/timer/), transition history, global parameters, and
runtime coordination records. The workflow builder uses
`ISchemePersistenceProvider<TSchemeMedium>` to load and save
[scheme definitions](https://docs.workflowengine.io/get-started/concepts/scheme/). Workflow Engine ships
[six database providers](https://workflowengine.io/features/multi-database/): SQL Server, PostgreSQL, MySQL, Oracle, MongoDB, and SQLite.

## What Persistence is

A persistence provider is a database adapter that implements the storage contracts required by Workflow Engine. `IPersistenceProvider`
covers runtime records, while
`ISchemePersistenceProvider<TSchemeMedium>` covers source and built schemes used by the workflow builder. The built-in providers implement
`IWorkflowProvider`, which combines both persistence contracts with XML scheme generation.

The persistence contracts cover these relationships:

- The workflow builder loads and saves source and built
  [schemes](https://docs.workflowengine.io/get-started/concepts/scheme/) through the scheme persistence contract.
- [Process instances](https://docs.workflowengine.io/get-started/concepts/process-instance/) are initialized, read, updated, and deleted through the runtime persistence
  contract.
- Persisted [parameters](https://docs.workflowengine.io/get-started/concepts/parameter/) are loaded and saved per process instance.
- [Timers](https://docs.workflowengine.io/get-started/concepts/timer/) are registered, queried, and removed through the runtime persistence contract.
- Transition history can be recorded through the provider when history persistence is enabled.

## How Persistence works

Each supported database has a separate provider project and NuGet package. You choose the provider that matches the database and configure
it for both the workflow builder and Workflow Runtime. The shipped `IWorkflowProvider` implementations support both persistence roles.

Relational database schema setup is separate from provider configuration. SQL Server, PostgreSQL, MySQL, Oracle, and SQLite providers
integrate with `OptimaJet.Workflow.Migrator`, whose
`RunMigrations()` method applies pending migrations. Applications can apply the provider SQL scripts separately instead. Configuring a
provider does not run migrations automatically.

## Persistence and Workflow Runtime

Workflow Runtime executes and manages workflows, while Persistence stores the data required across runtime calls and application restarts.
Runtime operations use `IPersistenceProvider` to initialize, load, update, and delete process data.

`WithPersistenceProvider(...)` assigns the runtime provider and initializes it with the current Workflow Runtime. The workflow builder
receives its scheme persistence provider separately. A built-in provider object can fill both roles because it implements
`IWorkflowProvider`.

## See also

- [Workflow Runtime](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/): Workflow Runtime uses runtime persistence for stored process data.
- [Scheme](https://docs.workflowengine.io/get-started/concepts/scheme/): The workflow builder loads and saves schemes through the scheme persistence contract.
- [Process Instance](https://docs.workflowengine.io/get-started/concepts/process-instance/): Persistence stores the current data and status of each process instance.
- [Framework-Agnostic Install](https://docs.workflowengine.io/get-started/framework-agnostic-install/): Configure a database provider, workflow builder, migrations, and Workflow Runtime.

## Frequently asked questions

**Which databases does Workflow Engine support?**

SQL Server, PostgreSQL, MySQL, Oracle, MongoDB, and SQLite. Each has a separate NuGet provider package.

**Can I switch databases after I have running process instances?**

Configuring Workflow Runtime and the workflow builder with a different provider changes the database they use but does not transfer existing
records. Moving to another database requires migrating the relevant schemes and process data before the application uses the new provider.

**Does Workflow Engine create its database tables automatically?**

No. Configuring a persistence provider does not create or update relational tables. Run `RunMigrations()` from `OptimaJet.Workflow.Migrator`
or apply the provider SQL scripts separately.