See www.zabbix.com for the official Zabbix site.

Docs/DB schema

From Zabbix.org
Jump to: navigation, search

What is this ?

These are partially auto-generated pages, documenting the Zabbix DB schema.

Why?

Having database schema documentation can be highly valuable. Just a few examples:

  • extract data for advanced reporting
  • create powerful scripts that directly manipulate the DB (managing maintenance periods in an automatic way, large-scale configuration changes etc)
  • understand how some features work, now that the specifications and developer comments are secret
  • save a lot of time for people who extend Zabbix (like the examples at Zabbix patches)
  • help debugging some problems - you can verify that the DB gets what you expect it to get
  • easily identify fields that changed in a version, or seeing which version added a table, to verify improvements like longer error messages
  • ...more?

Currently implemented

The current auto-generated features:

  • column table
    • lists fields and references
    • "hard" references (using DB referential integrity) are normal font, "soft" references (only by Zabbix code) are italics
    • references to the same table have the table name in bold black font
    • changes from previous version (new fields and references, changes to default/NULL/type) highlighted in orange
    • empty or no defaults replaced with "EMPTY" and "NONE" - this makes it both more clear and allows to highlight them as changed
    • if we know in which version a column appeared, a tooltip mentions that
    • if we know that a column will be gone in the next version, it is marked with [!] in the column list and a tooltip explains that
    • if a constraint is with "ON DELETE CASCADE", it is marked with C and a tooltip explains that
  • index table
    • lists primary key, other indexes, UNIQ status and fields, included in the key
    • new indexes highlighted in orange
    • if we know in which version an index appeared, a tooltip mentions that (but for the primary key only addition in the previous version is tracked)
  • sidebars to jump between version and tables
    • top of the sidebar shows which version this table appeared in (by showing missing versions in red)
    • if we know in which version a table appeared, the table is marked with [*] in the sidebar; if the table appeared in the current version, [*] is orange; tooltip explains in which version table appeared
    • if we know that a table will be gone in the next version, it is marked with [!] in the sidebar and a tooltip explains that
    • tables arranged by the first letter in the sidebar

What's missing ?

Actually, auto-generating data is nice, but the easiest part. The hard part is documenting what the data is. For example, what do fields like actions.def_longdata, items.flags or hosts.status hold ? What are the possible values ? Host statuses, for example, are :

HOST_STATUS_MONITORED           0
HOST_STATUS_NOT_MONITORED       1
HOST_STATUS_TEMPLATE            3
HOST_STATUS_PROXY_ACTIVE        5
HOST_STATUS_PROXY_PASSIVE       6

This would have to be added manually.

Can I help ?

Definitely. Adding the missing information is a great way to help.

You can add data from your personal knowledge, or look things up in Zabbix sources - frontend/php/include/defines.inc.php and include/common.h are two great places. You might also want to look at frontend/server/proxy code or an actual database you can experiment with.

See the pages for hosts, hosts and applications tables as an example for the detail and formatting.

All discussion on this topic very much welcome on IRC.

Technical TODO

  • trunk has been generated, but it is a moving target, thus the script would need a comparison mode to highlight differences, needing a manual update

Where is it ?

Start browsing at https://zabbix.org/wiki/Docs/DB_schema/2.0/acknowledges .