---
alias: operation-guide-backupdatabasestool
tags:
- database
description: "This documentation guides users through backing up Critical Manufacturing MES databases during installation"
---

# Backup Databases Tool

If any installations of Critical Manufacturing MES are already deployed, you can perform a backup of the current databases directly from the main Critical Manufacturing MES setup. You can use those same custom backup databases in the installation process.

## Using the UI

After running the `setup.exe` program from the root of the ISO, selecting **Backup Database** will start this section of the installation program.

!!! warning
	The installation of this environment is expected to have an associated customization package. If this is not the case, custom database objects (such as synonyms, jobs, and other) will not be updated to the new environment settings.

### Step 1: Import Configuration File

This step allows you to load a previously exported file with the configuration of the backups to perform. It will automatically fill out the information existing in the selected file.

!!! info
	You can also use a configuration file used in a previous installation since the fields are consistently named.

![Backup Databases - Import Original Backup Configuration File](../images/backup_import.png)

Select **Next** to continue.

### Step 2: General

In this screen, you must specify the following settings:

* **System Name** - name of the backup that will be generated.
* **Backup Share** - location where the backup files will be generated.
* **Use Compression** - whether the backup files should be zipped upon generation.
* **Force Backup** - force the creation of database backup files, even if a backup file already exists.

!!! info
	If a backup for any of the databases already exists in the backup share folder and the **force backup** setting is **disabled**, the system will use this backup files to create the package. For instance, if the System Name is `CriticalManufacturing`, the system can use `CriticalManufacturing.bak`, `CriticalManufacturingODS.bak`, and `CriticalManufacturingDWH.bak` in the backup share folder, provided they exist.

	Otherwise, if the **force backup** setting is **enabled**, the database backup files will be created using the current database. Also, considering this previous scenario with the System Name `CriticalManufacturing` where a previous database backup file for this database already exists, for example `CriticalManufacturing.bak`, it will be renamed to `CriticalManufacturing_old.bak`.

![Backup Databases - General Settings](../images/backup_generalsettings.png)

### Step 3: Databases

In this screen, you must specify the credentials for the connections to all the databases available for a given system:

* **Online**
* **ODS**
* **DWH**

For each database, specify the following settings:

* **Database Server** - address of the database server.
* **Database User** - user account with adequate permissions to connect to the database and perform the backup.
* **Database User Password** - password for the database user defined above.

![Backup Databases - Databases](../images/backup_databases.png)

### Step 4: Preview

Before the backup is performed, you will be shown a summary of the actions that will be performed.

![Backup Databases - Preview](../images/backup_preview.png)

### Step 5: Backup Databases

In this screen, you can **Export** all the current backup configuration data to a file. To export the current configuration data, you need to select **Export** and then choose a location and a file name.

![Backup Databases - Export](../images/backup_export.png)

Select **Backup** to begin the installation. You will have two tabs, one that shows the progress of the backup, and another that shows the details of the backup log.

![Backup Databases - Progress](../images/backup_progress.png)

After the process is completed successfully, a screen will display that information:

![Backup Databases - Success](../images/backup_success.png)

## Using the Command Line

You can also execute the backup functionality directly from the command line. For example:

```powershell
CmfDeploy.exe backup --parameters=parameters.json --packageSource=F:\packages
```

The following parameters are available:

* `--parameters` - Specifies the path to the parameters file (`parameters.json`). This file contains the MES database configuration and can be generated using the **Export** functionality described in Step 5 of this guide.
* `--packageSource` - Specifies the location of the "packages" directory from the ISO image. The example above assumes the ISO is mounted on drive `F:`.

## Using the EnvManager API

Use the EnvManager API to create and download SQL Server backup packages without opening the installation UI. The API creates one backup per request. Run the procedure separately for the Online, ODS, and DWH databases installed in the environment.

Authenticate the API request with an account that can access the EnvManager API. For authentication options, see the [Invoke MES HTTP API Guide](https://developer.criticalmanufacturing.com/explore/guides/customizations/business/invokemeshttpapi/).

### Step 1: Create a Backup

Send a `POST` request for the database to back up. Replace `{database-name}` with the SQL Server database name and `{environment-url}` with the base URL of the MES environment.

**Endpoint:** `POST {environment-url}/environment/sql/backup/{database-name}`

```powershell
curl --location "https://mesintegration.dev/environment/sql/backup/{database-name}" `
     --request POST `
     --header "Authorization: Bearer {your-token-here}" `
     --header "Content-Type: application/json" `
     --data '{
       "forceBackup": false,
       "useCompression": true
     }'
```

The request returns `202 Accepted` and a backup ID. Save this ID to check the backup status and download the package.

The request body supports the following optional properties:

* `forceBackup` - creates a new database backup when set to `true`. When set to `false` or omitted, the system can reuse an existing backup file.
* `useCompression` - compresses the backup package when set to `true`. The default value is `true`.

### Step 2: Check the Backup Status

Use the backup ID returned in Step 1 to check the backup status.

**Endpoint:** `GET {environment-url}/environment/sql/backup/{backup-id}/status`

```powershell
curl --location "https://mesintegration.dev/environment/sql/backup/{backup-id}/status" `
     --request GET `
     --header "Authorization: Bearer {your-token-here}"
```

Repeat the request while it returns `202 Accepted`. When the request returns `200 OK`, the response includes the `Completed` state and the backup package is available for download.

### Step 3: Download the Backup Package

After the backup reaches the `Completed` state, download its package.

**Endpoint:** `GET {environment-url}/environment/sql/backup/{backup-id}/download`

Use `--remote-header-name` and `--remote-name` so cURL saves the package with the filename returned by the Environment Manager.

```powershell
curl --location "https://mesintegration.dev/environment/sql/backup/{backup-id}/download" `
     --remote-header-name --remote-name `
     --request GET `
     --header "Authorization: Bearer {your-token-here}"
```

The endpoint returns a ZIP package for the database requested in Step 1.

### Troubleshooting

| Issue | Solution |
| --- | --- |
| Status returns `202 Accepted` | The backup is still running. Wait and check the status again. |
| Status returns `404 Not Found` | Verify the backup ID returned when the backup was created. |
| Create request returns `409 Conflict` | Wait for the conflicting backup operation to finish before retrying. |
| A request returns `500 Internal Server Error` | Review the EnvManager logs for details. |