BerkeleyDB - Perl extension for Berkeley DB version 2
use BerkeleyDB; $env = new BerkeleyDB::Env [OPTIONS] ; $db = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ; $db = new BerkeleyDB::Hash [OPTIONS] ; $db = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ; $db = new BerkeleyDB::Btree [OPTIONS] ; $hash{$key} = $value ; $value = $hash{$key} ; each %hash ; keys %hash ; values %hash ; $status = $db->db_get() $status = $db->db_put() ; $status = $db->db_del() ; $status = $db->db_sync() ; $hash_ref = $db->db_stat() ; ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ; ($flag, $old_offset, $old_length) = $db->partial_clear() ; $cursor = $db->db_cursor() ; $status = $cursor->c_get() ; $status = $cursor->c_put() ; $status = $cursor->c_del() ; $txn = $env->txn_begin() ; $status = $txn->txn_prepare() $status = $txn->txn_commit() $status = $txn->txn_abort() $status = $txn->txn_checkpoint() $status = $txn->txn_id() $status = $txn->txn_stat() $BerkeleyDB::Error $BerkeleyDB::db_version
NOTE: This document is still under construction, so it is likely to be incomplete.
This Perl module provides an interface to most of the functionality available in Berkeley DB version 2.
The reader is expected to be familiar with the Berkeley DB documentation. The db_appinit, db_cursor, db_open and db_txn man pages are particularly relevant.
The equivalent of the Berkeley DB function db_appinit. It is only needed when you want to make use of locking, logging or transactions.
db_appinit
$env = new BerkeleyDB::Env [OPTIONS] [ -Home => $path, ] [ -Config => { name => value, name => value }, ] [ -ErrFile => filename or filehandle, ] [ -ErrPrefix => "string", ] [ -Flags => number, ] [ -Verbose => boolean, ] [ -LockMax => number, ] [ -LogMax => number, ] [ -TxnMax => number, ]
Where the OPTIONS consist of any of the following:
The Flags option can consist of one of more of the following or'ed together.
DB_CREATE DB_INIT_LOCK DB_INIT_LOG DB_INIT_MPOOL DB_INIT_TXN DB_MPOOL_PRIVATE DB_NOMMAP DB_RECOVER DB_RECOVER_FATAL DB_THREAD DB_TXN_NOSYNC DB_USE_ENVIRON DB_USE_ENVIRON_ROOT
The environment class has the following methods:
$txn = $env->txn_begin() ;
$db->errPrefix("string") ;
The equivalent of db_open with type DB_HASH. Two forms
$db = new BerkeleyDB::Hash [ -Filename => "filename" ] [ -Flags => ] [ -Property => ] [ -Mode => ] [ -Cachesize => ] [ -Lorder => ] [ -Pagesize => ] [ -Env => ] [ -Txn => ] [ -Ffactor => ] [ -Nelem => ] [ -Hash => ]
and this
$db = tie %hash, 'BerkeleyDB::Hash', OPTIONS
where OPTIONS are the same as for the new constructor. In addition to the standard set of options (see "COMMON OPTIONS") BerkeleyDB::Hash supports these:
Used to specify additional flags.
DB_DUP
See "COMMON DATABASE METHODS".
use strict ; use BerkeleyDB ; my %hash ; my $filename = "database" ; tie %hash, 'BerkeleyDB::Hash', -Filename => $filename, -Flags => DB_CREATE, or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ; $hash{"fred"} = "barney" ; $hash{"joe"} = "harry" ; untie %hash ;
Btree supports one extra method
$ref = $db->db_stat() ;
Not implemented yet.
All database access class constructors support the common set of parameters defined below.
The database filename. If no filename is specified, the database will be created in-memory, and removed once the program terminates.
Specify how the database will be opened/created. The valid flags are:
DB_CREATE DB_NOMMAP DB_RDONLY DB_THREAD DB_TRUNCATE
The default is none.
Determines the file protection when the database is created. Defaults to 0666.
When working under a Berkeley DB environment, this parameter
Defaults to no environment.
All the database interfaces support a common set of methods.
Creates a cursor object. See CURSORS for details of the methods available when working with cursore.
When the "tie" interface is used, reading from and writing to the database is achieved via the tied hash.
A cursor is created with the db_cursor
db_cursor
todo.
See the Changes file.
The most recent version of BerkeleyDB can always be found on CPAN (see "CPAN" in perlmod for details), in the directory modules/by-module/BerkeleyDB.
The official web site for Berkeley DB is http://www.sleepycat.com/db. The ftp equivalent is ftp.sleepycat.com:/pub.
Copyright (c) 1997 Paul Marquess. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Although BerkeleyDB is covered by the Perl license, the library it makes use of, namely Berkeley DB version 2, is not. Berkeley DB has its own copyright and its own license. Please take the time to read it.
The license for Berkeley DB version 2, and how it relates to BerkeleyDB does need some extra clarification. Here are are few words taken from the Berkeley DB FAQ regarding the version 2 license:
The major difference is that the license for DB 2.0, when downloaded from the net, requires that the software that uses DB 2.0 be freely redistributable.
That means that if you want to use BerkeleyDB, and you have changed either the source for Berkeley DB or Perl, then the changes must be freely available.
In the case of Perl, the term source refers to the complete source code for Perl (e.g. sv.c, toke.c, perl.h) and any external modules that you are using (e.g. BerkeleyDB, Tk).
Note that any Perl scripts that you write are your property - this includes scripts that make use of BerkeleyDB. Neither the Perl license or the Berkeley DB license place any restriction on what you have to do with them.
If you are in any doubt about the license situation, contact either the Berkeley DB authors or the author of BerkeleyDB. See "AUTHOR" for details.
Paul Marquess <pmarquess@bfsec.bt.co.uk<gt>.
Questions about Berkeley DB may be addressed to <db@sleepycat.com<gt>.
perl(1), DB_File, Berkeley DB.
To install BerkeleyDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BerkeleyDB
CPAN shell
perl -MCPAN -e shell install BerkeleyDB
For more information on module installation, please visit the detailed CPAN module installation guide.