table_differ 0.6.10 → 0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 664380ceed99a8c963e10e4cbca8ef22aaa4ca0e
-  data.tar.gz: 4001965b54f65033d46cd68aed094eb8b5f85137
+  metadata.gz: 602a0b1ed4708321a8bee1cfc177a4c194df5208
+  data.tar.gz: 8ad8aa0badd13e031ce7a350bcc05fae945636b1
 SHA512:
-  metadata.gz: d6f709d20c230f814d77499eb10684553a36b4d0605254caefca757bd9337313686a833f30663a2c52ebf987974fbb1b651ecdccc815c3e03a12c07e63b33577
-  data.tar.gz: 9743c8e8118bda9387dabab7dd533618f1aaee33a5d604d0d7ce97c52c8c19aa74c4a7dba43914bf1473f4daa615b04344ef2afb6faf27c692b2116e7a69c43f
+  metadata.gz: 87f01c2b832339b5fe798dbc15d5ac906632c77abdcd34cb6a4181dc69f1dc9c684175ee881a289445e68277c306f0723f99f3785e897a7296dcffd38d7aa3c8
+  data.tar.gz: d86fd94c247b7e7977ca003bb830cfb87dd8e167f9ab67cb3188f09260daa2c4cf2c51c04ade1cafbc90a7f94287ef87cf35364a48bc4fe62124057b62979e11

data/Gemfile

@@ -1,2 +1,8 @@
 source 'https://rubygems.org'
 gemspec
+
+group :development do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-bundler'
+end

data/Guardfile

@@ -3,7 +3,7 @@ guard :bundler do
   watch(/^.+\.gemspec/)
 end
 
-guard :rspec do
+guard :rspec, cmd: 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{.*\.rb})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }

data/README.md

@@ -1,6 +1,6 @@
 # Table Differ
 
-Take snapshots of database tables and compute the differences between two snapshots.
+Snapshot database tables, restore them, and compute the differences between two snapshots.
 
 [![Build Status](https://api.travis-ci.org/bronson/table_differ.png?branch=master)](http://travis-ci.org/bronson/table_differ)
 [![Gem Version](https://badge.fury.io/rb/table_differ.svg)](http://badge.fury.io/rb/table_differ)
@@ -15,15 +15,21 @@ gem 'table_differ'
 
 ## Synopsis
 
+To follow this, replace `Attachment` with any model from your own application.
+Once you restore the snapshot, your database should appear unchanged.
+
 ```ruby
-Attachment.create_snapshot
-  => "attachments_20140626_233336"
-Attachment.first.update_attributes!(name: 'newname')
-added,removed,changed = Attachment.diff_snapshot   # diffs against most recent snapshot
+snapshot = Attachment.create_snapshot
+Attachment.first.update_attributes!(name: 'newname')    # make a change
+#     or run rake db:migrate, Attachment.delete_all, or anything.
+
+# compute the changes
+added,removed,changed = Attachment.diff_snapshot(snapshot)
   => [[], [], [<Attachment 1>]]
-changed.first.original_attributes    # returns original value for each field
-  => {"name" => 'oldname'}
-Attachment.delete_snapshot "attachments_20140626_233336"
+
+Attachment.restore_snapshot(snapshot)
+Attachment.delete_snapshot(snapshot)
+# and we're right back where we started
 ```
 
 ## Usage
@@ -31,52 +37,75 @@ Attachment.delete_snapshot "attachments_20140626_233336"
 Include TableDiffer in models that will be snapshotted:
 
 ```ruby
-class Property  < ActiveRecord::Base
+class Attachment  < ActiveRecord::Base
   include TableDiffer
   ...
 end
 ```
 
-### Snapshot a Table
-
-Any time you want to snapshot a table (say, before a new data import),
-call `create_snapshot`.
+### Create Snapshot
 
 ```ruby
 Property.create_snapshot
 Property.create_snapshot 'import_0012'
 ```
 
-If you don't specify a name then a numeric name based on the current
-date will be used (something like `property_20140606_124722`)
-Whatever naming scheme you use, the names need to sort alphabetically so
-Table Differ can know which one is most recent.
+If you don't specify a name then one will be specified for you.
+Whatever naming scheme you use, the names should sort alphabetically.
+Otherwise some Table Differ functions won't be able to default to the most recent snapshot.
 
-Use the snapshots method to return all the snapshots that exist now:
+### List Snapshots
 
 ```ruby
 Property.snapshots
 => ['property_import_0011', 'property_import_0012']
 ```
 
+### Restore Snapshot
+
+```ruby
+Property.restore_snapshot 'import_0012'
+```
+
+### Delete Snapshots
+
+```ruby
+Property.delete_snapshot  'import_0012'
+```
+
+Or multiple snapshots:
+
+```ruby
+Property.delete_snapshots  ['import_01', 'import_02']
+Property.delete_snapshots  # deletes all Property snapshots
+
+# more complex: delete all snapshots more than one week old
+week_old_name = Property.snapshot_name(1.week.ago)
+Property.delete_snapshots { |name| name < week_old_name }
+```
+
 ### Compute Differences
 
 Now, to retrieve a list of the differences, call diff_snapshot:
 
 ```ruby
-added,removed,changed = Property.diff_snapshot
+added,removed,changed = Attachment.diff_snapshot      # compute the change
+  => [[], [], [<Attachment 1>]]
+changed.first.original_attributes    # returns original value for each field
+  => {"name" => 'oldname'}
 ```
 
 This computes the difference between the current table and the most recent
 snapshot (determined alphabetically).  Each value is an array of ActiveRecord
 objects.  `added` contains the records that have been added since the snapshot
 was taken, `removed` contains the records that were removed, and `changed` contains
-records where, of course, one or more of their columns have changed.  Tablediffer
-doesn't follow foreign keys so, if you want that, you'll need to do it manually.
+records where, of course, one or more of their columns have changed.  Table Differ
+doesn't follow foreign keys for that would be madness.  If you want to discover
+changes in related tables, you'll need to snapshot and diff them one by one.
 
 Records in `added` and `changed` are regular ActiveRecord objects -- you can modify
 their attributes and save them.  Records in `removed`, however, aren't backed by
-a database object and should be treated read-only.
+a database object (obviously) and should be treated read-only.
 
 Changed records include a hash of the original attributes before the change was
 made.  For example, if you changed the name column from 'Nexus' to 'Nexii':
@@ -101,25 +130,24 @@ Property.diff_snapshot ignore: %w[ id created_at updated_at ]
 ```
 
 Note that if you ignore the primary key, Table Differ can no longer compute which
-columns have changed.  Changed records will appear as a remove followed by an add,
-so you can ignore the empty third array.
+columns have changed.  This is no problem, but changed records will appear as a
+remove followed by an add.  The changed array will always be empty.
 
 ```ruby
 added,removed = Attachment.diff_snapshot(ignore: 'id')
 ```
 
-If there are other fields that you can use to uniquely identify the records,
-you can specify them in the unique_by option.  This will ensure that changes
-are returned (not just adds/removes), and the ActiveRecord objects returned are
+If there are other fields that uniquely identify the records,
+you can specify them in the unique_by option.  This will cause changes to
+be computed, and the ActiveRecord objects returned are
 complete with IDs.  This requires one database lookup per returned object,
-however so, if your results sets are huge, this might not be a good idea.
+however so, if your results are large, this might not be a good idea.
 
 ```ruby
 # Normally ingoring the ID prevents diff from being able to compute the changed records.
-# If we can tell it that one or more fields can be used to uniquely identify the object,
-# then it can compute the changed records and return full ActiveRecord objects.
+# If we can use one or more fields to uniquely identify the object,
+# then changesets can be computed and full ActiveRecord objects will be returned.
 added,removed,changed = Contact.diff_snapshot(ignore: 'id', unique_by: [:property_id, :contact_id])
-
 ```
 
 Also, if you ignore the ID, you won't be able to update or save any models directly.
@@ -131,23 +159,8 @@ normally and still knows its ID.
 You can name the tables you want to diff explicitly:
 
 ```ruby
-a,r,c = Property.diff_snapshot(old: 'import_0012')   # changes between the named snapshot and now
-a,r,c = Property.diff_snapshot('cc', 'cd')           # difference between the two snapshots named cc and cd
-```
-
-### Delete Snapshots
-
-delete_snapshot gets rid of unwanted snapshots.
-Pass an array of names or a proc to specify which snapshots should be deleted,
-or `:all`.
-
-```ruby
-Property.delete_snapshot  'import_0012'
-Property.delete_snapshots :all
-
-week_old_name = Property.snapshot_name(1.week.ago)
-old_snapshots = Property.snapshots.select { |name| name < week_old_name }
-Property.delete_snapshots(old_snapshots)
+add,del,ch = Property.diff_snapshot(old: 'import_0012')   # differences between the named snapshot and the table
+add,del,ch = Property.diff_snapshot('cc', 'cd')           # differences between the snapshots named cc and cd
 ```
 
 ## Internals
@@ -156,8 +169,16 @@ Table Differ creates a full copy of the table whenever Snapshot is called.
 If your table is large enough that it would cause problems if it suddenly
 doubled in size, then this is not the gem for you.
 
-Table Differ diffs the tables server-side using only two SELECT queries.
-This should be plenty fast for any normal usage.
+Table Differ creates and restores snapshots with a single CREATE/SELECT statement,
+and it diffs the tables 100% server-side using two SELECTs.  It should be fast
+enough.
+
+It doesn't touch indicies.
+
+
+## Alternatives
+
+* [Stellar](https://github.com/fastmonkeys/stellar) appears to do the same thing, written in Python.
 
 
 ## Contributing

data/TODO

@@ -1,2 +1,3 @@
+TODO: the diff_snapshot(old: s) syntax is weird.
 TODO: try to mark relevant records read-only
 TODO: could CREATE DATABASE ... TEMPLATE work to create snapshots?

data/lib/table_differ.rb

@@ -38,6 +38,14 @@ module TableDiffer
       name
     end
 
+    def restore_snapshot name
+      name = snapshot_name(name)
+      raise "#{name} doesn't exist" unless connection.tables.include?(name)
+
+      delete_all
+      connection.execute("INSERT INTO #{table_name} SELECT * FROM #{name}")
+    end
+
     # deletes the named snapshot
     def delete_snapshot name
       connection.execute("DROP TABLE #{snapshot_name(name)}")
@@ -45,14 +53,15 @@ module TableDiffer
 
     # deletes every snapshot named in the array
     # Model.delete_snapshots(:all) deletes all snapshots
-    def delete_snapshots snaps
-      snaps = self.snapshots if snaps == :all
+    def delete_snapshots snaps=self.snapshots, &block
+      snaps = snaps.select(&block) if block
       snaps.each { |name| delete_snapshot(name) }
     end
 
     def table_differ_remap_objects params, records, table
       model = self
       if table != table_name
+        # create an exact copy of the model, but using a different table
         model = Class.new(self)
         model.table_name = table
       end
@@ -75,7 +84,6 @@ module TableDiffer
       end
     end
 
-    # ignore: %w[ created_at updated_at id ]
     def diff_snapshot options={}
       oldtable = snapshot_name(options[:old]) || snapshots.last
       newtable = snapshot_name(options[:new]) || table_name

data/lib/table_differ/version.rb

@@ -1,3 +1,3 @@
 module TableDiffer
-  VERSION = "0.6.10"
+  VERSION = "0.7"
 end

data/spec/snapshot_spec.rb

@@ -27,6 +27,27 @@ describe TableDiffer do
     expect(Model.snapshots.sort).to eq ['models_aiee', 'models_bee', 'models_cee']
   end
 
+  it "restores a snapshot" do
+    # TODO: test that it doesn't delete any indices
+    Model.create!(name: 'one')
+    first_id = Model.first.id   # ensure the ID doesn't change
+    snapshot = Model.create_snapshot('snapname')
+    Model.create!(name: 'two')
+
+    Model.restore_snapshot(snapshot)
+    expect(Model.pluck(:id, :name).sort).to eq [[first_id, 'one']]
+
+    Model.delete_snapshot(snapshot)
+  end
+
+  it "doesn't destroy the database if the snapshot can't be found" do
+    snapshot = Model.create_snapshot('snapname')
+    expect {
+      Model.restore_snapshot(snapshot+' ')
+    }.to raise_error(/doesn't exist/)
+    Model.delete_snapshot(snapshot)
+  end
+
   it "deletes a named snapshot" do
     Model.create_snapshot('snapname')
     expect(Model.snapshots.size).to eq 1
@@ -34,24 +55,28 @@ describe TableDiffer do
     expect(Model.snapshots.size).to eq 0
   end
 
-  it "deletes a bunch of snapshots" do
-    Model.create_snapshot('21')
-    Model.create_snapshot('22')
-    Model.create_snapshot('33')
-
-    to_delete = Model.snapshots.select do |snapname|
-      # return true for all tables with names divisble by 11
-      name = /(\d+)$/.match(snapname)[1]
-      (name.to_i % 11) == 0
-    end
-    Model.delete_snapshots(to_delete)
-    expect(Model.snapshots.sort).to eq ['models_21']
+  it "deletes all snapshots" do
+    Model.create_snapshot('snapname')
+    expect(Model.snapshots.size).to eq 1
+    Model.delete_snapshots
+    expect(Model.snapshots.size).to eq 0
   end
 
-  it "deletes all snapshots" do
+  it "doesn't delete snapshots if none specified" do
     Model.create_snapshot('snapname')
     expect(Model.snapshots.size).to eq 1
-    Model.delete_snapshots(:all)
+    Model.delete_snapshots []
+    expect(Model.snapshots.size).to eq 1
+    Model.delete_snapshots(Model.snapshots)
     expect(Model.snapshots.size).to eq 0
   end
+
+  it "deletes a block of snapshots" do
+    Model.create_snapshot('21')
+    Model.create_snapshot('22')
+    Model.create_snapshot('33')
+
+    Model.delete_snapshots { |name| name == 'models_22' || name == 'models_33' }
+    expect(Model.snapshots.sort).to eq ['models_21']
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: table_differ
 version: !ruby/object:Gem::Version
-  version: 0.6.10
+  version: '0.7'
 platform: ruby
 authors:
 - Scott Bronson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-03 00:00:00.000000000 Z
+date: 2014-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord