Documentation:MDriven Backup & Restore Guide

MDriven Backup & Restore Guide

This page was created by Charles on 2025-11-11. Last edited by Wikiadmin on 2026-07-29.

You can create a recoverable restore point before upgrading MDriven Server, Turnkey, or a deployed model by saving the Admin DB, the currently running model, and the model data export.

Create these backups before you upload a changed model or upgrade MDriven Server or Turnkey. Keep the three artifacts together and label them with the application, environment, and backup date; for example, Sales-Production-2026-07-28.

What you need to back up

MDriven separates server administration information from the business data used by the application. A complete restore point contains all of the following.

Backup artifact	What it contains	How you create it	When you use it
Admin DB snapshot	The model and its metadata, MDriven Server user accounts, roles, and access rights. The built-in Admin DB file can be `DatabaseVistaDB.vdb6` or `DatabaseCompact.sdf`.	Create a snapshot and download it from the Cloud Connection dialog, on Admin DB Access and Swap.	Restore the server administration database, including its stored model and server users.
Running model copy	The version of the model currently deployed to MDriven Server.	Keep a local copy of that model, or download the model from MDriven Server when you are unsure which version is running.	Upload the matching model before restoring exported model data.
Model data XML export	The application business data handled through the model.	Use the MDriven Server migration window in MDriven Designer to download the data as an XML file.	Restore application data into a compatible deployed model.

The Admin DB snapshot is not a substitute for the model data XML export. For example, restoring an Admin DB snapshot can restore MDriven Server users and the stored model, while restoring the XML export reloads the business objects that users created in the application.

Before you start

Plan a maintenance window. Snapshot and upload operations restart MDriven Server.
Use MDriven Designer to connect to the target MDriven Server.
Have the MDriven Server connection details ready: Name (user name), Password, and Server (MDriven Server URL).
Create and retain all three backup artifacts in the previous table. Do not overwrite an older known-good backup.
Record the credentials used by Turnkey to connect to MDriven Server. They may be needed after restoring an older Admin DB.

Back up the Admin DB

Use the Admin DB snapshot when you need to restore the server's administration database.

Open MDriven Designer.
Select the Cloud Connection icon to open the Cloud Connection dialog.
Open the Active MDriven Server tab.
Enter the Name, Password, and Server values for the MDriven Server, then connect.
Open the Admin DB Access and Swap tab.
Select Snapshot Admin DB.
Wait for the snapshot operation to finish. The MDriven Server status area can show 502 Bad Gateway expected due to server forced restart. This message is expected because the operation forces a server restart.
Check the server status. If MDriven Server does not return to a running state after a short wait, restart MDriven Server.
Select Download Snapshot Admin db and save the downloaded file with the rest of the restore point.

For the focused snapshot-and-upload workflow, see Documentation:Database download and upload.

Back up the running model

Keep a copy of the exact model version currently running on MDriven Server.

Locate the local model file that was deployed to the server and copy it into the backup set.
If you do not know which model version is deployed, use the MDriven Designer Cloud Connection dialog to download the model from MDriven Server.
Store the model with the Admin DB snapshot and XML data export.

This model is required because MDriven only allows model-data restore when the deployed model version matches the data backup.

Export model data

Export model data to an XML file before an upgrade or before testing a change that could affect data.

In MDriven Designer, select the System Prototype icon.
Open the MDriven Server tab.
Select Start System.
Confirm that MDriven Designer connects to MDriven Server. When it does, the Migrate button becomes available.
Select Migrate to open the migration window.
Select the download button to download all model data to an XML file.
Wait for the button's progress indicator to complete, then save the XML file with the matching model.

Restore an application

Choose the restore operation that matches the problem:

Situation	Restore action
You need to return the server administration database to a previous state.	Upload the Admin DB snapshot. This restores the stored administration information, including MDriven Server users and access rights.
You need to reload business data into a deployed application.	Upload the matching model, then load and save the model data XML export.
You need to return to a full pre-upgrade restore point.	Restore the saved model and matching model data, and upload the Admin DB snapshot when the server administration database must also be returned to that point.

Restore the model and model data

First deploy the model that matches the XML data export. Do not attempt to restore data into a different model version.

Upload the previously backed-up model to MDriven Server.
In MDriven Designer, select the System Prototype icon.
Open the MDriven Server tab.
Select Start System. Wait until the connection succeeds and Migrate is enabled.
Select Migrate.
Select the button that reads the saved XML data file.
Select Chunk Save to upload the loaded data to MDriven Server.
In the System Prototyper window, select Save to persist the loaded data permanently to the database.

Important: MDriven does not allow you to restore user data when the model version on MDriven Server differs from the model version used for the data backup. Restore or upload the matching model first.

Restore the Admin DB snapshot

Uploading an Admin DB snapshot replaces the target server's Admin DB. Use the snapshot that belongs to the restore point you intend to recover.

Open the Cloud Connection dialog and connect to the target MDriven Server.
Open the Admin DB Access and Swap tab.
Browse to the backed-up Admin DB snapshot.
Select Upload Admin db for replace.
Expect 502 Bad Gateway expected due to server forced restart in the MDriven Server status area. The upload forces a restart, so this message is normal.
Check that MDriven Server returns to a running state. If it does not return after a short wait, restart MDriven Server.

Check Turnkey after an Admin DB restore

An Admin DB restore can restore older MDriven Server credentials. Turnkey must use the same credentials to connect to MDriven Server.

Check the MDriven Server credentials in Turnkey's App_Data/MDrivenServerOverride.xml file.
Ensure that the user name and password in that file match the credentials restored in the Admin DB.
Restart Turnkey and verify that it can connect to MDriven Server.

If Turnkey is blocked because the connection password is no longer valid, reset the password for user a with PwdReset, then update MDrivenServerOverride.xml with the new password. For Docker deployments, the PwdReset file is PwdReset.txt, mounted at /pwdreset/PwdReset.txt; update the password in the Turnkey settings folder's mdriven-server override configuration before restarting the containers. See Documentation:Deploying MDriven Server and Turnkey with Docker.

Restore-point checklist

Before upgrading, confirm that you have:

An Admin DB snapshot downloaded from the target MDriven Server.
A local copy of the model currently running on that server.
A completed XML export of model data.
The MDriven Server and Turnkey connection credentials recorded and checked.
A clear label that ties the three backup artifacts to the same application and point in time.

For a .NET Framework-to-.NET Core upgrade, perform this backup before beginning the migration and use the matching restore procedure if the upgrade must be rolled back. See Documentation:Migrating From MDriven .NET Framework to .NET Core.

Contents