Skip to content
Switch branches/tags
Go to file


Build Status Code Climate Gem Version

Sequenced is a simple gem that generates scoped sequential IDs for ActiveRecord models. This gem provides an acts_as_sequenced macro that automatically assigns a unique, sequential ID to each record. The sequential ID is not a replacement for the database primary key, but rather adds another way to retrieve the object without exposing the primary key.


It's generally a bad practice to expose your primary keys to the world in your URLs. However, it is often appropriate to number objects in sequence (in the context of a parent object).

For example, given a Question model that has many Answers, it makes sense to number answers sequentially for each individual question. You can achieve this with Sequenced in one line of code:

class Question < ActiveRecord::Base
  has_many :answers

class Answer < ActiveRecord::Base
  belongs_to :question
  acts_as_sequenced scope: :question_id


Add the gem to your Gemfile:

gem 'sequenced'

Install the gem with bundler:

bundle install


To add a sequential ID to a model, first add an integer column called sequential_id to the model (or you many name the column anything you like and override the default). For example:

rails generate migration add_sequential_id_to_answers sequential_id:integer
rake db:migrate

Then, call the acts_as_sequenced macro in your model class:

class Answer < ActiveRecord::Base
  belongs_to :question
  acts_as_sequenced scope: :question_id

The scope option can be any attribute, but will typically be the foreign key of an associated parent object. You can even scope by multiple columns for polymorphic relationships:

class Answer < ActiveRecord::Base
  belongs_to :questionable, :polymorphic => true
  acts_as_sequenced scope: [:questionable_id, :questionable_type]

Multiple sequences can be defined by using the macro multiple times:

class Answer < ActiveRecord::Base
  belongs_to :account
  belongs_to :question

  acts_as_sequenced column: :question_answer_number, scope: :question_id
  acts_as_sequenced column: :account_answer_number, scope: :account_id

Schema and data integrity

This gem is only concurrent-safe for PostgreSQL databases. For other database systems, unexpected behavior may occur if you attempt to create records concurrently.

You can mitigate this somewhat by applying a unique index to your sequential ID column (or a multicolumn unique index on sequential ID and scope columns, if you are using scopes). This will ensure that you can never have duplicate sequential IDs within a scope, causing concurrent updates to instead raise a uniqueness error at the database-level.

It is also a good idea to apply a not-null constraint to your sequential ID column as well if you never intend to skip it.

Here is an example migration for a model that has a sequential_id scoped to a burrow_id:

# app/db/migrations/20151120190645_create_badgers.rb
class CreateBadgers < ActiveRecord::Migration
  def change
    create_table :badgers do |t|
      t.integer :sequential_id, null: false
      t.integer :burrow_id

    add_index :badgers, [:sequential_id, :burrow_id], unique: true

If you are adding a sequenced column to an existing table, you need to account for that in your migration.

Here is an example migration that adds and sets the sequential_id column based on the current database records:

# app/db/migrations/20151120190645_add_sequental_id_to_badgers.rb
class AddSequentalIdToBadgers < ActiveRecord::Migration
  add_column :badgers, :sequential_id, :integer

  execute <<~SQL
    UPDATE badgers
    SET sequential_id = old_badgers.next_sequential_id
    FROM (
        PARTITION BY burrow_id
        ORDER BY id
      ) AS next_sequential_id
      FROM badgers
    ) old_badgers
    WHERE =

  change_column :badgers, :sequential_id, :integer, null: false
  add_index :badgers, [:sequential_id, :burrow_id], unique: true


Overriding the default sequential ID column

By default, Sequenced uses the sequential_id column and assumes it already exists. If you wish to store the sequential ID in different integer column, simply specify the column name with the column option:

acts_as_sequenced scope: :question_id, column: :my_sequential_id

Starting the sequence at a specific number

By default, Sequenced begins sequences with 1. To start at a different integer, simply set the start_at option:

acts_as_sequenced start_at: 1000

You may also pass a lambda to the start_at option:

acts_as_sequenced start_at: lambda { |r| r.computed_start_value }

Indexing the sequential ID column

For optimal performance, it's a good idea to index the sequential ID column on sequenced models.

Skipping sequential ID generation

If you'd like to skip generating a sequential ID under certain conditions, you may pass a lambda to the skip option:

acts_as_sequenced skip: lambda { |r| r.score == 0 }


Suppose you have a question model that has many answers. This example demonstrates how to use Sequenced to enable access to the nested answer resource via its sequential ID.

# app/models/question.rb
class Question < ActiveRecord::Base
  has_many :answers

# app/models/answer.rb
class Answer < ActiveRecord::Base
  belongs_to :question
  acts_as_sequenced scope: :question_id

  # Automatically use the sequential ID in URLs
  def to_param

# config/routes.rb
resources :questions do
  resources :answers

# app/controllers/answers_controller.rb
class AnswersController < ApplicationController
  def show
    @question = Question.find(params[:question_id])
    @answer = @question.answers.find_by(sequential_id: params[:id])

Now, answers are accessible via their sequential IDs:  # Good

instead of by their primary keys:  # Bad


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request