Simplified snapshots and restoration for ActiveRecord models and associations with a transparent white-box implementation.
Key Features:
- Create and Restore snapshots of a parent record and any specified child records
- Predictible and explicit behaviour provides much needed clarity to your restore logic
- Snapshots are created upon request only, we do not use any callbacks
- Tiny method footprint so its easy to completely override the logic later
Why This Library:
Model Versioning and Restoration require concious thought, design, and understanding. You should understand your versioning and restoration process completely. This gem's small API and fully understandable design fully supports this.
I do not recommend using paper_trail-association_tracking because it is mostly a blackbox solution which encourages you to set it up and then assume its Just WorkingTM. This makes for major data problems later. Dont fall into this trap. Instead read this gems brief source code completely before use OR copy the code straight into your codebase. Once you know it, then you are free.
gem 'active_snapshot'
Then generate and run the necessary migrations to setup the snapshots
and snapshot_items
tables.
rails generate active_snapshot:install
rake db:migrate
Then add include ActiveSnapshot
to your ApplicationRecord or individual models.
class ApplicationRecord < ActiveRecord::Base
include ActiveSortOrder
end
This defines the following associations on your models:
has_many :snapshots, as: :item, class_name: 'Snapshot'
has_many :snapshot_items, as: :item, class_name: 'SnapshotItem'
It defines an optional extension to your model has_snapshot_children
.
It defines one instance method to your model: create_snapshot!
You now have access to the following methods:
post = Post.first
# Create snapshot grouped by identifier, only :identifier argument is required, all others are optional
snapshot = post.create_snapshot!(
identifier: "snapshot_1", # Required
user: current_user,
metadata: {
foo: :bar
},
)
# Restore snapshot and all its child snapshots
snapshot.restore!
# Destroy snapshot and all its child snapshots
# must be performed manually, snapshots and snapshot items are NEVER destroyed automatically
snapshot.destroy!
class Post < ActiveRecord::Base
include ActiveSnapshot
has_snapshot_children do
### Executed in the context of the instance / self
### In this example, we choose to do a fresh load from the database of the record and all associated records from the database
instance = self.class.includes(:comments, :ip_address).find(id)
### Define the associated records that will be restored
{
comments: instance.comments,
tags: {
records: instance.tags
},
ip_address: {
record: instance.ip_address,
delete_method: ->(item){ item.release! }
}
}
end
end
Now when you run create_snapshot!
the associations will be tracked accordingly
You can view all of the reified snapshot items by calling the following method. Its completely up to you on how to use this data.
reified_items = snapshot.fetch_reified_items
As a safety these records have the @readonly = true
attribute set on them. If you want to perform any write actions on the returned instances you will have to set @readonly = nil
.
writable_reified_items = snapshot.fetch_reified_items.transform_values do |array|
array.map{|x| x.instance_variable_set("@readonly", false); x}
end
A key aspect of this library is its simplicity and small API. For major functionality customizations we encourage you to first delete this gem and then copy this gems code directly into your repository.
I strongly encourage you to read the code for this library to understand how it works within your project so that you are capable of customizing the functionality later.
- SnapshotsConcern
- Defines
snapshots
andsnapshot_items
has_many associations - Defines
create_snapshot!
andhas_snapshot_children
methods
- Defines
- Snapshot
- Contains a unique
identifier
column has_many :item_snapshots
- Contains a unique
- SnapshotItem
- Contains
object
column with yaml encoded model instanceattributes
belongs_to :snapshot
- Contains
Created & Maintained by Weston Ganger - @westonganger