view release on metacpan or  search on metacpan

TableHash.pm  view on Meta::CPAN

longer tied to the database. 


=head1 PARAMETER SUMMARY

The full list of recognized parameters is:

DBI Parameters

    Param       Default         Description
    ------------------------------------------------------------------------
    DBIDriver   'mysql'         Name of DBI driver to try to use (only
                                    mysql has currently been tested by the
                                    author).

    HostName    'localhost'     Host name containing the database and table;

    Port        undef           Port number if different from the standard.
    
    Login       ''              Login to use when connecting, if any.

    Password       ''               Password to use when connecting, if any.

SQL Parameters

    Param       Default         Description
    ------------------------------------------------------------------------
    Database    ''              Name of database to connect to.

    TableName   ''              Table to connect to.

    KeyField    ''              Name of field in which lookup key is found.

    ValueField  ''              Name of field to pull value from.
                                If empty or undef, then a
                                multi-value hash is used both for
                                saving and retrieving.  This is
                                called "multi-value mode".

Module Parameters

    Param       Default         Description
    ------------------------------------------------------------------------
    FixedKeys   {}              If supplied, gives names and
                                fixed, hardcoded values that other
                                keys in the table must have; this
                                effectively limits the scope of
                                the tied hash from operating over
                                the entire table to operating over
                                just the subset of records that
                                match the values in FixedKeys.
                                This is called "multi-key mode".

    RetrieveFields  []          In multi-value mode, limits the
                                fields that are retrieved; default
                                is all fields in the record.

=head1 SUPPORT

I am unable to provide any technical support for this module.  The
whole reason I had to make it was that I was way too busy (lazy?) to
write all that SQL code...

But you are encouraged to send patches, bug warnings, updates, thanks,
or suggestions for improvements to the author as listed below.

Just be aware that I may not have time to respond.  Please be sure to
put the name of this module somewhere in the Subject line.

The code is a pretty simple tied hash implementation, so you're on
your own to debug it.  If you're having trouble debugging via the
"tie" interface, try instantiating an object directly (or retrieving
it when you tie (see perltie)) and calling its methods individually.
Use the debugger or Data::Dumper to dump intermediate values at key
points, or whatever it takes.  Use your database server logs if you
want to see what SQL code is getting generated.  Or contribute a
debugging mode to this module which prints out or logs the SQL
statements before executing them.

=head1 BUGS/GOTCHAS

Problem: If you iterate or enumerate the hash, all keys get pulled in
from the database and stay stored in memory for the lifetime of the
object.  FIRSTKEY, which is called every time you do a keys(), each()
or any full iteration or enumeration over the tied hash (such as
copying it) retrieves and hangs on to a full list of all keys in
KeyField.  If the keys are long or there are lots of them, this could
be a memory problem.  (Don't confuse this with CacheMode in which BOTH
keys AND values are stored in memory.)

Solutions:  

    1) Don't iterate or enumerate.  Just fetch and store.
    2) Only iterate or enumerate on short tables. 
    3) LValue or RValue hash slices should be safe to do.


=head1 INSTALLATION

Using CPAN module:

    perl -MCPAN -e 'install DBIx::TableHash'

Or manually:

    tar xzvf DBIx-TableHash*gz
    cd DBIx-TableHash-?.??
    perl Makefile.PL
    make
    make test
    make install

=head1 SEE ALSO

The DBIx::TableHash home page:

    http://christhorman.com/projects/perl/DBIx-TableHash/

The implementation in TableHash.pm.

The perlref and perltie manual pages.