From: "Ara.T.Howard" <Ara.T.Howard@...>
Date: 2005-05-13T09:05:29+09:00
Subject: [ANN] sldb-0.0.0


URLS

   http://raa.ruby-lang.org/search.rhtml?search=sldb
   http://codeforpeople.com/lib/ruby/sldb

ABOUT

   sldb is a multi-thread, multi-process, and nfs safe abstraction of sqlite
   databases.  the sldb module is a class generator for concrete databases.  so
   long as all access if via sldb multi-process and multi-process application may
   safely access a single sqlite database without worrying about the details of
   handling access when the database is locked.  all operations, including db
   creation and initialisation, are atomic - even on nfs.  the database has a
   built-in leasing mechanism which can detect failing nfs lockd servers and
   auto-recover.  if your database is not on nfs this does not apply.

AUTHOR

   ara [dot] t [dot] howard [at] noaa [dot] gov

SAMPLES

   <========< sample/a.rb >========>

   ~ > cat sample/a.rb

     require 'sldb'

     #
     # use the factory method to specify your database class
     #
     DB =
       SLDB::class {
         schema 'create table t ( a, b, c )'
         path 'sldb'
       }

     #
     # create and instance and use it - it will be created and initialized with the
     # schema on the first use
     #
     db = DB::new

     db.transaction do
       db.execute 'insert into t values (0,1,2)'
       db.execute('select * from t'){|tuple| p tuple}
     end


   ~ > ruby sample/a.rb

     ["0", "1", "2"]


   <========< sample/b.rb >========>

   ~ > cat sample/b.rb

     require 'csv'
     require 'sldb'

     DB = SLDB::class :schema => 'create table t ( a, b, c )'
     db = DB::new 'sldb'

     #
     # sldb uses arrayfields so many operations are natural since tuples are arrays,
     # yet can be indexed by field
     #
     db.transaction do
       db.execute "insert into t values ( 'A', 'B', 'C' )"
       db.execute('select * from t') do |tuple|
         puts "tuple => #{ tuple.inspect }"
         tuple.fields.each{|f| puts "  tuple[#{ f }] => #{ tuple[f] }"}
       end
     end

     puts

     #
     # csv generation is an example of something which is much more natural with
     # arrays
     #
     CSV::generate('csv') do |csv|
       db.ro_transaction{db.execute('select * from t'){|t| csv << t}}
     end
     puts(IO::read('csv'))


   ~ > ruby sample/b.rb

     tuple => ["A", "B", "C"]
       tuple[a] => A
       tuple[b] => B
       tuple[c] => C

     A,B,C


   <========< sample/c.rb >========>

   ~ > cat sample/c.rb

     require 'yaml'
     require 'sldb'

     DB = SLDB::new {
       schema <<-sql
         create table t0 ( a, b, c);
         create table t1 ( x, y, z);
       sql

       path 'sldb'
     }

     db = DB::new

     #
     # many utility methods exist to make working with the databases easier
     #
     db.transaction do
       db.tablenames.each do |tablename|
         tuple = db.tuple_for tablename
         tuple.fields.each{|f| tuple[f] = db.timestamp 'local' => true}
         values = db.quote tuple
         sql = "insert into #{ tablename } values (#{ values.join ',' })"
         db.execute sql
       end
     end

     db.read_only_transaction do
       db.tablenames.each do |tablename|
         db.execute("select * from #{ tablename }") do |t|
           t.map!{|f| db.stamptime f, 'local' => true}
           y t.to_hash
         end
       end
     end

   ~ > ruby sample/c.rb

     ---
     a: 2005-05-12 17:40:44.508297 -06:00
     b: 2005-05-12 17:40:44.508506 -06:00
     c: 2005-05-12 17:40:44.508534 -06:00
     ---
     x: 2005-05-12 17:40:44.509519 -06:00
     y: 2005-05-12 17:40:44.509577 -06:00
     z: 2005-05-12 17:40:44.509604 -06:00


   <========< sample/d.rb >========>

   ~ > cat sample/d.rb

     require 'yaml'
     require 'sldb'

     DB = SLDB::new { schema 'create table t ( tid, time )'; path 'sldb' }
     db = DB::new

     #
     # multi-processed/multi-threaded applications may simoultaneously access the db
     #

     4.times do
       unless fork
         pid = $$
         threads = []
         2.times do |i|
           threads <<
             Thread::new(i, db) do |tid, db|
               sleep rand
               tuple = db.tuple_for 't'
               tuple['tid'] = "#{ pid }:#{ tid }"
               tuple['time'] = Time::now.to_f
               values = db.quote tuple
               db.transaction{db.execute "insert into t values(#{ values.join ',' })"}
             end
         end
         threads.each{|t| t.join}
         exit!
       end
     end

     4.times{ Process::wait }

     report = Hash::new{|h,k| h[k] = []}

     db.transaction{db.execute("select * from t"){|t| report['t'] << t.to_hash}}

     y report

   ~ > ruby sample/d.rb

     ---
     t:
       -
         time: "1115941244.8331"
         tid: 10419:1
       -
         time: "1115941244.96111"
         tid: 10419:0
       -
         time: "1115941245.13287"
         tid: 10417:1
       -
         time: "1115941245.53131"
         tid: 10417:0
       -
         time: "1115941245.63987"
         tid: 10418:0
       -
         time: "1115941245.65228"
         tid: 10418:1
       -
         time: "1115941245.98649"
         tid: 10416:0
       -
         time: "1115941245.9987"
         tid: 10416:1


CAVEATS

   this library is __highly__ experimental and subject to change.



this is something i use often for my own personal work and thought someone
might find it useful.

enjoy.

-a
-- 
===============================================================================
| email :: ara [dot] t [dot] howard [at] noaa [dot] gov
| phone :: 303.497.6469
| renunciation is not getting rid of the things of this world, but accepting
| that they pass away. --aitken roshi
===============================================================================