Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Track changes to your models' data. Good for auditing or versioning.

Subscribe to updates I use paper_trail

Statistics on paper_trail

Number of watchers on Github 5008
Number of open issues 13
Average time to close an issue 10 days
Main language Ruby
Average time to merge a PR 1 day
Open pull requests 22+
Closed pull requests 49+
Last commit over 1 year ago
Repo Created over 10 years ago
Repo Last Updated over 1 year ago
Size 2.96 MB
Organization / Authorairblade
Latest Releasev7.0.0
Page Updated
Do you use paper_trail? Leave a review!
View open issues (13)
View paper_trail activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating paper_trail for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Build Status Dependency Status

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.


Version Documentation

Table of Contents

1. Introduction

1.a. Compatibility

paper_trail branch tags ruby activerecord
unreleased master >= 2.2.0 >= 4.2, < 6
8 master v8.x >= 2.2.0 >= 4.2, < 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

1.b. Installation

  1. Add PaperTrail to your Gemfile.

    gem 'paper_trail'

  2. 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.

  3. Add has_paper_trail to the models you want to track.

    class Widget < ActiveRecord::Base
  4. 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

1.c. Basic Usage

Your models now have a versions method which returns the paper trail of changes to your model.

widget = Widget.find 42
# [<PaperTrail::Version>, <PaperTrail::Version>, ...]

Once you have a version, you can find out what happened:

v = widget.versions.last
v.event # 'update', 'create', 'destroy'. See also: Custom Event Names
v.whodunnit # ID of `current_user`. Requires `set_paper_trail_whodunnit` callback.
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                                 # 'Doobly'

# Add has_paper_trail to Widget model.

widget.versions                             # []
widget.update_attributes name: 'Wotsit'             # '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 row. Most other auditing/versioning plugins store the After row.

1.d. API Summary

When you declare has_paper_trail in your model, you get these methods:

class Widget < ActiveRecord::Base

# Returns this widget's versions.  You can customise the name of the
# association, but overriding this method is not supported.

# Return the version this widget was reified from, or nil if it is live.
# You can customise the name of the method.

# Returns true if this widget is the current, live one; or false if it is from
# a previous version.

# Returns who put the widget into its current state.

# Returns the widget (not a version) as it looked at the given timestamp.

# Returns the widget (not a version) as it was most recently.

# Returns the widget (not a version) as it became next.

# Generates a version for a `touch` event (`widget.touch` does NOT generate a
# version)

# Enable/disable PaperTrail, for Widget, for the current request (not all threads)

# Is PaperTrail enabled for Widget, the class?

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.

# Returns who changed the item from the state it had in this version.

# Returns the next version.

# Returns the previous version.

# Returns the index of this version in all the versions.

# Returns the event that caused this version (create|update|destroy).

# Query the `versions.object` column (or `object_changes` column), by
# attributes, using the SQL LIKE operator.
# Known issue: `where_object_changes` with the default YAML serializer and
# an `object_changes` text column may return incorrect 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.

# Returns any information about the controller or request that you want
# PaperTrail to store alongside any changes that occur.

1.e. Configuration

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.

2. Limiting What is Versioned, and When

2.a. Choosing Lifecycle Events To Monitor

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]

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.

Custom Event Name

You may also have the PaperTrail::Version model save a custom string in its event field instead of the typical create, update, destroy. PaperTrail adds an attr_accessor to your model named paper_trail_event, and will insert it, if present, in the event column.

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'

Controlling the Order of AR Callbacks

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.

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

2.b. Choosing When To Save New Versions

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: { |t| t.language_code == 'US' },
                  unless: { |t| t.type == 'DRAFT'       }

Choosing Based on Changed Attributes

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.

2.c. Choosing Attributes To Monitor


You can ignore changes to certain attributes:

class Article < ActiveRecord::Base
  has_paper_trail ignore: [:title, :rating]

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]

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: { |obj| !obj.title.blank? } }

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]

2.d. Turning PaperTrail Off

PaperTrail is on by default, but sometimes you don't want to record versions.

Per Process

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

Per Request

Add a paper_trail_enabled_for_controller method to your controller.

class ApplicationController < ActionController::Base
  def paper_trail_enabled_for_controller
    # Don't omit `super` without a good reason.
    super && request.user_agent != 'Disable User-Agent'

Per Class


This setting, as with all PaperTrail.request settings, affects only the current request, not all threads.

Per Method

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'

During without_versioning, PaperTrail is disabled for the whole model (e.g. Widget), not just for the instance (e.g. @widget).

2.e. Limiting the Number of Versions Created

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

3. Working With Versions

3.a. Reverting And Undeleting A Model

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                                   # reverted

Alternatively you can find the version at a given time:

widget = widget.paper_trail.version_at(  # the widget as it was one day ago                                        # 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)
# Time passes....
versions = widget.versions    # versions ordered by versions.created_at, ascending
widget = versions.last.reify  # the widget as it was before destruction                   # 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.

3.b. Navigating Versions

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 =

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                        # true
widget = widget.paper_trail.previous_version                        # 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')

3.c. Diffing Versions

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'
# {
#   "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'
# {
#   "name"=>["Bob", "Robert"],
#   "updated_at"=>[2015-08-10 04:13:19 UTC, 2015-08-10 04:13:19 UTC]
# }
# {}

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:

If you want 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.

3.d. Deleting Old Versions

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]

4. Saving More Information About Versions

4.a. Finding Out Who Was Responsible For A Change

Set PaperTrail.request.whodunnit=, and that value will be stored in the version's whodunnit column.

PaperTrail.request.whodunnit = 'Andy Stewart'
widget.update_attributes name: 'Wibble'
widget.versions.last.whodunnit # Andy Stewart

Setting whodunnit to a Proc

whodunnit= also accepts a Proc, in the rare case that lazy evaluation is required.

PaperTrail.request.whodunnit = proc do
  caller.first{ |c| c.starts_with? Rails.root.to_s }

Because lazy evaluation can be hard to troubleshoot, this is not recommended for common use.

Setting whodunnit Temporarily

To set whodunnit temporarily, for the duration of a block, use PaperTrail.request:

PaperTrail.request(whodunnit: 'Dorian Mari') do
  widget.update_attributes name: 'Wibble'

Setting whodunnit with a controller callback

If your controller has a current_user method, PaperTrail provides a callback that will assign to whodunnit.

class ApplicationController
  before_action :set_paper_trail_whodunnit

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? ? : 'Public user'  # or whatever

See also: Setting whodunnit in the rails console

Terminator and Originator

A version's whodunnit column tells us 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 tells us 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.request.whodunnit = 'Alice'
widget.update_attributes name: 'Yankee'
widget.paper_trail.originator               # 'Alice'
PaperTrail.request.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'

Storing an ActiveRecord globalid in whodunnit

If you would like whodunnit to return an ActiveRecord object instead of a string, please try the paper_trail-globalid gem.

4.b. Associations

Experimental feature with many known issues. 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:

  1. Create a version_associations table
  2. 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

class Treasure < ActiveRecord::Base
  has_one :location

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

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_one :wotsit, autosave: true

class Wotsit < ActiveRecord::Base
  belongs_to :widget

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.reload.wotsit                             # nil

4.b.1. Known Issues

Associations are an experimental feature and have the following known issues, in order of descending importance.

  1. PaperTrail only reifies the first level of associations.
  2. Does not fully support STI (For example, see spec/models/person_spec.rb and PaperTrail::Reifiers::HasOne::FoundMoreThanOne error)
  3. #542 - Not compatible with transactional tests, aka. transactional fixtures.
  4. 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 (
  5. PaperTrail can't restore an association properly if the association record can be updated to replace its parent model (by replacing the foreign key)
  6. 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.
  7. 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

class Authorship < ActiveRecord::Base
  belongs_to :book
  belongs_to :person
  has_paper_trail      # NOTE

class Person < ActiveRecord::Base
  has_many :authorships, dependent: :destroy
  has_many :books, through: :authorships

Then each of the following will store authorship versions:

@book.authors << @dostoyevsky
@book.authors.create name: 'Tolstoy'
@book.author_ids = [,]

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)

See issue 113 for a discussion about this.

4.c. Storing Metadata

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

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.

Advantages of Metadata

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)

Metadata from Controllers

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 }

5. ActiveRecord

5.a. Single Table Inheritance (STI)

PaperTrail supports Single Table Inheritance, and even supports an un-versioned base model, as of 23ffbdc7e1.

class Fruit < ActiveRecord::Base
  # un-versioned base model
class Banana < Fruit

However, there is a known issue when reifying associations, see

5.b. Configuring the versions Association

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 # => NoMethodError

Overriding (instead of configuring) the versions method is not supported. Overriding associations is not recommended in general.

5.c. Generators

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.

  rails generate paper_trail:install [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

5.d. Protected Attributes

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.

If you must use protected_attributes for now, and want to use PT > 5, you can reopen PaperTrail::Version and add the following attr_accessible fields:

# app/models/paper_trail/version.rb
module PaperTrail
  class Version < ActiveRecord::Base
    include PaperTrail::VersionConcern
    attr_accessible :item_type, :item_id, :event, :whodunnit, :object, :object_changes, :created_at

This unsupported workaround has been tested with protected_attributes 1.0.9 / rails 4.2.8 / paper_trail 7.0.3.

6. Extensibility

6.a. Custom Version Classes

You can specify custom version subclasses with the :class_name option:

class PostVersion < PaperTrail::Version
  # custom behaviour, e.g:
  self.table_name = :post_versions

class Post < ActiveRecord::Base
  has_paper_trail class_name: 'PostVersion'

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).


  1. 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.
  2. 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

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

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
    # ...

  # Existing version method.  We don't want to clash.
  def version
    # ...

6.b. Custom Serializer

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:

PostgreSQL JSON column type support

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
  # ...

If you use the PostgreSQL json or jsonb column type, you do not need to specify a PaperTrail.serializer.

Convert existing YAML data to JSON

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.find_each do |version|
  version.update_column :new_object, YAML.load(version.object) if version.object

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)

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.

Convert a Column from Text to JSON

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'

  def down
    change_column :versions, :object, 'text USING object::text'

7. Testing

You may want to turn PaperTrail off to speed up your tests. See Turning PaperTrail Off above.

7.a. Minitest

First, disable PT for the entire ruby process.

# in config/environments/test.rb
config.after_initialize do
  PaperTrail.enabled = false

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
    PaperTrail.enabled = was_enabled
    PaperTrail.enabled_for_controller = was_enabled_for_controller

Then, use the helper in your tests.

test 'something that needs versioning' do
  with_versioning do
    # your test

7.b. RSpec

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

  with_versioning do
    it 'within a `with_versioning` block it will be turned on' do
      expect(PaperTrail).to be_enabled

  it 'can be turned on at the `it` or `describe` level', versioning: true do
    expect(PaperTrail).to be_enabled

The helper will also reset whodunnit 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

describe Widget do
  it 'is not versioned by default' do
    is_expected.to_not be_versioned

  describe 'add versioning to the `Widget` class' do
    before(:all) do
      class Widget < ActiveRecord::Base

    it 'enables paper trail' do be_versioned


The have_a_version_with matcher makes assertions about versions using where_object, based on the object column.

describe '`have_a_version_with` matcher' do
  it 'is possible to do assertions on version attributes' do
    widget.update_attributes!(name: 'Leonard', an_integer: 1)
    widget.update_attributes!(name: 'Tom')
    widget.update_attributes!(name: 'Bob')
    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'

The have_a_version_with_changes matcher makes assertions about versions using where_object_changes, based on the optional object_changes column.

describe '`have_a_version_with_changes` matcher' do
  it 'is possible to do assertions on version changes' do
    widget.update_attributes!(name: 'Leonard', an_integer: 1)
    widget.update_attributes!(name: 'Tom')
    widget.update_attributes!(name: 'Bob')
    expect(widget).to have_a_version_with_changes name: 'Leonard', an_integer: 2
    expect(widget).to have_a_version_with_changes an_integer: 2
    expect(widget).to have_a_version_with_changes name: 'Bob'

For more examples of the RSpec matchers, see the Widget spec

7.c. Cucumber

PaperTrail provides a helper for Cucumber that works similar to the RSpec helper. If you want 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 want 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

The helper will also reset the 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.

7.d. Spork

If you want 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'
  # ...

7.e. Zeus or Spring

If you want 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'

8. Integration with Other Libraries

9. Related Libraries and Ports



Please use GitHub's issue tracker.


Created by Andy Stewart in 2010, maintained since 2012 by Ben Atkins, since 2015 by Jared Beck, with contributions by over 150 people.


See our contribution guidelines


Intellectual Property

Copyright (c) 2011 Andy Stewart ( Released under the MIT licence.

paper_trail open issues Ask a question     (View All Issues)
  • about 3 years Not compatible with sinatra 2 yet
  • about 3 years Feature idea: Use background job to create version records
  • about 3 years Reified record cannot be persisted if associated record has been deleted
  • over 3 years Support for storing only incremental changes for json/jsonb columns
  • over 3 years where_object and where_object_changes do not handle integers
  • over 3 years bundle exec rake is failing for the first time but able to pass when I run it for the second time
  • almost 4 years Proposed: A convenient way to query versions in chronological order
  • almost 4 years Choosing associations to track
  • about 4 years Reify on associations fails if using Single Table Inheritance
  • over 4 years Switch the default serializer to JSON?
  • over 4 years Reification of associations is not compatible with transactional tests
  • about 5 years Support for partial reify/restore
  • about 5 years Maintaining coherency with migrations is convoluted
  • over 5 years Non-ActiveRecord ORM compatibility, e.g. Sequel
  • over 5 years t.integer :item_id does not play well with, nor complains about id: :uuid
  • over 5 years Compatibility between paper_trail and composite_primary_keys
  • almost 6 years [RC] Use different data storage engine
paper_trail open pull requests (View All Pulls)
  • Switch to Railtie, add config.paper_trail.enabled
  • Make whodunnit column configurable
  • Add Railtie config option: config.paper_trail.enabled
  • An idea to combat model pollution
  • Explicit requires
  • Added has_and_belongs_to_many reification
  • Check connection to database is present for validating table existence.
  • Model can override the global version limit
  • Fix issue 798 enum touch
  • Ensure order of association is enforced
  • Fix deprecation warning for paper_trail_on_destroy(:after)
  • Change paper_trail_on_destroy default to 'before'
  • Adding user active active model instance.
  • Run CI against rails/master
  • Don't use `reset_callbacks` in tests
  • Avoid allocating new hash when merging metadata
  • Add support for per-model version_limit
  • Organize association reification methods
  • Convert model test
  • Discussing the API for request variables, part 2
  • Add specs to request variables branch
  • Fix versions storing attributes as nil while manually creating a version
paper_trail questions on Stackoverflow (View All Questions)
  • Using where method with specific time versions on a class with Paper_trail
  • What's the right way to list all paper_trail versions including associations?
  • Paper_trail retrieve has_many association
  • Rails 4 x paper_trail: keep track of versions after item is destroyed
  • Rails 4 x paper_trail: filter versions by item_id with nested resources
  • Rails 4 x paper_trail: track which attributes are updated and display their new value
  • After installing paper_trail, get "irb: warn: can't alias context from irb_context." from rails console
  • PaperTrail (paper_trail) error after upgrading to Ruby 2.1.2 with RVM. Uninitialized constant PaperTrail::Rails::Engine
  • Rails 4 x paper_trail: undefined method for nil:NilClass after destroy
  • Paper_Trail: Show Diff Between Versions
  • How do I format the output from changeset using paper_trail in a view?
  • Paper_trail gem abilities
  • Saving version comments with paper_trail
  • Using paper_trail to reify acts_as_taggable_on associations
  • Edit a paper_trail version without creating a new version
  • Paper_Trail and CanCan: Rails_Admin doesn't show versions
  • Paper_Trail Showing Diff Between Two Versions
  • Adding Time and Date to Paper_Trail data
  • Unable to integrate auditing using paper_trail gem in rails 2 application from plugin
  • select versions from only one type in paper_trail
  • How to rectify versions on has_many/belongs_to association with paper_trail
  • Automatically setting who was responsible for a change in the console in paper_trail in Heroku
  • Delete all versions of paper_trail when delting a model
  • Display custom label for User in rails_admin paper_trail history
  • Upgrading from 4.0.2 to 4.2.0 breaks paper_trail code
  • Why is the paper_trail gem trying to do an empty insert in Rails 4.2/Ruby 2.2.0?
  • How to change the object view in paper_trail
  • Paper_trail and Kaminari problem
  • Testing with paper_trail with Rails 3
  • How can I use paper_trail gem to store creator details?
paper_trail list of languages used
Other projects in Ruby