User Database

Connectware provides REST APIs to perform database maintenance operations for backup and restore.

For creating a backup, there is one REST call (shown below) to trigger the creation of the backup file. As this is a time-consuming operation, the creation of the backup file will be ongoing for some time and the status of the backup operation can be queried by another REST call. Once the creation of the backup file is completed, the resulting backup file can be downloaded by yet another REST call.

For restoring the state of a backup, there is one REST call where the backup file can be uploaded and also the restore operation can be started immediately.

Limitations of restore across versions

In a cross-version scenario, where a backup file from an older version is used for restoring in a newer version, some seldom version combinations can occur where the restore operation is being refused due to database structure changes.

In this case, Connectware database maintenance status message will report the last possible version that can be used to restore from the given backup file. If this backup file needs to be restored, it is necessary to downgrade the Connectware version to the reported older version.

If such a Connectware version downgrade is necessary, first ensure another backup of all data. Then, shut down Connectware and remove the volumes named postgresql and service-manager (of which a backup was stored beforehand). Then, follow the regular steps for the installation of the older version, as described in detail in the following article:

https://www.cybus.io/learn/installing-the-connectware

After the older version is installed, the backup file can be used for restore again. After restoring from the backup file, it is recommended to upgrade the Connectware version again, then creating a new backup file which is now from the newer version.

Example REST calls

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”}}

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).

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

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, the database maintenance operation status can be queried again (as shown in the first command).