Skip to main content
The application database migration utility enables admin users to move the CData Arc 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 Arc 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.
  7. Add the connection string to your configuration. The steps depend on your platform:
    • Cross-Platform: Add the string to your configuration (see Configure the Cross-Platform Application Database). After you update the configuration to point to the new database, restart Arc.
    • .NET: When the migration completes, Arc remains in Safe Mode until the new connection string is applied and Arc restarts. Background services stay stopped, and files and transactions are not processed. Click Copy to copy the connection string, then update the AppDb entry in Web.Config:
      1. Open Web.Config and locate the <connectionStrings> section (be sure to uncomment the section).
      2. Add or replace the AppDb entry with the following, where <ConnectionString> is the connection string you copied:
        This example uses PostgreSQL. For SQL Server, set providerName to System.Data.CData.SQL. For MySQL, set it to System.Data.CData.MySQL. For more information, see Configure the .NET Application Database.
      3. Save Web.Config. Arc restarts automatically, so you do not need to restart it manually.

​
Safe Mode Behavior

When the migration begins, Arc 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 Arc process terminates unexpectedly during migration, the migration state is persisted in the backend database. On restart, Arc 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.