postgresql_cursor 0.2.0 → 0.3.0

data/README.rdoc

@@ -9,29 +9,39 @@ For web pages, an application would not want to process a large amount of data,
 Pagination scheme to present it to the users. Background processes sometimes need to generate a large 
 amount of data, and the ActiveRecord approach to load all data into memory is not the best fit here.
 
-Previous solutions employ pagination to fetch each block, 
-then re-running the query for the next "page". This gem avoids re-executing
-the query by using the PostgreSQL cursors. 
+Previous solutions employ pagination to fetch each block, then re-running the query for the next "page". 
+This gem avoids re-executing the query by using PostgreSQL's cursor feature.
 
-Like the #find_by_sql method, #find_cursor returns each row as a hash instead of an instantiated 
-model class. The rationale for this is performance, though an option to return instances is available. 
-Julian's benchmarks showed returning instances was a factor of 4 slower than return the hash.
+The ActiveRecord methods for the cursor return instances of the model class by default, however you 
+can pass in a block to override this strategy. For instance, returning Hashes instead of AR instances
+is faster. Julian's benchmarks showed returning instances was a factor of 4 slower than returning a hash.
+
+NOTE: This gem is intended to replace the 'postgresql-cursor' (with hyphen, not underscore) library. 
+I also plan on supporing ActiveRecord 3.x in the near future.
 
 ==Installation
  [sudo] gem install postgresql_cursor
 
-This does not require Rails to work, just ActiveRecord < 3.0.0 and the 'pg' gem.
+This does not require Rails to work, just ActiveRecord < 3.0.0 and the 'pg' gem. Rails 3 support is forthcoming.
+
+You can then configure your Rails application by adding to the config/environment.rb file
+  config.gem 'postgresql_cursor'
+or require the gem on your non-rails application
+  require 'rubygems'
+  require 'postgresql_cursor'
 
 ==Usage
 
-A Rails/ActiveRecord plugin for the PostgreSQL database adapter that will add
-cursors to a find_cursor() method to process very large result sets. 
+This library is intended to be used via ActiveRecord. It provides two methods on ActiveRecord::Base
+like the find() method, that will return cursor objects instead of an array of model instances. 
+
+Calling each() the returned cursor will yield a record to the block for each row. It handles a transaction
+block, open, buffering, and closing the cursor. In this way, it operates like an Array object. Note that
+it does not implement Enumerable, so no other methods are available.
 
-the *find_cursor* method uses cursors to pull in one data block (of x records) at a time, and 
-return each record as a Hash to a procedural block. When each data block is 
-exhausted, it will fetch the next one.
+* *find_with_cursor*( <i>find options</i>, :cursor=>{<i>cursor options</i>}, &block) returns a cursor for the data matching the find options. It takes an optional block accepting a column=>value hash which returns the object desired via each or next, instead of an instance of the model.
 
-*find_by_sql_with_cursor* takes a custom SQL statement and returns each row.
+* *find_by_sql_with_cursor*(<i>select statement</i>, <i>cursor options</i>, &block) takes a custom SQL statement and returns each row as above.
 
 ==Examples
 
@@ -39,7 +49,7 @@ exhausted, it will fetch the next one.
    puts row.to_json
  end
  
- Account.find_by_sql_with_cursor("select ...", :buffer_size=>1000) do |row|
+ Account.find_by_sql_with_cursor("select ...", :buffer_size=>1000).each do |row|
    row.process
  end
 

data/postgresql_cursor.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{postgresql_cursor}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Allen Fair"]
-  s.date = %q{2010-05-17}
+  s.date = %q{2010-07-29}
   s.description = %q{PostgreSQL Cursor is an extension to the ActiveRecord PostgreSQLAdapter for very large result sets. It provides a cursor open/fetch/close interface to access data without loading all rows into memory, and instead loads the result rows in "chunks" (default of 10_000 rows), buffers them, and returns the rows one at a time.}
   s.email = %q{allen.fair@gmail.com}
   s.extra_rdoc_files = [
@@ -31,7 +31,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/afair/postgresql_cursor}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{ActiveRecord PostgreSQL Adapter extension for using a cursor to return a large result set}
   s.test_files = [
     "test/helper.rb",
@@ -42,15 +42,15 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activerecord>, ["<= 2.3.5"])
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activerecord>, [">= 0"])
       s.add_runtime_dependency(%q<pg>, [">= 0"])
     else
-      s.add_dependency(%q<activerecord>, ["<= 2.3.5"])
+      s.add_dependency(%q<activerecord>, [">= 0"])
       s.add_dependency(%q<pg>, [">= 0"])
     end
   else
-    s.add_dependency(%q<activerecord>, ["<= 2.3.5"])
+    s.add_dependency(%q<activerecord>, [">= 0"])
     s.add_dependency(%q<pg>, [">= 0"])
   end
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: postgresql_cursor
 version: !ruby/object:Gem::Version 
+  hash: 19
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Allen Fair
@@ -14,30 +15,32 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-17 00:00:00 -04:00
+date: 2010-07-29 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activerecord
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
-    - - <=
+    - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
-        - 2
-        - 3
-        - 5
-        version: 2.3.5
+        - 0
+        version: "0"
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: pg
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
         version: "0"
@@ -73,23 +76,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: ActiveRecord PostgreSQL Adapter extension for using a cursor to return a large result set