FrontPage/KexiDBDesign/KexiDBDrivers

KexiDB Drivers Handling

 jstaniek, mar 2005

Driver loading

Drivers are loaded by KexiDB::DriverManager object. Kexi declares a single instance of it globally, which is available as Kexi::driverManager() global function, available in kexi.h.

Versioning

Each KexiDB driver implementation provide version info available in public via these methods:

 int KexiDB::Driver::versionMajor()
 int KexiDB::Driver::versionMinor()

For any driver module, it's required to match major and minor version of the driver between KexiDB library and driver module. Necessary checks are implemented in KexiDB::DriverManager. Within Kexi GUI, if you provided incompatble drivers, following error could occur:

In such situation, driver loading failed, even if it would work if you were lucku. In worst case you could get a segfault, if minor versions are not compatible, because that means binary-incompatibility between two versions (even now, KexiDB API quite is still improving). On the other hand, if major versions are not compatible, you are in risk that KexiDB storage method (eg. kexi__* tables) has changed, what can lead to data loss, inconsistences or instability.

Summing up, you should compile, install and distribute either kexidb/ directory and kexidb/drivers/ directory if the API or storage format has changed. Before compiling execute 'make clean' if you want to be sure.

Notes

• When KexiDB library is upgraded to a new version, every driver which should work with it (not only compile) should have updated X-Kexi-KexiDBVersion field in driver's *desktop file (don't forget to 'make install'). For example, after updading from 1.4 to 1.5, you need to update to this line in *.desktop file stored within your driver's directory:

 X-Kexi-KexiDBVersion=1.5

Remember: KexiDB library checks this value!

• We're always trying to maintain backward and forward compatibility for storage format and binary compatibility as well.
• Driver's version is not the same as "kexidb_major_ver" and "kexidb_minor_ver" database properties stored in a project created by Kexi, inside "kexidb" internal table. This is information about KexiDB library version used__ for creating the project (or most recently used to altering it). These properties are available after opening a Kexi-compatible project database using KexiDB::Connection object. Then you are able to get them using:

 int KexiDB::Connection::versionMajor()
 int KexiDB::Connection::versionMinor()