ActiveSnapshot

Add the gem to your Gemfile:

gem 'active_snapshot'

Then, run the installation generator and migrate your database to create the required snapshots and snapshot_items tables:

rails generate active_snapshot:install
rake db:migrate

Finally, include the module in your ApplicationRecord or specific models to enable snapshotting capabilities.

class ApplicationRecord < ActiveRecord::Base
  include ActiveSnapshot
end

To set up the necessary database schema for ActiveSnapshot, run the generator to create a migration that adds the snapshots and snapshot_items tables. This is a required step for the gem to function, as it relies on these tables to persist snapshot data.

rails generate active_snapshot:install

Dropping a database column will break the restore mechanism for existing snapshots, as the application will be unable to assign data to non-existent columns. ActiveSnapshot attempts to work around this by bypassing attribute assignment for keys that do not correlate to current database columns, but this should be handled carefully in your migration guidelines.

To detect if existing snapshots contain data for dropped columns, you can run this diagnostic script:

SnapshotItem.all.each do |snapshot_item|
  snapshot_item.object.keys.each do |key|
    klass = Class.const_get(snapshot_item.item_type)

    if !klass.column_names.include?(key)
      invalid_data = snapshot_item.object.slice(*klass.column_names)

      raise "invalid data found - #{invalid_data}"
    end
  end
end

You can calculate the differences between two snapshots or between a snapshot and the current state of a record using ActiveSnapshot::Snapshot.diff.

# Diff between two snapshots
from = post.snapshots.first
to = post.snapshots.second
diff = ActiveSnapshot::Snapshot.diff(from, to)

# Diff between a snapshot and the current record
from = post.snapshots.last
diff = ActiveSnapshot::Snapshot.diff(from, post)

# Example output format:
# [
#   {action: :update, item_type: "Post", item_id: 1, changes: {name: ["Old Name", "New Name"]}},
#   {action: :destroy, item_type: "Comment", item_id: 1, changes: {id: [1, nil], content: ["Some Content", nil]}},
#   {action: :create, item_type: "Comment", item_id: 2, changes: {id: [nil, 1], content: [nil, "New Content"]}}
# ]

Reification allows you to view ActiveRecord instances where the local object data matches the snapshotted data, even if the database has changed.

By default, reified records are set to readonly. To modify them, you must explicitly set the readonly attribute to false.

# Fetch reified items (returns [parent_record, children_hash])
# Children are readonly by default
reified_parent, reified_children_hash = snapshot.fetch_reified_items

# To make them writable:
reified_parent, reified_children_hash = snapshot.fetch_reified_items(readonly: false)
# OR
reified_children_hash.first.instance_variable_set("@readonly", false)

Once ActiveSnapshot is included in your model, you can manage snapshots using the following instance methods:

• create_snapshot!(options): Creates a new snapshot. All options are optional. Common options include identifier, user, and metadata.
• restore!: Restores the record and any associated child records defined via has_snapshot_children.
• destroy!: Manually destroys the snapshot and all its child snapshots. Note: Snapshots and snapshot items are NEVER destroyed automatically.

post = Post.first

# Create a snapshot
snapshot = post.create_snapshot!(
  identifier: "snapshot_1",
  user: current_user,
  metadata: { foo: :bar }
)

# Restore the snapshot
snapshot.restore!

# Destroy the snapshot manually
snapshot.destroy!

The storage_method setting determines how snapshot data is persisted. You can explicitly set this value to one of the supported formats. If not configured, the library attempts to detect the appropriate method based on the database schema (defaulting to serialized_json if the object attribute is a text type, otherwise native_json).

Supported values:

• serialized_yaml
• serialized_json
• native_json

Setting an invalid value will raise an ArgumentError.

# Example of setting the storage method
ActiveSnapshot.configure do |config|
  config.storage_method = 'native_json'
end

To retrieve the current configuration object without modification, call ActiveSnapshot.config without a block.

config = ActiveSnapshot.config

The restore! method reverts the associated resource and its children to the state captured in the snapshot. This operation is performed within an ActiveRecord::Base.transaction.

Behavior:

1. Cleanup: It identifies child records that were present in the resource but are not included in the snapshot's snapshot_items. It then removes them using the delete_method defined in the resource's children_to_snapshot mapping (defaults to destroy!).
2. Restoration: It iterates through all snapshot_items and calls restore_item! on each to recreate or update the records to their snapshotted state.

Warning: Snapshots and snapshot items are never destroyed automatically; you must manage their lifecycle manually.

snapshot = ActiveSnapshot::Snapshot.find(id)
snapshot.restore!

If you want to inspect the data captured in a snapshot without actually restoring it to the database, use fetch_reified_items. This method reconstructs the objects in memory.

Parameters:

• readonly: (Boolean, default: true) If true, the returned objects are marked as readonly! to prevent accidental database writes.

Return Value: Returns an array containing two elements: [reified_parent, reified_children_hash].

• reified_parent: The reconstructed instance of the main resource.
• reified_children_hash: A hash where keys are the child_group_name and values are arrays of the reconstructed child objects.

parent, children = snapshot.fetch_reified_items(readonly: true)

# Accessing data:
puts parent.name
puts children[:comments].first.body