view release on metacpan or  search on metacpan

lib/DBD/DBM.pm  view on Meta::CPAN

=item C<BerkeleyDB>

Berkeley DB version up to v4 (and maybe higher) - requires additional
installation but is easier than GDBM_File on non-GNU systems.

db4 comes with a many tools which allow repairing and migrating
databases.  This is the B<recommended> dbm type for production use.

=item C<MLDBM>

Serializer wrapper to support more than one column for the files.
Comes with serializers using C<Data::Dumper>, C<FreezeThaw> and
C<Storable>.

=item C<YAML::MLDBM>

Additional serializer for MLDBM. YAML is very portable between languages.

=item C<MLDBM::Serializer::JSON>

Additional serializer for MLDBM. JSON is very portable between languages,
probably more than YAML.

=back

=head1 GOTCHAS AND WARNINGS

Using the SQL DROP command will remove any file that has the name specified
in the command with either '.pag' and '.dir', '.db' or your {f_ext} appended
to it.  So this be dangerous if you aren't sure what file it refers to:

 $dbh->do(qq{DROP TABLE "/path/to/any/file"});

Each DBM type has limitations.  SDBM_File, for example, can only store
values of less than 1,000 characters.  *You* as the script author must
ensure that you don't exceed those bounds.  If you try to insert a value
that is larger than DBM can store, the results will be unpredictable.
See the documentation for whatever DBM you are using for details.

Different DBM implementations return records in different orders.
That means that you I<should not> rely on the order of records unless
you use an ORDER BY statement.

DBM data files are platform-specific.  To move them from one platform to
another, you'll need to do something along the lines of dumping your data
to CSV on platform #1 and then dumping from CSV to DBM on platform #2.
DBD::AnyData and DBD::CSV can help with that.  There may also be DBM
conversion tools for your platforms which would probably be quicker.

When using MLDBM, there is a very powerful serializer - it will allow
you to store Perl code or objects in database columns.  When these get
de-serialized, they may be eval'ed - in other words MLDBM (or actually
Data::Dumper when used by MLDBM) may take the values and try to
execute them in Perl.  Obviously, this can present dangers, so if you
do not know what is in a file, be careful before you access it with
MLDBM turned on!

See the entire section on L<Table locking and flock()> for gotchas and
warnings about the use of flock().

=head1 BUGS AND LIMITATIONS

This module uses hash interfaces of two column file databases. While
none of supported SQL engines have support for indices, the following
statements really do the same (even if they mean something completely
different) for each dbm type which lacks C<EXISTS> support:

  $sth->do( "insert into foo values (1, 'hello')" );

  # this statement does ...
  $sth->do( "update foo set v='world' where k=1" );
  # ... the same as this statement
  $sth->do( "insert into foo values (1, 'world')" );

This is considered to be a bug and might change in a future release.

Known affected dbm types are C<ODBM_File> and C<NDBM_File>. We highly
recommended you use a more modern dbm type such as C<DB_File>.

=head1 GETTING HELP, MAKING SUGGESTIONS, AND REPORTING BUGS

If you need help installing or using DBD::DBM, please write to the DBI
users mailing list at dbi-users@perl.org or to the
comp.lang.perl.modules newsgroup on usenet.  I cannot always answer
every question quickly but there are many on the mailing list or in
the newsgroup who can.

DBD developers for DBD's which rely on DBD::File or DBD::DBM or use
one of them as an example are suggested to join the DBI developers
mailing list at dbi-dev@perl.org and strongly encouraged to join our
IRC channel at L<irc://irc.perl.org/dbi>.

If you have suggestions, ideas for improvements, or bugs to report, please
report a bug as described in DBI. Do not mail any of the authors directly,
you might not get an answer.

When reporting bugs, please send the output of $dbh->dbm_versions($table)
for a table that exhibits the bug and as small a sample as you can make of
the code that produces the bug.  And of course, patches are welcome, too
:-).

If you need enhancements quickly, you can get commercial support as
described at L<http://dbi.perl.org/support/> or you can contact Jens Rehsack
at rehsack@cpan.org for commercial support in Germany.

Please don't bother Jochen Wiedmann or Jeff Zucker for support - they
handed over further maintenance to H.Merijn Brand and Jens Rehsack.

=head1 ACKNOWLEDGEMENTS

Many, many thanks to Tim Bunce for prodding me to write this, and for
copious, wise, and patient suggestions all along the way. (Jeff Zucker)

I send my thanks and acknowledgements to H.Merijn Brand for his
initial refactoring of DBD::File and his strong and ongoing support of
SQL::Statement. Without him, the current progress would never have
been made.  And I have to name Martin J. Evans for each laugh (and
correction) of all those funny word creations I (as non-native
speaker) made to the documentation. And - of course - I have to thank
all those unnamed contributors and testers from the Perl
community. (Jens Rehsack)