DatabaseStandard

Summary: Working towards a standard for database integration to PmWiki
Version: 0.1
Prerequisites: ADOdb
Status:beta
Maintainer: XES
Categories:

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
Additional:

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)

Cookbook /
AuthPhpBB3  Use phpBB3 user authentication for PmWiki
AuthPhpBBUsersAndGroups  Use phpBB3 user authentication and groups for PmWiki
AuthPunBB  Use PunBB/FluxBB user authentication for PmWiki (Draft)
AuthUserDbase  Enables user authentication via database, whether from another application, or standalone (beta)
AuthUserDbase-Talk  Enables user authentication via database (beta)
CompareDatabaseRecipes  Comparison of Database Recipes for PmWiki (draft)
DatabaseStandard-Talk  
DatabaseStandard-Users  User notes for the DatabaseStandard recipe.
DataQuery  Retrieve records and query results from any database supported by ADOdb (such as MySQL) and portray them as wiki pages, allowing them to be processed by other wiki functions such as pagelists, includes, page text variables, and ZAP. (beta)
SelectQuery  Run a SQL SELECT query based on parameters submitted (demo at Interdependent Web)
SQLite  Store wiki pages in an SQLite database file (Experimental)

Contributors

XES, Ben Stallings, Marc

Comments

See discussion at DatabaseStandard-Talk

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.