Bot::Cobalt::DB - Locking Berkeley DBs with serialization
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;
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.
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, );
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.
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.
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).
Returns a boolean value representing whether or not the DB is currently open and locked.
dbclose closes and unlocks the database.
The put method adds an entry to the database:
$db->put($key, $value);
The value can be any data structure serializable by JSON::MaybeXS.
Note that keys should be properly encoded:
my $key = "\x{263A}"; utf8::encode($key); $db->put($key, $data);
The get method retrieves a (deserialized) key.
$db->put($key, { Some => 'hash' } ); ## . . . later on . . . my $ref = $db->get($key);
The del method removes a key from the database.
$db->del($key);
dbkeys will return a list of keys in list context, or the number of keys in the database in scalar context.
You can serialize/export the entirety of the DB via dbdump.
## Export to a HASH my $dbcopy = $db->dbdump('HASH'); ## YAML::Syck my $yamlified = $db->dbdump('YAML'); ## YAML::XS my $yamlified = $db->dbdump('YAMLXS'); ## JSON::MaybeXS my $jsonified = $db->dbdump('JSON');
See Bot::Cobalt::Serializer for more on freeze() and valid formats.
freeze()
A tool called cobalt2-dbdump is available as a simple frontend to this functionality. See cobalt2-dbdump --help
cobalt2-dbdump --help
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.
Jon Portnoy <avenj@cobaltirc.org>
To install Bot::Cobalt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bot::Cobalt
CPAN shell
perl -MCPAN -e shell install Bot::Cobalt
For more information on module installation, please visit the detailed CPAN module installation guide.