Quick links: Content - sections - sub sections
EN FR

jDb, the abstract layer to access to a database, has a plugin system, or "drivers". A driver allows to access to a specific database.

Activation

See the chapter about jDb tp know how to activate a driver for jDb.

Creating a jDb driver

A jDb driver must implement several classes:

  • a class which connects to database and executes queries, inheriting from jDbConnection
  • a class collecting results, inheriting from jDbResultSet
  • classes inheriting from jDbSchema and jDbTable, to allow to query and modify the schema of a database

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.dbschema.php : schema file

Each file shall declares and implements its related class:

  • exampleDbConnection : connection class
  • exampleDbResultSet : resultset class
  • exampleDbSchema and exampleDbTable : schema classes

Connection class

It must inherit from jDbConnection and implement methods marked as abstract in jDbConnection. 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 disconnection 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), or false if the query has failed
  • _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. It returns also a result set.
  • 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 abstract methods of jDbResultSet. This object should be returned by the _doQuery, _doLimitQuery and prepare() of the connection object.

You should redefine these 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 id 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 et execute, for prepared queries.

See jDbResultSet reference.

Schema classes

Many methods should be redefined. Look at the reference API to know which to implements.

Existing drivers

lib/jelix/plugins/db/ contains all jelix standard drivers : mysqli, postgresql, sqlite3, sqlsrv, oci.