Installation

This guide covers all installation methods for OpaqueId, from basic setup to advanced configurations.

• TOC

Requirements

Before installing OpaqueId, ensure your environment meets these requirements:

System Requirements

• Ruby 3.2+ - OpaqueId uses modern Ruby features and requires Ruby 3.2 or higher
• Rails 8.0+ - Built specifically for Rails 8.0 and later versions
• ActiveRecord 8.0+ - For model integration and generator functionality

Database Requirements

• Any ActiveRecord-supported database - SQLite, PostgreSQL, MySQL, etc.
• Database permissions - Ability to create tables and indexes

Installation Methods

Method 1: Using Bundler (Recommended)

This is the recommended approach for Rails applications.

Step 1: Add to Gemfile

Add OpaqueId to your application’s Gemfile:

# Gemfile
gem 'opaque_id'

Step 2: Install Dependencies

Run bundle install to install the gem and its dependencies:

bundle install

Step 3: Generate Setup

Use the Rails generator to set up OpaqueId for your models:

# For a User model
rails generate opaque_id:install User

# For multiple models
rails generate opaque_id:install User
rails generate opaque_id:install Post
rails generate opaque_id:install Comment

Step 4: Run Migrations

Execute the generated migrations:

rails db:migrate

Method 2: Manual Installation

If you prefer manual installation or need more control over the setup process.

Step 1: Install the Gem

gem install opaque_id

Step 2: Create Migration Manually

Create a migration file:

rails generate migration AddOpaqueIdToUsers opaque_id:string:uniq

Step 3: Edit Migration

Update the migration file:

# db/migrate/YYYYMMDDHHMMSS_add_opaque_id_to_users.rb
class AddOpaqueIdToUsers < ActiveRecord::Migration[8.0]
  def change
    add_column :users, :opaque_id, :string
    add_index :users, :opaque_id, unique: true
  end
end

Step 4: Update Model

Manually include the concern in your model:

# app/models/user.rb
class User < ApplicationRecord
  include OpaqueId::Model
end

Step 5: Run Migration

rails db:migrate

Method 3: From Source

For development or if you need the latest features.

Step 1: Clone Repository

git clone https://github.com/nyaggah/opaque_id.git
cd opaque_id

Step 2: Build and Install

gem build opaque_id.gemspec
gem install opaque_id-*.gem

Step 3: Add to Gemfile

# Gemfile
gem 'opaque_id', path: '/path/to/opaque_id'

Step 4: Install Dependencies

bundle install

Generator Options

The Rails generator supports several options for customization:

Basic Usage

rails generate opaque_id:install ModelName

Custom Column Name

rails generate opaque_id:install User --column-name=public_id

This will:

• Create a public_id column instead of opaque_id
• Add self.opaque_id_column = :public_id to your model

Multiple Models

rails generate opaque_id:install User
rails generate opaque_id:install Post --column-name=slug
rails generate opaque_id:install Comment

Post-Installation Setup

Verify Installation

Check that everything is working correctly:

# In Rails console
rails console

# Test basic functionality
user = User.create!(name: "Test User")
puts user.opaque_id
# => Should output a 21-character alphanumeric string

# Test finder methods
found_user = User.find_by_opaque_id(user.opaque_id)
puts found_user.name
# => "Test User"

Configure Global Settings (Optional)

Create an initializer for global configuration:

# config/initializers/opaque_id.rb
OpaqueId.configure do |config|
  config.default_length = 15
  config.default_alphabet = OpaqueId::STANDARD_ALPHABET
end

Troubleshooting

Common Installation Issues

Issue: Generator Not Found

Error: Could not find generator 'opaque_id:install'

Solution: Ensure the gem is properly installed and bundled:

bundle install
bundle exec rails generate opaque_id:install User

Issue: Migration Fails

Error: ActiveRecord::StatementInvalid or similar database errors

Solution: Check your database permissions and Rails version:

# Check Rails version
rails --version

# Check database connection
rails db:version

Issue: Model Not Updated

Error: Generator runs but model file isn’t updated

Solution: Check file permissions and ensure the model file exists:

# Check if model file exists
ls app/models/user.rb

# Check file permissions
ls -la app/models/user.rb

Issue: Bundle Install Fails

Error: Dependency conflicts or version issues

Solution: Update your Gemfile and run bundle update:

bundle update
bundle install

Version Compatibility

Ruby Version Issues

If you’re using an older Ruby version:

# Check Ruby version
ruby --version

# Update Ruby (using rbenv)
rbenv install 3.2.0
rbenv local 3.2.0

Rails Version Issues

If you’re using an older Rails version:

# Check Rails version
rails --version

# Update Rails
bundle update rails

Database-Specific Issues

PostgreSQL

Ensure you have the correct PostgreSQL adapter:

# Gemfile
gem 'pg', '~> 1.1'

MySQL

Ensure you have the correct MySQL adapter:

# Gemfile
gem 'mysql2', '~> 0.5'

SQLite

SQLite should work out of the box with Rails:

# Gemfile
gem 'sqlite3', '~> 1.4'

Uninstallation

If you need to remove OpaqueId from your application:

Step 1: Remove from Gemfile

# Gemfile
# gem 'opaque_id'  # Comment out or remove this line

Step 2: Remove Dependencies

bundle install

Step 3: Remove Migrations (Optional)

If you want to remove the opaque_id columns:

rails generate migration RemoveOpaqueIdFromUsers opaque_id:string
rails db:migrate

Step 4: Remove Model Code

Remove the include statement from your models:

# app/models/user.rb
class User < ApplicationRecord
  # include OpaqueId::Model  # Comment out or remove this line
end

Next Steps

After successful installation:

1. Read the Getting Started Guide for basic usage
2. Explore Configuration for advanced setup
3. Check out Use Cases for real-world usage patterns
4. Review API Reference for complete documentation

Support

If you encounter issues during installation:

1. Check the troubleshooting section above
2. Review the GitHub Issues for similar problems
3. Open a new issue with details about your environment and the error