OpaqueId

A simple Ruby gem for generating secure, opaque IDs for ActiveRecord models. OpaqueId provides a drop-in replacement for nanoid.rb using Ruby’s built-in SecureRandom methods, with slug-like IDs as the default for optimal URL safety and user experience.

• TOC

Features

• 🔐 Cryptographically Secure: Uses Ruby’s SecureRandom for secure ID generation
• ⚡ High Performance: Optimized algorithms with fast paths for 64-character alphabets
• 🎯 Collision-Free: Built-in collision detection with configurable retry attempts
• 🔧 Highly Configurable: Customizable alphabet, length, column name, and validation rules
• 🚀 Rails Integration: Seamless ActiveRecord integration with automatic ID generation
• 📦 Rails Generator: One-command setup with rails generate opaque_id:install
• 🧪 Well Tested: Comprehensive test suite with statistical uniformity tests
• 📚 Rails 8.0+ Compatible: Built for modern Rails applications

Quick Start

1. Add to your Gemfile

gem 'opaque_id'

2. Generate migration and update model

rails generate opaque_id:install User

3. Run migration

rails db:migrate

4. Use in your models

class User < ApplicationRecord
  include OpaqueId::Model
end

# Create a user - opaque_id is automatically generated
user = User.create!(name: "John Doe")
puts user.opaque_id # => "izkpm55j334u8x9y2a"

# Find by opaque_id
user = User.find_by_opaque_id("izkpm55j334u8x9y2a")

Why OpaqueId?

OpaqueId replaces the need for nanoid.rb by providing:

• Native Ruby implementation using SecureRandom
• Better performance with optimized algorithms
• Rails 8.0+ compatibility out of the box
• ActiveRecord integration with automatic ID generation
• Collision handling with configurable retry attempts
• Flexible configuration for different use cases

Installation

Requirements

• Ruby 3.2+
• Rails 8.0+
• ActiveRecord 8.0+

Using Bundler (Recommended)

Add this line to your application’s Gemfile:

gem 'opaque_id'

And then execute:

bundle install

Manual Installation

gem install opaque_id

Getting Started

Ready to get started? Check out our Getting Started Guide for a comprehensive walkthrough.

Documentation

• Getting Started - Quick setup and basic usage
• Installation - Detailed installation guide
• Usage - Comprehensive usage examples
• Configuration - All configuration options
• Alphabets - Built-in alphabets and custom options
• Algorithms - Technical algorithm details
• Performance - Benchmarks and optimization tips
• Security - Security considerations and best practices
• Use Cases - Real-world examples and applications
• API Reference - Complete API documentation
• Development - Contributing and development setup

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

This project follows an “open source, closed contribution” model. We welcome bug reports, feature requests, and documentation improvements through GitHub Issues.

Performance & Benchmarks

You can run benchmarks to test OpaqueId’s performance and uniqueness characteristics on your system.

Quick Test:

# Test 10,000 ID generation
ruby -e "require 'opaque_id'; start=Time.now; 10000.times{OpaqueId.generate}; puts \"Generated 10,000 IDs in #{(Time.now-start).round(4)}s\""

Expected Results:

• Performance: 100,000+ IDs per second on modern hardware
• Uniqueness: Zero collisions in practice (theoretical probability < 10^-16 for 1M IDs)

For comprehensive benchmarks including collision tests, alphabet distribution analysis, and performance comparisons, see the Benchmarks Guide.

Acknowledgements

• nanoid.rb - Original inspiration and reference implementation
• NanoID - The original JavaScript implementation
• PlanetScale Article by Mike Coutermarsh - Excellent explanation of opaque ID benefits