Skip to main content
The application database migration utility enables admin users to move the backend application data from the embedded database to an external database. The migration engine includes a source-database router that auto-detects the embedded database, then handles the migration. The embedded database varies by platform:
  • Cross-Platform: H2
  • .NET: SQLite
Embedded database limitations such as performance at scale and limits on concurrent access are common reasons why you might want to use this utility. The following external databases are supported targets:
  • SQL Server
  • MySQL
  • PostgreSQL
The migration moves all tables from the backend database to the target database, including tables such as the following:
  • Transaction logs
  • Message logs
  • Audit logs
  • Connector state
  • SLA status data
  • General application data
Before you begin, consider the timing of your migration, because the mandatory Safe Mode blocks all file processing. You might want to run the process during a planned maintenance window.

​
Migrate the Application Database

To launch the utility, navigate to Settings > Advanced, scroll to the Migration section and select Application Database Migration.
  1. Application database migration is not supported in high availability (HA) deployments. You must stop any other nodes and acknowledge that all other nodes are stopped before you can continue. Check I understand all other HA nodes must be stopped, then click Next.
  2. You must be in Safe Mode to continue the migration process. This disables all background services, stops all connectors, and blocks inbound endpoints to ensure data integrity throughout the migration process. Click Enter Safe Mode.
  3. Click Select Database, choose your target database type from the list above, then provide the connection details for the target database.
  4. Click Test Connection to validate the connection.
  5. Click Begin Migration. Data is migrated table by table. Migration time is based on data volume and can take anywhere from a few minutes to several hours.
  6. Once the migration completes successfully, you are given a connection string. Add that string to your configuration (see Configure the Cross-Platform Application Database or Configure the .NET Application Database for platform-specific information).
  7. After you update the configuration to point to the new database, restart .

​
Safe Mode Behavior

When the migration begins, enters Safe Mode, which affects the entire application by putting it into a state where nothing can be written to the current database:
  • All connectors are stopped, which means no send or receive file processing.
  • Background services are paused, including automation, SLA monitoring, connector monitoring, scheduled reports, disk space monitoring, and so on.
  • Inbound endpoints are blocked, which means that API requests, webhooks, Flow API calls, SFTP server connections, and email inbox all return errors.
  • The UI is restricted: all logged-in users see a Safe Mode Active message, which prevents them from performing normal operations until the migration is complete.
  • Admin users have access to the Start, Abort, and Monitor Progress migration controls.
  • Non-admin users see the Safe Mode status but cannot manage the migration in any way. Connection string details are redacted.

​
Recovery and Resilience

  • Crash recovery: If the process terminates unexpectedly during migration, the migration state is persisted in the backend database. On restart, detects the incomplete migration so you can resume from where it left off instead of starting over.
  • Background services remain paused during recovery until you explicitly complete or cancel the migration.