ruby-bdb/bdb

Ruby Berkeley DB

Description

Ruby bindings for Berkeley DB versions 4.2-5.1.

One of the ruby-bdb projects. See also:

• sbdb - A simpler, more Ruby-like API
• tuple - A binary array serialisation library used by bdb internally

Installation

From Git

You can check out the latest source from git:

git clone git://github.com/ruby-bdb/bdb.git

As a Gem

At the moment this library is not available on RubyForge. To install it as a gem, do the following:

[sudo] gem install bdb

For Berkeley DB v4.7 installed from MacPorts do the following:

[sudo] env ARCHFLAGS="-arch i386" gem install bdb

This assumes you're on OS X and BerkeleyDB wasn't compiled as a universal binary.

Sample Usage

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.encrypt = 'yourpassword'   # If you need it.
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.

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

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.

bdb's Issues

Concurrency failure?

I wrote the following to test that concurrent access to a database works as it should, and it gives me incorrect output:

require 'bdb'
include Bdb

FNAME = "bdbtest.db"

def createdb
    Db.new.open(nil,FNAME,nil,Db::HASH,DB_CREATE,0).close(0)
end

def newdb
    Db.new.open(nil,FNAME,nil,Db::HASH,0,0)
end

File.unlink FNAME rescue nil
createdb
db1 = newdb
# If this line is "db2 = db1" then the test works fine.
db2 = newdb

n = 500

db1['x'] = "0"
n.times {
    db1['x'] = ((db1['x'].to_i)+1).to_s
    db2['x'] = ((db2['x'].to_i)+1).to_s
}

puts "These should both be #{n*2}:"
puts db1['x']
puts db2['x']

So far this fails on Ubuntu 12.04 x86_64 / bdb 5.1 / ruby 1.9.3p0 / bdb-0.2.6.5, where "1.3.0p0" is the Ubuntu packaged version. Haven't yet tested other combinations.

Is this a bug or is my test incorrect?

ruby1.9?

Hi,
Do you have any plan to support ruby1.9? thanks

Does not install from source / or as a gem on my Mac OS X

I am trying to install this as a gem and directly from the source. In both cases the creation of Makefile fails, Its not able to find db_version() with no arguments and it fails. I have tried with both db46 and db47. Let me know if you know anything about this issue.

Thanks.

ruby 1.9.3 problem -- undefined symbol: UINT2FIX

ruby-1.9.3-p0 :001 > require 'bdb'
LoadError: /home/nik/.rvm/gems/ruby-1.9.3-p0/gems/bdb-0.2.6.5/ext/bdb.so: undefined symbol: UINT2FIX - /home/nik/.rvm/gems/ruby-1.9.3-p0/gems/bdb-0.2.6.5/ext/bdb.so
from /home/nik/.rvm/rubies/ruby-1.9.3-p0/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:59:in require' from /home/nik/.rvm/rubies/ruby-1.9.3-p0/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:59:inrescue in require'
from /home/nik/.rvm/rubies/ruby-1.9.3-p0/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:35:in require' from (irb):1 from /home/nik/.rvm/rubies/ruby-1.9.3-p0/bin/irb:16:in

'
ruby-1.9.3-p0 :002 >

Tests fail on 1.9.3-p286

I was trying to get bdb working on a newer system and kept running into problems. Cloned this repo to run the test suite and got the following error repeatedly:

/home/xubuntu/dev/bdb/lib/bdb/environment.rb:60:in `block in env': undefined method `set_timeout' for # (NoMethodError)
        from /home/xubuntu/dev/bdb/lib/bdb/environment.rb:115:in `synchronize'
        from /home/xubuntu/dev/bdb/lib/bdb/environment.rb:49:in `env'
        from /home/xubuntu/dev/bdb/lib/bdb/environment.rb:91:in `block in transaction'
        from /home/xubuntu/dev/bdb/lib/bdb/environment.rb:120:in `block (2 levels) in synchronize'
        from :28:in `block in exclusive'
        from :10:in `synchronize'
        from :27:in `exclusive'
        from /home/xubuntu/dev/bdb/lib/bdb/environment.rb:120:in `block in synchronize'
...

BDB 5.1.25 on Xubuntu 12.04.

Not sure where to go from here... any idea what's causing this?

fix for Queue and Recno db_put function to work on Debian Squeeze amd64

in ext/bdb.c function db_put:

change this:
if ( flags & DB_APPEND == DB_APPEND ) {
VALUE str = rb_str_new(key.data,key.size);
if (key.data) free(key.data);
return str;
}

to this:
if ( (flags & DB_APPEND )== DB_APPEND ) {
VALUE str = rb_str_new(key.data,key.size);
/* if (key.data) free(key.data); */
return str;
}