Restoring a Backup Locally
Introduction
Restoring a backup locally can be useful if you want to test your cloud environment's data without interrupting your live cloud environment. This lets you see locally how your app behaves when using data in your cloud environment. By using Mendix Studio Pro and a PostgreSQL database, you can debug your app using backups of data from your cloud environments such as test/acceptance/production.
This how-to explains how to do the following:
- Download a backup from your cloud environment
- Create a new database
- Configure the settings of the app
- Download and restore FileDocument (binary) objects in your Domain Model
Prerequisites
Before starting this how-to, make sure you have completed the following prerequisites:
-
Download a backup that you want to restore locally.
-
Install PostgreSQL version 12 or above (as you need pgAdmin version 4.12 or above) on your local machine by downloading and running the PostgreSQL Installer. When installing, use the program defaults and choose a password.
You will need this password later to allow your Mendix app to access the restored data.This how-to was made with PostgreSQL version 15.14 -
When you are restoring a database hosted in Mendix Cloud, or when downloading a full backup, your local machine must have 7-Zip or another utility that can extract files from .gz and .tar archives.
Restoring the Backup to Postgres
Once PostgreSQL is installed and you have downloaded a backup file, you need to create a local database in PostgreSQL. The backup database will be restored into this local PostgreSQL database.
If your backup came from Mendix Cloud, it will have been compressed as a .gz file. You will first have to extract the file (or files) from this archive using a tool such as 7-Zip.
If you have downloaded a full backup, this will also have been archived as a .tar file, which you need to extract to get your .backup file containing the database backup. The .backup file is in the db folder of the archive.
-
Open the pgAdmin 4 application on your computer.
-
In the navigation pane, select Default Workspace.
-
Click the Object Explorer to open the Servers
-
Expand your specific PostgreSQL server instance. For example, PostgreSQL 15.
-
Right-click the Databases and Create a new database.
-
Fill in the Database name.
-
Select the correct Owner (the default is postgres)
-
Click Save.
-
Right-click the newly created database and click Restore....
-
Select the .backup file you downloaded.
-
Click the Data Options tab.
-
Under Do not save, enable Owner.
-
Click Restore.
-
Wait until you see a "Process Completed" message about the backup on your screen.
Linking the Database to the App in Mendix Studio Pro
After the backup has been restored as a local Postgres database, you have to link the database to Studio Pro. This tells Studio Pro to use the database that you have just created in PostgreSQL, rather than the database that was originally created with the app.
-
Open your app in Studio Pro.
-
Open App > Settings from the App Explorer.
-
Under the tab Configurations, click New.
-
Fill in the database information:
- Name: {a unique name}
- Type: PostgreSQL
- URL: localhost:5432
- Database name: {database name} (the name of the database you created in pgAdmin)
- User name: {database owner} (set when you created the database in pgAdmin; the default is postgres)
- Password: {password for database owner} (by default, this is the password you provided for Postgres when first setting up PostgreSQL)
-
Click OK.
-
Run the app by clicking Run Locally ( ) or choosing the menu option Run > Run Locally.
Restoring Files
The steps above restore the database but do not restore any FileDocuments (which are binary files, such as images).
If you also want to restore the FileDocuments, follow these steps:
-
Download a Full Snapshot.
-
From the Studio Pro menu, select App > Show App Directory in Explorer (Windows) or App > Show App Directory in Finder (macOS)
-
Navigate to the deployment/data/files folder within your app.
-
Extract the {backup name}.tar file from the .gz archive using a program like 7-Zip.
-
Extract the contents of your tree folder from the backup archive to the deployment/data/files folder within your app.
-
Run the app by clicking Run Locally ( ) or choosing the menu option Run > Run Locally.