jdbc-helper 0.5.1 → 0.6.0

data/README.rdoc

@@ -1,223 +0,0 @@
-    _     _ _                 _          _                 
-   (_)   | | |               | |        | |                
-    _  __| | |__   ___ ______| |__   ___| |_ __   ___ _ __ 
-   | |/ _` | '_ \ / __|______| '_ \ / _ \ | '_ \ / _ \ '__|
-   | | (_| | |_) | (__       | | | |  __/ | |_) |  __/ |   
-   | |\__,_|_.__/ \___|      |_| |_|\___|_| .__/ \___|_|   
-  _/ |                                    | |              
- |__/                                     |_|              
-
-= jdbc-helper
-
-A JDBC helper for Ruby/Database developers.
-JDBCHelper::Connection object wraps around a JDBC connection and provides much nicer interface to
-crucial database operations from primitive selects and updates to more complex ones involving
-batch updates, prepared statements and transactions.
-As the name implies, this gem only works on JRuby.
-
-== Installation
-=== Install gem
- gem install jdbc-helper
-
-=== Setting up CLASSPATH
-Add the appropriate JDBC drivers to the CLASSPATH.
- export CLASSPATH=$CLASSPATH:~/lib/mysql-connector-java-5.1.16-bin.jar:~/lib/ojdbc6.jar
-
-=== In Ruby
- require 'jdbc-helper'
-
-== Examples
-=== Connecting to a database
-
- # :driver and :url must be given
- conn = JDBCHelper::Connection.new(
-              :driver => 'com.mysql.jdbc.Driver',
-              :url    => 'jdbc:mysql://localhost/test')
- conn.close
- 
- 
- # Optional :user and :password
- conn = JDBCHelper::Connection.new(
-              :driver   => 'com.mysql.jdbc.Driver',
-              :url      => 'jdbc:mysql://localhost/test',
-              :user     => 'mysql',
-              :password => '')
- conn.close
-
-
- # MySQL shortcut connector
- conn = JDBCHelper::MySQLConnector.connect('localhost', 'mysql', '', 'test')
- conn.close
-
-  # Oracle shortcut connector
- conn = JDBCHelper::OracleConnector.connect(host, user, password, service_name)
- conn.close
-
-=== Querying database table
-
- conn.query("SELECT a, b, c FROM T") do |row|
-     row.labels
-     row.rownum
-
-     row.a, row.b, row.c          # Dot-notation
-     row[0], row[1], row[2]       # Numeric index
-     row['a'], row['b'], row['c'] # String index. Case-insensitive.
-     row[:a], row[:b], row[:c]    # Symbol index. Case-insensitive.
-
-     row[0..-1]                   # Range index. Returns an array of values.
-     row[0, 3]                    # Offset and length. Returns an array of values.
- end
-
- # Returns an array of rows when block is not given
- rows = conn.query("SELECT b FROM T")
- uniq_rows = rows.uniq
-
- # You can even nest queries
- conn.query("SELECT a FROM T") do |row1|
-     conn.query("SELECT * FROM T_#{row1.a}") do |row2|
-         # ...
-     end
- end
-
- # `enumerate' method returns an Enumerable object if block is not given.
- # When the result set of the query is expected to be large and you wish to
- # chain enumerators, `enumerate' is much preferred over `query'. (which returns the
- # array of the entire rows)
- conn.enumerate("SELECT * FROM LARGE_T").each_slice(1000) do |slice|
-    slice.each do | row |
-        # ...
-    end
- end
-
-=== Updating database table
- del_count = conn.update("DELETE FROM T")
-
-=== Transaction
- committed = conn.transaction do |tx|
-     # ...
-     # Transaction logic here
-     # ...
-
-     if success
-         tx.commit
-     else
-         tx.rollback
-     end
-     # You never reach here.
- end
-
-=== Using batch interface
- conn.add_batch("DELETE FROM T");
- conn.execute_batch
- conn.add_batch("DELETE FROM T");
- conn.clear_batch
-
-=== Using prepared statements
- p_sel = conn.prepare("SELECT * FROM T WHERE b = ? and c = ?")
- p_sel.query(100, 200) do |row|
-     p row
- end
- p_sel.close
-
- p_upd = conn.prepare("UPDATE T SET a = ? WHERE b = ?")
- count = 0
- 100.times do |i|
-     count += p_upd.update('updated a', i)
- end
-
- p_upd.add_batch('pstmt + batch', 10)
- p_upd.add_batch('pstmt + batch', 20)
- p_upd.add_batch('pstmt + batch', 30)
- p_upd.execute_batch
- p_upd.close
-
-=== Using table wrappers (since 0.2.0)
- # For more complex examples, refer to test/test_object_wrapper.rb
-
- # Creates a table wrapper
- table = conn.table('test.data')
-
- # Counting the records in the table
- table.count
- table.count(:a => 10)
- table.where(:a => 10).count
-
- table.empty?
- table.where(:a => 10).empty?
-
- # Selects the table by combining select, where, and order methods
- table.select('a apple', :b).where(:c => (1..10)).order('b desc', 'a asc') do |row|
-   puts row.apple
- end
-
- # Build select SQL
- sql = table.select('a apple', :b).where(:c => (1..10)).order('b desc', 'a asc').sql
-
- # Updates with conditions
- table.update(:a => 'hello', :b => JDBCHelper::SQL('now()'), :where => { :c => 3 })
- # Or equivalently,
- table.where(:c => 3).update(:a => 'hello', :b => JDBCHelper::SQL('now()'))
-
- # Insert into the table
- table.insert(:a => 10, :b => 20, :c => JDBCHelper::SQL('10 + 20'))
- table.insert_ignore(:a => 10, :b => 20, :c => 30)
- table.replace(:a => 10, :b => 20, :c => 30)
-
- # Update with common default values
- with_defaults = table.default(:a => 10, :b => 20)
- with_defaults.insert(:c => 30)
- with_defaults.where('a != 10 or b != 20').update   # sets a => 10, b => 20
-
- # Batch updates with batch method
- table.batch.insert(:a => 10, :b => 20, :c => JDBCHelper::SQL('10 + 20'))
- table.batch.insert_ignore(:a => 10, :b => 20, :c => 30)
- conn.execute_batch
-
- # Delete with conditions
- table.delete(:c => 3)
- # Or equivalently,
- table.where(:c => 3).delete
-
- # Truncate or drop table (Cannot be undone)
- table.truncate!
- table.drop!
-
-=== Using function wrappers (since 0.2.2)
- conn.function(:mod).call 5, 3
- conn.function(:coalesce).call(nil, nil, 'king')
-
-=== Using procedure wrappers (since 0.3.0)
- # Working with IN/INOUT/OUT parameteres
- # Bind by ordinal number
- conn.procedure(:update_and_fetch_something).call(
-          100,                 # Input parameter 
-          ["value", String],   # Input/Output parameter
-          Fixnum               # Output parameter
- )
-
- # Bind by parameter name
- conn.procedure(:update_and_fetch_something).call(
-          :a => 100, :b => ["value", String], :c => Fixnum)
-
-=== Using sequence wrappers (since 0.4.2)
- seq = conn.sequence(:my_seq)
- next = seq.nextval
- curr = seq.currval
- seq.reset!
- seq.reset! 100
-
-== Contributing to jdbc-helper
-
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2011 Junegunn Choi. See LICENSE.txt for
-further details.
-

data/test/test_performance.rb

@@ -1,138 +0,0 @@
-require 'helper'
-require 'benchmark'
-
-class TestPerformance < Test::Unit::TestCase
-	include JDBCHelperTestHelper
-
-	def setup
-		@table = 'tmp_jdbc_helper'
-		@range = 'aaa'..'aaz'
-		@count = 10000 # Increase this for performance measurement
-	end
-
-	def teardown
-		each_connection do | conn |
-			drop_table conn
-		end
-	end
-
-	# No assertion here.
-	def test_performance
-		each_connection do | conn |
-			reset conn
-			puts "Normal inserts: #{Benchmark.measure {
-				@count.times do |i|
-					conn.update "insert into #{@table} values (#{@range.map{rand @count}.join ','})"
-				end
-			}.real}"
-
-			puts "Normal inserts (batch & chuck-transactional): #{Benchmark.measure {
-				(0...@count).each_slice(50) do |slice|
-					conn.transaction do
-						slice.each do |i|
-              conn.add_batch "insert into #{@table} values (#{@range.map{rand @count}.join ','})"
-						end
-						conn.execute_batch
-					end
-				end
-			}.real}"
-
-			puts "Prepared inserts: #{Benchmark.measure {
-				pins = conn.prepare "insert into #{@table} values (#{@range.map{'?'}.join ','})"
-				@count.times do |i|
-					pins.update *(@range.map {rand @count})
-				end
-				pins.close
-			}.real}"
-
-			puts "Prepared inserts (batch & chuck-transactional): #{Benchmark.measure {
-				pins = conn.prepare "insert into #{@table} values (#{@range.map{'?'}.join ','})"
-				(0...@count).each_slice(50) do |slice|
-					conn.transaction do
-						slice.each do |i|
-							pins.add_batch *(@range.map {rand @count})
-						end
-						pins.execute_batch
-					end
-				end
-				pins.close
-			}.real}"
-
-			puts "Inserts with hash: #{Benchmark.measure {
-				table = conn.table(@table)
-				@count.times do |i|
-					table.insert @range.inject({}) { |hash, key| hash[key] = rand; hash }
-				end
-			}.real}"
-
-			puts "Inserts with hash (batch & chunk-transactional): #{Benchmark.measure {
-				table = conn.table(@table)
-        btable = table.batch
-				(0...@count).each_slice(50) do |slice|
-					conn.transaction do
-						slice.each do |i|
-							btable.insert @range.inject({}) { |hash, key| hash[key] = rand; hash }
-						end
-						conn.execute_batch
-					end
-				end
-			}.real}"
-
-			assert_equal @count * 6, conn.table(@table).count
-
-			conn.query("select * from #{@table}") do |row|
-				# ...
-			end
-
-			puts "Accessing records using dot notation: #{Benchmark.measure {
-				conn.query("select * from #{@table}") do |row|
-					@range.each do |r|
-						row.send r
-					end
-				end
-			}.real}"
-
-			puts "Accessing records using numeric indexes: #{Benchmark.measure {
-				conn.query("select * from #{@table}") do |row|
-					@range.each_with_index do |r,i|
-						row[i]
-					end
-				end
-			}.real}"
-
-			puts "Chaining enumerators with query: #{Benchmark.measure {
-				conn.query("select * from #{@table}").each_slice(50) do |slice|
-					slice.each do |row|
-						@range.each_with_index do |r,i|
-							row[i]
-						end
-					end
-				end
-			}.real}"
-
-			puts "Chaining enumerators with enumerate: #{Benchmark.measure {
-				conn.enumerate("select * from #{@table}").each_slice(50) do |slice|
-					slice.each do |row|
-						@range.each_with_index do |r,i|
-							row[i]
-						end
-					end
-				end
-			}.real}"
-		end
-	end
-
-	def create_table conn
-		conn.update("create table #{@table} (#{@range.map { |e| "#{e} int" }.join(', ')})")
-	end
-
-	def drop_table conn
-		conn.update("drop table #{@table}") rescue nil
-	end
-
-	def reset conn
-		drop_table conn
-		create_table conn
-	end
-end
-