README

   1 = tdb - Trivial Database bindings for Ruby
   2
   3 TDB is much like other DBM implementations, except it allows concurrent
   4 writer processes.  TDB was initially developed for Samba, but is used by
   5 other projects as well.  These Ruby bindings allow Ruby apps to read and
   6 write to the same databases used by Samba!
   7
   8 == Features
   9
  10 * Concurrent reader and writer processes may safely operate on the
  11   same file.  This is great for MRI 1.8 and 1.9 where multi-core
  12   performance is easiest to achieve with processes and not threads.
  13
  14 * Fork-safe, you may fork and share the same TDB object in your parent
  15   and child processes.
  16
  17 * Releases the GVL for slow disk operations under Ruby 1.9 so
  18   other threads can run (but not other TDB operations on the same file)
  19
  20 * Includes several {hash functions}[link:Hash_Functions.html]
  21   not included by upstream TDB.
  22
  23 == Caveats
  24
  25 These caveats will be addressed upstream in
  26 {TDB2}[http://mid.gmane.org/201008021002.47351.rusty@rustcorp.com.au]
  27
  28 * NOT native thread-safe by default, you MUST initialize your TDB
  29   objects with <code>:threadsafe => true</code> or call
  30   TDB#threadsafe! on each TDB object if you run with threads
  31   under Ruby 1.9 (but not 1.8).
  32
  33 * Database size is limited to 4G, even on 64-bit systems.
  34
  35 * TDB should be created with an appropriate :hash_size for large databases
  36   or performance will suffer.
  37
  38 == Install
  39
  40 The original tdb library from the {main site}[http://tdb.samba.org/] is
  41 required.  Debian users can just <code>apt-get install tdb-dev</code>.
  42 Non-Debian users: building against upstream tdb 1.2.2 and 1.2.7 are
  43 known to be broken, so installing tdb from the latest git is
  44 recommended.
  45
  46 The library consists of a C extension so you'll need a C compiler
  47 and Ruby development libraries/headers.
  48
  49 You may download the tarball from our
  50 {download site}[http://bogomips.org/ruby-tdb/files/] and run setup.rb after
  51 unpacking it:
  52
  53   http://bogomips.org/ruby-tdb/files/
  54
  55 You may also install it via RubyGems on RubyGems.org:
  56
  57   gem install tdb
  58
  59 If you have a tdb installation in a non-standard prefix, you
  60 will have to use:
  61
  62   gem install tdb -- --with-tdb-dir=$PFX
  63
  64 Or if you have a non-standard prefix that linkers normally do not search:
  65
  66   gem install tdb -- --with-tdb-dir=$PFX --with-dldflags=-Wl,-rpath=$PFX/lib
  67
  68 You can get the latest source via git from the following locations
  69 (these versions may not be stable):
  70
  71   git://git.bogomips.org/ruby-tdb.git
  72   git://repo.or.cz/ruby-tdb.git (mirror)
  73
  74 You may browse the code from the web and download the latest snapshot
  75 tarballs here:
  76
  77 * http://git.bogomips.org/cgit/ruby-tdb.git (cgit)
  78 * http://repo.or.cz/w/ruby-tdb.git (gitweb)
  79
  80 See the HACKING guide on how to contribute and build prerelease gems
  81 from git.
  82
  83 == Contact
  84
  85 All feedback (bug reports, user/development dicussion, patches, pull
  86 requests) go to the {mailing list}[mailto:ruby.tdb@librelist.org].
  87
  88 For the latest on tdb releases, you may check our NEWS page (and
  89 subscribe to our Atom feed).