DBrb 0.1.0

data/lib/DB.rb

@@ -0,0 +1,245 @@
+# DBrb - database access library for Ruby.
+# 
+# Copyright (c) 2006 Tim Becker
+#
+# Released under the same terms as Ruby
+# (http://www.ruby-lang.org/en/LICENSE.txt)
+#
+#
+# see DBrb for documentation.
+
+require 'dbi'
+
+
+#:title: DBrb : RDoc Documenation
+
+# +DBrb+ is  a wrapper to facilitate working with {Ruby
+# DBI}[http://sourceforge.net/projects/ruby-dbi].  The intention is to
+# make the most commonly used DB functionality (as determined by me) easy and
+# intuitive to use.
+#
+# === Examples
+#
+# 	db = DBrb.new("my_dbi_driver_string", "usr", "credentials")
+#
+# 	# return single value or array if a single row is selected
+#	i = db.sql("select max(id) from some_table") 
+#	name, last_name =  db.sql("SELECT name, last_name FROM some_name WHERE id = ?", 1000)
+#
+# should the two examples above return more than one row, the first
+# one is used.
+# 
+#	db.sql("SELECT name, last_name FROM some_name WHERE id < ?", 1000) do |row|
+#		puts "#{row.name} #{row.last_name}"
+#		# in case of conflicts with existing methods, you can use:
+#		row["last_name"]
+#	end
+#	
+# The row that the +sql+ iterates over is the standard DBI::Row, which
+# has been supplemented with accessor methods named after the columns
+# in case these don't conflict with existing methods.
+
+
+class DBrb
+
+	# 
+	def initialize driver, usr=nil, pwd=nil, params=nil
+		@driver=driver
+		@usr=usr
+		@pwd=pwd
+		@params=params
+		
+
+		@pstatements = {}
+
+		if block_given?
+			yield self
+			self.close
+		end
+
+	end
+	
+	# +sql+ is the method that does all the work. The only required
+	# parameter is +stmt+, which passes a string with the SQL
+	# statement to be executed. The optional parameters in +args+
+	# get bound to '?'-placeholders in the statement.
+	#
+	# This method can be called in several ways.
+	# * Statements not returning results:
+	#
+	#	db.sql "UPDATE sometable SET somevalue=somevalue+1"
+	#
+	# * If the statement returns a single value, that value is returned by the method call:
+	# 
+	#
+	#	value = db.sql "SELECT value FROM sometable LIMIT 1"
+	#
+	# * Statements returning several values in a single row:
+	#	first_name, last_name = 
+	#		db.sql "SELECT first, last 
+	#			FROM sometable
+	#			LIMIT 1"
+	#
+	# (It should go without saying: if a single row result is expected like in the
+	# examples above but the statement returns several rows, the first one is used.)
+	#
+	# * If a block is passed to the method, it can be used to iterate over the results.
+	#
+	#	db.sql("SELECT first, last FROM sometable WHERE last=?", "Smith") do |row|
+	#		puts "Name: #{row.first} #{row.last}
+	#	end  
+	#
+	# * or, in case the resulting rows only contain a single column :
+	# 	
+	#	db.sql "SELECT first FROM sometable" do |firstname|
+	#		puts "Hello #{firstname}!"
+	#	end
+	
+	def sql(stmt, *args, &block) #:yields: row
+				#optional args and an optional block
+		_sql_internal(stmt,false,*args, &block)
+	end
+
+	# Similar to the sql method. This method is meant for `INSERT`
+	# and `UPDATE` statements and returns the RPC (row processed
+	# count), i.e. the number of rows affected by the statement.
+	# 
+
+	def sql_count (stmt, *args, &block)
+		_sql_internal(stmt,true,*args,&block)	
+	end
+
+	# Closes all resources used by this object instance.
+	def close 
+		@pstatements.each_value {|pstmt|
+			pstmt[0].finish
+		}
+		@pstatements = {}
+		@db.disconnect
+		@db = nil
+	end
+
+	# _Debug_ _method_. This method dumps statistics about how often
+	# each sql statement was executed by this instance. Statistics
+	# are reset after calls to `close`
+	def dumpStmtStats 
+		@pstatements.each_pair { |stmt, arr|
+			puts "#{stmt} : #{arr[1]}"
+		} if @pstatements
+	end
+
+	def to_s
+		"DBrb: #{@driver}"
+	end
+
+protected
+
+	# Returns a (cached) reference to the DBI driver.  Default
+	# behaviour is to create a single connection, keeping it cached
+	# and reusing it for all DB statements executed by this object
+	# instance.
+	#
+	# This method is used internally by `sql` and could be
+	# overridden in case you require different behaviour, e.g.
+	# creating a new connection for each executed statement or
+	# maintaining several connections.
+	
+	def get_db 
+		return @db if @db && @db.connected?  
+		@db = DBI.connect(@driver, @usr, @pwd, @params) 
+	end
+
+	def _sql_internal (stmt, count, *args) #:yields: row
+		#optional args and an optional block
+		pstmt = get_pstmt stmt
+		pstmt.execute *args
+		
+		
+		ret_val = nil	
+		begin
+			if block_given?
+				pstmt.each { |row|
+					if row.length==1
+						yield row[0]
+					else
+						yield row
+					end
+				} 
+			else 
+					unless count
+						ret_val = pstmt.fetch if pstmt.fetchable?
+						ret_val = ret_val[0] if ret_val && ret_val.length==1
+					end
+		
+			end	
+		rescue NoMethodError 
+			# calling fetch for mysql drivers on stmts returning
+			# no rows (INSERT...) is fucked.
+
+#			Message: <"undefined method `fetch_row' for nil:NilClass">
+#			---Backtrace---
+#			/usr/local/lib/ruby/site_ruby/1.8/DBD/Mysql/Mysql.rb:424:in `fetch'
+#			/usr/local/lib/ruby/site_ruby/1.8/dbi/dbi.rb:811:in `fetch'
+#			/usr/local/lib/ruby/site_ruby/1.8/dbi/dbi.rb:836:in `each'
+		end
+	
+		ret_val = pstmt.rows if count
+		pstmt.cancel # clean up
+		return ret_val
+
+	end
+
+
+	
+private
+	
+	# Maintains a cache of all prepared statments.  Each prepared
+	# statement executed by `sql` is prepared only once and reused in
+	# case the same sql statement is executed a second time.
+	#
+	# Prepared statements are disposed when `close` is called.
+	
+	def get_pstmt stmt #:doc:
+		#@pstatements[stmt] ||= get_db.prepare stmt
+		@pstatements[stmt] ||= [nil,0]
+		@pstatements[stmt][1] += 1
+		@pstatements[stmt][0] ||= get_db.prepare stmt
+	end
+	
+
+end
+module DBI
+	# augments DBI::Row with a +method_missing+ method that lets the
+	# row behave as if it had accessor methods for each colum.	
+	class Row
+		def method_missing meth_id
+			return self[meth_id]
+		end
+	end
+end
+
+if $0==__FILE__
+	sql = DBrb.new('DBI:PG:stats2', 'test', 'test')
+	row = sql.sql("SELECT * FROM post WHERE nick=? LIMIT 10", "muppet")
+	puts row.nick
+	row = sql.sql("SELECT * FROM post WHERE nick=? LIMIT 10", "Philo")
+	puts row.nick
+	puts sql.sql("SELECT count(*) from post")
+	
+	puts sql.sql("SELECT count(*) from post")
+
+	puts sql.sql("SELECT nick from post limit 20") {|nick|
+		puts nick
+	}
+
+	puts sql.sql("SELECT nick, url from post limit 20") {|row|
+		puts row.nick, row.url
+	}
+	
+	sql.dumpStmtStats
+	
+	sql.close
+
+	
+
+end

data/tests/DbrbTest.rb

@@ -0,0 +1,204 @@
+
+
+require 'DB'
+require 'test/unit'
+
+# Since each test needs to be executed for several different database
+# engines, DBrbTest maintains an array of instances, each connected to
+# one of the backends. the `test_...` methods iterate over the
+# connections and call the actual test methods, which are named like the
+# `test_...` methods without the `test_` part, with each DBrb instance.
+# E.g. test_create_test_table calls `create_test_table` once with each
+# connection.
+
+class DbrbTest < Test::Unit::TestCase
+	
+	# These are the DB logins to test. I'm currently using a
+	# postgres server, with DB, user and pwd all set to `test`. In
+	# case you'd like to test other databases, just add the
+	# necessary connection parameters.
+	
+	@@credentials = [
+		['DBI:PG:test', 'test', 'test'],
+		['DBI:Mysql:test;socket=/var/run/mysqld/mysqld.sock;database=test', 'test', 'test'] # there must be a better way.
+	]
+
+	def setup
+		@time = Time.new
+		@connections = []
+		@@credentials.each { |cred|
+			@connections.push DBrb.new(*cred)
+		}
+	end
+
+	def teardown
+		@connections.each {|conn|
+			conn.close
+		}
+	end
+	
+	# Each test case follows the same scheme: the same tests are
+	# executed for each database and wrapped in a
+	# `assert_nothing_raised` assertion that fails in case of
+	# database exceptions.
+
+	def each_ok
+		@connections.each {|conn|
+			assert_nothing_raised {
+				yield conn
+			}
+		}
+	end
+	
+	#Set up the example table for the tests.
+	def test_a_create_test_table
+		each_ok { |conn|
+			# This should be as generic as possible to 
+			# accomodate different DB's
+			conn.sql "
+			CREATE TABLE test_table (
+				col_vc 		VARCHAR(50),
+				col_num 	NUMERIC,
+				col_bool	BOOLEAN,
+				col_double	DOUBLE PRECISION,
+				col_int		INTEGER,
+				col_date	DATE,
+				col_time	TIME,
+				col_timestamp	TIMESTAMP
+			)"
+		}
+	end
+
+		
+
+	def test_b_insert_values
+		each_ok {|con|
+			%w{zero one two three four five six seven eight
+			nine ten}.each_with_index {|num, i|
+				con.sql("INSERT INTO test_table 
+					VALUES (?,?,?,?,?,?,?,?)",
+					num, i, i%2==0,"#{i}.#{i}".to_f,i, @time, @time, @time)
+			}
+		}
+	end
+
+	
+	
+	def test_c_select_values 
+		each_ok { |db|
+
+			tst = SelectTest.new db, self
+			tst.do "one", 	"SELECT col_vc FROM test_table WHERE col_num=?", 1
+			tst.do "2", 	"SELECT col_num FROM test_table WHERE col_vc=?", "two"
+			# postgres: 0 mysql: false
+			#tst.do 0, 	"SELECT col_bool FROM test_table WHERE col_vc=?", "three"
+
+			#postgres 4.4 mysql "4.4"
+			#tst.do 4.4, 	"SELECT col_double FROM test_table WHERE col_vc=?", "four"
+			tst.do 5, 	"SELECT col_int FROM test_table WHERE col_vc=?", "five"
+			tst.do ["six",6],"SELECT col_vc, col_int FROM test_table WHERE col_double=?", 6.6
+		}
+	end
+	
+	# Date handling seems to be very implementation specific...
+	def test_c_select_date
+		each_ok { |db|	
+			date = db.sql("SELECT col_date FROM test_table LIMIT 1")
+			
+			assert_equal(@time.year, date.year, db.to_s)
+			assert_equal(@time.mon, date.month, db.to_s)
+			assert_equal(@time.day, date.day, db.to_s)
+			
+			time = db.sql("SELECT col_time FROM test_table LIMIT 1")
+
+			if time.class != DBI::Time 
+				# postgres driver doesn't return DBI::Time
+				puts "\nWarning, #{db} returning '#{time.class}' instead of DBI::TIME" 
+				assert_equal(@time.strftime("%H:%M:%S"), time, db)
+			else
+				assert_equal(@time.hour, time.hour, db)
+				assert_equal(@time.min, time.min,db)
+				assert_equal(@time.sec, time.sec,db)
+			end
+			
+			timestamp = db.sql("SELECT col_timestamp FROM test_table LIMIT 1")
+			
+			if timestamp.class != DBI::Timestamp
+				# mysql driver doesn't return DBI::Timestamp...
+				puts "\nWarning, #{db} returning '#{timestamp.class}' instead of DBI::TIMESTAMP"
+				assert_equal(@time.strftime("%Y-%m-%d %H:%M:%S"), timestamp, db.to_s)
+			else
+				assert_equal(@time.year, timestamp.year, db.to_s)
+				assert_equal(@time.mon, timestamp.month, db.to_s)
+				assert_equal(@time.day, timestamp.day, db.to_s)
+				assert_equal(@time.hour, timestamp.hour, db.to_s)
+				assert_equal(@time.min, timestamp.min, db.to_s)
+				assert_equal(@time.sec, timestamp.sec, db.to_s)
+			end
+		}
+	end
+
+	def test_c_select_with_block 
+		each_ok { |db|
+			comp_arr = [0,1,2,3,4,5,6,7,8,9,10]
+			
+			arr = []
+			db.sql "SELECT col_int FROM test_table ORDER BY col_int" do |i|
+				arr.push i
+			end
+			assert_equal comp_arr, arr
+				
+			arr=[]
+
+			db.sql "SELECT col_int, col_date FROM test_table ORDER BY col_int" do |row|
+				arr.push row.col_int
+			end
+			assert_equal comp_arr, arr
+		}
+	end
+
+	
+	def test_d_update_values
+		each_ok do |db|
+			db.sql "UPDATE test_table SET col_int = col_int+1"
+			comp_arr = [1,2,3,4,5,6,7,8,9,10,11]
+			
+			arr = []
+			db.sql "SELECT col_int FROM test_table ORDER BY col_int" do |i|
+				arr.push i
+			end
+			assert_equal comp_arr, arr	
+		end
+	end
+
+	def test_e_count
+		each_ok do |db|
+			c = db.sql_count "UPDATE test_table SET col_int = col_int+2" 
+			assert_equal(11, c, db)
+
+			c = db.sql_count "SELECT * FROM test_table" do |row|
+				arr=row
+			end
+			
+			assert(c==0||c==11, db)
+		end
+	end
+
+	#Drop the test table
+	def test_z_drop_test_table
+		each_ok {|con|
+			con.sql "DROP TABLE test_table"
+		}
+	end
+
+end
+
+class SelectTest
+	def initialize db, tcase
+		@db=db
+		@tcase=tcase
+	end
+	def do val, sql, *args
+		@tcase.assert_equal(val, @db.sql(sql, *args), @db.to_s)
+	end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: DBrb
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-05-14 00:00:00 +02:00
+summary: Easier access to databases.
+require_paths: 
+- lib
+email: tim@kuriositaet.de
+homepage: http://www.kuriositaet.de/ruby/dbrb
+rubyforge_project: 
+description: DBrb is a database access layer meant to be easier and more consistant to use than ruby DBI. Currently, and for the forseeable future it's  implemented as a wrapper to the DBI lib.
+autorequire: DB.rb
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Tim Becker
+files: 
+- tests/DbrbTest.rb
+- lib/DB.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: 
+- DBI
+dependencies: []
+