• View
• Edit
• History
• Attach
• Print
• Backlinks

DatabaseStandard

Questions answered by this recipe

This section is optional; use it to indicate the types of questions (if any) this recipe is intended to answer. How can you create a new cookbook recipe (or update your recipe) to take advantage of the same database standards as other cookbook authors? How can you write a cookbook recipe that works in dozens of different databases?

Description

Working towards a standard for database integration to PmWiki.

Notes

Requires ADOdb. See below.

Prerequisites

Admins should install ADOdb in their cookbook/ folder OR set $ADOdbLocation to point to the adodb folder if it is located elsewhere. You can set $ADOdbLocation in your local/config file like so: $ADOdbLocation = '/location/path/to/adodb/adodb.inc.php';

The above line should read like so: $ADOdbLocation = '/location/path/to/adodb/';

adodb-connect.php

Install this file in your cookbook/ folder: adodb-connect.phpΔ

It is not necessary or desirable to include adodb-connect.php in your config.php. It does not do anything by itself; it is designed to be included within a recipe.

config.php Set-Up

$Databases['connection_name'] = array(
 'driver' => 'mysql',
 'hostname' => 'db.example.net',
 'database' => 'database_name',
 'username' => 'user_name',
 'password' => 'example_password');

"Driver" must match one of the ADOdb-supported database types. You may specify as many connection_names in this way as you have databases on your system -- connections to them will only be opened as needed by the recipes.

Note: It appears that you must use a different username and password for each connection (which is to say each database). This is inconvenient, but until we find a better solution it's the only workaround.

starting an ADOdb connection in your recipe

Note: the instructions below are for recipe authors, NOT FOR THOSE WHO ARE USING RECIPES THAT HAVE ALREADY BEEN WRITTEN. Do not use these lines in your config.php file, only in a recipe file!

To take advantage of sharing database connections to a single database, use the ADOdbConnect function like this:

include_once "$FarmD/cookbook/adodb-connect.php";
  ADOdbConnect('connection_name');

The database will be assigned to the global object $DB['connection_name'], and you can then pass commands to the object as described in the ADOdb documentation. If another recipe has already opened a connection to $DB['connection_name'], the function will return true and take no further action.

The ADOdbConnect function returns either true (if successful) or an error message. To handle the error, you might do something like this instead of the function call above:

$out = ADOdbConnect('connection_name');
  if ($out !== TRUE) return $out;

If all cookbook authors use this standard, PmWiki only needs to connect once per database per instance.

Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

• 2006-11-01 version 0.1

ADOdb error handling in PmWiki

Ben asked me to post an example of how to use the inbuilt ADOdb error handling with PmWiki. The benefits of doing this are that all recipes will automatically be provided with a db error handler. The recipe author has to do nothing at all to benefit from this feature.

From a PmWiki admin point of view, db error reporting is centralised and can be managed as a single task.

In addition, one can take advantage of PmWiki's features.

For example, say you want to receive email notification of all db errors as they occur. That's fine, but if you configure the db error handler to send an email for each error then there's the problem of managing a potentially constant stream of emails. Instead, you can write errors to a PmWiki page and then apply a PmWiki notify to that page. In this way, you can receive immediate notification of a db problem, and can set the notify parameters to suppress a potential avalanche of emails.

To use this demonstration of ADOdb's error handling you need to do the following:

1. Add the following line to config.php after the include for adodb-connect.php
   require_once $ADOdbLocation.'pmwiki-adodb-errorhandler.inc.php';
   where $ADOdbLocation is the location of the ADOdb package defined within adodb-connect.php. (In normal circumstances, you would include this require_once within adodb-connect.php itself.)
2. Copy the following file to $ADOdbLocation
   pmwiki-adodb-errorhandler.inc.phpΔ
   This version allows you to write errors to Site.DbErrors (when ADODB_ERROR_LOG_TYPE == 4). In addition, it has also been amended to allow it to send an email on every db error (when ADODB_ERROR_LOG_TYPE == 1).
3. Configure the error handler via the following parameters in config.php. You can find more on PHP error_log here
   define('ADODB_ERROR_LOG_TYPE',n);
   where n determines where the db errors are written
   • n=0: error_log
   • n=1: email
   • n=2: remote
   • n=3: file
   • n=4: PmWiki
   For the purposes of the demo, simply set
   define('ADODB_ERROR_LOG_TYPE',4);
4. To test, create a db error of some type -- an invalid SQL SELECT will suffice. All being well, the error will be written to Site.DbErrors.
5. To use notify, first ensure that you have notify working on your wiki, then add a line like the following to Site.NotifyList
   notify=dbadmin@example.com name=Site.DbErrors

When ADODB_ERROR_LOG_FROM is defined and ADODB_ERROR_LOG_TYPE == 1, then all db errors will be sent via email. To configure this, set something like:

  define('ADODB_ERROR_LOG_TYPE',1);
  define('ADODB_ERROR_LOG_DEST','adodberrs@'.$_SERVER['SERVER_NAME'].'.com');
  define('ADODB_ERROR_LOG_FROM','From: dbconnect@'.$_SERVER['SERVER_NAME'].'.com');

[Note: the above comment was posted by Marc on January 11, 2007, at 06:57 AM]

See Also

References in Cookbook to DatabaseStandard (probably recipes using this recipe)

Contributors

XES, Ben Stallings, Marc

Comments

See discussion at DatabaseStandard-Talk