Skip to main content
We recommend backing up your database regularly, especially before upgrading Speckle. Backing up a database is often required for a database upgrade, migrating your database between servers, or recovering from an incident. Speckle’s preferred method of backing up and restoring data in a Postgres database is with pgAdmin. This guide assumes you are running Speckle via Docker Compose.

​
Prerequisites

  1. Docker should be installed and running
  2. Manual installation instructions should have been completed

​
Setup pgAdmin

1

Check and start pgAdmin

Check if pgAdmin is already running:
docker ps --filter name='pgadmin'
If not running, create docker-compose-pgadmin.yml with the following configuration:
version: '3'
services:
  pgadmin:
    image: dpage/pgadmin4
    restart: always
    environment:
      PGADMIN_DEFAULT_EMAIL: '[email protected]'
      PGADMIN_DEFAULT_PASSWORD: 'admin'
    volumes:
      - pgadmin-data:/var/lib/pgadmin
    ports:
      - '127.0.0.1:16543:80'
networks:
  default:
    name: speckle-server
volumes:
  pgadmin-data:
Then start pgAdmin:
docker compose --file docker-compose-pgadmin.yml up --detach
2

Access pgAdmin

Find the pgAdmin port and access the dashboard:
docker ps --filter name='pgadmin'
Open http://127.0.0.1:16543/ in your browser (replace 16543 with your actual port).

​
Backup

1

Backup database

Connect to pgAdmin, then connect to your Postgres server. Right-click on the speckle database, select Backup..., choose a location, and click Backup to start the process.

​
Upgrade

1

Deploy new version

Clone the Speckle Server repository and deploy the updated version:
git clone https://github.com/specklesystems/speckle-server.git
cd speckle-server
git checkout tags/2.9.0 -b main
docker compose -f ./docker-compose-deps.yml up --detach
2

Verify deployment

Check that all containers are running:
docker ps
3

Stop and clean up old database

⚠️ CAUTION This will cause Speckle to stop working until restored. Notify users before proceeding.Stop and remove the old Postgres container:
docker stop speckle-server-postgres-1
docker rm speckle-server-postgres-1
Find and delete the database volume:
docker volume ls --filter name='postgres'
docker volume rm speckle-server_postgres-data

​
Restore

1

Transfer and restore backup

If needed, transfer your backup file to the host machine, then copy it to the pgAdmin container:
docker cp BACKUP_FILE_NAME speckle-server-pgadmin-1:'/var/lib/pgadmin/storage/admin_localhost.com/'
Connect to pgAdmin, create a new speckle database, then right-click it and select restore to load your backup.
2

Verify restoration

Deploy the Speckle server if it is not already running, and verify the data is correct.
Your database has been successfully backed up, upgraded, and restored. Regular backups are recommended as part of your maintenance routine, regardless of whether you’re performing upgrades.
Last modified on February 28, 2026