Skip to content

HOWTO – Migrate NetBox Database to PostgreSQL HA

Migrate the NetBox database from a postgresql-core bootstrap instance to a Patroni HA cluster using platform/onprem/netbox-db-migrate. The module quiesces NetBox, dumps the source DB with pg_dump, restores to the HA target with pg_restore, and validates row counts. It does not repoint NetBox's connection string: that is done separately via onprem/netbox-ha-cutover@v1.

Difficulty: Advanced Prerequisites: platform/onprem/netbox state is ok; platform/postgresql-ha state is ok with a netbox database and user pre-created; NETBOX_DB_PASSWORD set in vault; SSH access to the NetBox host from the Ansible control machine.

Context

The migration module is an explicit, operator-confirmed operation, not an automatic reconcile. It requires three gates to be set to true in the inputs file:

Gate Protects
maintenance_confirm Confirms NetBox can be taken offline
migration_confirm Confirms the dump/restore may proceed
target_replace_confirm Confirms the HA target database may be overwritten

No gate defaults to true. Omitting any gate causes the module to exit without making changes.

Module ref: platform/onprem/netbox-db-migrate Driver: config/ansible · Profile: onprem-linux@v1.0 Source state: platform/onprem/postgresql-core Target state: platform/postgresql-ha

Preconditions and safety checks

  1. Confirm postgresql-ha is healthy and the netbox database exists:

    hyops state show --env <env> --module platform/postgresql-ha

  2. Confirm NetBox is reachable and in a clean state (no pending migrations):

    hyops state show --env <env> --module platform/onprem/netbox

  3. Confirm NETBOX_DB_PASSWORD is present in vault:

    hyops secrets ensure --env <env> NETBOX_DB_PASSWORD

  4. Take a snapshot of the NetBox VM and the source PostgreSQL host if your environment supports it. The module does not create snapshots.

Steps

1. Initialise the inputs file

hyops module init --env <env> \
  --module platform/onprem/netbox-db-migrate \
  --dest-name netbox-db-migrate.yml

Edit ~/.hybridops/envs/<env>/config/modules/netbox-db-migrate.yml:

# Source DB — resolves from postgresql-core state by default
source_db_state_ref: "platform/onprem/postgresql-core"
source_db_app_key: "netbox"

# Target DB — resolves from postgresql-ha state by default
target_db_state_ref: "platform/postgresql-ha"
target_db_app_key: "netbox"

# NetBox host — resolves from platform-vm state by default
target_state_ref: "platform/onprem/platform-vm#platform_vms"
target_vm_key: "netbox-01"

# Safety gates — all must be true to proceed
maintenance_confirm: true
migration_confirm: true
target_replace_confirm: true

# Behaviour
quiesce_netbox: true
start_netbox_after_migration: false  # leave stopped until cutover
validate_row_counts: true
dump_artifact_dir: "/var/lib/hybridops/netbox-migration"

2. Run the module

hyops apply --env <env> \
  --module platform/onprem/netbox-db-migrate \
  --inputs ~/.hybridops/envs/<env>/config/modules/netbox-db-migrate.yml

The module executes in order:

  1. Quiesces netbox, netbox-worker, and netbox-housekeeping compose services.
  2. Runs pg_dump from the source host; writes the dump file to dump_artifact_dir on the NetBox VM.
  3. Runs pg_restore against the HA target.
  4. Validates row counts per table between source and target.
  5. Publishes migration state (cap.db.netbox_migration).

NetBox remains stopped at the end of this module (start_netbox_after_migration: false). Do not restart it manually before running the cutover step.

3. Confirm migration state

hyops state show --env <env> --module platform/onprem/netbox-db-migrate

State ok confirms the dump, restore, and row-count check all passed. The state record includes the artifact path and the per-table count comparison.

Verification

  • Module state is ok.
  • validate_row_counts output shows matching counts for all user tables. Any mismatch is reported as a warning in the run log and causes the module to exit with an error.

  • Dump artifact is present on the NetBox host:

    ls -lh /var/lib/hybridops/netbox-migration/

  • NetBox compose stack is stopped (expected at this point):

    docker compose -p netbox ps

Post-actions

  • Proceed to the cutover step to repoint NetBox at the HA cluster:

    hyops blueprint deploy --env <env> \
  --ref onprem/netbox-ha-cutover@v1 \
  --execute

  • After cutover confirms state ok, start NetBox and validate the UI and API.

  • Retain the dump artifact for at least one full backup cycle before removing it.
  • Decommission the source postgresql-core NetBox database only after the HA cluster has been running in production for a defined period per your change process.

References

License: MIT-0 for code, CC-BY-4.0 for documentation