rails-uuid-pk

Dead-simple UUIDv7 primary keys for modern Rails apps

Automatically use UUID v7 for all primary keys in Rails applications. Works with PostgreSQL, MySQL, and SQLite — zero configuration required. Just add the gem and you're done!

• Uses native SecureRandom.uuid_v7 (Ruby 3.3+)
• Automatically sets :uuid as default primary key type
• Works perfectly on PostgreSQL, MySQL, and SQLite
• Zero database extensions needed
• Production-ready logging for debugging and monitoring

Add to your Gemfile:

gem "rails-uuid-pk", "~> 0.11"

Then run:

bundle install

That's it! The gem automatically enables UUIDv7 primary keys for all your models.

After installation, every new model automatically gets a uuid primary key with UUIDv7 values:

rails g model User name:string email:string
# → creates id: :uuid with automatic uuidv7 generation

# This works out of the box:
User.create!(name: "Alice")  # ← id is automatically a proper UUIDv7

For specific models, you can opt out:

class LegacyModel < ApplicationRecord
  use_integer_primary_key
  # Uses integer auto-incrementing primary key instead of UUIDv7
end

# Migration must also use :integer
create_table :legacy_models, id: :integer do |t|
  t.string :name
end

Migration helpers automatically detect mixed primary key types and set appropriate foreign key types:

# Rails will automatically use integer foreign keys when referencing LegacyModel
create_table :related_records do |t|
  t.references :legacy_model, null: false  # → integer foreign key
  t.references :user, null: false          # → UUID foreign key (User uses UUIDs)
end

When installing Action Text or Active Storage, migrations automatically integrate with UUID primary keys - no changes needed.

Polymorphic associations work seamlessly with UUID primary keys. Foreign key types are automatically detected.

UUIDv7 provides excellent performance with monotonic ordering and reduced index fragmentation compared to UUIDv4.

• Generation: ~800,000 UUIDs/second with cryptographic security
• Storage: Native UUID (16B) on PostgreSQL, VARCHAR(36) on MySQL/SQLite
• Index Performance: Better locality than random UUIDs

For detailed performance analysis and optimization guides, see PERFORMANCE.md.

For architecture decisions and design rationale, see ARCHITECTURE.md.

See DEVELOPMENT.md for setup instructions, testing, and contribution guidelines.

For security considerations and vulnerability reporting, see SECURITY.md.

Bug reports and pull requests welcome on GitHub. See DEVELOPMENT.md for contribution guidelines.

MIT License - see MIT-LICENSE for details.