[ANN] sldb-0.0.0

[Ara.T.Howard]

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
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
===============================================================================