This distribution contains Tie::DBI and Tie::RDBM, two modules that
allow you to tie associative arrays to relational databases using the
DBI library.  The hash is tied to a table in a local or networked
database.  Reading from the hash retrieves values from the datavbase.
Storing into the hash updates the database (if you have sufficient
privileges).

Tie::DBI implements a fully general binding between the hash and the
table, allowing you to access fields in this manner:

   $h{strawberries}->{quantity} = 228;

Tie::RDBM implements a more limited binding which gives you access to
only one column of the table.  However it is faster, can create and
destroy tables on the fly, and provides an interface whereby you can
store and retrieve complex Perl objects from the database table.

In addition to this package, you will need the DBI database interface
module, plus the DBD driver for the database of your choice.  To be
able to store and retrieve non-scalar values via the Tie::RDBM
interface you will also need Storable.pm These are all available at a
CPAN near you:

	http://www.perl.com/CPAN/

To install:

	1. perl Makefile.PL
	2. make
	3. make test [optional]
	4. make install

To read the documentation:

	perldoc Tie::DBI
        perldoc Tie::RDBM

"make test" requires you to have a database named "test" up and
running on the local machine.  The database must allow table add and
drop privileges for the current user.  The test script will search for
an installed DBD driver to use.  You can override its choice by
specifying DRIVER=<driver name> on the command line.  For example:
	
   make test DRIVER=mysql

If you need to specify a different database, or need to provide a
username and password to log in, you can provide these values as DB,
USER and PASS, respectively, as in:

   make test DRIVER=Oracle DB=DEMO USER=fred PASS=xyzzy

And some drivers, such as Pg, want funny database names, as in:

   make test DRIVER=Pg DB=dbname=test USER=fred PASS=xyzzy

Databases differ in their capabilities, and some can't support binary
data types (or support them in a difficult, non-standard way).  Such
databases include mSQL, Postgres and Informix.  On those databases, it
is not possible to store arbitrary Perl data structures into Tie::RDBM
hashes.  For this reason Tie::RDBM tests #13 and #14 will be skipped.
The test will fail if you do not have Storable.pm installed on your
system.

The Postgres driver breaks when you try to set a field to null by
passing it an under variable.  This causes Tie::DBI test #29 to fail.

In addition, there is vast heterogeneity among DBD drivers which
renders this interface inoperative for certain databases.  It has been 
tested and is known to work on the following databases:

	1) DBD::mysql
	2) DBD::Oracle
	3) DBD::mSQL (skips Tie::RDB tests 13-14)
	4) DBD::CSV (skips Tie::DBI test #29)
	5) DBD::Postgres (skips Tie::RDBM tests 13-14 and flunks Tie::DBI test #29)
	6) DBD::Informix (skips Tie::RDBM tests 13-14)
	7) DBD::Sybase (partial, croaks on each())
	8) DBD::Solid
	9) DBD::ODBC (on mysql ODBC driver)

Microsoft SQL server works partially with Tie::DBI (everything but
"each") and not at all with Tie::RDBM.  This is because SQL server
doesn't allow there to be multiple pending queries on the database.
Let me know if you can get it to run with true Sybase servers, and any
other drivers you try.

For more information, see the perldoc documentation.  Also be sure to
check out Gerald Richter's DBIx::Recordset, which puts a tied array
interface on the results of arbitrary SQL expressions and is optimized 
for use in embperl.

The latest version of this module is available on CPAN.

References:

The DBI home page:
http://www.hermetica.com/technologia/perl/DBI

Gerald Richter's DBIx::Recordset:
http://perl.apache.org/embperl.html.

Lincoln Stein
lstein@cshl.org