CloneKit!

An ActiveRecord-ish toolkit library for building database record cloning without the business logic and executing cloning operations, especially for multi-tenant applications using ActiveRecord or Mongoid.

Why does cloning require a special toolkit?

When operating a multi-tenant system, copying database records is fraught with perils that can wreak havoc on customer integrity. Failing to remap foreign ids does not usually trigger database integrity errors (especially in MongoDB ) but are even more insidious.

There is likely an alternative business logic required when records are copied and merged. CloneKit can help you assemble that logic.

How do I clone?

Let's pretend you have a account that you want to clone to a new account.

classBlogPostincludeMongoid::Documentfield:account_id,type: BSON::ObjectIdfield:blog_type_id,type: BSON::ObjectIdfield:body,type: Stringend

You can specify the dependency order of cloning, the scope of the operation, and the specific cloning behavior inside a specification:

CloneKit::MongoSpecification.new(BlogPost)do |spec|
spec.dependencies=%w(AccountBlogType)# Helps derive the cloning orderspec.emitter=TenantEmitter.new(BlogPost)# The scope of the operation for this collectionspec.cloner=CloneKit::Cloners::MongoidRulesetCloner.new(# The cloning behaviorBlogPost,rules: [ReTenantRule.new,CloneKit::Rules::Remap.new("BlogPost","Account"=>"account_id","BlogType"=>"blog_type_id")])spec.after_operationdo |operation|
...
endend

Dependencies can also be dynamically defined by using a proc or lambda:

CloneKit::MongoSpecification.new(BlogPost)do |spec|
spec.dependencies=->{env.test? ? %w(Foo) : %w(Bar)}end

Writing an Emitter

By default, CloneKit specifications utilize an empty emitter, making all clones no-ops. Emitters are expected to make db calls using logic defined in the emitter.

Emitter rules

• Emitters must respond to #emit_all and #scope.
• emit_all must return an object that responds to #pluck.

CloneKit::ActiveRecordSpecification.new(BlogPost)do |spec|
...
spec.emitter=ActiveRecordEmitter.new(BlogPost)
...
endclassActiveRecordEmitterdefinitialize(klass)self.klass=klassenddefscope(_args)klass.all# add any scope restrictions hereenddefemit_all(args)# the method that will be used to pluck the record idsscope(args)endprivateattr_accessor:klassend

Custom Cloners

Cloners are the classes that determine what model class is cloned and how. There are several built-in cloners that can be extended. See lib/clone_kit/cloners for a list.

Custom cloners will need to define:

1. The Mongoid or ActiveRecord model class, which will be used to make db calls
2. Rules, which are executed in the defined order and determine how the ids are mapped from source to destination records. See more in next section.
3. Merge fields, which allow two records to be merged into one provided all listed fields are equal.

Optionally, if you are merging records you will probably want to override the compare and merge methods with custom logic, though basic logic comes for free.

CloneKit::ActiveRecordSpecification.new(self)do |spec|
...
spec.cloner=BlogPostCloner.new
...
endclassBlogPostCloner < ActiveRecordRulesetClonerOMIT_ATTRIBUTES=[:created_at,:updated_at]definitializesuper(BlogPost,# model classrules: [# rulesCloneKit::Rules::Except.new(*OMIT_ATTRIBUTES),CloneKit::Rules::Remap.new(BlogPost)],merge_fields: [])# merge fieldsenddefcompare(first,second)# returns a boolean to determine if two records are mergeableenddefmerge(records)# returns a single record that is the merged result# of all argument `records`,# e.g. [{ a: 1, b: 1 }, { a: 2, b: 1}] => { a: 2, b: 1 }endend

Writing a Cloner rule

Rules respond to a single #fix method. #fix mutates a record's attributes, allowing the same attributes object to be passed down a pipeline of rules.

# given the following rulesrules: [CloneKit::Rules::Except.new(:title),CloneKit::Rules::Remap.new(BlogPost,"Author"=>"author_id")]# a blog post's attributes will be changed{title: "Title",content: "Content",author_id: 5}{content: "Content",author_id: 5}# CloneKit::Rules::Except{content: "Content",author_id: 6}# CloneKit::Rules::Remap

See lib/clone_kit/rules for examples with documentation.

Installation

Add this line to your application's Gemfile:

gem'clone_kit'

And then execute:

$ bundle

Or install it yourself as:

$ gem install clone_kit

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kapost/clone_kit.