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:
$ADOdbLocation = '/location/path/to/adodb/adodb.inc.php';
The above line should read like so:
$ADOdbLocation = '/location/path/to/adodb/';
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
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
$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".
- 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:
- Add the following line to
config.phpafter the include for
$ADOdbLocationis the location of the ADOdb package defined within
adodb-connect.php. (In normal circumstances, you would include this
- Copy the following file to
$ADOdbLocationpmwiki-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).
- 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
- To test, create a db error of some type -- an invalid SQL SELECT will suffice. All being well, the error will be written to
- To use notify, first ensure that you have notify working on your wiki, then add a line like the following to
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]
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-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)
See discussion at DatabaseStandard-Talk