jdbc-helper 0.7.7 → 0.8.0

data/{CHANGELOG.markdown → CHANGELOG.md}

@@ -1,3 +1,17 @@
+### 0.8.0
+
+0.8.0 introduces a few backward-incompatible changes.
+
+* `Connection#ResultSetEnumerator` is renamed to `Connection::ResultSet`
+* `Connection#query` method will return a ResultSet object instead of an Array
+  * `Connection#enumerate` method is now retired, and just a synonym for query method
+  * Partially consumed ResultSet must be closed explicitly
+* `ResultSet#each` method will return an enumerator when block is not given
+* Refined TableWrapper interface with external [sql_helper](https://github.com/junegunn/sql_helper) gem
+  * The use of `JDBCHelper::SQL` is deprecated
+* Added MariaDB connector
+* Added SQLite connector
+
 ### 0.7.7 / 2013/01/0?
 * `PreparedStatment`s and `TableWrapper`s now inherit the fetch size of the connection
 * Added `JDBCHelper::TableWrapper#fetch_size`

data/{README.markdown → README.md}

@@ -42,17 +42,17 @@ require 'jdbc-helper'
 ```ruby
 # :driver and :url must be given
 conn = JDBCHelper::Connection.new(
-             :driver => 'com.mysql.jdbc.Driver',
-             :url    => 'jdbc:mysql://localhost/test')
+             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 => password)
+             driver:   'com.mysql.jdbc.Driver',
+             url:      'jdbc:mysql://localhost/test',
+             user:     'mysql',
+             password: password)
 conn.close
 ```
 
@@ -61,39 +61,32 @@ conn.close
 jdbc-helper provides shortcut connectors for the following databases
 so that you don't have to specify lengthy class names and JDBC URLs.
 
-* MySQL (`JDBCHelper::MySQL`)
-* Oracle (`JDBCHelper::Oracle`)
-* PostgreSQL (`JDBCHelper::PostgreSQL`)
-* MS SQL Server (`JDBCHelper::MSSQL`)
-* Cassandra (`JDBCHelper::Cassandra`)
-* FileMaker Pro (`JDBCHelper::FileMaker`)
+- MySQL (`JDBCHelper::MySQL`)
+- MariaDB (`JDBCHelper::MariaDB`)
+- Oracle (`JDBCHelper::Oracle`)
+- PostgreSQL (`JDBCHelper::PostgreSQL`)
+- MS SQL Server (`JDBCHelper::MSSQL`)
+- Cassandra (`JDBCHelper::Cassandra`)
+- FileMaker Pro (`JDBCHelper::FileMaker`)
+- SQLite (`JDBCHelper::SQLite`)
 
 ```ruby
-# MySQL shortcut connector
-mc = JDBCHelper::MySQL.connect(host, user, password, db)
-
-# Oracle shortcut connector
-oc = JDBCHelper::Oracle.connect(host, user, password, service_name)
-
-# PostgreSQL shortcut connector
-pc = JDBCHelper::PostgreSQL.connect(host, user, password, db)
-
-# MS SQL Server shortcut connector
-sc = JDBCHelper::MSSQL.connect(host, user, password, db)
-
-# Cassandra CQL3 connector
-cc = JDBCHelper::Cassandra.connect(host, keyspace)
-
-# FileMaker Pro shortcut connector
-fmp = JDBCHelper::FileMaker.connect(host, user, password, db)
-
-# Extra parameters
-mc = JDBCHelper::MySQL.connect(host, user, password, db,
-       :rewriteBatchedStatements => true)
+mysql     = JDBCHelper::MySQL.connect(host, user, password, db)
+mariadb   = JDBCHelper::MariaDB.connect(host, user, password, db)
+oracle    = JDBCHelper::Oracle.connect(host, user, password, service_name)
+postgres  = JDBCHelper::PostgreSQL.connect(host, user, password, db)
+mssql     = JDBCHelper::MSSQL.connect(host, user, password, db)
+cassandra = JDBCHelper::Cassandra.connect(host, keyspace)
+filemaker = JDBCHelper::FileMaker.connect(host, user, password, db)
+sqlite    = JDBCHelper::SQLite.connect(file_path)
+
+# With extra parameters
+mysql = JDBCHelper::MySQL.connect(host, user, password, db,
+          rewriteBatchedStatements: true)
 
 # With connection timeout of 30 seconds
-mc = JDBCHelper::MySQL.connect(host, user, password, db,
-       :rewriteBatchedStatements => true, :timeout => 30)
+mysql = JDBCHelper::MySQL.connect(host, user, password, db,
+          rewriteBatchedStatements: true, timeout: 30)
 
 # When block is given, connection is automatically closed after the block is executed
 JDBCHelper::Cassandra.connect(host, keyspace) do |cc|
@@ -104,7 +97,7 @@ end
 ### Querying database table
 
 ```ruby
-conn.query("SELECT a, b, c FROM T") do |row|
+conn.query('SELECT a, b, c FROM T') do |row|
   row.labels
   row.rownum
 
@@ -120,23 +113,26 @@ conn.query("SELECT a, b, c FROM T") do |row|
   row.to_h                     # Row as a Hash
 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 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 |
+# Connection::ResultSet object is returned when block is not given
+# - ResultSet is automatically closed when entirely iterated
+rows = conn.query('SELECT * FROM T')
+uniq_rows = rows.to_a.uniq
+
+# However, partially consumed ResultSet objects *must be closed* manually
+rset = conn.query('SELECT * FROM T')
+rows = rset.take(2)
+rset.close
+
+# Enumerator chain
+conn.query('SELECT * FROM LARGE_T').each_slice(1000).with_index do |slice, idx|
+  slice.each do |row|
     # ...
   end
 end
@@ -144,17 +140,17 @@ end
 
 ### Updating database table
 ```ruby
-del_count = conn.update("DELETE FROM T")
+del_count = conn.update('DELETE FROM T')
 ```
 
 ### Executing any SQL
 ```ruby
-rset = conn.execute("SELECT * FROM T")
+rset = conn.execute('SELECT * FROM T')
 rset.each do |row|
   # Returned result must be used or closed
 end
 
-del_count = conn.execute("DELETE FROM T")
+del_count = conn.execute('DELETE FROM T')
 ```
 
 ### Transaction
@@ -175,21 +171,21 @@ end
 
 ### Using batch interface
 ```ruby
-conn.add_batch("DELETE FROM T");
+conn.add_batch('DELETE FROM T')
 conn.execute_batch
-conn.add_batch("DELETE FROM T");
+conn.add_batch('DELETE FROM T')
 conn.clear_batch
 ```
 
 ### Using prepared statements
 ```ruby
-p_sel = conn.prepare("SELECT * FROM T WHERE b = ? and c = ?")
+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 = ?")
+p_upd = conn.prepare('UPDATE T SET a = ? WHERE b = ?')
 count = 0
 100.times do |i|
   count += p_upd.update('updated a', i)
@@ -213,9 +209,6 @@ pstmt.java.getMetaData
 
 ### Using table wrappers (since 0.2.0)
 ```ruby
-# For more complex examples, refer to test/test_object_wrapper.rb
-SQL = JDBCHelper::SQL
-
 # Creates a table wrapper
 table = conn.table('test.data')
 # Or equievalently,
@@ -223,43 +216,43 @@ table = conn['test.data']
 
 # Counting the records in the table
 table.count
-table.count(:a => 10)
-table.where(:a => 10).count
+table.count(a: 10)
+table.where(a: 10).count
 
 table.empty?
-table.where(:a => 10).empty?
+table.where(a: 10).empty?
 
-# Selects the table by combining select, where, order and fetch_size methods
-table.select('a apple', :b).where(:c => (1..10)).order('b desc', 'a asc').fetch_size(100).each do |row|
+# Selects the table by combining select, where, order, limit and fetch_size methods
+table.select('a apple', :b).where(c: (1..10)).order('b desc', 'a asc').fetch_size(100).limit(1000).each 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
+sql = table.select('a apple', :b).where(c: (1..10)).order('b desc', 'a asc').sql
 
 # Updates with conditions
-table.where(:c => 3).update(:a => 'hello', :b => SQL.expr('now()'))
+table.where(c: 3).update(a: 'hello', b: { sql: 'now()' })
 
 # Insert into the table
-table.insert(:a => 10, :b => 20, :c => SQL.expr('10 + 20'))
-table.insert_ignore(:a => 10, :b => 20, :c => 30)
-table.replace(:a => 10, :b => 20, :c => 30)
+table.insert(a: 10, b: 20, c: { 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 = 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 => SQL.expr('10 + 20'))
-table.batch.insert_ignore(:a => 10, :b => 20, :c => 30)
-table.batch.where(:a => 10).update(:a => 20)
+table.batch.insert(a: 10, b: 20, c: { sql: '10 + 20' })
+table.batch.insert_ignore(a: 10, b: 20, c: 30)
+table.batch.where(a: 10).update(a: 20)
 table.execute_batch :insert, :update
 
 # Delete with conditions
-table.delete(:c => 3)
+table.delete(c: 3)
 # Or equivalently,
-table.where(:c => 3).delete
+table.where(c: 3).delete
 
 # Truncate or drop table (Cannot be undone)
 table.truncate!
@@ -268,26 +261,23 @@ table.drop!
 
 #### Building complex where clauses
 ```ruby
-# Shortcut. Or you can just include JDBCHelper
-SQL = JDBCHelper::SQL
-
 # With any number of Strings, Arrays and Hashes
 scope = table.where(
-  "x <> 'hello'",                      # x <> 'hello'
-  ["y = ? or z > ?", 'abc', 10],       # and (y = 'abc' or z > 10)
-  :a => 'abc',                         # and a = 'abc'
-  :b => (1..10),                       # and b >= 1 and b <= 10
-  :c => (1...10),                      # and c >= 1 and c < 10
-  :d => %w[a b c],                     # and d in ('a', 'b', 'c')
-  :e => SQL.expr('sysdate'),           # and e = sysdate
-  :f => SQL.not_null,                  # and f is not null
-  :g => SQL.gt(100),                   # and g > 100
-  :h => SQL.lt(100),                   # and h < 100
-  :i => SQL.like('ABC%'),              # and i like 'ABC%'
-  :j => SQL.not_like('ABC%'),          # and j not like 'ABC%'
-  :k => SQL.le( SQL.expr('sysdate') )  # and k <= sysdate
+  "x <> 'hello'",                # x <> 'hello'
+  ["y = ? or z > ?", 'abc', 10], # and (y = 'abc' or z > 10)
+  a: 'abc',                      # and a = 'abc'
+  b: (1..10),                    # and b between 1 and 10
+  c: (1...10),                   # and c >= 1 and c < 10
+  d: %w[a b c],                  # and d in ('a', 'b', 'c')
+  e: { sql: 'sysdate' },         # and e = sysdate
+  f: { not: nil },               # and f is not null
+  g: { gt: 100, le: 200 },       # and g > 100 and g <= 200
+  h: { lt: 100 },                # and h < 100
+  i: { like: 'ABC%' },           # and i like 'ABC%'
+  j: { not: { like: 'ABC%' } },  # and j not like 'ABC%'
+  k: { le: { sql: 'sysdate' } }  # and k <= sysdate
 )
-scope.update(:a => 'xyz')
+scope.update(a: 'xyz')
 ```
 
 #### Invalid use of plain String conditions
@@ -353,7 +343,7 @@ conn.procedure(:update_and_fetch_something).call(
 
 # Bind by parameter name
 conn.procedure(:update_and_fetch_something).call(
-         :a => 100, :b => ["value", String], :c => Fixnum)
+         a: 100, b: ["value", String], c: Fixnum)
 ```
 
 ### Using sequence wrappers (since 0.4.2)

data/jdbc-helper.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |gem|
   gem.version       = JDBCHelper::VERSION
 
   gem.add_runtime_dependency 'insensitive_hash', '>= 0.2.4'
+  gem.add_runtime_dependency 'sql_helper', '~> 0.1.1'
   gem.add_development_dependency "bundler"
   gem.add_development_dependency "simplecov"
   gem.add_development_dependency "test-unit"

data/lib/jdbc-helper/connection/prepared_statement.rb

@@ -27,13 +27,13 @@ class PreparedStatement < ParameterizedStatement
     @java_obj = nil
   end
 
-  # @return [Fixnum|ResultSetEnumerator]
+  # @return [Fixnum|ResultSet]
   def execute(*params)
     check_closed
 
     set_params(params)
     if @java_obj.execute
-      ResultSetEnumerator.new(@java_obj.getResultSet)
+      ResultSet.new(@java_obj.getResultSet)
     else
       @java_obj.getUpdateCount
     end
@@ -52,19 +52,16 @@ class PreparedStatement < ParameterizedStatement
     check_closed
 
     set_params(params)
-    # sorry, ignoring privacy
-    @conn.send(:process_and_close_rset, @java_obj.execute_query, &blk)
-  end
-
-  # @return [JDBCHelper::Connection::ResultSetEnumerator]
-  def enumerate(*params, &blk)
-    check_closed
-
-    return query(*params, &blk) if block_given?
-
-    set_params(params)
-    ResultSetEnumerator.new(@java_obj.execute_query)
+    enum = ResultSet.new(@java_obj.execute_query)
+    if block_given?
+      enum.each do |row|
+        yield row
+      end
+    else
+      enum
+    end
   end
+  alias enumerate query
 
   # Adds to the batch
   # @return [NilClass]

data/lib/jdbc-helper/connection/{result_set_enumerator.rb → result_set.rb}

@@ -7,48 +7,47 @@ module JDBCHelper
 class Connection
 # Class for enumerating query results.
 # Automatically closed after used. When not used, you must close it explicitly by calling "close".
-class ResultSetEnumerator
+class ResultSet
   include Enumerable
 
   def each
+    return enum_for(:each) unless block_given?
     return if closed?
 
-    count = -1
-    begin
-      while @rset.next
-        idx = 0
-        # Oracle returns numbers in NUMERIC type, which can be of any precision.
-        # So, we retrieve the numbers in String type not to lose their precision.
-        # This can be quite annoying when you're just working with integers,
-        # so I tried the following code to automatically convert integer string into integer
-        # when it's obvious. However, the performance drop is untolerable.
-        # Thus, commented out.
-        #
-        # if v && @cols_meta[i-1] == java.sql.Types::NUMERIC && v !~ /[\.e]/i
-        #   v.to_i
-        # else
-        #   v
-        # end
-        yield Connection::Row.new(
-            @col_labels,
-            @col_labels_d,
-            @getters.map { |gt|
-              case gt
-              when :getBigNum
-                v = @rset.getBigDecimal idx+=1
-                @rset.was_null ? nil : v.toPlainString.to_i
-              when :getBigDecimal
-                v = @rset.getBigDecimal idx+=1
-                @rset.was_null ? nil : BigDecimal.new(v.toPlainString)
-              else
-                v = @rset.send gt, idx+=1
-                @rset.was_null ? nil : v
-              end
-            }, count += 1)
-      end
-    ensure
-      close
+    while @nrow
+      idx = 0
+      # Oracle returns numbers in NUMERIC type, which can be of any precision.
+      # So, we retrieve the numbers in String type not to lose their precision.
+      # This can be quite annoying when you're just working with integers,
+      # so I tried the following code to automatically convert integer string into integer
+      # when it's obvious. However, the performance drop is untolerable.
+      # Thus, commented out.
+      #
+      # if v && @cols_meta[i-1] == java.sql.Types::NUMERIC && v !~ /[\.e]/i
+      #   v.to_i
+      # else
+      #   v
+      # end
+      row = Connection::Row.new(
+          @col_labels,
+          @col_labels_d,
+          @getters.map { |gt|
+            case gt
+            when :getBigNum
+              v = @rset.getBigDecimal idx+=1
+              @rset.was_null ? nil : v.toPlainString.to_i
+            when :getBigDecimal
+              v = @rset.getBigDecimal idx+=1
+              @rset.was_null ? nil : BigDecimal.new(v.toPlainString)
+            else
+              v = @rset.send gt, idx+=1
+              @rset.was_null ? nil : v
+            end
+          }, @rownum += 1)
+      close unless @nrow = @rset.next
+      yield row
     end
+    close
   end
 
   def close
@@ -90,11 +89,7 @@ private
           if precision > 0 && scale >= 0
             # Numbers with fractional parts
             if scale > 0
-              if precision <= 15
-                :getDouble
-              else
-                :getBigDecimal
-              end
+              :getBigDecimal
             # Numbers without fractional parts
             else
               if precision <= 9
@@ -119,9 +114,11 @@ private
 
     end
 
+    @rownum = -1
+    @nrow   = @rset.next
     @closed = false
   end
-end#ResultSetEnumerator
+end#ResultSet
 end#Connection
 end#JDBCHelper
 

data/lib/jdbc-helper/connection.rb

@@ -8,7 +8,7 @@ require 'jdbc-helper/connection/parameterized_statement'
 require 'jdbc-helper/connection/prepared_statement'
 require 'jdbc-helper/connection/callable_statement'
 require 'jdbc-helper/connection/statement_pool'
-require 'jdbc-helper/connection/result_set_enumerator'
+require 'jdbc-helper/connection/result_set'
 require 'jdbc-helper/connection/row'
 
 require 'jdbc-helper/wrapper/object_wrapper'
@@ -137,7 +137,7 @@ class Connection
   # @param [Hash] args
   def initialize(args = {})
     # Subsequent deletes should not affect the input
-    @args = Marshal.load(Marshal.dump(args))
+    @args = args
     args = InsensitiveHash[ @args ]
 
     raise ArgumentError.new("driver not given") unless args.has_key? :driver
@@ -241,18 +241,18 @@ class Connection
     status == :committed
   end
 
-  # Executes an SQL and returns the count of the update rows or a ResultSetEnumerator object
+  # Executes an SQL and returns the count of the update rows or a ResultSet object
   # depending on the type of the given statement.
-  # If a ResultSetEnumerator is returned, it must be enumerated or closed.
+  # If a ResultSet is returned, it must be enumerated or closed.
   # @param [String] qstr SQL string
-  # @return [Fixnum|ResultSetEnumerator]
+  # @return [Fixnum|ResultSet]
   def execute(qstr)
     check_closed
 
     stmt = @spool.take
     begin
       if stmt.execute(qstr)
-        ResultSetEnumerator.send(:new, stmt.getResultSet) { @spool.give stmt }
+        ResultSet.send(:new, stmt.getResultSet) { @spool.give stmt }
       else
         rset = stmt.getUpdateCount
         @spool.give stmt
@@ -277,16 +277,14 @@ class Connection
 
   # Executes a select query.
   # When a code block is given, each row of the result is passed to the block one by one.
-  # If a code block not given, this method will return the array of the entire result rows.
-  # (which can be pretty inefficient when the result set is large. In such cases, use enumerate instead.)
-  #
-  # The concept of statement object of JDBC is encapsulated, so there's no need to do additional task,
-  # when you nest select queries, for example.
+  # If not given, ResultSet is returned, which can be used to enumerate through the result set.
+  # ResultSet is closed automatically when all the rows in the result set is consumed.
   #
+  # @example Nested querying
   #   conn.query("SELECT a FROM T") do | trow |
-  #       conn.query("SELECT * FROM U_#{trow.a}") do | urow |
-  #           # ... and so on ...
-  #       end
+  #     conn.query("SELECT * FROM U_#{trow.a}").each_slice(10) do | urows |
+  #       # ...
+  #     end
   #   end
   # @param [String] qstr SQL string
   # @yield [JDBCHelper::Connection::Row]
@@ -294,40 +292,24 @@ class Connection
   def query(qstr, &blk)
     check_closed
 
-    @spool.with do | stmt |
-      rset = stmt.execute_query(qstr)
-      process_and_close_rset(rset, &blk)
-    end
-  end
-
-  # Returns an enumerable object of the query result.
-  # "enumerate" method is preferable when dealing with a large result set,
-  # since it doesn't have to build a large array.
-  #
-  # The returned enumerator is automatically closed after enumeration.
-  #
-  #   conn.enumerate('SELECT * FROM T').each_slice(10) do | slice |
-  #       slice.each { | row | print row }
-  #       puts
-  #   end
-  #
-  # @param [String] qstr SQL string
-  # @yield [JDBCHelper::Connection::Row] Yields each record if block is given
-  # @return [JDBCHelper::Connection::ResultSetEnumerator] Returns an enumerator if block is not given
-  def enumerate(qstr, &blk)
-    check_closed
-
-    return query(qstr, &blk) if block_given?
-
     stmt = @spool.take
     begin
       rset = stmt.execute_query(qstr)
-      return ResultSetEnumerator.send(:new, rset) { @spool.give stmt }
-    rescue Exception
+    rescue Exception => e
       @spool.give stmt
       raise
     end
+
+    enum = ResultSet.send(:new, rset) { @spool.give stmt }
+    if block_given?
+      enum.each do |row|
+        yield row
+      end
+    else
+      enum
+    end
   end
+  alias enumerate query
 
   # Adds a statement to be executed in batch
   # Adds to the batch
@@ -480,24 +462,6 @@ private
     stmt
   end
 
-  def process_and_close_rset(rset) # :nodoc:
-    enum = ResultSetEnumerator.send :new, rset
-    rows = []
-
-    begin
-      enum.each do | row |
-        if block_given?
-          yield row
-        else
-          rows << row
-        end
-      end
-      block_given? ? nil : rows
-    ensure
-      enum.close
-    end
-  end
-
   def close_pstmt pstmt
     @pstmts.delete pstmt
   end

data/lib/jdbc-helper/connector/mariadb.rb

@@ -0,0 +1,24 @@
+# encoding: UTF-8
+# Junegunn Choi (junegunn.c@gmail.com)
+
+module JDBCHelper
+# Shortcut connector for MariaDB
+module MariaDB
+  extend Connector
+
+  # @param [String] host
+  # @param [String] user
+  # @param [String] password
+  # @param [String] db
+  # @param [Hash] extra_params
+  # @return [JDBCHelper::Connection]
+  def self.connect(host, user, password, db, extra_params = {}, &block)
+    connect_impl :mariadb, {
+      :url      => "jdbc:mysql://#{host}/#{db}",
+      :user     => user,
+      :password => password
+    }, extra_params, &block
+  end
+end#MariaDB::Connector
+end#JDBCHelper
+

data/lib/jdbc-helper/connector/sqlite.rb

@@ -0,0 +1,19 @@
+# encoding: UTF-8
+# Junegunn Choi (junegunn.c@gmail.com)
+
+module JDBCHelper
+# Shortcut connector for SQLite
+module SQLite
+  extend Connector
+
+  # @param [String] path
+  # @param [Hash] extra_params
+  # @return [JDBCHelper::Connection]
+  def self.connect(path, extra_params = {}, &block)
+    connect_impl :sqlite, {
+      :url      => "jdbc:sqlite:#{path}",
+    }, extra_params, &block
+  end
+end#SQLite::Connector
+end#JDBCHelper
+