Quick links: Content - sections - sub sections
EN FR
The page corresponding to the latest stable release can be seen in the Jelix 1.8 Manual

Creating a jDb driver

A jDb driver must implement four classes :

  • a class which connects to database and executes queries, inheriting from jDbConnection
  • a class collecting results, inheriting from jDbResultSet
  • a utility class collecting basic infos on database such as table list, field list of a table. inheriting from jDbTools
  • a helper class to build requests, inheriting from jDaoGenerator

Namings and Files

Class names, file names and location depends on your driver name of course and must follow the scheme below.

Assert you have chosen example as driver name.

Driver files should be located in db/example/ sub-directory of a plugins repository.

Filename conventions :

  • example.dbconnection.php : connection file
  • example.dbresultset.php : resultset file
  • example.dbtools.php : tool file
  • example.daobuilder.php : dao query builder file

Each file shall declares and implements its related class :

  • exampleDbConnection : connection class
  • exampleDbResultSet : resultset class
  • exampleDbTools : tool class
  • exampleDaoBuilder : dao builder class

Connection class

It must inherit from jDbConnection and implement jDbConnection abstract methods.

Its role is to create or free a connection to the database, execute queries, initiate transaction.

So the connection class should redefine some methods:

  • The constructor, if you have some things to do during the instanciation
  • _connect() and _disconnect(), for the connection and the deconnection to the database.
  • _quote, to escape a string which will be used inside a query string.
  • _doQuery and _doLimitQuery, to execute queries which return records, so this methods should return an object which inherits from jDbResultset (see below)
  • _doExec, to execute queries like UPDATE, INSERT, DELETE. It should return the number of affected records, or false if the query failed
  • prepare(), to prepare queries
  • beginTransaction(), commit(), rollback(), for transaction
  • errorInfo() and errorCode(), to get the last error message and its code.
  • lastInsertId(), allowing to retrieve the last value of an auto incremented field.
  • _autoCommitNotify()

If the driver doesn't support a feature, it should throw an exception.

See jDbConnection reference.

Resultset Class

It must inherit from jDbResultSet and implement jDbResultSet abstract methods. This object should be returned bu the _doQuery and _doLimitQuery of the connection object.

You should redefine this methods:

  • _fetch() : it should retrieve the next record in the list of records. It should take care of the _fetchMode property. The _idResult property content the resource identifiant of the result set.
  • _free(), to free the resource of the result set
  • _rewind(), to put the "cursor" at the begin of the results list.
  • rowCount, which returns the number of results
  • bindColumn, bindParam, bindValue, columnCount and execute, for prepared queries

See jDbResultSet reference.

Utility Class

It must inherit from jDbTools. This class is used mainly by the jelix-scripts, to generate daos.

You should redefine this methods:

  • _getTableList(): returns an array of table names
  • _getFieldList(), returns the list of fields of a table. This list contains some jDbFieldProperties objects.
  • execSQLScript(), if you want to redefine the way how a SQL script is parsed an executed.

See jDbTools reference.

SLQ Query builder class

That class is useful to jDao. jDao generates PHP classes implementing hardcoded SQL queries dispatched in methods. Those queries, particularly their syntax vary between database systems. Those syntax subtleties are defined in each driver in a specific class.

It must inherit from @CjDaoGenerator and overload one or more of its methods, properties :

  • genSelectPattern()
  • _encloseName()
  • genUpdateAutoIncrementPK()
  • $propertiesListForInsert
  • $trueValue, $falseValue
  • _getAutoIncrementPKField()

See details in jDaoGenerator API reference .

Existing drivers

lib/jelix/plugins/db/ contains all jelix standard drivers : mysql, postgresql, sqlite, pdo, intuition.