Skip to main content
Applies to BloodHound Enterprise only This guide applies to on-premises deployments of BloodHound Enterprise using an external PostgreSQL database instead of the PostgreSQL database bundled with the embedded cluster. PostgreSQL 18 enables new capabilities, delivers meaningful performance improvements, and is required for BloodHound Enterprise. If your external database is still running PostgreSQL 16, follow the steps on this page to upgrade and migrate your data.
The PostgreSQL 18 Docker image uses a different volume mount path than version 16. If your external database runs in Docker, you cannot simply update the image tag — the volume mount point has changed.
PostgreSQL versionVolume mount path
16 (and earlier)/var/lib/postgresql/data
18 (and later)/var/lib/postgresql
Starting a PostgreSQL 18 container against an existing PostgreSQL 16 volume will fail.

​
Before you begin

Back up your database before starting the upgrade. Verify that your backup is complete and restorable before proceeding.
Confirm the following before you begin:
  • You have access to a PostgreSQL 18 instance (or can upgrade your existing host to PostgreSQL 18)
  • You have sufficient disk space for a full database dump
  • Your database administrator is available to adapt commands to your specific environment
  • You know your PostgreSQL connection details (host, port, username, database name)
The exact commands in this guide vary depending on how your external database is deployed (Docker, bare-metal, VM, or managed service). Work with your database administrator to adapt the procedure to your environment. For a concrete Docker Compose reference, see the Community Edition upgrade guide.

​
Upgrade process

1

Stop BloodHound Enterprise

Stop the BloodHound Enterprise application to prevent new writes to the database during the upgrade.
2

Dump the PostgreSQL 16 database

Use pg_dump to export your existing database to a compressed dump file. Replace the placeholder values with your actual connection details:
pg_dump -h [host] -p 5432 -U [username] -d [database] -Fc -Z 9 -f pg16_backup.dump
Verify that the dump file was created and has a non-zero size before continuing.
3

Back up your data directory

If your PostgreSQL instance uses a data volume or directory, create a backup of it before making changes. The exact method depends on your deployment.
4

Upgrade PostgreSQL to version 18

Upgrade your PostgreSQL instance to version 18 using the method appropriate for your environment.
PostgreSQL major version upgrades are not backward-compatible. After upgrading to PostgreSQL 18, you cannot start the service against a PostgreSQL 16 data directory without first restoring from your dump file.
5

Restore the database

After PostgreSQL 18 is running, restore the database from the dump file:
pg_restore -h [host] -p 5432 -U [username] -d [database] --clean --if-exists pg16_backup.dump
Wait for the restore to complete before proceeding.
6

Restart BloodHound Enterprise

Start the BloodHound Enterprise application and confirm it connects to the upgraded database successfully.

​
Verify the upgrade

After the application restarts, confirm that the database is healthy and your data is intact.
1

Confirm the PostgreSQL version

Connect to your PostgreSQL instance and run the following query to confirm PostgreSQL 18 is running:
SELECT version();
The output should include PostgreSQL 18.
2

Log in to BloodHound Enterprise

Open your browser and navigate to your BloodHound Enterprise instance. Log in and verify that your data, collectors, and configuration are intact.
3

Monitor application logs

Review the BloodHound Enterprise application logs for any database connection errors or migration issues immediately after restart.

​
Clean up

After you have verified that the upgrade was successful and your data is intact, remove the temporary dump file and any volume backups you created during the migration. Remove any snapshot or volume backups using the tools appropriate for your environment.