EncodedId::Rails

encoded_id-rails is a gem that provides Rails integration for encoded_id, making it easy to use encoded IDs with your ActiveRecord models.

Why use EncodedId::Rails?

Obfuscate database IDs in URLs: Hide sequential numeric IDs from users
Human-friendly URLs: Generate readable, user-friendly URLs for your resources
Slugged IDs: Combine human-readable names with encoded IDs (e.g., /users/bob-smith--usr_p5w9-z27j)
Annotated IDs: Include model information in encoded IDs (e.g., user_p5w9-z27j)
Finder methods: Find ActiveRecord models using encoded IDs
Automatic URL generation: Override to_param to use encoded IDs in URL helpers
Persistence: Optionally store encoded IDs in the database for efficient lookups

Installation

Add this line to your application’s Gemfile:

gem 'encoded_id-rails'

And then execute:

bundle install

Then run the installation generator:

rails generate encoded_id:rails:install

This will create a configuration file at config/initializers/encoded_id.rb.

Quick Start

# Include in your model
class User < ApplicationRecord
  include EncodedId::Rails::Model
end

# Create a user
user = User.create(name: "John Doe")

# Get the encoded ID
user.encoded_id
# => "user_p5w9-z27j"

# Get a slugged version (if you implement name_for_encoded_id_slug)
user.slugged_encoded_id 
# => "john-doe--user_p5w9-z27j"

# Find a user by encoded ID
User.find_by_encoded_id("user_p5w9-z27j")
# => #<User id: 123, name: "John Doe">

# Find by just the hash part (without model annotation)
User.find_by_encoded_id("p5w9-z27j")
# => #<User id: 123, name: "John Doe">

# Find by slugged version too
User.find_by_encoded_id("john-doe--user_p5w9-z27j")
# => #<User id: 123, name: "John Doe">

Using in Routes

# In config/routes.rb
Rails.application.routes.draw do
  resources :users, param: :encoded_id
end

# In your controller
class UsersController < ApplicationController
  def show
    @user = User.find_by_encoded_id!(params[:encoded_id])
  end
end

# In your views, URL helpers will use encoded IDs
link_to "View User", user_path(user)
# => "/users/user_p5w9-z27j"

Optional Path Parameter Modules

To automatically use encoded IDs in URL helpers, include one of these modules:

# Use encoded IDs in URL helpers
class User < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::PathParam
end

# Or use slugged encoded IDs in URL helpers
class User < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::SluggedPathParam
  
  def name_for_encoded_id_slug
    full_name
  end
end

This will override to_param to return the encoded ID or slugged encoded ID, making URL helpers automatically use encoded IDs.

Optional Persistence Module

For better performance with frequent encoded ID lookups, you can persist encoded IDs:

# Generate migration for User model
rails generate encoded_id:rails:add_columns User

Then include the persistence module:

class User < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::Persists
end

Optional ActiveRecord Integration

For seamless integration with standard ActiveRecord finder methods:

class Product < ApplicationRecord
  include EncodedId::Rails::Model
  include EncodedId::Rails::ActiveRecordFinders
end

# Create a product
product = Product.create(name: "Example Product")
encoded_id = product.encoded_id  # => "product_p5w9-z27j"

# Now standard ActiveRecord methods work with encoded IDs
Product.find(encoded_id)           # => #<Product id: 1, name: "Example Product">
Product.find_by_id(encoded_id)     # => #<Product id: 1, name: "Example Product">
Product.where(id: encoded_id)      # => #<ActiveRecord::Relation [#<Product id: 1>]>

# In controllers, just use params[:id] directly
def show
  @product = Product.find(params[:id])  # Works with both regular IDs and encoded IDs
end

Important: This module should NOT be used with models that use string-based primary keys (like UUIDs).

Features in Detail

🔄 Encoded IDs are reversible (supports both HashIds and Sqids encoding engines)
💅 Support for slugged IDs that are URL friendly
🔖 Annotated IDs to help identify the model
👓 Human-readable IDs split into groups
👥 Support for multiple IDs encoded in one string
🛡️ Blocklist support to prevent certain words in encoded IDs
🔄 Seamless ActiveRecord integration for transparent handling of encoded IDs