Understanding Netbox Database Structure

While trying to wrap my head around some of the NetBox database relationships, I wished for a database schema diagram... I looked through the documentation and code repo but found nothing, so I needed a tool to automatically generate diagrams based on an existing database.

In this post, I'll show you how to point SchemaSpy at a running NetBox Docker instance and get a browsable report with relationship diagrams in about 10 minutes.

Choosing the tool

A quick search turned up three good candidates:

Tool	What it does	Best for
SchemaSpy	Open-source, Java-based. Reads database metadata and generates interactive HTML reports and diagrams.	Automated, detailed reports from an existing database
DBeaver	Universal database client (PostgreSQL, MySQL, Oracle, etc.) with ER diagram generation.	Working with many database systems and exploring complex schemas interactively
DbSchema	Visual database designer that can reverse-engineer a database and export SQL.	Needing both a visual model and SQL export

I went with SchemaSpy because it runs in Docker and requires no GUI or installation, which fits nicely next to a NetBox Docker setup.

Prerequisites

• Docker and Docker Compose installed

• A running NetBox instance using netbox-docker

SchemaSpy

Documentation

I set up a fresh install of netbox docker, and downloaded schemaspy (docker image) and its dependencies.

Step 1: Confirm NetBox's database is running

From your netbox-docker directory:

$ docker compose ps

You should see a `postgres` service in the `running` state. That service name (`postgres`) is the hostname SchemaSpy will use to reach the database.

Step 2: Find the Docker network name

SchemaSpy has to join the same network as the database:

$ docker network ls | grep netbox

With the default setup it's `netbox-docker_default` (Compose names it `<project-folder>_default`). If you cloned the repo into a different folder name, yours will differ, so note it down.

Step 3: Get the database credentials

NetBox Docker stores them in env/postgres.env:

$ cat env/postgres.env

POSTGRES_DB=netbox
POSTGRES_PASSWORD=FAKE_PASSWORD
POSTGRES_USER=netbox

Step 4: Create a working directory

Keep SchemaSpy's files outside the NetBox repo:

mkdir -p ~/schemaspy/output
cd ~/schemaspy

Step 5: Create the SchemaSpy config file

Create schemaspy.properties with the values from Step 3:

# Database type: pgsql11 = PostgreSQL 11 and newer
schemaspy.t=pgsql11

# Connection details
schemaspy.host=postgres
schemaspy.port=5432
schemaspy.db=netbox
schemaspy.u=netbox
schemaspy.p=FAKE_PASSWORD

# PostgreSQL schema to analyze
schemaspy.s=public

Step 6: Run SchemaSpy

docker run --rm \
  --network netbox-docker_default \
  -v "$PWD/output:/output" \
  -v "$PWD/schemaspy.properties:/schemaspy.properties" \
  schemaspy/schemaspy:latest

What each part does:

Flag	Purpose
--rm	Removes the container after it finishes
--network ...	Joins NetBox's network so postgres resolves (use the name from Step 2)
-v .../output:/output	Where the report is written on your machine
-v .../schemaspy.properties:/schemaspy.properties	Mounts your config where the image expects it

Step 7: Open the report

# Linux
xdg-open output/index.html
# macOS
open output/index.html

Output

It produced a browsable report in the output directory, filled with interesting information about the database.

When I checked the "Relationships" tab, it displayed a diagram of the tables and their relationships—exactly what I was looking for!

Result

Two diagrams are generated, a “compact” and a “large” (can verify under /diagrams/summary). The Netbox version at this time of this writing, NetBox Community v4.1.6

Review

The diagrams look good, but there are many arrow intersections, making them hard to read. The export file is in HTML, so I can't drag and drop to move the tables around.

The following is an image for the dcim_device table. You can see that this would not scale very nicely with the amount of arrows.

This is a useful tool, but I'm curious if I can export the diagram to a popular format that other programs can read, like MS Visio, Pencil, or another diagram tool.