> ## Documentation Index
> Fetch the complete documentation index at: https://specterops-bp-2735-release-notes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade an external PostgreSQL database

> Upgrade an external PostgreSQL database from version 16 to 18 for on-premises deployments of BloodHound Enterprise.

<img noZoom src="https://mintcdn.com/specterops-bp-2735-release-notes/2djt2Sp9UeFPjBFr/assets/enterprise-edition-pill-tag.svg?fit=max&auto=format&n=2djt2Sp9UeFPjBFr&q=85&s=f1e5b5b68b628fd10faf78983d19efbf" alt="Applies to BloodHound Enterprise only" width="225" height="45" data-path="assets/enterprise-edition-pill-tag.svg" />

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.

<Warning>
  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 version | Volume 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.
</Warning>

## Before you begin

<Warning>
  Back up your database before starting the upgrade. Verify that your backup is complete and restorable before proceeding.
</Warning>

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)

<Note>
  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](/get-started/upgrade-postgres).
</Note>

## Upgrade process

<Steps>
  <Step title="Stop BloodHound Enterprise">
    Stop the BloodHound Enterprise application to prevent new writes to the database during the upgrade.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Upgrade PostgreSQL to version 18">
    Upgrade your PostgreSQL instance to version 18 using the method appropriate for your environment.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Restore the database">
    After PostgreSQL 18 is running, restore the database from the dump file:

    ```bash theme={null}
    pg_restore -h [host] -p 5432 -U [username] -d [database] --clean --if-exists pg16_backup.dump
    ```

    Wait for the restore to complete before proceeding.
  </Step>

  <Step title="Restart BloodHound Enterprise">
    Start the BloodHound Enterprise application and confirm it connects to the upgraded database successfully.
  </Step>
</Steps>

## Verify the upgrade

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

<Steps>
  <Step title="Confirm the PostgreSQL version">
    Connect to your PostgreSQL instance and run the following query to confirm PostgreSQL 18 is running:

    ```sql theme={null}
    SELECT version();
    ```

    The output should include `PostgreSQL 18`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Monitor application logs">
    Review the BloodHound Enterprise application logs for any database connection errors or migration issues immediately after restart.
  </Step>
</Steps>

## 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.