view release on metacpan or  search on metacpan

BerkeleyDB.pod.P  view on Meta::CPAN

Berkeley DB library and the... TODO

The B<db_appinit>, B<db_cursor>, B<db_open> and B<db_txn> man pages are
particularly relevant.

The interface to Berkeley DB is implemented with a number of Perl
classes.

=head1 The BerkeleyDB::Env Class

The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB
function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and
B<DBENV-E<gt>open> in Berkeley DB 3.x (or later). Its purpose is to initialise a
number of sub-systems that can then be used in a consistent way in all
the databases you make use of in the environment.

If you don't intend using transactions, locking or logging, then you
shouldn't need to make use of B<BerkeleyDB::Env>.

Note that an environment consists of a number of files that Berkeley DB
manages behind the scenes for you. When you first use an environment, it
needs to be explicitly created. This is done by including C<DB_CREATE>
with the C<Flags> parameter, described below.

=head2 Synopsis

    $env = new BerkeleyDB::Env
             [ -Home         => $path, ]
             [ -Server       => $name, ]
             [ -CacheSize    => $number, ]
             [ -Config       => { name => value, name => value }, ]
             [ -ErrFile      => filename, ]
             [ -MsgFile      => filename, ]
             [ -ErrPrefix    => "string", ]
             [ -Flags        => number, ]
             [ -SetFlags     => bitmask, ]
             [ -LockDetect   => number, ]
             [ -TxMax        => number, ]
             [ -LogConfig    => number, ]
             [ -MaxLockers   => number, ]
             [ -MaxLocks     => number, ]
             [ -MaxObjects   => number, ]
             [ -SharedMemKey => number, ]
             [ -Verbose      => boolean, ]
             [ -BlobThreshold=> $number, ]
             [ -BlobDir      => directory, ]
             [ -Encrypt      => { Password => "string",
	                          Flags    => number }, ]

All the parameters to the BerkeleyDB::Env constructor are optional.

=over 5

=item -Home

If present, this parameter should point to an existing directory. Any
files that I<aren't> specified with an absolute path in the sub-systems
that are initialised by the BerkeleyDB::Env class will be assumed to
live in the B<Home> directory.

For example, in the code fragment below the database "fred.db" will be
opened in the directory "/home/databases" because it was specified as a
relative path, but "joe.db" will be opened in "/other" because it was
part of an absolute path.

    $env = new BerkeleyDB::Env
             -Home         => "/home/databases"
    ...

    $db1 = new BerkeleyDB::Hash
	     -Filename => "fred.db",
	     -Env => $env
    ...

    $db2 = new BerkeleyDB::Hash
	     -Filename => "/other/joe.db",
	     -Env => $env
    ...

=item -Server

If present, this parameter should be the hostname of a server that is running
the Berkeley DB RPC server. All databases will be accessed via the RPC server.

=item -Encrypt

If present, this parameter will enable encryption of  all data before
it is written to the database. This parameters must be given a hash
reference. The format is shown below.

    -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }

Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>.

This option requires Berkeley DB 4.1 or better.

=item -Cachesize

If present, this parameter sets the size of the environments shared memory
buffer pool.

=item -TxMax

If present, this parameter sets the number of simultaneous
transactions that are allowed.  Default 100.  This default is
definitely too low for programs using the MVCC capabilities.

=item -LogConfig

If present, this parameter is used to configure log options.

=item -MaxLockers

If present, this parameter is used to configure the maximum number of
processes doing locking on the database.  Default 1000.

=item -MaxLocks

If present, this parameter is used to configure the maximum number of
locks on the database.  Default 1000.  This is often lower than required.

BerkeleyDB.pod.P  view on Meta::CPAN

To delete a filter pass C<undef> to it.

=head2 The Filter

When each filter is called by Perl, a local copy of C<$_> will contain
the key or value to be filtered. Filtering is achieved by modifying
the contents of C<$_>. The return code from the filter is ignored.

=head2 An Example -- the NULL termination problem.

Consider the following scenario. You have a DBM database that you need
to share with a third-party C application. The C application assumes
that I<all> keys and values are NULL terminated. Unfortunately when
Perl writes to DBM databases it doesn't use NULL termination, so your
Perl application will have to manage NULL termination itself. When you
write to the database you will have to use something like this:

    $hash{"$key\0"} = "$value\0" ;

Similarly the NULL needs to be taken into account when you are considering
the length of existing keys/values.

It would be much better if you could ignore the NULL terminations issue
in the main application code and have a mechanism that automatically
added the terminating NULL to all keys and values whenever you write to
the database and have them removed when you read from the database. As I'm
sure you have already guessed, this is a problem that DBM Filters can
fix very easily.

## nullFilter

Hopefully the contents of each of the filters should be
self-explanatory. Both "fetch" filters remove the terminating NULL,
and both "store" filters add a terminating NULL.


=head2 Another Example -- Key is a C int.

Here is another real-life example. By default, whenever Perl writes to
a DBM database it always writes the key and value as strings. So when
you use this:

    $hash{12345} = "something" ;

the key 12345 will get stored in the DBM database as the 5 byte string
"12345". If you actually want the key to be stored in the DBM database
as a C int, you will have to use C<pack> when writing, and C<unpack>
when reading.

Here is a DBM Filter that does it:

## intFilter

This time only two filters have been used -- we only need to manipulate
the contents of the key, so it wasn't necessary to install any value
filters.

=head1 Using BerkeleyDB with MLDBM

Both BerkeleyDB::Hash and BerkeleyDB::Btree can be used with the MLDBM
module. The code fragment below shows how to open associate MLDBM with
BerkeleyDB::Btree. To use BerkeleyDB::Hash just replace
BerkeleyDB::Btree with BerkeleyDB::Hash.

    use strict ;
    use BerkeleyDB ;
    use MLDBM qw(BerkeleyDB::Btree) ;
    use Data::Dumper;

    my $filename = 'testmldbm' ;
    my %o ;

    unlink $filename ;
    tie %o, 'MLDBM', -Filename => $filename,
                     -Flags    => DB_CREATE
                    or die "Cannot open database '$filename: $!\n";

See the MLDBM documentation for information on how to use the module
and for details of its limitations.

=head1 EXAMPLES

TODO.

=head1 HINTS & TIPS

=head2 Sharing Databases With C Applications

There is no technical reason why a Berkeley DB database cannot be
shared by both a Perl and a C application.

The vast majority of problems that are reported in this area boil down
to the fact that C strings are NULL terminated, whilst Perl strings
are not. See L<An Example -- the NULL termination problem.> in the DBM
FILTERS section for a generic way to work around this problem.


=head2 The untie Gotcha

TODO

=head1 COMMON QUESTIONS

This section attempts to answer some of the more common questions that
I get asked.


=head2 Relationship with DB_File

Before Berkeley DB 2.x was written there was only one Perl module that
interfaced to Berkeley DB. That module is called B<DB_File>. Although
B<DB_File> can be build with Berkeley DB 1.x, 2.x, 3.x or 4.x, it only
provides an interface to the functionality available in Berkeley DB
1.x. That means that it doesn't support transactions, locking or any of
the other new features available in DB 2.x or better.

=head2 How do I store Perl data structures with BerkeleyDB?

See L<Using BerkeleyDB with MLDBM>.

=head1 HISTORY