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?
Working towards a standard for database integration to PmWiki.
Requires ADOdb. See below.
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:
The above line should read like so:
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.
$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
The ADOdbConnect function returns either
$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.
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".
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:
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]