• Icinga Database essentials
Skip to end of metadata
Go to start of metadata

Getting started: Doctrine database models

Starting with Icinga Web 1.5, the external Icinga-Api will be replaced by an iternal database layer using Doctrine to assure cross-database compatibility.This section gives you a short overview about how to access data in Icinga-Web. Later parts of this document will also explain how to create DataStores on serverside, which let you easily export your datamodel to the client, allowing you to use predefined grid and tree functions to display and evaluate your data.
The database files are located in your icinga-web folder under app/modules/Api/lib/database. The models contain all fields available by ido2db and their relations to each other. If you're looking for a field or relation name, that's the place to go.

Why Doctrine ?! Real men use plain SQL!

  • Doctrine offers the possibility to use several database backends (more than ido2db supports at this time) with minimal effort
  • It almost makes fun working with databases if you don't have to worry about how to represent your data in an object form
  • It's not icinga-specific, every module developer can use the ORM
  • Module developers can use 'Soft Relations', i.e. tell doctrine that there is a specific relation to an icinga object without touching the database constraints
    The drawbacks, of course, is that there is a little more memory and processing overhead than when using plain SQL. But keep in mind: Calculation time is cheaper than working time!

Doctrine Models and Agavi Models


There are two kinds of models in icinga-web: Doctrine Models and Agavi Models. Both have nothing to do with each other! Doctrine Models define Database Structures, while Agavi Models are models in the MVC concept and contain the applications business logic.
If it's not possible to refer to the kind of model from the context, the model type will be explicitly written out.

Database model Structure

If you look at the models (here the BaseIcingaHosts Model) you'll notice it consists of two parts: setTableDefinition and setUp.

The first one handles the structure of your table and can be automatically generated from your database by doctrine:

The setUp class handles definitions of your database relations

Here, three relations are defined:

  • 'object' points to the object reference in the IcingaObjects class
  • 'parents' points to other hosts defined as parents in the IcingaHostParenthosts class, using host_id for the local side and host_object_id for the foreign side (the idField is an icinga-specific doctrine patch in icinga to use foreign keys in this table as the reference column).
  • 'services' points to every service defined for this host

Using doctrine models in icinga-web

The ApiDataRequestModel class

The ApiDataRequestModel class is an agavi model which handles request creation for you.

This code will create a ApiDataRequestModel which returns a IcingaDoctrine_Query object for the database "my database", which can then be accessed in various ways discussed now:

Accessing as arrays

This is the solution if you have large datasets which you don't want to change, extend, etc. with further request.:

This will return a result like:

Pretty good for 3 lines of code, isn't it?

Better select the primary id


When using objects or arrays, we recommend you to always select the primary id, because doctrine sometimes only returns the first row if you not do so. But we're on this bug !

Accessing as records

Record access requires a little more memory overhead than array access but offers you more possibilities like saving, modifying records or browsing through the data (while doctrine fetches missing entities from the db).

Record is now an instance of Doctrine_Collection containing Doctrine_Records. You can use get or set functions to access data like in a normal object:

Grouping, Joining, Ordering, etc.

The focus of this documentation lies on icinga-web, for advanced queries refer to the official doctrine documentation.

API models

ApiDataRequestModel only provides basic functionality, which is good for generic requests or creating your own helpers. There are several subclasses that provide methods to access services, hosts, hostgroups, etc.

For example the ApiHostRequestModel allows you to quickly request host information.

Manually switch databases


As we're using the same models for different databases, the DBALManagerModel manages selection of databases

  • No labels