Replace paged_operations_size method with :rows_per_page option

I did not use this approach when developing the plugin because I
was using a splat for paged_update.  However, as Dataset#update
only takes a hash and not a splat, paged_update should do the same,
making it possible to support an options hash.  Currently, only the
:rows_per_page option is supported.

Minor documentation updates while here.

lib/sequel/plugins/paged_operations.rb

@@ -6,7 +6,7 @@ module Plugins
  # +paged_delete+ dataset methods. These behave similarly to
  # the default +update+ and +delete+ dataset methods, except
  # that the update or deletion is done in potentially multiple
- # queries (by default, affected 1000 rows per query).
+ # queries (by default, affecting 1000 rows per query).
  # For a large table, this prevents the change from
  # locking the table for a long period of time.
  #
@@ -19,7 +19,7 @@ module Plugins
  #
  # Examples:
  #
- # Album.where{name <= 'M'}.paged_update(:updated_at=>Sequel::CURRENT_TIMESTAMP)
+ # Album.where{name <= 'M'}.paged_update(updated_at: Sequel::CURRENT_TIMESTAMP)
  # # SELECT id FROM albums WHERE (name <= 'M') ORDER BY id LIMIT 1 OFFSET 1001
  # # UPDATE albums SET updated_at = CURRENT_TIMESTAMP WHERE ((name <= 'M') AND ("id" < 1002))
  # # SELECT id FROM albums WHERE ((name <= 'M') AND (id >= 1002)) ORDER BY id LIMIT 1 OFFSET 1001
@@ -37,20 +37,6 @@ module Plugins
  # # SELECT id FROM albums WHERE (name > 'M') ORDER BY id LIMIT 1 OFFSET 10001
  # # DELETE FROM albums WHERE (name > 'M')
  #
- # To set the number of rows to be updated or deleted per query
- # by +paged_update+ or +paged_delete+, you can use the
- # +paged_operations_size+ dataset method:
- #
- # Album.where{name <= 'M'}.paged_operations_size(3).
- # paged_update(:updated_at=>Sequel::CURRENT_TIMESTAMP)
- # # SELECT id FROM albums WHERE (name <= 'M') ORDER BY id LIMIT 1 OFFSET 4
- # # UPDATE albums SET updated_at = CURRENT_TIMESTAMP WHERE ((name <= 'M') AND ("id" < 5))
- # # SELECT id FROM albums WHERE ((name <= 'M') AND (id >= 5)) ORDER BY id LIMIT 1 OFFSET 4
- # # UPDATE albums SET updated_at = CURRENT_TIMESTAMP WHERE ((name <= 'M') AND ("id" < 9) AND (id >= 5))
- # # ...
- # # SELECT id FROM albums WHERE ((name <= 'M') AND (id >= 12345)) ORDER BY id LIMIT 1 OFFSET 4
- # # UPDATE albums SET updated_at = CURRENT_TIMESTAMP WHERE ((name <= 'M') AND (id >= 12345))
- # 
  # The plugin also adds a +paged_datasets+ method that will yield
  # separate datasets limited in size that in total handle all
  # rows in the receiver:
@@ -64,6 +50,17 @@ module Plugins
  # # Runs: SELECT id FROM albums WHERE ((name <= 'M') AND (id >= 10002)) ORDER BY id LIMIT 1 OFFSET 1001
  # # Prints: SELECT * FROM albums WHERE ((name <= 'M') AND (id >= 10002))
  #
+ # To set the number of rows per page, pass a :rows_per_page option:
+ #
+ # Album.where{name <= 'M'}.paged_update({x: Sequel[:x] + 1}, rows_per_page: 4)
+ # # SELECT id FROM albums WHERE (name <= 'M') ORDER BY id LIMIT 1 OFFSET 4
+ # # UPDATE albums SET x = x + 1 WHERE ((name <= 'M') AND ("id" < 5))
+ # # SELECT id FROM albums WHERE ((name <= 'M') AND (id >= 5)) ORDER BY id LIMIT 1 OFFSET 4
+ # # UPDATE albums SET x = x + 1 WHERE ((name <= 'M') AND ("id" < 9) AND (id >= 5))
+ # # ...
+ # # SELECT id FROM albums WHERE ((name <= 'M') AND (id >= 12345)) ORDER BY id LIMIT 1 OFFSET 4
+ # # UPDATE albums SET x = x + 1 WHERE ((name <= 'M') AND (id >= 12345))
+ # 
  # You should avoid using +paged_update+ or +paged_datasets+
  # with updates that modify the primary key, as such usage is
  # not supported by this plugin.
@@ -72,28 +69,32 @@ module Plugins
  #
  # Usage:
  #
- # # Make all model subclasses support paged update/delete
+ # # Make all model subclasses support paged update/delete/datasets
  # # (called before loading subclasses)
  # Sequel::Model.plugin :paged_operations
  #
- # # Make the Album class support paged update/delete
+ # # Make the Album class support paged update/delete/datasts
  # Album.plugin :paged_operations
  module PagedOperations
  module ClassMethods
- Plugins.def_dataset_methods(self, [:paged_datasets, :paged_delete, :paged_update, :paged_operations_size])
+ Plugins.def_dataset_methods(self, [:paged_datasets, :paged_delete, :paged_update])
  end
 
  module DatasetMethods
  # Yield datasets for subsets of the receiver that are limited
  # to no more than 1000 rows (you can configure the number of
  # rows using paged_operations_size).
- def paged_datasets
+ #
+ # Options:
+ # :rows_per_fetch :: The maximum number of rows in each yielded dataset
+ # (unless concurrent modifications are made to the table).
+ def paged_datasets(opts=OPTS)
  unless defined?(yield)
- return enum_for(:paged_datasets)
+ return enum_for(:paged_datasets, opts)
  end
 
  pk = _paged_operations_pk(:paged_update)
- base_offset_ds = offset_ds = _paged_operations_offset_ds
+ base_offset_ds = offset_ds = _paged_operations_offset_ds(opts)
  first = nil
 
  while last = offset_ds.get(pk)
@@ -113,10 +114,14 @@ def paged_datasets
  # Delete all rows of the dataset using using multiple queries so that
  # no more than 1000 rows are deleted at a time (you can configure the
  # number of rows using paged_operations_size).
- def paged_delete
+ #
+ # Options:
+ # :rows_per_fetch :: The maximum number of rows affected by each DELETE query
+ # (unless concurrent modifications are made to the table).
+ def paged_delete(opts=OPTS)
  pk = _paged_operations_pk(:paged_delete)
  rows_deleted = 0
- offset_ds = _paged_operations_offset_ds
+ offset_ds = _paged_operations_offset_ds(opts)
  while last = offset_ds.get(pk)
  rows_deleted += where(pk < last).delete
  end
@@ -127,24 +132,21 @@ def paged_delete
  # no more than 1000 rows are updated at a time (you can configure the
  # number of rows using paged_operations_size). All arguments are
  # passed to Dataset#update.
- def paged_update(*args)
+ #
+ # Options:
+ # :rows_per_fetch :: The maximum number of rows affected by each UPDATE query
+ # (unless concurrent modifications are made to the table).
+ def paged_update(values, opts=OPTS)
  rows_updated = 0
- paged_datasets do |ds|
- rows_updated += ds.update(*args)
+ paged_datasets(opts) do |ds|
+ rows_updated += ds.update(values)
  end
  rows_updated
  end
 
- # Set the number of rows to update or delete per query when using
- # paged_update or paged_delete.
- def paged_operations_size(rows)
- raise Error, "paged_operations_size rows must be greater than 0" unless rows >= 1
- clone(:paged_operations_rows=>rows)
- end
-
  private
 
- # Run some basic checks before running paged UPDATE or DELETE queries,
+ # Run some basic checks common to paged_{datasets,delete,update}
  # and return the primary key to operate on as a Sequel::Identifier.
  def _paged_operations_pk(meth)
  raise Error, "cannot use #{meth} if dataset has a limit or offset" if @opts[:limit] || @opts[:offset]
@@ -159,11 +161,13 @@ def _paged_operations_pk(meth)
  end
  end
 
- # The dataset that will be used by paged_update and paged_delete
- # to get the upper limit for the next UPDATE or DELETE query.
- def _paged_operations_offset_ds
- offset = @opts[:paged_operations_rows] || 1000
- _force_primary_key_order.offset(offset)
+ # The dataset that will be used by paged_{datasets,delete,update}
+ # to get the upper limit for the next query.
+ def _paged_operations_offset_ds(opts)
+ if rows_per_page = opts[:rows_per_page]
+ raise Error, ":rows_per_page option must be at least 1" unless rows_per_page >= 1
+ end
+ _force_primary_key_order.offset(rows_per_page || 1000)
  end
  end
  end

spec/extensions/paged_operations_spec.rb

@@ -129,9 +129,9 @@
  ]
  end
 
- it "#paged_operations_size should set the page size for paged_update" do
+ it "#paged_delete should support :rows_per_page option" do
  @db.numrows = [4, 4, 2]
- @ds.paged_operations_size(4).paged_delete.must_equal 10
+ @ds.paged_delete(:rows_per_page=>4).must_equal 10
  @db.sqls.must_equal [
  "SELECT id FROM albums ORDER BY id LIMIT 1 OFFSET 4",
  "DELETE FROM albums WHERE (id < 1002)",
@@ -142,9 +142,9 @@
  ]
  end
 
- it "#paged_operations_size should set the page size for paged_delete" do
+ it "#paged_update should support :rows_per_page option" do
  @db.numrows = [4, 4, 2]
- @ds.paged_operations_size(4).paged_update(:x=>1).must_equal 10
+ @ds.paged_update({:x=>1}, :rows_per_page=>4).must_equal 10
  @db.sqls.must_equal [
  "SELECT id FROM albums ORDER BY id LIMIT 1 OFFSET 4",
  "UPDATE albums SET x = 1 WHERE (id < 1002)",
@@ -155,9 +155,9 @@
  ]
  end
 
- it "#paged_operations_size should set the page size for paged_datasets" do
+ it "#paged_datasets should support :rows_per_page option" do
  @db.numrows = [4, 4, 2]
- @ds.paged_operations_size(4).paged_datasets.map(&:sql).must_equal [
+ @ds.paged_datasets(:rows_per_page=>4).map(&:sql).must_equal [
  "SELECT * FROM albums WHERE (id < 1002)",
  "SELECT * FROM albums WHERE ((id < 2002) AND (id >= 1002))",
  "SELECT * FROM albums WHERE (id >= 2002)"
@@ -168,9 +168,11 @@
  "SELECT id FROM albums WHERE (id >= 2002) ORDER BY id LIMIT 1 OFFSET 4",
  ]
  end
- it "should raise error for invalid size passed to paged_operations_size" do
- proc{@ds.paged_operations_size(0)}.must_raise Sequel::Error
- proc{@ds.paged_operations_size(-1)}.must_raise Sequel::Error
+ it "should raise error for invalid :rows_per_page option" do
+ proc{@ds.paged_datasets(:rows_per_page=>0){}}.must_raise Sequel::Error
+ proc{@ds.paged_datasets(:rows_per_page=>-1){}}.must_raise Sequel::Error
+ proc{@ds.paged_delete(:rows_per_page=>0)}.must_raise Sequel::Error
+ proc{@ds.paged_update({:x=>1}, :rows_per_page=>0)}.must_raise Sequel::Error
  end
 
  it "should raise error for dataset with limit" do
@@ -235,17 +237,4 @@
  "SELECT id FROM albums WHERE (id >= 2002) ORDER BY id LIMIT 1 OFFSET 1000",
  ]
  end
-
- it "should offer paged_operations_size class method" do
- @db.numrows = [4, 4, 2]
- @c.paged_operations_size(4).paged_delete.must_equal 10
- @db.sqls.must_equal [
- "SELECT id FROM albums ORDER BY id LIMIT 1 OFFSET 4",
- "DELETE FROM albums WHERE (id < 1002)",
- "SELECT id FROM albums ORDER BY id LIMIT 1 OFFSET 4",
- "DELETE FROM albums WHERE (id < 2002)",
- "SELECT id FROM albums ORDER BY id LIMIT 1 OFFSET 4",
- "DELETE FROM albums"
- ]
- end
 end

spec/integration/plugin_test.rb

@@ -3042,7 +3042,7 @@ def set(k, v, ttl) self[k] = v end
  it "Model#paged_delete should work on unfiltered dataset" do
  @sizes.each do |rows|
  @db.transaction(:rollback=>:always) do
- @model.paged_operations_size(rows).paged_delete.must_equal 100
+ @model.paged_delete(:rows_per_page=>rows).must_equal 100
  @model.count.must_equal 0
  end
  end
@@ -3054,7 +3054,7 @@ def set(k, v, ttl) self[k] = v end
  expected = 100.times.map{|i| [i+1, i+200]}
  @sizes.each do |rows|
  @db.transaction(:rollback=>:always) do
- @model.paged_operations_size(rows).paged_update(:o=>Sequel[:o] + 200).must_equal 100
+ @model.paged_update({:o=>Sequel[:o] + 200}, :rows_per_page=>rows).must_equal 100
  @model.select_order_map([:id, :o]).must_equal expected
  end
  end
@@ -3067,7 +3067,7 @@ def set(k, v, ttl) self[k] = v end
  @sizes.zip(final_counts).each do |rows, expected_fc|
  @db.transaction(:rollback=>:always) do
  counts = []
- @model.paged_operations_size(rows).paged_datasets{|ds| counts << ds.count}
+ @model.paged_datasets(:rows_per_page=>rows){|ds| counts << ds.count}
  counts.pop.must_equal expected_fc
  counts.each{|c| c.must_equal rows}
  end
@@ -3081,7 +3081,7 @@ def set(k, v, ttl) self[k] = v end
  ds = @model.where{id < 50}
  @sizes.each do |rows|
  @db.transaction(:rollback=>:always) do
- ds.paged_operations_size(rows).paged_delete.must_equal 49
+ ds.paged_delete(:rows_per_page=>rows).must_equal 49
  ds.count.must_equal 0
  @model.count.must_equal 51
  end
@@ -3098,7 +3098,7 @@ def set(k, v, ttl) self[k] = v end
  other_expected = 51.times.map{|i| [i+50, i+49]}
  @sizes.each do |rows|
  @db.transaction(:rollback=>:always) do
- ds.paged_operations_size(rows).paged_update(:o=>Sequel[:o] + 200).must_equal 49
+ ds.paged_update({:o=>Sequel[:o] + 200}, :rows_per_page=>rows).must_equal 49
  ds.select_order_map([:id, :o]).must_equal ds_expected
  other.select_order_map([:id, :o]).must_equal other_expected
  end
@@ -3114,7 +3114,7 @@ def set(k, v, ttl) self[k] = v end
  @sizes.zip(final_counts).each do |rows, expected_fc|
  @db.transaction(:rollback=>:always) do
  counts = []
- ds.paged_operations_size(rows).paged_datasets{|ds| counts << ds.count}
+ ds.paged_datasets(:rows_per_page=>rows){|ds| counts << ds.count}
  counts.pop.must_equal expected_fc
  counts.each{|c| c.must_equal rows}
  end