KDb/Drivers/How to implement a KDb driver: Difference between revisions

Latest revision as of 23:55, 24 June 2023

Note

Development questions: contact the maintainer: [1]

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.

Information

This page contains restored and modernized knowledge from the KexiDBDrivers_General.html page of kexi-project.org

@@ Line 1: / Line 1: @@
 {{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.
@@ Line 9: / Line 11: @@
 * 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
-  Drivers are located in kexidb/drivers/ 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.
-* 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 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:
-* 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.
+**   KDbConnection
+**   KDbCursor
+**   KDbDriver
-* 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.
+* 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.
-: 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.
+* 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.
-* 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.
+* 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.
-: Driver .desktop file has following custom fields defined:
+* 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-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:
+* 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.
-  kexidb_{name}driver.desktop
+* 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.
-: where {name} is a unique driver name, eg. sqlite3 or mysql.
+{{Info|This page contains restored and modernized knowledge from the KexiDBDrivers_General.html page of kexi-project.org}}