Reporting database¶

Ferrule can copy every inventory into PostgreSQL, so Grafana, Power BI or anything else with a PostgreSQL connector can report on it with no plugin. This is a paid feature, and free during the 30-day trial.

It's a copy. The inventory files on Ferrule's volume stay the master: inventories taken before the database was connected are copied in on the first sync, and the database can be dropped and rebuilt from the files at any time. It needs no backup of its own.

What you get¶

Everything goes into the schema ferrule:

runs: one row per inventory.
One table per sheet: sources, vms, disks, nics, partitions, snapshots, hosts, host_nics, datastores, clusters, health, orphaned_disks and changes.
With capacity planning: capacity (each resource's use, threshold and forecast, as of that inventory), reclaim and storage_growth. See Reports and the monthly summary.
vm_attributes: vCenter's custom attributes.
A latest_ view of each sheet, such as latest_vms, for the fleet as the newest inventory saw it.

A column is named from its sheet's heading, in lower case with underscores: Memory GiB is memory_gib, Free % is free_pct, Speed Mb/s is speed_mb_s. A column added in a later release is added to the table (ADD COLUMN IF NOT EXISTS) on the next sync, so older rows read it as empty.

Every row carries run_id and taken. Inventories that INVENTORY_KEEP expires are expired in the database too.

Set it up¶

The stack's own PostgreSQLYour own PostgreSQL

The easy way. The setup wizard can do it for you: tick Reporting database, and it writes these lines with passwords it makes.

COMPOSE_PROFILES=postgres
INVENTORY_DB_PASSWORD=<a long random password>
INVENTORY_DB_READER_PASSWORD=<another, 12 or more characters>

If COMPOSE_PROFILES already lists something, such as gotify, add postgres to it with a comma: COMPOSE_PROFILES=gotify,postgres.
The stack starts another container, ferrule-postgres, and Ferrule finds it on its own.
Settings → Stack environment can make both passwords with Make a password.

It listens on the Docker host at 127.0.0.1:5432, so only the Docker host itself can reach it. For Power BI or Grafana on another machine, set INVENTORY_DB_BIND=0.0.0.0. INVENTORY_DB_PORT changes the port.

INVENTORY_DB_URL=postgres://ferrule:<password>@db.example.com:5432/reports?sslmode=verify-full
INVENTORY_DB_READER_PASSWORD=<12 or more characters>

The account in the URL needs to be able to create the ferrule schema in that database, and to create roles if you want the reader login made.
If the server's certificate is signed by your own CA, put the CA's certificate in INVENTORY_DB_CA.

Apply the lines as usual: Pull and redeploy in Portainer, or docker compose up -d.

If the postgres container doesn't start

Some Portainer versions don't pass COMPOSE_PROFILES on to Compose. Run PostgreSQL as its own stack instead, and use INVENTORY_DB_URL.

Connect Grafana or Power BI¶

Sign in as ferrule_reader with INVENTORY_DB_READER_PASSWORD, never as the writer. That login can only read the ferrule schema.

Field	Value
Host	your Docker host, or your own server
Port	`5432`, or your `INVENTORY_DB_PORT`
Database	`ferrule` for the stack's own
User	`ferrule_reader`
Schema	`ferrule`

The stack's own database doesn't use TLS

In Grafana, set TLS/SSL Mode to disable. In Power BI, untick Encrypt connection.

Change a password¶

Change INVENTORY_DB_PASSWORD or INVENTORY_DB_READER_PASSWORD and redeploy the whole stack. That's all it takes: the stack's PostgreSQL takes the new writer password within about a minute, and Ferrule updates the reader login itself. For your own PostgreSQL, change the writer's password there first, then in INVENTORY_DB_URL.

How long it keeps¶

As long as the inventory files: INVENTORY_KEEP days, 365 by default. 2557 keeps seven years, as SOX audits ask.

If something's wrong¶

The Database copy line on the Inventory panel says how the copy is doing.

What you see	What to do
failing, with a reason	Check the address and password, and that the database is running. The Inventory database copy failing alert says the same
`ferrule_reader not made: … at least 12 characters`	Use a longer `INVENTORY_DB_READER_PASSWORD`. The copy carries on meanwhile
paused	The trial or license has ended. What's already in the database stays
DISAGREES	The database and Ferrule's files don't match. See Inventory reports

If the stack's own database still refuses a new password, remove the stack's postgres-data volume and redeploy. Nothing is lost: Ferrule copies every inventory back in.