Bdb

Ruby 1.9 bindings for Berkeley DB versions 4.2-4.7.

Download

Currently this library is available via git at:

   git://github.com/espace/bdb.git

Installation

From Git

You can check out the latest source from git:

   git clone git://github.com/espace/bdb.git

As a Gem

At the moment this library is not available on Rubyforge. To install it as a
gem, do the following (for custom compiled version 4.7):

   gem install espace-bdb --source http://gems.github.com

This will wokrs on ubuntu.

Sample Usage

The New Way..

  require ‘berkeleydb’


	
creating an environment

  @env = BDB::Env.new(‘environment_path’,flags)


	
create btree DB

#if file_name is nil, then the table will be created in memory,
#if table_name is nil and file_name exists, the table name will be the same as file_name
#marshal: if you are sending a ruby object to be stored, turn this to true, it will loaded as an object when you request it.
@btree = @env.btree(file_name,table_name,marshal=false)


	
Inserting a record

    @btree.put(key,data,transaction=nil,flags=0)


	
Reading a record
	
Returns an array containing the key and the value 

    key,value = @btree.get(key)


	
Using as a queue

     @btree.push(data)  #Inserts the record with the current time stamp

     @btree.pop   #Returns the record with the smallest key



	
create Hash Table DB
	
Parameters are the same as Brtee

@hash = @env.hash(file_name=nil,table_name=nil,marshal=false)


	
Inserting a record

    @hash.put(key,data,transaction=nil,flags=0)


	
Reading a record
	
Returns an array containing the key and the value 

    key,value = @hash.get(key)

#Add Btree Index
@hash.add_btree_index
#Find in Index
@hash.find_in_index(data)


	
create Queue DB

@queue = @env.queue(record_length,file_name,marshal=false)

	
Push A record

     @queue.push(data)


	
Pop A record

     @queue.pop(data)

The Old Way

  env = Bdb::Env.new(0)

  env_flags =  Bdb::DB_CREATE |    # Create the environment if it does not already exist.

               Bdb::DB_INIT_TXN  | # Initialize transactions

               Bdb::DB_INIT_LOCK | # Initialize locking.

               Bdb::DB_INIT_LOG  | # Initialize logging

               Bdb::DB_INIT_MPOOL  # Initialize the in-memory cache.

  env.open(File.join(File.dirname(FILE), ‘tmp’), env_flags, 0);

db = env.db
db.open(nil, ‘db1.db’, nil, Bdb::Db::BTREE, Bdb::DB_CREATE | Bdb::DB_AUTO_COMMIT, 0)
txn = env.txn_begin(nil, 0)
db.put(txn, ‘key’, ‘value’, 0)
txn.commit(0)
value = db.get(nil, ‘key’, nil, 0)
db.close(0)
env.close

API

This interface is most closely based on the DB4 C api and tries to maintain close
interface proximity. That API is published by Oracle at http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/frame.html.

All function arguments systematically omit the leading DB handles and TXN handles.
A few calls omit the flags parameter when the documentation indicates that no
flag values are used – cursor.close is one.

Notes

New features Added

• Adding compatability to Ruby 1.9.1
• Getting The Queue DB fixed and working
• Supporting working with BDB memory only environments
• Adding a nice and neat easy Ruby wrapper to maintain DB objects and access, these wrappers don’t have all the features like the old code, but it covers the common cases, However, the old code still works.
• Some other small bug fixes

The defines generator is imperfect and includes some defines that are not
flags. While it could be improved, it is easier to delete the incorrect ones.
Thus, if you decide to rebuild the defines, you will need to edit the resulting
file. This may be necessary if using a different release of DB4 than the ones
the authors developed against. In nearly every case the defines generator works
flawlessly.

The authors have put all possible caution into ensuring that DB and Ruby cooperate.
The memory access was one aspect carefully considered. Since Ruby copies
when doing String#new, all key/data retrieval from DB is done with a 0 flag,
meaning that DB will be responsible. See this
news group posting about the effect of that.

The only other design consideration of consequence was associate. The prior
version used a Ruby thread local variable and kept track of the current
database in use. The authors decided to take a simpler approach since Ruby is green
threads. A global array stores the VALUE of the Proc for a given association
by the file descriptor number of the underlying database. This is looked
up when the first layer callback is made. It would have been better considered
if DB allowed the passing of a (void *) user data into the alloc that would
be supplied during callback. So far this design has not produced any problems.