NAME

Bot::Cobalt::DB - Locking Berkeley DBs with serialization

SYNOPSIS

  use Bot::Cobalt::DB;
  
  ## ... perhaps in a Cobalt_register ...
  my $db_path = $core->var ."/MyDatabase.db";
  my $db = Bot::Cobalt::DB->new(
    File => $db_path,
  );
  
  ## Open (and lock):
  $db->dbopen;
  
  ## Do some work:
  $db->put("SomeKey", $some_deep_structure);
  
  for my $key ($db->dbkeys) {
    my $this_hash = $db->get($key);
  }
  
  ## Close and unlock:
  $db->dbclose;

DESCRIPTION

Bot::Cobalt::DB provides a simple object-oriented interface to basic DB_File (Berkeley DB 1.x) usage.

BerkDB is a fast and simple key/value store. This module uses JSON to store nested Perl data structures, providing easy database-backed storage for Bot::Cobalt plugins.

Constructor

new() is used to create a new Bot::Cobalt::DB object representing your Berkeley DB:

  my $db = Bot::Cobalt::DB->new(
    File => $path_to_db,

   ## Optional arguments:
   
    # Database file mode
    Perms => $octal_mode,

    ## Locking timeout in seconds
    ## Defaults to 5s:
    Timeout => 10,
    
    ## Normally, references are serialized transparently.
    ## If Raw is enabled, no serialization filter is used and you're 
    ## on your own.
    Raw => 0,
  );

Opening and closing

Database operations should be contained within a dbopen/dbclose:

  ## open, put, close:
  $db->dbopen || croak "dbopen failure";
  $db->put($key, $data);
  $db->dbclose;
  
  ## open for read-only, read, close:
  $db->dbopen(ro => 1) || croak "dbopen failure";
  my $data = $db->get($key);
  $db->dbclose;

Methods will fail if the DB is not open.

If the DB for this object is open when the object is DESTROY'd, Bot::Cobalt::DB will attempt to close it safely.

Locking

Proper locking is done -- that means the DB is 're-tied' after a lock is granted and state cannot change between database open and lock time.

The attempt to gain a lock will time out after five seconds (and "dbopen" will return boolean false).

The lock is cleared on "dbclose".

If the Bot::Cobalt::DB object is destroyed, it will attempt to dbclose for you, but it is good practice to keep track of your open/close calls and attempt to close as quickly as possible.

Methods

dbopen

dbopen opens and locks the database. If 'ro => 1' is specified, this is a LOCK_SH shared (read) lock; otherwise it is a LOCK_EX exclusive (write) lock.

Try to call a dbclose as quickly as possible to reduce locking contention.

dbopen() will return false (and possibly warn) if the database could not be opened (probably due to lock timeout).

is_open

Returns a boolean value representing whether or not the DB is currently open and locked.

dbclose

dbclose closes and unlocks the database.

put

The put method adds an entry to the database:

  $db->put($key, $value);

The value can be any data structure serializable by JSON::XS; that is to say, any shallow or deep data structure NOT including blessed references.

get

The get method retrieves a (deserialized) key.

  $db->put($key, { Some => 'hash' } );
  ## . . . later on . . .
  my $ref = $db->get($key);

del

The del method removes a key from the database.

  $db->del($key);

dbkeys

dbkeys will return a list of keys in list context, or the number of keys in the database in scalar context.

dbdump

You can serialize/export the entirety of the DB via dbdump.

  ## YAML::Syck
  my $yamlified = $db->dbdump('YAML');
  ## YAML::XS
  my $yamlified = $db->dbdump('YAMLXS');
  ## JSON::XS
  my $jsonified = $db->dbdump('JSON');

See Bot::Cobalt::Serializer for more on freeze() and valid formats.

A tool called cobalt2-dbdump is available as a simple frontend to this functionality. See cobalt2-dbdump --help

FORMAT

Bot::Cobalt::DB databases are Berkeley DB 1.x, with NULL-terminated records and values stored as JSON. They're intended to be easily portable to other non-Perl applications.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>