Subversion-Projekte lars-tiefland.php_share

** Introduction:

PEAR MDB is a project to merge PEAR DB and Metabase into one DB

abstraction layer.

You can get info on these at:

  PEAR DB: http://pear.php.net

  Metabase: http://phpclasses.upperdesign.com/browse.html/package/20/

At these URLs you will also find the licensing information on these two

projects along with the credits.

If you have any questions or suggestions you can contact me (Lukas Smith)

at this email address:

  smith@backendmedia.com

Co-Author is Christopher Linn:

  clinn@backendmedia.com

Or even better post a message to these 3 mailinglists (please include

all of these because there are people on each of these mailinglists that

care about this project and have asked to be included in any

discussion):

  pear-dev@lists.php.net

  metabase-dev@yahoogroups.com

  dev@binarycloud.tigris.org

** Features

MDB provides a common API for all support RDBMS. The main difference to most

other DB abstraction packages is that MDB goes much further to ensure

portability. Among other things MDB features:

* An OO-style query API

* A DSN (data source name) or array format for specifying database servers

* Datatype abstraction and on demand datatype conversion

* Portable error codes

* Sequential and non sequential row fetching as well as bulk fetching

* Ordered array and associative array for the fetched rows

* Prepare/execute (bind) emulation

* Sequence emulation

* Replace emulation

* Limited Subselect emulation

* Row limit support

* Transactions support

* Large Object support

* Index/Unique support

* Extension Framework to load advanced functionality on demand

* Table information interface

* RDBMS management methods (creating, dropping, altering)

* RDBMS independent xml based schema definition management

* Altering of a DB from a changed xml schema

* Reverse engineering of xml schemas from an existing DB (currently only MySQL)

* Full integration into the PEAR Framework

* Wrappers for the PEAR DB and Metabase APIs

* PHPDoc API documentation

Currently supported RDBMS:

MySQL

PostGreSQL

Oracle (beta)

Frontbase SQL (alpha)

Querysim

Other soon to follow.

** Getting started:

I would first recommend taking a look at MDB_test.php.

This should give you a general feel of how to interact with MDB.

After that you may want to take a look at the rather large API

at www.backendmedia.com/MDB/docs. There you will also find a document

describing the xml schema format and a little tutorial (it was

just recently ported from Metabase, so it may contain errors).

** Current State:

The current release can be found at the PEAR webpage:

  http://pear.php.net/package-info.php?package=MDB

----------------------------------- WARNING -----------------------------------

MDB is still undergoing active development and therefore its API might

change slightly until drivers for ODBC and Sybase/MS-SQL have been added. But

since MDB is heavily based on PEAR DB and Metabase who both have drivers for

these RDBMS this is probably fairly unlikely to happen or have large effects.

It is unlikely that BC specific code will be written to maintain BC for only

release prior to this version.

Furthermore the manager might see some drastic changes in the future which would

affect the manager.php and the get*Definition() methods in the manager_*.php.

However this will most likely be extending the functionality and not changing

existing functionality.

----------------------------------- WARNING -----------------------------------

All but the MySQL driver are still missing the reverse engineering of xml schemas.

The core of MDB is very stable since quite sometime, with very few bugs that

had to be fixed or API changes that had to be made. The manager is still in a

bit of flux as the API is still not final and some methods still need to be

split up into smaller methods to improve readability and flexability. Also

new features will be added as needed by the MDB_frontend project.

The 1.0 of MDB can be considered stable for the RDBMS it currently

supports. As with any software there is the possiblity of bugs which I am

commited to fix quickly. As explained above there may be changes in the API

that may break BC until we hit 1.1. The version number 1.0 was just a natural

progression from the initial version number of 0.9. This 1.0 release is a

definite milestone and the version number reflects this. The next milestone

will be 1.1 to be expected in Fall 2002 (see the Roadmap for details).

** Package Content:

As a user the only php script you will need to include is MDB.php which will

install to your PEAR root directory. All other files and their containing

classes will be included via MDB::factory(), MDB::connect(), MDB::loadFile().

Currently the supported drivers are mysql and pgsql.

File you may include are:

peardb_wrapper (PEAR DB Wrapper)

metabase_wrapper (Metabase Wrapper)

Date (MDB_Date class which helps in converting MDB Timestamps to other formats)

Manager (MDB_Manager class which does the XML schema handling)

The only exception to this rule is reverse_engineer_xml_schema.php which you

have to call directly from a browser. This very simple script will help you

with handling schema files and create schema files from existing databases. This

script requires PEAR::Var_Dump package.

The package also contains various files that explain how MDB works. These files

will install into your docs dir found in the PEAR root dir.

Furthermore MDB provides an extensive testing framework that works through a

browser and command line interface. There are several other test that test the

two wrappers. These files will install into your test dir found in the

PEAR root dir.

** Documentation:

PHPDoc generated documentation can be found at: http://www.backendmedia.com/MDB/docs/

The entire "public" API and most of the "private" methods (except for some of

the lob classes) have been documented with PHPDoc comments. Most of the API

is borrowed from PEAR DB, so you can look there for detailed documentation.

Since there are a large number of new methods available thanks to the Metabase

heritage of MDB you will also have to take a look in the Metabase documentation

(which can be found at the URL mentioned above, but does require that

you register with phpclasses). Most of these Metabase functions have

been renamed. Looking at the metabase_wrapper.php file should help finding

the new method name in MDB.

For example ($db being an MDB object):

  $converted_value = MetabaseGetTimestampFieldValue($database, $value);

would now be

  $converted_value = $db->getTimestampValue($value);

If you want to help out with documentation please email me.

** Testing:

For most of the tests you can set the username/password/hostname in the relevant

config file. The user will need to have the right to create new databases.

test.php/clitest.php/testchoose.php: Is the native testing suite provided by

MDB. Please see the README in the tests directory for details.

driver_test.php: Is the testing suite provided by Metabase you will need

to configure what driver to test and the relevant section in the array found in

driver_test_config.php to fit your enviornment.

MDB_test.php: Several test calls to MDB's native API.

MDB_pear_wrapper_test.php: Several test calls to MDB's PEAR DB Wrapper.

MDB_test.php and MDB_pear_wrapper_test.php require PEAR::VAR_Dump package and

are configured to use the following settings:

username = metapear

password = funky

hostname = localhost

** How to write new Drivers:

Skeleton drivers are provided in the docs directory of the MDB package.

MDB is mostly based in Metabase. The method naming and formatting is

changed to better match the PEAR CS however. Therefore the best starting

point is to first take one of the Metabase drivers (metabase_[DRIVER NAME].php)

and compare it with a corresponding MDB driver ([DRIVER NAME].php and

manager_[DRIVER NAME].php). This will give a good idea what changes you have to

make to an existing Metabase driver in order to make it MDB compatible.

(Note: In order to get the Metabase code you will need to download it from

phpclasses using the URL provided at the top).

Alot of methods have been renamed from the original Metabase API. The best

place to find the name to what a method has been renamed you should look

at the metabase_wrapper.php file.

Please also note that some methods have been taken from PEAR DB so for some

missing methods you can check the PEAR DB driver.

Another alternative would be to take a MDB driver and hack it to fit

the new RDBMS. I would however recommend working with the existing

Metabase driver for that RDBMS when doing those changes. This will

surely be faster and it will ensure that the new driver takes full

advantage of the MDB framework (which is to large parts based on

Metabase).

In order to check compliance of the driver with MDB you can use the testing

suite (see the "testing" section above)

** History

MDB was started after Manuel broad be into the discussion about getting the

features of Metabase into PEAR that was going on (again) in December 2001. He

suggested that I could take on this project. After alot of discussion about

how when and if etc I started development in February 2002.

MDB is based on Metabase but has been reworked severely to better match

the PEAR DB API and PEAR CS. The approach I have taken so far is to take DB.php

from PEAR DB and make it create a Metabase object. I have changed the

Metabase structure slightly. The formatting has been reworked

considerably to better fit the final structure (MDB standalone with a

BC-wrapper for Metabase and PEAR DB), to fit the PEAR CS and to make it

easier for other people to contribute.

The metabase_interface.php was been renamed to metabase_wrapper.php and

now only serves as a wrapper to keep BC with Metabase. A wrapper will

have to be created for PEAR DB as well.

Basically the result is a Metabase that is really close to the PEAR DB

structure. I have also added any missing methods from PEAR DB. Work on

moving the error handling to PEAR error handling is under way but still

needs some work.

** Credits (never to early for those huh? :-)  ):

I would especially like to thank Manuel Lemos (Author of Metabase) for

getting me involved in this and generally being around to ask questions.

I would also like to thank Tomas Cox and Stig S. Bakken from the PEAR

projects for help in undertstanding PEAR, solving problems and trusting

me enough. Paul Cooper for the work on the pgsql driver. Furthermore I

would like to thank Alex Black for being so enthusiastic about this

project and offering binarycloud as a test bed for this project.

Christian Dickmann for being the first to put MDB to some real use,

making MDB use PEAR Error and working on the XML schema manager.

Finally Peter Bowyer for starting the discussion that made people pick

up this project again after the first versions of what was then called

"metapear" have been ideling without much feedback. I guess I should

also thank BackendMedia (my company :-)  ) for providing the necessary means

to develop this on company time (actually for the most part my entire

life is company time ... so it goes)