CDB::TinyCDB - Perl extension for TinyCDB library to cdb databases
use CDB::TinyCDB; # open ( direct file access ) my $cdb = CDB::TinyCDB->open( 'my.cdb' ); # load ( loads file into memory ) my $cdb = CDB::TinyCDB->load( 'my.cdb' ); # returns first occurence of key in file print $cdb->get("key"); # returns all records for key print "$_\n" for $cdb->getall("key"); # returns last record for key print $cdb->getlast("key"); # checks if key exists print $cdb->exists("key"); # iterates over all entries while ( my ($key, $value) = $cdb->each ) { # same as cdb -d my.cdb, but skips null keys printf("+%d,%d:%s->%s\n", length($key), length($value), $key, $value); } # returns all keys (skips null keys) print "$_\n" for $cdb->keys;
or
use CDB::TinyCDB; # open/load for updating - loads all existing records into temp file my $cdb = CDB::TinyCDB->open( 'my.cdb', for_update => "my.cdb.$$" ); my $cdb = CDB::TinyCDB->load( 'my.cdb', for_update => "my.cdb.$$" ); # add new records (allows duplicates) print "records added: ", $cdb->put_add( k1, 'value1'); # 1 print "records added: ", $cdb->put_add( k1 => 'value1', k2 => 'value2' ); # 2 # replace and remove old records print "records replaced: ", $cdb->put_replace( k3, 'value3'); # 0 print "records replaced: ", $cdb->put_replace( key, 'value'); # 1 # replace and fill with null old records print "records replaced: ", $cdb->put_replace0( k2, 'value3'); # 1 # add and warn if record previously existed print "records added: ", $cdb->put_warn( k1, 'value4'); # 1 # warns: Key k1 already exists - added anyway # checks if key exists print $cdb->exists("k1"); # dies if record already existed eval { $cdb->put_insert( k1, 'value1'); }; if ( $@ ) { print "k1 wasn't added: $@\n"; # Unable to insert new record - key exists } # commit changes and reopen/reload db - temp file replaces my.cdb $cdb->finish( save_changes => 1, reopen => 1); # same as $cdb->finish(); print $cdb->getlast("k1"); # value4 # finish without saving changes $cdb->finish( save_changes => 0 ); # finish without reopening file $cdb->finish( reopen => 0 );
use CDB::TinyCDB; # create new cdb file my $cdb = CDB::TinyCDB->create( 'my-new.cdb', "my-new.cdb.$$" ); # add new records (allows duplicates) print "records added: ", $cdb->put_add( k1, 'value1'); # 1 print "records added: ", $cdb->put_add( k1 => 'value1', k2 => 'value2' ); # 2 # replace and remove old records print "records replaced: ", $cdb->put_replace( k3, 'value3'); # 0 print "records replaced: ", $cdb->put_replace( key, 'value'); # 1 # replace and fill with null old records print "records replaced: ", $cdb->put_replace0( k2, 'value3'); # 1 # add and warn if record previously existed print "records added: ", $cdb->put_warn( k1, 'value4'); # 1 # warns: Key k1 already exists - added anyway # checks if key exists print $cdb->exists("k1"); # dies if record already existed eval { $cdb->put_insert( k1, 'value1'); }; if ( $@ ) { print "k1 wasn't added: $@\n"; # Unable to insert new record - key exists } # commit changes and reopen/reload db - temp file replaces my-new.cdb $cdb->finish( save_changes => 1 ); # same as $cdb->finish(); # reading is not allowed in create mode print $cdb->getlast("k1"); # dies
CDB::TinyCDB is a perl extension for TinyCDB library to query and create CDB files;
TinyCDB supports two variants of query interface - first that maps the cdb file into memory (using mmap(2) on *nixes and MapViewOfFile on Windows) and the second one which reads file directly from disk.
Loads the CDB into memory - designed to be efficient for multiple queries.
my $cdb = CDB::TinyCDB->load( 'my.cdb' );
Opens file and acceses it using read(2) and seek(2) - designed to be efficient for single queries or if cdb file is huge.
my $cdb = CDB::TinyCDB->open( 'my.cdb' );
Both load and open support same query methods (even though TinyCDB doesn't support some of them in open mode).
print $cdb->get("key");
Returns first occurence of key in file.
print "$_\n" for $cdb->getall("key");
Returns all records for given key.
print $cdb->getlast("key");
Returns last record for key. Useful if there are duplicated records added by "put_add".
print $cdb->exists("key");
Returns if key exists in file.
while ( my ($key, $value) = $cdb->each ) { printf("+%d,%d:%s->%s\n", length($key), length($value), $key, $value); }
Iterates over all entries in file. Maintains the current position in file, so while iterating please don't call other methods.
Note: CDB allows to have duplicated keys, so don't use it directly to create hashes.
Note: it doesn't return records with zero length keys (most likely replaced by "put_replace0").
print "$_\n" for $cdb->keys;
Returns all keys.
CDB database file is created in two steps: first, temporary file created and written to disk, and second, that temporary file is renamed to permanent place. Unix rename(2) call is atomic operation, it removes destination file if any AND renames another file in one step. This way it is guaranteed that readers will not see incomplete database. To prevent multiple simultaneous updates, locking may also be used.
Note: rename(2) requires that both files are on the same filesystem.
In create mode no query methods can be used. The only exception is "exists", but it may significantly slow down the whole process, as it currently flushes internal buffer to disk on every call with key those hash value already exists in db.
my $cdb = CDB::TinyCDB->create( 'my-new.cdb', "my-new.cdb.$$" );
Creates new cdb file (my-new.cdb) and uses temporary file until changes are committed (my-new.cdb.$$).
print "records added: ", $cdb->put_add( k1, 'value1'); # 1 print "records added: ", $cdb->put_add( k1 => 'value1', k2 => 'value2' ); # 2 print "records added: ", $cdb->put_add( %hash ); # scalar keys %hash
Adds new records and returns number of records added. No duplicate checking will be performed - allowing duplicate keys to exists.
print "records replaced: ", $cdb->put_replace( k3, 'value3'); # 0 print "records replaced: ", $cdb->put_replace( key, 'value'); # 1
If the key already exists, it will be removed from the database before adding new key,value pair. This requires moving data in the file, and can be quite slow if the file is large. All matching old records will be removed this way.
Returns number of records replaced.
print "records replaced: ", $cdb->put_replace0( k2, 'value3'); # 1
If the key already exists and it isn't the last record in the file, old record will be zeroed out before adding new key,value pair. This is alot faster than "put_replace", but some extra data will still be present in the file. The data -- old record -- will not be accessible by normal searches, but will appear in direct file dumps (cdb -d).
# dies if record already existed eval { $cdb->put_insert( k1, 'value1'); }; if ( $@ ) { print "k1 wasn't added: $@\n"; # Unable to insert new record - key exists }
Add key,value pair only if such key does not exists in a database. Note that since query (see "get" above) will find first added record, this mode is somewhat useless (but allows to reduce database size in case of repeated keys). This is the same as calling "exists" followed by "put_add" if the key was not found.
print "records added: ", $cdb->put_warn( k1, 'value4'); # 1 # warns: Key k1 already exists - added anyway
Add key,value pair unconditionally, but also check if this key already exists. This is equivalent of calling "exists", printing a warning if key exists, and unconditionally followed by "put_add".
$cdb->finish();
Commits changes and renames temp file into chosen CDB file. Allows to abort changes when called like this:
$cdb->finish( save_changes => 0 );
Although TinyCDB doesn't support updating already existent files CDB::TinyCDB provides inteface to do so.
my $cdb = CDB::TinyCDB->open( 'my.cdb', for_update => "my.cdb.$$" ); my $cdb = CDB::TinyCDB->load( 'my.cdb', for_update => "my.cdb.$$" );
Depending on the query method used CDB will be reopened or reloaded after changes are committed.
On startup it loads all existing records into temp file, where new records will be added. Until changes are committed the query methods will be used against the old file.
Allows querying the old file - for all above please see "Query methods".
Note: "exists" however will check against temp file.
Add new records - for all above please see "Create methods".
Commits changes and renames temp file into chosen CDB file, which will be then reopened/reloaded.
Allows to abort changes with:
Allows to abort file reloading with:
$cdb->finish( reopen => 0 );
Note: both params can be used together in single call.
None by default.
Please see README file if you need to install it from sources.
Use tied hashes for accessing cdb files - doesn't require external libraries.
TinyCDB home page. Some methods description were copied from there.
Alex J. G. Burzyński, <ajgb@cpan.org>
Copyright (C) 2010 by Alex J. G. Burzyński
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.
To install CDB::TinyCDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CDB::TinyCDB
CPAN shell
perl -MCPAN -e shell install CDB::TinyCDB
For more information on module installation, please visit the detailed CPAN module installation guide.