Zabbix 2.2 features, part 1 – Automatic database upgrading

Zabbix currently is at version 2.0, and this version took quite a long time to get out – almost 2 and a half years. Of course, all that wait was not in vain – Zabbix 2.0 provided a huge amount of new features. It did mean that you and me had to wait for quite some time before benefiting from those features, though, so there will be an effort to make Zabbix 2.2 happen sooner. Let’s start to look at the improvements Zabbix 2.2 will provide – and let’s start with the one that everybody upgrading will notice – automated database schema upgrades.

Articles in 2.2 feature series:

To get some things clarified right away, we should probably deal with the question “when will 2.2 be out”. Saying that it will take less time than 2.0 might not help that much, so let’s look at the semi-official roadmap of Zabbix.

A word of warning – the roadmap does suggest May 1st as the possible release date, but that is the optimistic “if all goes well” date. The actual release date may be later.

With that out of the way, let’s concentrate on the first improvement 2.2 will deliver:

Automated database upgrade

Major Zabbix upgrades have always been the same – along with other tasks one had to patch the database, manually. There was an SQL patch file provided, which had to be run before starting the new version of the Zabbix server.

This was cumbersome for most users, and especially hard to deal with for packagers. Anybody who installed Zabbix from distribution packages would still have to manually patch the database after doing a major upgrade – the upgrade itself being a single command for most users.

Zabbix 2.2 does away with this step by introducing a fully automatic database patching.

Automatic DB patching – summary

The database patching will be done by the Zabbix server process. Whenever the server is started up, it will check the current database version and upgrade it, if necessary.

Zabbix frontend will check the database version and fail to work if the version is not correct.

A bit more detail

That was simple – but let’s look at some more detail.

Detecting database version

First thing that has to happen – Zabbix server must figure out whether it should do any database patching. This is done by adding a new table called dbversion with two fields mandatory and optional. If the upgrade has to happen from Zabbix 2.0, which does not have this table, server will check whether field server_check_interval exists in the table config – if so, it will consider this to be Zabbix 2.0 installation, add dbversion table and proceed with the patching accordingly.

What’s so special about that server_check_interval field? Just that it was the last database schema change for Zabbix 2.0. If that field is present, it has to be 2.0.

Mandatory and optional versions

But what about those mandatory and optional versions? They are a small trick to allow similar changes as were happening before – in one major version of Zabbix (like 2.0, 2.2) no database schema changes are allowed… except things that do not break compatibility, like changing some indexes for performance reasons. Previously a possibility to add or change indexes was mentioned in release notes, and could be optionally performed by users.

As indexes might be updated in a minor version in the future as well, it wouldn’t be too nice if one would upgrade Zabbix server from version 2.2.8 to 2.2.9, and the frontend would stop working. To handle this automatically, Zabbix server will patch the database and increase the optional version only, if updating indexes. It will let the server know what changes it has already performed to the database while still allowing an older frontend version to work without any issues.

The patching

Zabbix server will now print out some database version information in the logfile whenever it starts up. If the database is not up to date, automatic upgrade will be started. As the upgrade happens, progress will be logged as well. An example of an upgrade session would look like this:

current database version (mandatory/optional): 02010008/02010008
required mandatory version: 02010021 
starting automatic database upgrade 
completed 7% of database upgrade 
completed 15% of database upgrade 
completed 23% of database upgrade 
completed 30% of database upgrade 
completed 38% of database upgrade 
completed 46% of database upgrade 
completed 53% of database upgrade 
completed 61% of database upgrade 
completed 69% of database upgrade 
completed 76% of database upgrade 
completed 84% of database upgrade 
completed 92% of database upgrade 
completed 100% of database upgrade 
database upgrade fully completed

If the patching process would fail at any step, server would quit to allow fixing the issue (either by changing database contents, fixing the patch or some other method). When the server would be started again later, it would see how far the previous patching attempt went by the version in the dbversion table and continue where it left off.

Frontend and the version

Zabbix frontend does not do any database upgrades – it only checks the version of the database to know whether it is compatible. When doing this check, the optional database version is ignored, only the mandatory is verified – and it must match exactly the mandatory version frontend is supporting. If that does not happen, you will see the following instead of the frontend:

In this case the frontend is a bit older than the database – database version is 2010027, frontend version is 2010026. If the optional version was different, that would not be taken into account at all.

Interested in even more technical detail? Read the full specification.

More complex patches and using trunk

This change does bring some additional benefits as well. Sometimes the changes that had to be done to the database were a bit more complicated – for example, the format of simple checks changed in Zabbix 2.0, and what was before an item key of ssh,22 had to be net.tcp.service[ssh] instead. Database patches actually did convert all the keys to the new syntax, but doing that in pure SQL for several database engines was not the most pleasant task ever. The ability to handle such complex cases partially in the server code will mean better upgrade process for everybody and less time spent by developers to do tricky SQL.

Second task that was not simple until now – using the cutting edge development branch – trunk. One had to patch the database manually, following the changes developers were doing. While there was a community maintained attempt to automate this, it was available for MySQL only and sometimes lagged behind the official changes.

If you would like to follow trunk because you are curious about new features or would like to test it (highly suggested), see basic instructions for getting and compiling development versions.

This entry was posted in Technical and tagged . Bookmark the permalink.

5 Responses to Zabbix 2.2 features, part 1 – Automatic database upgrading

  1. Vitaly Nikolaev says:

    This is great, but will it make life of guys with DB partitioning configured harder (or impossible?)

    • We do all our best not to change structure of historial (history, trends) tables, therefore the automatic database upgrade will not touch them at least in Zabbix 2.2.

  2. Harri says:

    Maybe I am too blind to see, but I missed some information about older database versions, e.g. 1.8.x. Is there an automatic path, or do I have to manually convert my database to the 2.0 format first?

    • Richlv says:

      you have to patch the database to 2.0 version first by using supplied sql files – same as before. once the db is at the “2.0″ state, you can benefit from the automated upgrading

  3. fernandop says:

    Is there a way to get sql scripts to upgrade from 2.0.9 to 2.2 instead of using automatic upgrade? We have our oracle databases controlled externally so we need to figure how to split the app upgrade from the db upgrade…