mattbauer / bdb

Ruby Berkeley DB

This URL has Read+Write access

Added installation instructions for db4.6 from MacPorts
Piotr Usewicz (author)
Sat Jan 10 12:29:26 -0800 2009
mattbauer (committer)
Mon Jan 12 06:13:08 -0800 2009
commit  3d4a54eb05928b924eb00b8174cb603dc63825d2
tree    88adfe612c31dc45fc24229fbe1f2a44bb19f5da
parent  fdc66853722fe9936f5033287efa432ca7aa6e13
bdb / README.textile
raw normal view history
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 1 h1. Bdb
20a23048 » danj 2006-02-13 Initial revision 2
3fc7b753 » mattbauer 2008-12-30 Note 4.7 in the README 3 Ruby bindings for Berkeley DB versions 4.2-4.7.
20a23048 » danj 2006-02-13 Initial revision 4
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 5 h2. Download
20a23048 » danj 2006-02-13 Initial revision 6
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 7 Currently this library is available via git at:
20a23048 » danj 2006-02-13 Initial revision 8
d8a5fee0 » mattbauer 2008-12-30 Remove type from README 9 <pre>
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 10 git://github.com/mattbauer/bdb.git
d8a5fee0 » mattbauer 2008-12-30 Remove type from README 11 </pre>
20a23048 » danj 2006-02-13 Initial revision 12
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 13 h2. Installation
20a23048 » danj 2006-02-13 Initial revision 14
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 15 h3. From Git
16
17 You can check out the latest source from git:
18
d8a5fee0 » mattbauer 2008-12-30 Remove type from README 19 <pre>
20 git clone git://github.com/mattbauer/bdb.git
21 </pre>
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 22
23 h3. As a Gem
20a23048 » danj 2006-02-13 Initial revision 24
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 25 At the moment this library is not available on Rubyforge. To install it as a
3d4a54eb » pusewicz 2009-01-10 Added installation instruct... 26 gem, do the following (for custom compiled version 4.7):
20a23048 » danj 2006-02-13 Initial revision 27
d8a5fee0 » mattbauer 2008-12-30 Remove type from README 28 <pre>
29 sudo env ARCHFLAGS="-arch i386" gem install mattbauer-bdb --source http://gems.github.com -- --with-db-dir=/usr/local/BerkeleyDB.4.7
30 </pre>
31
3d4a54eb » pusewicz 2009-01-10 Added installation instruct... 32 For Berkeley DB v4.6 installed from MacPorts do the following:
33
34 <pre>
35 sudo env ARCHFLAGS="-arch i386" gem install mattbauer-bdb --source http://gems.github.com -- --with-db-include=/opt/local/include/db46 --with-db-lib=/opt/local/lib/db46
36 </pre>
37
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 38 This assumes you're on OS X and BerkeleyDB wasn't compiled as a universal binary.
20a23048 » danj 2006-02-13 Initial revision 39
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 40 h2. Sample Usage
20a23048 » danj 2006-02-13 Initial revision 41
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 42 <pre>
43 env = Bdb::Env.new(0)
44 env_flags = Bdb::DB_CREATE | # Create the environment if it does not already exist.
45 Bdb::DB_INIT_TXN | # Initialize transactions
46 Bdb::DB_INIT_LOCK | # Initialize locking.
47 Bdb::DB_INIT_LOG | # Initialize logging
48 Bdb::DB_INIT_MPOOL # Initialize the in-memory cache.
49 env.open(File.join(File.dirname(__FILE__), 'tmp'), env_flags, 0);
50
51 db = env.db
52 db.open(nil, 'db1.db', nil, Bdb::Db::BTREE, Bdb::DB_CREATE | Bdb::DB_AUTO_COMMIT, 0)
20a23048 » danj 2006-02-13 Initial revision 53
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 54 txn = env.txn_begin(nil, 0)
55 db.put(txn, 'key', 'value', 0)
56 txn.commit(0)
20a23048 » danj 2006-02-13 Initial revision 57
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 58 value = db.get(nil, 'key', nil, 0)
20a23048 » danj 2006-02-13 Initial revision 59
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 60 db.close(0)
61 env.close
62 </pre>
20a23048 » danj 2006-02-13 Initial revision 63
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 64 h2. API
20a23048 » danj 2006-02-13 Initial revision 65
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 66 This interface is most closely based on the DB4 C api and tries to maintain close
67 interface proximity. That API is published by Oracle at "http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/frame.html":http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/frame.html.
20a23048 » danj 2006-02-13 Initial revision 68
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 69 All function arguments systematically omit the leading DB handles and TXN handles.
70 A few calls omit the flags parameter when the documentation indicates that no
71 flag values are used - cursor.close is one.
20a23048 » danj 2006-02-13 Initial revision 72
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 73 h2. Notes
20a23048 » danj 2006-02-13 Initial revision 74
67462380 » mattbauer 2008-12-30 Getting the gem version wor... 75 The defines generator is imperfect and includes some defines that are not
76 flags. While it could be improved, it is easier to delete the incorrect ones.
77 Thus, if you decide to rebuild the defines, you will need to edit the resulting
78 file. This may be necessary if using a different release of DB4 than the ones
79 the authors developed against. In nearly every case the defines generator works
80 flawlessly.
81
82 The authors have put all possible caution into ensuring that DB and Ruby cooperate.
83 The memory access was one aspect carefully considered. Since Ruby copies
84 when doing String#new, all key/data retrieval from DB is done with a 0 flag,
85 meaning that DB will be responsible. See "this":http://groups.google.com/group/comp.databases.berkeley-db/browse_frm/thread/4f70a9999b64ce6a/c06b94692e3cbc41?tvc=1&q=dbt+malloc#c06b94692e3cbc41
86 news group posting about the effect of that.
87
88 The only other design consideration of consequence was associate. The prior
89 version used a Ruby thread local variable and kept track of the current
90 database in use. The authors decided to take a simpler approach since Ruby is green
91 threads. A global array stores the VALUE of the Proc for a given association
92 by the file descriptor number of the underlying database. This is looked
93 up when the first layer callback is made. It would have been better considered
94 if DB allowed the passing of a (void *) user data into the alloc that would
95 be supplied during callback. So far this design has not produced any problems.