Track changes to your models, for auditing or versioning. See how a model looked at any stage in its lifecycle, revert it to any version, or restore it after it has been destroyed.
- 1. Introduction
- 2. Limiting What is Versioned, and When
- 3. Working With Versions
- 4. Saving More Information About Versions
- 5. ActiveRecord
- 6. Extensibility
- 7. Testing
- 8. Sinatra
paper_trail | branch | tags | ruby | activerecord |
---|---|---|---|---|
unreleased | master | >= 2.1.0 | >= 4.0, < 6 | |
7 | 7-stable | v7.x | >= 2.1.0 | >= 4.0, < 6 |
6 | 6-stable | v6.x | >= 1.9.3 | >= 4.0, < 6 |
5 | 5-stable | v5.x | >= 1.9.3 | >= 3.0, < 5.1 |
4 | 4-stable | v4.x | >= 1.8.7 | >= 3.0, < 5.1 |
3 | 3.0-stable | v3.x | >= 1.8.7 | >= 3.0, < 5 |
2 | 2.7-stable | v2.x | >= 1.8.7 | >= 3.0, < 4 |
1 | rails2 | v1.x | >= 1.8.7 | >= 2.3, < 3 |
-
Add PaperTrail to your
Gemfile
.gem 'paper_trail'
-
Add a
versions
table to your database and an initializer file for configuration:bundle exec rails generate paper_trail:install bundle exec rake db:migrate
If using rails_admin, you must enable the experimental Associations feature. For more information on this generator, see section 5.c. Generators.
-
Add
has_paper_trail
to the models you want to track.class Widget < ActiveRecord::Base has_paper_trail end
-
If your controllers have a
current_user
method, you can easily track who is responsible for changes by adding a controller callback.class ApplicationController before_action :set_paper_trail_whodunnit end
Your models now have a versions
method which returns the "paper trail" of
changes to your model.
widget = Widget.find 42
widget.versions
# [<PaperTrail::Version>, <PaperTrail::Version>, ...]
Once you have a version, you can find out what happened:
v = widget.versions.last
v.event # 'update', 'create', or 'destroy'
v.created_at # When the `event` occurred
v.whodunnit # If the update was via a controller and the
# controller has a current_user method, returns the
# id of the current user as a string.
widget = v.reify # The widget as it was before the update
# (nil for a create event)
PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version. This is useful when you start keeping a paper trail for models that already have records in the database.
widget = Widget.find 153
widget.name # 'Doobly'
# Add has_paper_trail to Widget model.
widget.versions # []
widget.update_attributes :name => 'Wotsit'
widget.versions.last.reify.name # 'Doobly'
widget.versions.last.event # 'update'
This also means that PaperTrail does not waste space storing a version of the
object as it currently stands. The versions
method gives you previous
versions; to get the current one just call a finder on your Widget
model as
usual.
Here's a helpful table showing what PaperTrail stores:
Event | create | update | destroy |
---|---|---|---|
Model Before | nil | widget | widget |
Model After | widget | widget | nil |
PaperTrail stores the values in the Model Before column. Most other auditing/versioning plugins store the After column.
When you declare has_paper_trail
in your model, you get these methods:
class Widget < ActiveRecord::Base
has_paper_trail
end
# Returns this widget's versions. You can customise the name of the
# association, but overriding this method is not supported.
widget.versions
# Return the version this widget was reified from, or nil if it is live.
# You can customise the name of the method.
widget.version
# Returns true if this widget is the current, live one; or false if it is from
# a previous version.
widget.paper_trail.live?
# Returns who put the widget into its current state.
widget.paper_trail.originator
# Returns the widget (not a version) as it looked at the given timestamp.
widget.paper_trail.version_at(timestamp)
# Returns the widget (not a version) as it was most recently.
widget.paper_trail.previous_version
# Returns the widget (not a version) as it became next.
widget.paper_trail.next_version
# Generates a version for a `touch` event (`widget.touch` does NOT generate a
# version)
widget.paper_trail.touch_with_version
# Turn PaperTrail off for all widgets.
Widget.paper_trail.disable
# Turn PaperTrail on for all widgets.
Widget.paper_trail.enable
# Is PaperTrail enabled for Widget, the class?
Widget.paper_trail.enabled?
# Is PaperTrail enabled for widget, the instance?
widget.paper_trail.enabled_for_model?
And a PaperTrail::Version
instance (which is just an ordinary ActiveRecord
instance, with all the usual methods) adds these methods:
# Returns the item restored from this version.
version.reify(options = {})
# Return a new item from this version
version.reify(dup: true)
# Returns who put the item into the state stored in this version.
version.paper_trail_originator
# Returns who changed the item from the state it had in this version.
version.terminator
version.whodunnit
version.version_author
# Returns the next version.
version.next
# Returns the previous version.
version.previous
# Returns the index of this version in all the versions.
version.index
# Returns the event that caused this version (create|update|destroy).
version.event
# Query the `versions.object` column (or `object_changes` column), by
# attributes, using the SQL LIKE operator. Known issue: inconsistent results for
# numeric values due to limitations of SQL wildcard matchers against the
# serialized objects.
PaperTrail::Version.where_object(attr1: val1, attr2: val2)
PaperTrail::Version.where_object_changes(attr1: val1)
In your controllers you can override these methods:
# Returns the user who is responsible for any changes that occur.
# Defaults to current_user.
user_for_paper_trail
# Returns any information about the controller or request that you want
# PaperTrail to store alongside any changes that occur.
info_for_paper_trail
Many aspects of PaperTrail are configurable for individual models; typically
this is achieved by passing options to the has_paper_trail
method within
a given model.
Some aspects of PaperTrail are configured globally for all models. These
settings are assigned directly on the PaperTrail.config
object.
A common place to put these settings is in a Rails initializer file
such as config/initializers/paper_trail.rb
or in an environment-specific
configuration file such as config/environments/test.rb
.
You can choose which events to track with the on
option. For example, to
ignore create
events:
class Article < ActiveRecord::Base
has_paper_trail :on => [:update, :destroy]
end
has_paper_trail
installs callbacks for these lifecycle events. If there are
other callbacks in your model, their order relative to those installed by
PaperTrail may matter, so be aware of any potential interactions.
You may also have the PaperTrail::Version
model save a custom string in its
event
field instead of the typical create
, update
, destroy
. PaperTrail
supplies a custom accessor method called paper_trail_event
, which it will
attempt to use to fill the event
field before falling back on one of the
default events.
a = Article.create
a.versions.size # 1
a.versions.last.event # 'create'
a.paper_trail_event = 'update title'
a.update_attributes :title => 'My Title'
a.versions.size # 2
a.versions.last.event # 'update title'
a.paper_trail_event = nil
a.update_attributes :title => "Alternate"
a.versions.size # 3
a.versions.last.event # 'update'
The has_paper_trail
method installs AR callbacks. If you need to control
their order, use the paper_trail_on_*
methods.
class Article < ActiveRecord::Base
# Include PaperTrail, but do not add any callbacks yet. Passing the
# empty array to `:on` omits callbacks.
has_paper_trail :on => []
# Add callbacks in the order you need.
paper_trail.on_destroy # add destroy callback
paper_trail.on_update # etc.
paper_trail.on_create
end
The paper_trail.on_destroy
method can be further configured to happen
:before
or :after
the destroy event. In PaperTrail 4, the default is
:after
. In PaperTrail 5, the default will be :before
, to support
ActiveRecord 5. (see paper-trail-gem#683)
You can choose the conditions when to add new versions with the if
and
unless
options. For example, to save versions only for US non-draft
translations:
class Translation < ActiveRecord::Base
has_paper_trail :if => Proc.new { |t| t.language_code == 'US' },
:unless => Proc.new { |t| t.type == 'DRAFT' }
end
Starting with PaperTrail 4.0, versions are saved during an after-callback. If you decide whether to save a new version based on changed attributes, please use attribute_name_was instead of attribute_name.
You can ignore
changes to certain attributes:
class Article < ActiveRecord::Base
has_paper_trail ignore: [:title, :rating]
end
Changes to just the title
or rating
will not create a version record.
Changes to other attributes will create a version record.
a = Article.create
a.versions.length # 1
a.update_attributes title: 'My Title', rating: 3
a.versions.length # 1
a.update_attributes title: 'Greeting', content: 'Hello'
a.versions.length # 2
a.paper_trail.previous_version.title # 'My Title'
Or, you can specify a list of the only
attributes you care about:
class Article < ActiveRecord::Base
has_paper_trail only: [:title]
end
Only changes to the title
will create a version record.
a = Article.create
a.versions.length # 1
a.update_attributes title: 'My Title'
a.versions.length # 2
a.update_attributes content: 'Hello'
a.versions.length # 2
a.paper_trail.previous_version.content # nil
The :ignore
and :only
options can also accept Hash
arguments.
class Article < ActiveRecord::Base
has_paper_trail only: { title: Proc.new { |obj| !obj.title.blank? } }
end
If the title
is not blank, then only changes to the title
will create a version record.
a = Article.create
a.versions.length # 1
a.update_attributes content: 'Hello'
a.versions.length # 2
a.update_attributes title: 'Title One'
a.versions.length # 3
a.update_attributes content: 'Hai'
a.versions.length # 3
a.paper_trail.previous_version.content # "Hello"
a.update_attributes title: 'Title Two'
a.versions.length # 4
a.paper_trail.previous_version.content # "Hai"
Configuring both :ignore
and :only
is not recommended, but it should work as
expected. Passing both :ignore
and :only
options will result in the
article being saved if a changed attribute is included in :only
but not in
:ignore
.
You can skip attributes completely with the :skip
option. As with :ignore
,
updates to these attributes will not create a version record. In addition, if a
version record is created for some other reason, these attributes will not be
persisted.
class Article < ActiveRecord::Base
has_paper_trail :skip => [:file_upload]
end
PaperTrail is on by default, but sometimes you don't want to record versions.
Turn PaperTrail off for all threads in a ruby
process.
PaperTrail.enabled = false
This is commonly used to speed up tests. See Testing below.
There is also a rails config option that does the same thing.
# in config/environments/test.rb
config.paper_trail.enabled = false
Add a paper_trail_enabled_for_controller
method to your controller.
class ApplicationController < ActionController::Base
def paper_trail_enabled_for_controller
request.user_agent != 'Disable User-Agent'
end
end
Widget.paper_trail.disable
Widget.paper_trail.enable
You can call a method without creating a new version using without_versioning
.
It takes either a method name as a symbol:
@widget.paper_trail.without_versioning :destroy
Or a block:
@widget.paper_trail.without_versioning do
@widget.update_attributes :name => 'Ford'
end
PaperTrail is disabled for the whole model
(e.g. Widget
), not just for the instance (e.g. @widget
).
Configure version_limit
to cap the number of versions saved per record. This
does not apply to create
events.
# Limit: 4 versions per record (3 most recent, plus a `create` event)
PaperTrail.config.version_limit = 3
# Remove the limit
PaperTrail.config.version_limit = nil
PaperTrail makes reverting to a previous version easy:
widget = Widget.find 42
widget.update_attributes :name => 'Blah blah'
# Time passes....
widget = widget.paper_trail.previous_version # the widget as it was before the update
widget.save # reverted
Alternatively you can find the version at a given time:
widget = widget.paper_trail.version_at(1.day.ago) # the widget as it was one day ago
widget.save # reverted
Note version_at
gives you the object, not a version, so you don't need to call
reify
.
Undeleting is just as simple:
widget = Widget.find(42)
widget.destroy
# Time passes....
versions = widget.versions # versions ordered by versions.created_at, ascending
widget = versions.last.reify # the widget as it was before destruction
widget.save # the widget lives!
You could even use PaperTrail to implement an undo system; Ryan Bates has!
If your model uses optimistic locking don't forget to increment your
lock_version
before saving or you'll get a StaleObjectError
.
You can call previous_version
and next_version
on an item to get it as it
was/became. Note that these methods reify the item for you.
live_widget = Widget.find 42
live_widget.versions.length # 4, for example
widget = live_widget.paper_trail.previous_version # => widget == live_widget.versions.last.reify
widget = widget.paper_trail.previous_version # => widget == live_widget.versions[-2].reify
widget = widget.paper_trail.next_version # => widget == live_widget.versions.last.reify
widget.paper_trail.next_version # live_widget
If instead you have a particular version
of an item you can navigate to the
previous and next versions.
widget = Widget.find 42
version = widget.versions[-2] # assuming widget has several versions
previous = version.previous
next = version.next
You can find out which of an item's versions yours is:
current_version_number = version.index # 0-based
If you got an item by reifying one of its versions, you can navigate back to the version it came from:
latest_version = Widget.find(42).versions.last
widget = latest_version.reify
widget.version == latest_version # true
You can find out whether a model instance is the current, live one -- or whether
it came instead from a previous version -- with live?
:
widget = Widget.find 42
widget.live? # true
widget = widget.paper_trail.previous_version
widget.live? # false
And you can perform WHERE
queries for object versions based on attributes:
# All versions that meet these criteria.
PaperTrail::Version.where_object(content: "Hello", title: "Article")
There are two scenarios: diffing adjacent versions and diffing non-adjacent versions.
The best way to diff adjacent versions is to get PaperTrail to do it for you.
If you add an object_changes
text column to your versions
table, either at
installation time with the rails generate paper_trail:install --with-changes
option or manually, PaperTrail will store the changes
diff (excluding any
attributes PaperTrail is ignoring) in each update
version. You can use the
version.changeset
method to retrieve it. For example:
widget = Widget.create :name => 'Bob'
widget.versions.last.changeset
# {
# "name"=>[nil, "Bob"],
# "created_at"=>[nil, 2015-08-10 04:10:40 UTC],
# "updated_at"=>[nil, 2015-08-10 04:10:40 UTC],
# "id"=>[nil, 1]
# }
widget.update_attributes :name => 'Robert'
widget.versions.last.changeset
# {
# "name"=>["Bob", "Robert"],
# "updated_at"=>[2015-08-10 04:13:19 UTC, 2015-08-10 04:13:19 UTC]
# }
widget.destroy
widget.versions.last.changeset
# {}
The object_changes
are only stored for creation and updates, not when an
object is destroyed.
Please be aware that PaperTrail doesn't use diffs internally. When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained. A version stores all of its object's data, not a diff from the previous version. This means you can delete any version without affecting any other.
To diff non-adjacent versions you'll have to write your own code. These libraries may help:
For diffing two strings:
- htmldiff: expects but doesn't require HTML input and produces HTML output. Works very well but slows down significantly on large (e.g. 5,000 word) inputs.
- differ: expects plain text input and produces plain text/coloured/HTML/any output. Can do character-wise, word-wise, line-wise, or arbitrary-boundary-string-wise diffs. Works very well on non-HTML input.
- diff-lcs: old-school, line-wise diffs.
For diffing two ActiveRecord objects:
- Jeremy Weiskotten's PaperTrail fork: uses ActiveSupport's diff to return an array of hashes of the changes.
- activerecord-diff: rather like ActiveRecord::Dirty but also allows you to specify which columns to compare.
If you wish to selectively record changes for some models but not others you
can opt out of recording changes by passing :save_changes => false
to your
has_paper_trail
method declaration.
Over time your versions
table will grow to an unwieldy size. Because each
version is self-contained (see the Diffing section above for more) you can
simply delete any records you don't want any more. For example:
sql> delete from versions where created_at < 2010-06-01;
PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
Set PaperTrail.whodunnit=
, and that value will be stored in the version's
whodunnit
column.
PaperTrail.whodunnit = 'Andy Stewart'
widget.update_attributes :name => 'Wibble'
widget.versions.last.whodunnit # Andy Stewart
If your controller has a current_user
method, PaperTrail provides a
before_action
that will assign current_user.id
to PaperTrail.whodunnit
.
You can add this before_action
to your ApplicationController
.
class ApplicationController
before_action :set_paper_trail_whodunnit
end
You may want set_paper_trail_whodunnit
to call a different method to find out
who is responsible. To do so, override the user_for_paper_trail
method in
your controller like this:
class ApplicationController
def user_for_paper_trail
logged_in? ? current_member.id : 'Public user' # or whatever
end
end
See also: Setting whodunnit in the rails console
Sometimes you want to define who is responsible for a change in a small scope
without overwriting value of PaperTrail.whodunnit
. It is possible to define
the whodunnit
value for an operation inside a block like this:
PaperTrail.whodunnit = 'Andy Stewart'
widget.paper_trail.whodunnit('Lucas Souza') do
widget.update_attributes :name => 'Wibble'
end
widget.versions.last.whodunnit # Lucas Souza
widget.update_attributes :name => 'Clair'
widget.versions.last.whodunnit # Andy Stewart
A version's whodunnit
records who changed the object causing the version
to
be stored. Because a version stores the object as it looked before the change
(see the table above), whodunnit
returns who stopped the object looking like
this -- not who made it look like this. Hence whodunnit
is aliased as
terminator
.
To find out who made a version's object look that way, use
version.paper_trail_originator
. And to find out who made a "live" object look
like it does, call paper_trail_originator
on the object.
widget = Widget.find 153 # assume widget has 0 versions
PaperTrail.whodunnit = 'Alice'
widget.update_attributes :name => 'Yankee'
widget.paper_trail.originator # 'Alice'
PaperTrail.whodunnit = 'Bob'
widget.update_attributes :name => 'Zulu'
widget.paper_trail.originator # 'Bob'
first_version, last_version = widget.versions.first, widget.versions.last
first_version.whodunnit # 'Alice'
first_version.paper_trail_originator # nil
first_version.terminator # 'Alice'
last_version.whodunnit # 'Bob'
last_version.paper_trail_originator # 'Alice'
last_version.terminator # 'Bob'
If you would like whodunnit
to return an ActiveRecord
object instead of a
string, please try the paper_trail-globalid gem.
Experimental feature, not recommended for production. See known issues below.
PaperTrail can restore three types of associations: Has-One, Has-Many, and Has-Many-Through. In order to do this, you will need to do two things:
- Create a
version_associations
table - Set
PaperTrail.config.track_associations = true
(e.g. in an initializer)
Both will be done for you automatically if you install PaperTrail with the
--with_associations
option
(e.g. rails generate paper_trail:install --with-associations
)
If you want to add this functionality after the initial installation, you will
need to create the version_associations
table manually, and you will need to
ensure that PaperTrail.config.track_associations = true
is set.
PaperTrail will store in the version_associations
table additional information
to correlate versions of the association and versions of the model when the
associated record is changed. When reifying the model, PaperTrail can use this
table, together with the transaction_id
to find the correct version of the
association and reify it. The transaction_id
is a unique id for version records
created in the same transaction. It is used to associate the version of the model
and the version of the association that are created in the same transaction.
To restore Has-One associations as they were at the time, pass option :has_one => true
to reify
. To restore Has-Many and Has-Many-Through associations, use
option :has_many => true
. To restore Belongs-To association, use
option :belongs_to => true
. For example:
class Location < ActiveRecord::Base
belongs_to :treasure
has_paper_trail
end
class Treasure < ActiveRecord::Base
has_one :location
has_paper_trail
end
treasure.amount # 100
treasure.location.latitude # 12.345
treasure.update_attributes :amount => 153
treasure.location.update_attributes :latitude => 54.321
t = treasure.versions.last.reify(:has_one => true)
t.amount # 100
t.location.latitude # 12.345
If the parent and child are updated in one go, PaperTrail can use the
aforementioned transaction_id
to reify the models as they were before the
transaction (instead of before the update to the model).
treasure.amount # 100
treasure.location.latitude # 12.345
Treasure.transaction do
treasure.location.update_attributes :latitude => 54.321
treasure.update_attributes :amount => 153
end
t = treasure.versions.last.reify(:has_one => true)
t.amount # 100
t.location.latitude # 12.345, instead of 54.321
By default, PaperTrail excludes an associated record from the reified parent
model if the associated record exists in the live model but did not exist as at
the time the version was created. This is usually what you want if you just want
to look at the reified version. But if you want to persist it, it would be
better to pass in option :mark_for_destruction => true
so that the associated
record is included and marked for destruction. Note that mark_for_destruction
only has an effect on associations marked with autosave: true
.
class Widget < ActiveRecord::Base
has_paper_trail
has_one :wotsit, autosave: true
end
class Wotsit < ActiveRecord::Base
has_paper_trail
belongs_to :widget
end
widget = Widget.create(:name => 'widget_0')
widget.update_attributes(:name => 'widget_1')
widget.create_wotsit(:name => 'wotsit')
widget_0 = widget.versions.last.reify(:has_one => true)
widget_0.wotsit # nil
widget_0 = widget.versions.last.reify(:has_one => true, :mark_for_destruction => true)
widget_0.wotsit.marked_for_destruction? # true
widget_0.save!
widget.reload.wotsit # nil
Associations are an experimental feature and have the following known issues, in order of descending importance.
- PaperTrail only reifies the first level of associations.
- #542 - Not compatible with transactional tests, aka. transactional fixtures.
- #841 - Without a workaround, reified records cannot be persisted if their associated records have been deleted.
- Requires database timestamp columns with fractional second precision.
- Sqlite and postgres timestamps have fractional second precision by default. MySQL timestamps do not. Furthermore, MySQL 5.5 and earlier do not support fractional second precision at all.
- Also, support for fractional seconds in MySQL was not added to rails until ActiveRecord 4.2 (rails/rails#14359).
- PaperTrail can't restore an association properly if the association record can be updated to replace its parent model (by replacing the foreign key)
- Currently PaperTrail only supports a single
version_associations
table. Therefore, you can only use a single table to store the versions for all related models. Sorry for those who use multiple version tables. - PaperTrail relies on the callbacks on the association model (and the :through association model for Has-Many-Through associations) to record the versions and the relationship between the versions. If the association is changed without invoking the callbacks, Reification won't work. Below are some examples:
Given these models:
class Book < ActiveRecord::Base
has_many :authorships, :dependent => :destroy
has_many :authors, :through => :authorships, :source => :person
has_paper_trail
end
class Authorship < ActiveRecord::Base
belongs_to :book
belongs_to :person
has_paper_trail # NOTE
end
class Person < ActiveRecord::Base
has_many :authorships, :dependent => :destroy
has_many :books, :through => :authorships
has_paper_trail
end
Then each of the following will store authorship versions:
@book.authors << @dostoyevsky
@book.authors.create :name => 'Tolstoy'
@book.authorships.last.destroy
@book.authorships.clear
@book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
But none of these will:
@book.authors.delete @tolstoy
@book.author_ids = []
@book.authors = []
Having said that, you can apparently get all these working (I haven't tested it myself) with this patch:
# In config/initializers/active_record_patch.rb
module ActiveRecord
# = Active Record Has Many Through Association
module Associations
class HasManyThroughAssociation < HasManyAssociation #:nodoc:
alias_method :original_delete_records, :delete_records
def delete_records(records, method)
method ||= :destroy
original_delete_records(records, method)
end
end
end
end
See issue 113 for a discussion about this.
You can store arbitrary model-level metadata alongside each version like this:
class Article < ActiveRecord::Base
belongs_to :author
has_paper_trail :meta => { :author_id => :author_id,
:word_count => :count_words,
:answer => 42 }
def count_words
153
end
end
PaperTrail will call your proc with the current article and store the result in
the author_id
column of the versions
table.
Don't forget to add any such columns to your versions
table.
Why would you do this? In this example, author_id
is an attribute of
Article
and PaperTrail will store it anyway in a serialized form in the
object
column of the version
record. But let's say you wanted to pull out
all versions for a particular author; without the metadata you would have to
deserialize (reify) each version
object to see if belonged to the author in
question. Clearly this is inefficient. Using the metadata you can find just
those versions you want:
PaperTrail::Version.where(:author_id => author_id)
You can also store any information you like from your controller. Override
the info_for_paper_trail
method in your controller to return a hash whose keys
correspond to columns in your versions
table.
class ApplicationController
def info_for_paper_trail
{ :ip => request.remote_ip, :user_agent => request.user_agent }
end
end
PaperTrail supports Single Table Inheritance, and even supports an
un-versioned base model, as of 23ffbdc7e1
.
class Fruit < ActiveRecord::Base
# un-versioned base model
end
class Banana < Fruit
has_paper_trail
end
However, there is a known issue when reifying associations, see paper-trail-gem#594
You may configure the name of the versions
association by passing
a different name to has_paper_trail
.
class Post < ActiveRecord::Base
has_paper_trail class_name: 'Version', versions: :drafts
end
Post.new.versions # => NoMethodError
Overriding (instead of configuring) the versions
method is not supported.
Overriding associations is not recommended in general.
PaperTrail has one generator, paper_trail:install
. It writes, but does not
run, a migration file. It also creates a PaperTrail configuration initializer.
The migration adds (at least) the versions
table. The
most up-to-date documentation for this generator can be found by running rails generate paper_trail:install --help
, but a copy is included here for
convenience.
Usage:
rails generate paper_trail:install [options]
Options:
[--with-changes], [--no-with-changes] # Store changeset (diff) with each version
[--with-associations], [--no-with-associations] # Store transactional IDs to support association restoration
Runtime options:
-f, [--force] # Overwrite files that already exist
-p, [--pretend], [--no-pretend] # Run but do not make any changes
-q, [--quiet], [--no-quiet] # Suppress status output
-s, [--skip], [--no-skip] # Skip files that already exist
Generates (but does not run) a migration to add a versions table. Also generates an initializer file for configuring PaperTrail
As of version 6, PT no longer supports rails 3 or the protected_attributes gem. If you are still using them, you may use PT 5 or lower. We recommend upgrading to strong_parameters as soon as possible.
You can specify custom version subclasses with the :class_name
option:
class PostVersion < PaperTrail::Version
# custom behaviour, e.g:
self.table_name = :post_versions
end
class Post < ActiveRecord::Base
has_paper_trail :class_name => 'PostVersion'
end
Unlike ActiveRecord's class_name
, you'll have to supply the complete module
path to the class (e.g. Foo::BarVersion
if your class is inside the module
Foo
).
- For models which have a lot of versions, storing each model's versions in a separate table can improve the performance of certain database queries.
- Store different version metadata for different models.
If you are using Postgres, you should also define the sequence that your custom version class will use:
class PostVersion < PaperTrail::Version
self.table_name = :post_versions
self.sequence_name = :post_versions_id_seq
end
If you only use custom version classes and don't have a versions
table, you
must let ActiveRecord know that the PaperTrail::Version
class is an
abstract_class
.
# app/models/paper_trail/version.rb
module PaperTrail
class Version < ActiveRecord::Base
include PaperTrail::VersionConcern
self.abstract_class = true
end
end
You can also specify custom names for the versions and version associations.
This is useful if you already have versions
or/and version
methods on your
model. For example:
class Post < ActiveRecord::Base
has_paper_trail :versions => :paper_trail_versions,
:version => :paper_trail_version
# Existing versions method. We don't want to clash.
def versions
...
end
# Existing version method. We don't want to clash.
def version
...
end
end
By default, PaperTrail stores your changes as a YAML
dump. You can override
this with the serializer config option:
PaperTrail.serializer = MyCustomSerializer
A valid serializer is a module
(or class
) that defines a load
and dump
method. These serializers are included in the gem for your convenience:
If you use PostgreSQL, and would like to store your object
(and/or
object_changes
) data in a column of type json
or type jsonb
, specify
json
instead of text
for these columns in your migration:
create_table :versions do |t|
...
t.json :object # Full object changes
t.json :object_changes # Optional column-level changes
...
end
If you use the PostgreSQL json
or jsonb
column type, you do not need
to specify a PaperTrail.serializer
.
If you've been using PaperTrail for a while with the default YAML serializer and you want to switch to JSON or JSONB, you're in a bit of a bind because there's no automatic way to migrate your data. The first (slow) option is to loop over every record and parse it in Ruby, then write to a temporary column:
add_column :versions, :new_object, :jsonb # or :json
PaperTrail::Version.reset_column_information
PaperTrail::Version.find_each do |version|
version.update_column :new_object, YAML.load(version.object)
end
remove_column :versions, :object
rename_column :versions, :new_object, :object
This technique can be very slow if you have a lot of data. Though slow, it is safe in databases where transactions are protected against DDL, such as Postgres. In databases without such protection, such as MySQL, a table lock may be necessary.
If the above technique is too slow for your needs, and you're okay doing without PaperTrail data temporarily, you can create the new column without converting the data.
rename_column :versions, :object, :old_object
add_column :versions, :object, :jsonb # or :json
After that migration, your historical data still exists as YAML, and new data will be stored as JSON. Next, convert records from YAML to JSON using a background script.
PaperTrail::Version.where.not(old_object: nil).find_each do |version|
version.update_columns old_object: nil, object: YAML.load(version.old_object)
end
Finally, in another migration, remove the old column.
remove_column :versions, :old_object
If you use the optional object_changes
column, don't forget to convert it
also, using the same technique.
If your object
column already contains JSON data, and you want to change its
data type to json
or jsonb
, you can use the following DDL. Of course,
if your object
column contains YAML, you must first convert the data to JSON
(see above) before you can change the column type.
Using SQL:
alter table versions
alter column object type jsonb
using object::jsonb;
Using ActiveRecord:
class ConvertVersionsObjectToJson < ActiveRecord::Migration
def up
change_column :versions, :object, 'jsonb USING object::jsonb'
end
def down
change_column :versions, :object, 'text USING object::text'
end
end
You may want to turn PaperTrail off to speed up your tests. See Turning PaperTrail Off above.
First, disable PT for the entire ruby
process.
# in config/environments/test.rb
config.after_initialize do
PaperTrail.enabled = false
end
Then, to enable PT for specific tests, you can add a with_versioning
test
helper method.
# in test/test_helper.rb
def with_versioning
was_enabled = PaperTrail.enabled?
was_enabled_for_controller = PaperTrail.enabled_for_controller?
PaperTrail.enabled = true
PaperTrail.enabled_for_controller = true
begin
yield
ensure
PaperTrail.enabled = was_enabled
PaperTrail.enabled_for_controller = was_enabled_for_controller
end
end
Then, use the helper in your tests.
test "something that needs versioning" do
with_versioning do
# your test
end
end
PaperTrail provides a helper, paper_trail/frameworks/rspec.rb
, that works with
RSpec to make it easier to control when PaperTrail
is enabled during
testing.
# spec/rails_helper.rb
ENV["RAILS_ENV"] ||= 'test'
require 'spec_helper'
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
...
require 'paper_trail/frameworks/rspec'
With the helper loaded, PaperTrail will be turned off for all tests by
default. To enable PaperTrail for a test you can either wrap the
test in a with_versioning
block, or pass in :versioning => true
option to a
spec block.
describe "RSpec test group" do
it 'by default, PaperTrail will be turned off' do
expect(PaperTrail).to_not be_enabled
end
with_versioning do
it 'within a `with_versioning` block it will be turned on' do
expect(PaperTrail).to be_enabled
end
end
it 'can be turned on at the `it` or `describe` level like this', :versioning => true do
expect(PaperTrail).to be_enabled
end
end
The helper will also reset the PaperTrail.whodunnit
value to nil
before each
test to help prevent data spillover between tests. If you are using PaperTrail
with Rails, the helper will automatically set the PaperTrail.controller_info
value to {}
as well, again, to help prevent data spillover between tests.
There is also a be_versioned
matcher provided by PaperTrail's RSpec helper
which can be leveraged like so:
class Widget < ActiveRecord::Base
end
describe Widget do
it "is not versioned by default" do
is_expected.to_not be_versioned
end
describe "add versioning to the `Widget` class" do
before(:all) do
class Widget < ActiveRecord::Base
has_paper_trail
end
end
it "enables paper trail" do
is_expected.to be_versioned
end
end
end
It is also possible to do assertions on the versions using have_a_version_with
matcher.
describe '`have_a_version_with` matcher' do
before do
widget.update_attributes!(name: 'Leonard', an_integer: 1)
widget.update_attributes!(name: 'Tom')
widget.update_attributes!(name: 'Bob')
end
it "is possible to do assertions on version attributes" do
expect(widget).to have_a_version_with name: 'Leonard', an_integer: 1
expect(widget).to have_a_version_with an_integer: 1
expect(widget).to have_a_version_with name: 'Tom'
end
end
There is also a have_a_version_with_changes
matcher. This is only usable if your versions table has an object_changes
column for storing changesets.
describe '`have_a_version_with_changes` matcher' do
before do
widget.update_attributes!(name: 'Leonard', an_integer: 1)
widget.update_attributes!(name: 'Tom')
widget.update_attributes!(name: 'Bob')
end
it "is possible to do assertions on version changes" do
expect(widget).to have_a_version_with name: 'Leonard', an_integer: 2
expect(widget).to have_a_version_with an_integer: 2
expect(widget).to have_a_version_with name: 'Bob'
end
end
For more examples of the RSpec matchers, see the Widget spec
PaperTrail provides a helper for Cucumber that works similar to the RSpec helper.If you wish to use the helper, you will need to require in your cucumber helper like so:
# features/support/env.rb
ENV["RAILS_ENV"] ||= "cucumber"
require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
...
require 'paper_trail/frameworks/cucumber'
When the helper is loaded, PaperTrail will be turned off for all scenarios by a
before
hook added by the helper by default. When you wish to enable PaperTrail
for a scenario, you can wrap code in a with_versioning
block in a step, like
so:
Given /I want versioning on my model/ do
with_versioning do
# PaperTrail will be turned on for all code inside of this block
end
end
The helper will also reset the PaperTrail.whodunnit
value to nil
before each
test to help prevent data spillover between tests. If you are using PaperTrail
with Rails, the helper will automatically set the PaperTrail.controller_info
value to {}
as well, again, to help prevent data spillover between tests.
If you wish to use the RSpec
or Cucumber
helpers with Spork, you will
need to manually require the helper(s) in your prefork
block on your test
helper, like so:
# spec/rails_helper.rb
require 'spork'
Spork.prefork do
# This file is copied to spec/ when you run 'rails generate rspec:install'
ENV["RAILS_ENV"] ||= 'test'
require 'spec_helper'
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
require 'paper_trail/frameworks/rspec'
require 'paper_trail/frameworks/cucumber'
...
end
If you wish to use the RSpec
or Cucumber
helpers with Zeus or
Spring, you will need to manually require the helper(s) in your test
helper, like so:
# spec/rails_helper.rb
ENV["RAILS_ENV"] ||= 'test'
require 'spec_helper'
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
require 'paper_trail/frameworks/rspec'
See paper_trail-sinatra.
- Jutsu #8 - Version your RoR models with PaperTrail, Thibault, 29th September 2014
- Versioning with PaperTrail, Ilya Bodrov, 10th April 2014
- Using PaperTrail to track stack traces, T James Corcoran's blog, 1st October 2013.
- RailsCast #255 - Undo with PaperTrail, 28th February 2011.
- Keep a Paper Trail with PaperTrail, Linux Magazine, 16th September 2009.
Please use GitHub's issue tracker.
Many thanks to:
- Dmitry Polushkin
- Russell Osborne
- Zachery Hostens
- Jeremy Weiskotten
- Phan Le
- jdrucza
- conickal
- Thibaud Guillaume-Gentil
- Danny Trelogan
- Mikl Kurkov
- Franco Catena
- Emmanuel Gomez
- Matthew MacLeod
- benzittlau
- Tom Derks
- Jonas Hoglund
- Stefan Huber
- thinkcast
- Dominik Sander
- Burke Libbey
- 6twenty
- nir0
- Eduard Tsech
- Mathieu Arnold
- Nicholas Thrower
- Benjamin Curtis
- Peter Harkins
- Mohd Amree
- Nikita Cernovs
- Jason Noble
- Jared Mehle
- Eric Schwartz
- Ben Woosley
- Philip Arndt
- Daniel Vydra
- Byron Bowerman
- Nicolas Buduroi
- Pikender Sharma
- Paul Brannan
- Ben Morrall
- Yves Senn
- Ben Atkins
- Tyler Rick
- Bradley Priest
- David Butler
- Paul Belt
- Vlad Bokov
- Sean Marcia
- Chulki Lee
- Lucas Souza
- Russell Osborne
- Ben Li
- Felix Liu
Copyright (c) 2011 Andy Stewart ([email protected]). Released under the MIT licence.