> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-1/documentation/installation-and-upgrades/backing-up-the-connectware-database.md).

# Backing Up the Connectware Database

Connectware stores its configuration, users, and service state in a PostgreSQL database. This guide shows how to create, verify, and restore a database backup on both Kubernetes and Docker.

Run this procedure before upgrading Connectware, before applying destructive maintenance, or on a regular schedule.

## Prerequisites

* Sufficient local disk space to hold the SQL dump. The database is usually small, but depending on how you use Connectware it can grow to multiple gigabytes.
* The PostgreSQL container is running and ready.

{% tabs %}
{% tab title="Kubernetes" %}

* `kubectl` access to the namespace in which Connectware is installed.
* The `postgresql-0` pod is `Running` and `Ready`.
  {% endtab %}

{% tab title="Docker" %}

* Shell access to the host running the Docker Composition.
* The PostgreSQL container is up. If your Docker Composition lives in `/opt/connectware`, the container is named `connectware-postgresql-1` by default. The container prefix matches the folder name of your Docker Composition, so if you installed elsewhere the name is `<folder-name>-postgresql-1`.
  {% endtab %}
  {% endtabs %}

## Creating a Backup

Dump the `cybus_connectware` database to a local file using the command for your platform.

{% hint style="warning" %}
Any changes made to Connectware after you create a backup are lost when you restore that backup. Create the backup as close as possible to the moment you need it — for example, immediately before an upgrade.
{% endhint %}

{% tabs %}
{% tab title="Kubernetes" %}
Replace `${NAMESPACE}` with your Connectware namespace.

{% code lineNumbers="true" %}

```bash
kubectl exec -n ${NAMESPACE} postgresql-0 -- \
    bash -c "pg_dump -U cybus-admin --if-exists -c cybus_connectware" \
    > connectware_database.sql
```

{% endcode %}
{% endtab %}

{% tab title="Docker" %}
If you are not sure which container hosts PostgreSQL, list the candidates:

{% code lineNumbers="true" %}

```bash
docker container ls -f "label=io.cybus.connectware=core" -f "label=com.docker.compose.service=postgresql"
```

{% endcode %}

If more than one container is shown, identify the correct one by its prefix — it matches the folder name of your Docker Composition. For example, an install in `/opt/connectware` yields `connectware-postgresql-1`.

Replace `${CONTAINER_NAME}` with the name from the `NAMES` column.

{% code lineNumbers="true" %}

```bash
docker exec ${CONTAINER_NAME} \
    bash -c "pg_dump -U cybus-admin --if-exists -c cybus_connectware" \
    > connectware_database.sql
```

{% endcode %}
{% endtab %}
{% endtabs %}

The resulting `connectware_database.sql` file contains a full logical backup with `DROP IF EXISTS` statements for a clean restore.

{% hint style="warning" %}
Store the backup in a secure location outside the host or cluster. The dump contains sensitive data such as user records and encrypted secrets.
{% endhint %}

### Verifying the Backup

Confirm that the dump file is non-empty and ends with `-- PostgreSQL database dump complete`. The verification command is the same on both platforms:

{% code lineNumbers="true" %}

```bash
tail -n 3 connectware_database.sql
```

{% endcode %}

If the file is empty or the closing line is missing, the backup did not complete. Investigate the PostgreSQL container logs and retry.

## Restoring a Backup

{% hint style="warning" %}
Restoring overwrites the current database contents. Only restore into an installation that is ready to accept a full replacement, for example a freshly provisioned PostgreSQL volume.
{% endhint %}

Pipe the dump back into `psql` inside the PostgreSQL container, then restart the Connectware workloads so all services pick up the restored state.

{% tabs %}
{% tab title="Kubernetes" %}

1. Wait for the `postgresql-0` pod to become ready.
2. Pipe the dump back into `psql`:

{% code lineNumbers="true" %}

```bash
cat connectware_database.sql | kubectl exec -n ${NAMESPACE} postgresql-0 \
  -i -- psql -U cybus-admin -d cybus_connectware
```

{% endcode %}

3. Restart the Connectware workloads so all services pick up the restored state:

{% code lineNumbers="true" %}

```bash
kubectl -n ${NAMESPACE} rollout restart deployment,statefulset \
  -l app.kubernetes.io/part-of=connectware
```

{% endcode %}
{% endtab %}

{% tab title="Docker" %}

1. Wait for the PostgreSQL container to be running.
2. Pipe the dump back into `psql`. Replace `${CONTAINER_NAME}` with the PostgreSQL container name.

{% code lineNumbers="true" %}

```bash
cat connectware_database.sql | docker exec -i ${CONTAINER_NAME} \
  psql -U cybus-admin -d cybus_connectware
```

{% endcode %}

3. Restart Connectware so all services pick up the restored state. Run this from your Connectware installation directory (by default `/opt/connectware`):

{% code lineNumbers="true" %}

```bash
docker compose down && docker compose up -d
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Verifying the Restore

Wait for all containers or pods to return to a running and ready state, then sign in to the [Admin UI](/2-4-1/getting-started/admin-ui.md) and confirm that your services and users are present.

## Scheduling Regular Backups

The backup and verify commands run on demand. To automate backups, wrap the `pg_dump` invocation in a scheduler appropriate for your platform — for example a Kubernetes `CronJob` on Kubernetes, or `cron` / `systemd` timers on the Docker host — and ship the resulting SQL file to offsite storage.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-1/documentation/installation-and-upgrades/backing-up-the-connectware-database.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.