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.
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?
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.
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.