View source for KDb/Drivers/How to implement a KDb driver

{{Note|Development questions: contact the maintainer: [https://community.kde.org/Kexi/Contact#Contact_active_contributors_directly]}}

== Introduction ==

The internal KDb API of database drivers is designed for development new and maintaining existing drivers. Along the way a number of rules and recommendations have been formulated.

* For best results, contact the maintainer prior to starting any work
* New drivers should be developed for the master or lastest stable branch
* The KDb git repository is sufficient source code dependency for the task
* For automatic testing, tests from the KDb repository should 100% succeed, it is recommended to add new specific tests when it makes sense
* For manual tests  it is adviced to also build KEXI (kexi.git), and run with the new driver

== Directory layout ==

* Drivers are located in src/drivers/ subdirectory
* Autotests are located in autotests/ subdirectory
* Manual tests are located in tests/ subdirectory

== Details ==
* The API is split to cover a number of smaller internal aspects of a driver. They should be easier to understand by the developer without leaving space for interpretation. 
* It is advised to use lower-level '''C API''' of the given backend/database, instead of using its C++ (or any other high level) API. C++ API usually implements data handling aspects in its own specific manner. This can make hard or impossible to "map" the APIs to KDb. Aother possible benefit of using the '''C API''' is performance due to higher level of control. Then, lower-level APIs may be more stable and more wide accessible.
* To implement a driver derive from a few KDb classes:

**   KDbConnection
**   KDbCursor
**   KDbDriver

* Class naming convention: add a prefix of your drivers name to the class name, for example in case of MySQL the name of the cursor class was mapped from KDbCursor to KDbMySqlCursor. 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. Adding another file-based driver may be practical but at the moment not for KEXI, due to possible maintenance overhead.

* During the implementation you can learn about details of implementation of, for example, PostgreSQL driver's implementation, if the new database driver is server-based, or into SQLite driver's implementation, if the new database driver is file-based. These two drivers are usually best implemented and are updated for current API.

* Plugin description files. Each KDb driver is a software service implementing "KDb/Driver" service type. Thus, any driver has it's own .json file containing, the following fields (apart of other standard ones such as name, version):

* X-KDb-FileBased: true for file-based driver
* X-KDb-ImportingEnabled: true if database importing for this driver is supported
* For file-based drivers the Mimetypes field is important as well.

* Naming scheme for the driver binary is: kdb_*driver.so (on *nix), e.g.  kdb_sqlitedriver.so.
* Naming scheme for the driver's json file is kdb_*driver.json.