User Database

Backup and restore via REST API.

Connectware provides dedicated REST APIs to perform database maintenance operations, specifically for creating backups and restoring them. These operations ensure that system data can be preserved and recovered reliably.

Backup Process

To create a backup, a REST call can be used to trigger the generation of a backup file. Because this is a time-consuming operation, the backup runs asynchronously. The status of the backup can be checked with a separate REST call. Once the process is complete, the resulting backup file can be downloaded via another REST endpoint.

Restore Process

To restore the database from a backup, a single REST call is used where the backup file is uploaded. The restore process begins immediately after the upload.

Restoring Across Connectware Versions

When restoring backups across different Connectware versions, certain version combinations may fail due to structural changes in the database schema.

If this occurs, the maintenance status message will indicate the last compatible version that can restore the backup.

To proceed, it may be necessary to install an older version of Connectware:

1. Create a fresh backup of all data.

2. Shut down Connectware.

3. Remove the postgresql volume (after ensuring their backup is stored).

4. Install the older Connectware version. See Installing Connectware.

5. Once you have installed the older Connectware version, repeat the restore operation.

6. After completing the restore, it is recommended to upgrade Connectware back to the newer version and immediately create a fresh backup from this updated version.

Example REST Calls

Check Status of Maintenance Operation

To validate the status of a database maintenance operation, you can use the following CURL command:

curl -k --header "Content-Type: application/json" \
--request GET -u admin \
https://<HOST>/api/maintenance/db

The result looks like this:

{
  "running": false,
  "backup": {
    "succeded": true,
    "id": "1.0.73_2022-02-16T15:37:19.242Z",
    "statusMessage": "OK",
    "startDate": "2022-02-16T15:37:19.242Z",
    "endDate": "2022-02-16T15:37:19.270Z"
  },
  "restore": {
    "succeded": true,
    "id": "1.0.73_2022-02-16T10:19:11.377Z",
    "statusMessage": "OK",
    "startDate": "2022-02-16T15:38:39.197Z",
    "endDate": "2022-02-16T15:38:39.385Z"
  }
}

Start Backup Creation

To start the creation of a backup file, call the following CURL command:

curl -k --request POST  -u admin \
https://<HOST>/api/maintenance/db/backup

On success, the request returns HTML status code 202 (Accepted).

Download Backup File

To download the database backup in a file /tmp/connectware-db-backup.tgz, call the following CURL command:

curl -k --request GET  -u admin \
https://<HOST>/api/maintenance/db/backup \
--output /tmp/connectware-db-backup.tgz

Restore from Backup File

To restore the database from the backup file /tmp/connectware-db-backup.tgz, call the following CURL command:

curl -k --request POST -u admin \
-F file=@/tmp/connectware-db-backup.tgz \
https://<HOST>/api/maintenance/db/restore

On success, the request returns HTML status code 202 (Accepted).

After each operation, you can check the current database maintenance status again using the status query.