teaminsight-legacy / undestroy

Move AR records to alternate table on destroy and allow restoring.

Undestroy

Provides automatic archiving of ActiveRecord models before the object is destroyed. It is designed to be database agnostic and easy to extend with custom functionality. Migrations will be run in parallel on the archive table when run on the original table. Additional archive schema can be appended to the archive table for storing tracking data (default: deleted_at).

Installation

Add this line to your application's Gemfile:

gem 'undestroy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install undestroy

You can also tell Undestroy to not extend ActiveRecord when required by using this line in your Gemfile instead:

gem 'undestroy', :require => 'undestroy/without_binding'

If you do this you must call Undestroy::Binding::ActiveRecord.add(MyARSubclass) where MYARSubclass is the class you want Undestroy to extend instead.

Usage

To activate Undestroy on a model, simply call the undestroy method on the class like so:

class Person < ActiveRecord::Base
  undestroy
end

This method can also accept an options hash or block to further customize Undestroy to your needs. Here are some of the common options:

• :table_name: use this table for archiving (Defaults to the source class's table_name prefixed with the :prefix option).
• :prefix: use this prefix for table names -- if :table_name is set this option does nothing (default: "archive_")
• :abstract_class: use this as the base class for the target_class specify an alternate for custom extensions (defaults to ActiveRecord::Base)
• :migrate: Determines whether Undestroy will handle automatic migrations (default: true)
• :indexes: When :migrate is true should indexes be migrated as well? (default: false)
• add_field(name, type, value=nil, &block): method on the Config object that configures a new field for the archive table. The return value of the block or value of value is used as the value of the field. The block will be passed the instance of the object to be archived as an argument.

You can also use a block to handle the configuration:

class Post < ActiveRecord::Base
  undestroy do |config|
    config.prefix = "old_"
    config.add_field :deleted_by_id, :integer do |instance|
      User.current.id if User.current
    end
  end
end

Advanced Options:

• :fields: Specify a hash of Field objects describing additional fields you would like to include on the archive table. The preferred method of specificying fields is through the add_field method with the block configuration method. (defaults to deleted_at timestamp).
• :model_paths: Array of paths where Undestroy models live. This is used to autoload models before migrations are run (default: Rails.root.join('app', 'models')).
• :source_class: the AR model of the originating data. Set automatically to class undestroy method is called on.
• :target_class: use this AR model for archiving. Set automatically to dynamically generated class based on archive_* options.
• internals: internal classes to use for archival process. Possible keys are :archive, :transfer and :restore. Defaults to corresponding internal classes. Customize to your heart's content.

person = Person.create(:name => "Billy Mcgeeferson")
# Creates a new person record in people table
person.destroy
# => Inserts record in archive_people table
# => Deletes record from people table
People.restore(person.id)
People.archived.where(:name => "Billy Mcgeeferson").restore_all
# => Two ways to restore the record back to the people table
People.archived.find(person.id).restore_copy
# => Restores the record, but doesn't remove the archived record
People.find(person.id).destroy!
# => Destroys the record without archiving

Configuring

You can specify custom global configurations for Undestroy through a configuration block in your application initializer:

Undestroy::Config.configure do |config|
  config.abstract_class = ArchiveModelBase
  config.add_field :deleted_by_id, :datetime do |instance|
    User.current.id if User.current
  end
end

Options set in this block will be the default for all models with undestroy activated. They can be overriden with options passed to the undestroy method

Architecture

Checkout the ARCH.md file for docs on how the gem is setup internally, or just read the code. My goal was to make it easy to understand and extend.

Enjoy!

Acknowledgements

• acts_as_archive author Winton Welsh for inspiration

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

undestroy's Issues

Custom fields on model configuration

When I configure a model with an extra field, like the deleted_by_id example in the documentation, it doesn't add the column when the migrations are run. Oddly enough, when I configure it globally it works as expected.

Check before transferring row to archive table

@tpett @kellyredding Can we get a check for an existing row before a new row is created and saved? I'm getting:

PG::Error: ERROR:  duplicate key value violates unique constraint "archive_artwork_locations_pkey"
DETAIL:  Key (id)=(10) already exists.

in a valid case. We are removing artworks, which removes it's associated models, one of them being artwork_locations. The problem is another model is removing artwork_locations in the same transaction and has already done so. Thus, undestroy tries to insert the same row into the archive table twice. Both of these cases need to happen as they are so I don't think there is a good workaround for this. Also, this is more inline with AR's normal behavior; calling destroy on the same model multiple times doesn't throw any errors.

Something like:

instance = Model.where(:id => from[:id]).first
instance ||= Model.new(from)
instance.save!

is what I'm thinking.