CloudBeaver Workspace Backup

Table of contents

• Backup and restore data
  • Access a running container
  • Backup the database
  • Copy workspace files from the container
  • Restore the database
  • Restore the workspace
• Troubleshooting
  • Automatic PostgreSQL backup fails during upgrade

Backup and restore data

CloudBeaver stores all data on disk in the /opt/cloudbeaver/workspace directory, which is typically mounted to a folder on the host machine (/var/cloudbeaver/workspace or /var/cloudbeaver-ee/workspace).

For additional information on these commands, see the official Docker CLI Documentation.

To back up this data, follow these Docker commands for common tasks:

Access a running container

List services:

docker-compose config --services

• This command lists all services defined in your docker-compose.yml file.
• Find the name of the CloudBeaver service from the output.

Access the CloudBeaver container's shell:

docker-compose exec -it <service_name> /bin/bash

• Replace <service_name> with the exact name of your CloudBeaver service from the previous command.

• If your container uses a different shell (like sh instead of bash), adjust the command accordingly:

  docker-compose exec -it <service_name> sh

Backup the database

If CloudBeaver uses a PostgreSQL database, back up the database to a dump file before stopping the container.

For more details on an internal database, see Server Database.

To create a backup of all PostgreSQL databases:

docker-compose exec <service_name> pg_dump -C -d cloudbeaver -U postgres > postgres_backup.sql

Copy workspace files from the container

First, create a backup of the workspace inside the running container:

docker-compose exec cloudbeaver tar -czvf /var/backups/backup.tgz -C /opt/cloudbeaver/workspace .

• This command compresses the workspace directory into backup.tgz.

To copy the backup file (backup.tgz) from the container to your local machine:

docker cp $(docker-compose ps -q <service_name>):/opt/cloudbeaver/backup.tgz /path/to/backup/location/

• Replace /path/to/backup/location/ with the desired local destination.

If you're using CloudBeaver AWS, copy the backup from your EC2 instance to your local machine:

scp -i your-key.pem ec2-user@your-instance-ip:/path/to/backup.tgz ./local-destination/

Restore the database

Important: Ensure you have a PostgreSQL cluster running. If PostgreSQL isn't running, start it with:

docker-compose up -d postgres

If this is a new installation, clone the deployment repository and navigate to the directory:

git clone https://github.com/dbeaver/cloudbeaver-deploy.git
cd cloudbeaver-deploy

To restore the PostgreSQL database:

1. Copy the database dump file back to the PostgreSQL container:

   docker cp ./postgres_backup.sql $(docker-compose ps -q postgres):/postgres_backup.sql

2. Restore the database inside the PostgreSQL container:

   docker-compose exec postgres psql -U postgres -f /postgres_backup.sql

3. Optionally, delete the dump file from the PostgreSQL container to free up space:

   docker-compose exec postgres rm /postgres_backup.sql

Restore the workspace

To restore the workspace data:

1. Copy the workspace backup file back to the container:

   docker cp /path/to/backup/location/backup.tgz $(docker-compose ps -q <service_name>)":/opt/cloudbeaver/backup.tgz"

   • Replace /path/to/backup/location/ with the desired local destination.

2. Extract the backup in the container:

   docker-compose exec <service_name> tar -xvf /var/backups/backup.tgz -C /opt/cloudbeaver/workspace/

Troubleshooting

Automatic PostgreSQL backup fails during upgrade

If you're upgrading CloudBeaver CE and using PostgreSQL as the management database, the container may fail to start after the upgrade. The log will show that pg_dump was called but failed, and the schema migration was rolled back.

This happens because CloudBeaver automatically runs pg_dump before applying management database schema changes, but the Community Edition image doesn't include the PostgreSQL client packages required to run it. Depending on the environment, you may see one of these errors:

Cannot run program "pg_dump": error=2, No such file or directory

Can't locate PgCommon.pm in @INC

You have two options:

• Install PostgreSQL client tools in the container - build a custom image on top of the CE image:

  FROM dbeaver/cloudbeaver:<version>
  RUN apt-get update && \
      apt-get install -y postgresql-common postgresql-client

  Replace <version> with the exact version you're upgrading to.

• Disable automatic backup - set the CLOUDBEAVER_DB_BACKUP_ENABLED=false environment variable, or set backupEnabled: false in the database section of cloudbeaver.conf. Back up the database manually before every upgrade instead. For manual backup commands, see Backup the database.