Yet another changes tracker/auditor for Rails' ActiveRecord.
- Tracks associations. Yes, it tracks associations!
- Model changes are stored as an append-only log of immutalbe diffs (deltas).
- Each delta contains information about an action (add, remove, change), what was changed, who changed it, and a serialized json payload of the changed value.
- This library is designed for easy output/streaming to whatever destination you want.
- Adapters. As this library is in early alpha, only ActiveRecord adapter is available. HTTP, ActiveJob, Mongo, Redis and Kafka (maybe) adapters will be available later.
THIS LIBRARY IS IN EARLY DEVELOPMENT STAGE. There WILL be breaking changes until 0.1 release.
Add delta
to your Gemfile
gem 'delta', github: 'konukhov/delta'
Then generate a migration (or, if you're non-Rails user, copy it manually from lib/generators).
bundle install
bundle exec rails g delta:create_talbe
Docs, examples and roadmap will be available later.
See couple of raw examples and use cases below.
class Order < ActiveRecord::Base
has_many :line_items
has_many :items, through: :line_items
track_deltas :address, :promo_code, :items
end
order = Order.create(address: "Some address", items: [item1])
order.update address1: "New address", promo_code: "promo"
order.items << item2
After this order.deltas
will be looking like this:
[
{
id: 1,
user: <User:...>, # if updated from controller with current_user
model: <Order:...>,
object: { # There's always an array
[{
name: "address",
action: "C", # "C" == change, "A" == add, "R" == remove
timestamp: 1441335511,
object: "New address"
},
{
name: "promo_code",
action: "C",
timestamp: 1441335511,
object: "promo"
}]
}
},
{
id: 2,
user: <User:...>,
model: <Order:...>,
object: {
[{
name: "items",
action: "A"
timestamp: 1441335543,
object: { "id" => 1 } # associations are serialized like this by default
}]
}
}
]
For more complicated use cases use track_deltas_on
. Those use cases include:
- Including more fields in serialized associations.
- Tracking associations changes.
- You want to track only added associations.
class Company < ActiveRecord::Base
has_many :employments
has_many :employees, through: :employments
belongs_to :user
track_deltas_on :name
track_deltas_on :employments, serialize: [:position, :salary],
notify: true, # Track association changes.
# Could also be an association
# name, like `notify: :company`.
only: [] # `only` option means which
# actions (add, remove for
# associations) to track.
track_deltas_on :employees, serialize: [:first_name, :last_name]
end
company = Company.create(name: "My company")
company.employees << employee # Created delta with serialized employee.
Employment
.where(company: company, employee: employee)
.first
.update(position: "Engineer") # Created delta for company with serialized employemnt.
Caveats:
- For now Delta tracks only model updates.
- Tracks association changes only if associaion has_one or belongs_to model.
- Be careful with
has_many :through
associations since there're usually 2 objects being added - an associated model and a through model. Do not track both.
Bug reports and pull requests are welcome on GitHub at https://github.com/konukhov/delta. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
- https://github.com/airblade/paper_trail
- https://github.com/collectiveidea/audited
The gem is available as open source under the terms of the MIT License.