FrontPage/KexiDBDesign/KexiDBDrivers

General Issues For KexiDB Driver Developers

Questions on specific implementation problems, proposals for KexiDB API extending, etc.? - please contact Jaroslaw Staniek, KexiDB designer, maintainer, staniek@kde.org.

KexiDB API for database drivers is designed for developing drivers using following rules:

• For KexiDB source code see kexidb/ subdirectory in Kexi source code tree.

 Drivers are located in kexidb/drivers/ subdirectory.

• The API is splitted for a number of really small internal pieces (methods) that should be well understood by driver developer. Pieces are smaller to avoid misunderstunding what exactly the given method should deliver and how it shopuld behave. Small pieces can also avoid much of development work when KexiDB is about to change and there is something to add or change in the drivers code.

• It is hightly adviced to use lower-level C API of the given database, instead of using C++ API. In fact, C++ API usually implements things like database cursors in own (often magic) fashion, while KexiDB tries to deliver generic cursor's framework. Other issue when you're using C API instead of C++ is efficiency of the resulted solution.

• Newer KexiDB API versions have more-and-more options that allow given driver's implementation talk to KexiDB about what functionality driver can deliver and/or in what fashion (for example transactions support: no trasactions/single transaction/multiple transaction/multiple nested transactions).

• KexiDB drivers are work as the KDE Service Libraries

• To add your driver implementation you will need to derive from few classes from KexiDB (not just the Driver class):

  KexiDB::Connection
  KexiDB::Cursor
  KexiDB::Driver

• Naming convention: add a prefix of your drivers name to the class name, for example: KexiDB::Cursor --> KexiDB::MySqlCursor. Names should be started from uppercase letter.

• Support for file-based (not server-connection based) has been added. Currently it is used for SQLite driver, the default driver for Kexi.

• During implementation you can learn how things were implemented by looking into PostgreSQL driver's implementation (if your database is server-based) and into SQLite driver's implementation (if your database is file-based). These two drivers are usually best implemented and updated for current API state.

Note: please don't be confused that PostgreSQL driver uses libpqxx C++ API, while above we've discussed that using C API would be a better choice. PostgreSQL driver case is just exception from the rule and shows that using C++ API there could be redundant.

• Description files. Each KexiDB driver is a KDE Service implementing "Kexi/DBDriver" service type (see kexidb/kexidb_driver.desktop file). Thus, any driver has it's own .desktop file installed to KDE services directory on install time.

Driver .desktop file has following custom fields defined:

• X-Kexi-DriverName, e.g. SQLite3 or MySQL, case insensitive
• X-Kexi-DriverType, possible types:
  • File for file-based db drivers (currently SQLite 2 and 3)
  • Server for server-based db drivers
• X-Kexi-FileDBDriverMime, only meaningful for file-based db drivers (e.g. application/x-kexiproject-sqlite3 for SQLite 3). It's used to detect files by it's header and/or name extension
• X-Kexi-KexiDBVersion, driver version, it's important since it must be compatible with kexidb library. If not, driver will not be loaded. Format of version string is currently X.Y, where X == major version, Y == minor version (example: 1.4).

Note: Versions are usually backward compatible (1.4 driver should work when 1.3 is expected) but not in the opposite way. Always keep version value of X-Kexi-KexiDBVersion field of your driver updated for current KexiDB version.

• Naming guidelines. .desktop file should be named using following form:

 kexidb_{name}driver.desktop

where {name} is a unique driver name, eg. sqlite3 or mysql.