# 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:

{% code lineNumbers="true" %}

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

{% endcode %}

The result looks like this:

{% code lineNumbers="true" %}

```yaml
{“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”}}
```

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cybus.io/1-9-0/documentation/backup-and-restore/user-database.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.