Backing Up the Connectware Database

Create and restore a logical backup of the Connectware PostgreSQL database on Kubernetes and Docker.

Connectware stores its configuration, users, and service state in a PostgreSQL database. This page 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.

Kubernetes

• kubectl access to the namespace in which Connectware is installed.

• The postgresql-0 pod is Running and Ready.

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.

Creating a Backup

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

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.

Kubernetes

Replace ${NAMESPACE} with your Connectware namespace.

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

Docker

If you are not sure which container hosts PostgreSQL, list the candidates:

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

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.

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

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

Store the backup in a secure location outside the host or cluster. The dump contains sensitive data such as user records and encrypted secrets.

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:

tail -n 3 connectware_database.sql

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

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.

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

Kubernetes

1. Wait for the postgresql-0 pod to become ready.

2. Pipe the dump back into psql:

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

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

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

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.

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

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

docker compose down && docker compose up -d

Verifying the Restore

Wait for all containers or pods to return to a running and ready state, then sign in to the Admin UI 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.