oracle_raw 0.1.6 → 0.1.8

data/README.md

@@ -0,0 +1,93 @@
+oracle_raw
+==========
+
+This is a library for interfacing with an Oracle Database. It uses ActiveRecord Oracle Enhanced adapter (https://github.com/rsim/oracle-enhanced) for connection pooling, but otherwise a raw Ruby-OCI8 connection (http://ruby-oci8.rubyforge.org/en/) is used. 
+
+Installation 
+============
+
+```bash
+gem install oracle_raw
+```
+
+Usage
+=====
+
+At the moment the following methods are implemented:
+
+* `query`: a general querying method
+* `with_connection`: a method taking a block as an argument; inside the block you can use a raw connection object to execute queries, updates etc.
+
+Connect to a database and create a pool of five connections. Global options (see below) and pool size are not mandatory. Default pool size is 1. 
+
+```ruby
+tnsnames = '(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SID = TEST)))'
+schema = 'scott'
+password = 'tiger'
+connection_pool_size = 5
+global_options = {}
+
+db = OracleRaw.new(tnsnames, schema, password, connection_pool_size, global_options)
+```
+
+Get a connection from the pool and do something with it: 
+
+```ruby
+db.with_connection { |c| 
+	c.exec('create table names (id number, name varchar2(50))') 
+	c.exec("insert into names (id, name) values (1, 'Paul')") 
+	c.exec("insert into names (id, name) values (2, 'Maria')")
+	c.commit
+}
+```
+
+Use query method (handles connection internally). Without parameters:
+
+```ruby
+db.query('select name from names')
+=> {:data=>[["Paul"], ["Maria"]]}
+```
+
+Query with parameters: 
+
+```ruby
+db.query('select name from names where id = :id', [[:id, 1, Integer]])
+=> {:data=>[["Paul"]]}
+```
+
+Query with options: the behaviour of the query method can be controlled with the following options given to initializer, #query or both: 
+
+* `:metadata`: if `:all`, returns the number of items in the result set, column names in lower case, and the time and duration of the query. If `:none`, returns only the result set. 
+* `:item_format`: if `:hash`, query returns the result items as hashes. The default is `:array`, i.e. the items are arrays. 
+* `:amount`: if `:all_rows`, returns all rows. If `:first_row`, returns only the first row. If `:single_value`, returns only the first value of the first row. `:single_value` cannot be used if `:item_format` is `:hash`. Default is to return all rows. 
+
+Global options can be changed after initialization. 
+Options given to `query` override global options given to initializer (but not when the option value is nil). 
+
+```ruby
+db.query('select name from names', nil, {:item_format => :hash})
+=> {:data=>[{"NAME"=>"Paul"}, {"NAME"=>"Maria"}]}
+
+db.query('select name from names', nil, {:item_format => :array})
+=> {:data=>[["Paul"], ["Maria"]]}
+
+db.query('select name from names', nil, {:metadata=>:plain})
+=> [["Paul"], ["Maria"]]
+
+db.query('select name from names', nil, {:metadata => :all})
+=> {:count=>2, :columns=>["name"], :data=>[["Paul"], ["Maria"]], :date=>2012-09-17 15:53:46 +0300, :duration=>0.0016196}
+
+db.query('select count(*) from names', nil, {:amount=>:single_value, :metadata=>:plain}).to_i
+=> 2
+```
+
+Close the connection pool: 
+
+```ruby
+db.close
+```
+
+Copyright
+=========
+
+Copyright (c) 2011 opiskelijarekisteri-devel. License: LGPLv3. See LICENSE.txt for further details.

data/Rakefile

@@ -16,7 +16,7 @@ Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "oracle_raw"
   gem.homepage = "http://github.com/opiskelijarekisteri-devel/oracle_raw"
-  gem.license = "GPLv3"
+  gem.license = "LGPLv3"
   gem.summary = %Q{Ruby library for interfacing with an Oracle Database using pooled OCI8 raw connections.}
   gem.description = %Q{This is a Ruby library for interfacing with an Oracle Database using pooled OCI8 raw connections (http://ruby-oci8.rubyforge.org/en/). Connection pooling is achieved by utilizing ActiveRecord Oracle Enhanced adapter (https://github.com/rsim/oracle-enhanced).}
   gem.email = "opiskelijarekisteri-devel@helsinki.fi"
@@ -32,17 +32,9 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-  test.rcov_opts << '--exclude "gems/*"'
-end
-
 task :default => :test
 
-require 'rake/rdoctask'
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 

data/VERSION

@@ -1 +1 @@
-0.1.6
+0.1.8

data/lib/oracle_raw.rb

@@ -1,8 +1,4 @@
 # encoding: UTF-8
-# 
-# Author::    opiskelijarekisteri-devel (mailto:opiskelijarekisteri-devel@helsinki.fi)
-# Copyright:: Copyright (c) 2011 opiskelijarekisteri-devel
-# License::   GNU General Public License, Version 3 (http://www.gnu.org/copyleft/gpl.txt)
 
 require 'oci8'
 
@@ -35,60 +31,18 @@ require 'active_record'
 # This is a Ruby library for interfacing with an Oracle Database using pooled OCI8 raw connections (http://ruby-oci8.rubyforge.org/en/).
 # It uses ActiveRecord Oracle Enhanced adapter (https://github.com/rsim/oracle-enhanced) for connection pooling.
 #
-# At the moment the following methods are implemented:
-# * #query: a general querying method
-# * #with_connection: a method taking a block as an argument; inside the block you can use a raw connection object to execute queries, updates etc.
-#
-# The behaviour of the query method can be controlled with the following options given to initializer, #query or both: 
-# * +:metadata+: if +:all+, returns the number of items in the result set, column names in lower case, and the time and duration of the query. If +:none+, returns only the result set. 
-# * +:item_format+: if +:hash+, query returns the result items as hashes. The default is +:array+, i.e. the items are arrays. 
-# * +:amount+: if +:all_rows+, returns all rows. If +:first_row+, returns only the first row. If +:single_value+, returns only the first value of the first row. +:single_value+ cannot be used if +:item_format+ is +:hash+. Default is to return all rows. 
-#
-# Global options can be changed after initialization.  
-# Options given to #query override global options given to initializer (but not when the option value is nil).
-# 
 # == Installation
 #
 # <tt>gem install oracle_raw</tt>
 #
 # == Usage
 #
-# <tt>tnsnames = '(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SID = TEST)))'</tt>
-#
-# <tt>schema = 'scott'</tt>
-#
-# <tt>password = 'tiger'</tt>
-#
-# <tt>connection_pool_size = 5</tt>
-#
-# <tt>global_options = { :metadata => :all, :item_format => :hash, :amount => :first_row }</tt>
-#
-# <tt>db = OracleRaw.new(tnsnames, schema, password, connection_pool_size, global_options)</tt>
-#
-# <tt>students_sql = 'select * from students where last_name = :last_name' and first_name = :first_name</tt>
-#
-# <tt>last_name = 'Kruskal-Wallis'</tt>
-#
-# <tt>first_name = 'Lucy'</tt>
-#
-# <tt>result = db.query(students_sql, [[:last_name, last_name, String], [:first_name, first_name, String]])</tt>
-#
-# <tt>puts result[:rowcount]</tt>
-#
-# <tt>puts result[:duration]</tt>
-#
-# <tt>result = db.query(students_sql, [[:last_name, last_name, String, 50], [:first_name, first_name, String, 50]], { :metadata => :none, :item_format => :array })</tt>
-#
-# <tt>puts result[:data]</tt>
+# Consult the README. 
 # 
-# <tt>sysdate_sql = 'select sysdate from dual'</tt>
+# == Additional information
 #
-# <tt>puts db.query(sysdate_sql, nil, { :metadata => :none, :amount => :single_value})[:data]</tt>
-#
-# <tt>puts db.with_connection { |c| (c.exec(sysdate_sql).fetch)[0] }</tt>
-#
-#--
 # ActiveRecord and ConnectionPool documentation:
+#
 # * http://ar.rubyonrails.org/
 # * http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/ConnectionPool.html
 
@@ -123,58 +77,54 @@ class OracleRaw
 		ActiveRecord::Base.connection_pool.with_connection { |conn| yield conn.raw_connection }
 	end
 
-	# Depending whether the +:metadata+ option is +:all+ or +:none+, returns either of the following:
+	# Depending whether the +:metadata+ option is +:none+ or +:all+, returns either a plain result set or a map of the following kind:
 	#
 	# <tt>{ :count => rowcount, :columns => colnames, :data => data, :date => date, :duration => duration }</tt>
-	#
-	# <tt>{ :data => data }</tt>
 	# 
-	# If an exception occurs, returns <tt>{ :exception => e }</tt>.
+	# Exception are propagated to the caller.
 
 	def query(sqlquery, parameters = [], options = {})
 
-		begin
-			with_connection { |conn|
+		with_connection { |conn|
 
-				starttime = Time.new; data = []
+			starttime = Time.new; data = []
 
-				cursor = conn.parse(sqlquery)
-				cursor.bind_parameters(parameters) if parameters
-				cursor.exec_with_prefetch(5000)
+			cursor = conn.parse(sqlquery)
+			cursor.bind_parameters(parameters) if parameters
+			cursor.exec_with_prefetch(5000)
 
-				case options[:item_format] || @global_options[:item_format]
+			case options[:item_format] || @global_options[:item_format]
 
-					when :hash then
+				when :hash then
 
-						case options[:amount] || @global_options[:amount]
+					case options[:amount] || @global_options[:amount]
 
-							when :first_row then data = cursor.fetch_hash()
-							else while r = cursor.fetch_hash(); data << r;  end 
-						end
-					else 
-						case options[:amount] || @global_options[:amount]
+						when :first_row then data = cursor.fetch_hash()
+						else while r = cursor.fetch_hash(); data << r;  end 
+					end
+				else 
+					case options[:amount] || @global_options[:amount]
 
-							when :single_value then temp = cursor.fetch(); data = (temp ? temp[0] : nil)
-							when :first_row then data = cursor.fetch()
-							else while r = cursor.fetch(); data << r; end
-						end
-				end
+						when :single_value then temp = cursor.fetch(); data = (temp ? temp[0] : nil)
+						when :first_row then data = cursor.fetch()
+						else while r = cursor.fetch(); data << r; end
+					end
+			end
 
-				case options[:metadata] || @global_options[:metadata]
+			case options[:metadata] || @global_options[:metadata]
 
-					when :all then
-						colnames = cursor.get_col_names.each do |n| n.downcase! end 
-						rowcount = cursor.row_count
-						cursor.close
-						{:count => rowcount, :columns => colnames, :data => data, :date => starttime, :duration => Time.new - starttime}
-					else	
-						cursor.close
-						{:data => data}
-				end
-			}
-		rescue => e
-			{:exception => e}
-		end
+				when :all then
+					colnames = cursor.get_col_names.each do |n| n.downcase! end 
+					rowcount = cursor.row_count
+					cursor.close
+					{:count => rowcount, :columns => colnames, :data => data, :date => starttime, :duration => Time.new - starttime}
+				when :plain then
+					cursor.close
+					data
+				else	
+					cursor.close
+					{:data => data}
+			end
+		}
 	end
 end
-

data/test/test_oracle_raw.rb

@@ -36,7 +36,8 @@ class TestOracleRaw < Test::Unit::TestCase
 			c.exec("insert into oracle_raw_test (name, age) values ('Lucia', 25)")
 
 			cursor = c.parse('insert into oracle_raw_test (name, age) values (:name, :age)')
-			cursor.bind_parameters([[:name, 'Kinnie', String], [:age, 30, Integer]])
+			cursor.bind_param(:name, 'Kinnie', String)
+			cursor.bind_param(:age, 30, Integer)
 			cursor.exec
 			cursor.close
 
@@ -67,7 +68,7 @@ class TestOracleRaw < Test::Unit::TestCase
 		start = Time.new; num_calls = 1000
 		num_calls.times do 
 			result = db.query('select 1 from dual') 
-puts result[:exception].backtrace if result[:exception]
+			#puts result[:exception].backtrace if result[:exception]
 			assert_equal(result[:exception], nil)
 		end
 		puts "\nSpeed test: pooled: #{num_calls/(Time.new - start)} calls/second.\n"
@@ -106,5 +107,29 @@ puts result[:exception].backtrace if result[:exception]
 		assert(/ORA-00942/ =~ result[:exception].message)
 		db.close
 	end
-end
 
+	def test_bind
+		db = connect
+		id = 10
+		lastname = 'Kruskal-Wallis'
+		q = "select * from students where id = :id"
+
+                db.with_connection { |c|
+
+			cursor = c.parse(q)
+
+			# these should work and do work
+			cursor.bind_param(':id', id, Fixnum)                   
+
+			# these should not work and do not work
+			cursor.bind_param(':id', lastname, Fixnum)         # TypeError; ok
+			assert(/ORA-00942/ =~ result[:exception].message)
+			cursor.bind_param(':lastname', lastname, String)   # OCIError; ok
+			assert(/ORA-00942/ =~ result[:exception].message)
+
+			cursor.close
+		}
+		db.close # clear connection pool
+		true
+	end
+end

metadata

@@ -1,131 +1,142 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: oracle_raw
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.1.8
   prerelease: 
-  version: 0.1.6
 platform: ruby
-authors: 
+authors:
 - opiskelijarekisteri-devel
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-11-27 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: ruby-oci8
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 2.0.6
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.2
   type: :runtime
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+- !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 3.1.1
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.8
   type: :runtime
   prerelease: false
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.8
+- !ruby/object:Gem::Dependency
   name: activerecord-oracle_enhanced-adapter
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 1.4.0
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.1
   type: :runtime
   prerelease: false
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.1
+- !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 1.0.0
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.1.5
   type: :development
   prerelease: false
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.1.5
+- !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 1.6.4
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.8.4
   type: :development
   prerelease: false
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: rcov
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-  type: :development
-  prerelease: false
-  version_requirements: *id006
-description: This is a Ruby library for interfacing with an Oracle Database using pooled OCI8 raw connections (http://ruby-oci8.rubyforge.org/en/). Connection pooling is achieved by utilizing ActiveRecord Oracle Enhanced adapter (https://github.com/rsim/oracle-enhanced).
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+description: This is a Ruby library for interfacing with an Oracle Database using
+  pooled OCI8 raw connections (http://ruby-oci8.rubyforge.org/en/). Connection pooling
+  is achieved by utilizing ActiveRecord Oracle Enhanced adapter (https://github.com/rsim/oracle-enhanced).
 email: opiskelijarekisteri-devel@helsinki.fi
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - LICENSE.txt
-- README.rdoc
-files: 
+- README.md
+files:
 - .document
 - Gemfile
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - lib/oracle_raw.rb
 - test/helper.rb
 - test/test_oracle_raw.rb
 homepage: http://github.com/opiskelijarekisteri-devel/oracle_raw
-licenses: 
-- GPLv3
+licenses:
+- LGPLv3
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 4539384040906102851
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 2071649133811204594
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Ruby library for interfacing with an Oracle Database using pooled OCI8 raw connections.
+summary: Ruby library for interfacing with an Oracle Database using pooled OCI8 raw
+  connections.
 test_files: []
-