NAME

Paranoid::BerkeleyDB -- Paranoid BerkeleyDB Usage Routines

MODULE VERSION

$Id: BerkeleyDB.pm,v 0.2 2008/02/27 06:46:39 acorliss Exp $

SYNOPSIS

  use Paranoid::BerkeleyDB;

  $db = Paranoid::BerkeleyDB->new(DbDir => '/tmp', DbName => 'foo.db');
  $rv = $db->addDb($dbname);

  $val = $db->getVal($key);
  $val = $db->getVal($key, $dbname);

  $rv = $db->setVal($key, $val);
  $rv = $db->setVal($key, $val, $dbname);

  @keys = $db->getKeys();
  @keys = $db->getKeys($dbname);

  $db->purgeDb();
  $db->purgeDb($dbname);

  @dbs = $db->listDbs();

REQUIREMENTS

Paranoid

Paranoid::Debug

Paranoid::Filesystem

Paranoid::Lockfile

BerkeleyDB;

DESCRIPTION

This provides a OO-based wrapper for BerkeleyDB that creates concurrent-access BerkeleyDB databases. Each object can have multiple databases, but all databases within an object will use a single shared environment. To make this multiprocess safe an external lock file is used with only one process at a time allowed to hold an exclusive write lock, even if the write is intended for a different database.

Databases and environments are created using the defaults for both the environment and the databases. This won't be the highest performance implementation for BerkeleyDB, but it should be the safest and most robust. This is part of the Paranoid Suite, after all.

Limitations: all keys and all values must be valid strings. That means that attempting to set a valid key's associated value to undef will fail to add that key to the database.

METHODS

new

  $db = Paranoid::BerkeleyDB->new(DbDir => '/tmp', DbName => 'foo.db');

Creating an object will fail if the BerkeleyDB module is not present and return undef. Two arguments are required: DbDir which is the path to the directory where the database files will be stored, and DbName which is the filename of the database itself. If DbDir doesn't exist it will be created for you automatically.

This method will create a BerkeleyDB Environment and to support multiprocess transactions.

Any errors in the operation will be stored in Paranoid::ERROR.

addDb

  $rv = $db->addDb($dbname);

The adds another database to the current object and environment. Calling this method does require an exclusive write to the database to prevent race conditions.

Any errors in the operation will be stored in Paranoid::ERROR.

getVal

  $val = $db->getVal($key);
  $val = $db->getVal($key, $dbname);

The getVal method retrieves the associated string to the passed key. Called with one argument the method uses the default database. Otherwise, a second argument specifying the specific database is required.

Requesting a non-existent key or from a nonexistent database will result in an undef being returned. In the case of the latter an error message will also be set in Paranoid::ERROR.

setVal

  $rv = $db->setVal($key, $val);
  $rv = $db->setVal($key, $val, $dbname);

This method adds or updates an associative pair. If the passed value is undef the key is deleted from the database. If no database is explicitly named it is assumed that the default database is the one to work on.

Requesting a non-existent key or from a nonexistent database will result in an undef being returned. In the case of the latter an error message will also be set in Paranoid::ERROR.

getKeys

  @keys = $db->getKeys();
  @keys = $db->getKeys($dbname);

This returns all of the keys in the requested database, in hash order.

purgeDb

  $db->purgeDb();
  $db->purgeDb($dbname);

This method purges all associative pairs from the designated database. If no database name was passed then the default database will be used. This method returns the number of records purged, or a -1 if an invalid database was requested.

listDbs

  @dbs = $db->listDbs();

Returns a list of databases accessible by this object.

HISTORY

None as of yet.

AUTHOR/COPYRIGHT

(c) 2005 Arthur Corliss (corliss@digitalmages.com)

cpanm Paranoid

perl -MCPAN -e shell
install Paranoid