view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    copy.

    Please remember that the object returned by the _copy methods is no
    longer tied to the database.

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.

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.

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.

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

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.

    The mysql home page:

        http://mysql.com/