rails-uuid-pk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e1ef0fefbc7527b8c728500ad6280dd8f3fd8ab1aaf3c7fe708b952c8bae326
+  data.tar.gz: db36f10be02bbac2fe2befb4993489a3b9ad346e4b798a0af1a885c89bd883f4
+SHA512:
+  metadata.gz: d16161f270f32d71e76cb02339954bf3abd378f1d6a652ebfde0f5ab85e44147a1216969dc5b9e47f1a25bc89a37487bdc63dd983d67941c4de0f53c325b699e
+  data.tar.gz: f4720b5cbd0d71bbdb78fd2157b09bbe6a886264f9b4460274a00cef3141ba18b6fa0c5afaf7b66354bffb2dc49ea92165f6729fe4c1c5c43f8b84985ca61232

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v1.0.0.html).
+
+## [0.1.0] - 2026-01-07
+
+### Added
+- Initial release with UUIDv7 primary key support for Rails applications
+- Automatic UUIDv7 generation using `SecureRandom.uuid_v7`
+- Railtie for automatic inclusion in all ActiveRecord models
+- Generator for installation and setup
+- Support for PostgreSQL and SQLite databases
+- Comprehensive test suite
+- AGENTS.md file for LLM coding agent guidance
+- Development section in README.md with setup and testing instructions

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Joon Lee
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+# rails-uuid-pk
+
+**Dead-simple UUIDv7 primary keys for modern Rails apps**  
+Works great with **PostgreSQL 18+** and **SQLite 3.51+** — zero extra extensions required.
+
+[![Gem Version](https://img.shields.io/gem/v/rails-uuid-pk.svg?style=flat-square)](https://rubygems.org/gems/rails-uuid-pk)
+[![Ruby](https://img.shields.io/badge/ruby-≥3.3-red.svg?style=flat-square)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-≥8.1-9650f9.svg?style=flat-square)](https://rubyonrails.org)
+
+## Why this gem?
+
+- Uses **native** `SecureRandom.uuid_v7` (Ruby 3.3+)
+- Automatically sets `:uuid` as default primary key type
+- Adds reliable `before_create` callback for UUIDv7 generation
+- Works perfectly on **both PostgreSQL 18+** and **SQLite** (and older PostgreSQL versions too)
+- Zero database extensions needed
+- Minimal and maintainable — no monkey-patching hell
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "rails-uuid-pk", "~> 0.1"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate rails_uuid_pk:install
+```
+
+The generator will:
+
+- Set `primary_key_type: :uuid` in your generators config
+- Create `app/models/concerns/has_uuidv7_primary_key.rb` (optional explicit include)
+- Show important compatibility notes
+
+## Usage
+
+After installation, **every new model** you generate will get a `uuid` primary key with automatic UUIDv7 values:
+
+```bash
+rails g model User name:string email:string
+# → creates id: :uuid with automatic uuidv7 generation
+```
+
+That's it! No changes needed in your models.
+
+```ruby
+# This works out of the box:
+User.create!(name: "Alice")  # ← id is automatically a proper UUIDv7
+```
+
+## Important Compatibility Notes
+
+### Action Text & Active Storage
+
+**These Rails engines do NOT automatically respect the `primary_key_type: :uuid` setting** when generating their install migrations.
+
+When you run:
+
+```bash
+rails action_text:install
+rails active_storage:install
+```
+
+You **MUST** manually edit the generated migration and change:
+
+```ruby
+t.references :record, null: false, polymorphic: true, index: false
+# to
+t.references :record, null: false, polymorphic: true, index: false, type: :uuid
+```
+
+Same applies to `active_storage_attachments.record_id`.
+
+**Without this change** you will get:
+
+- `PG::DatatypeMismatch` errors
+- Duplicate key violations on uniqueness indexes
+- Association failures
+
+This is a **long-standing Rails limitation** (still present in Rails 8+).  
+The gem shows a big warning during installation — but double-check every time you install these engines.
+
+### Other polymorphic associations
+
+Any **custom polymorphic** association you create manually should also explicitly use `type: :uuid` if the parent models use UUID primary keys.
+
+```ruby
+# Good
+has_many :comments, as: :commentable, foreign_key: { type: :uuid }
+
+# Risky (may cause type mismatch)
+has_many :comments, as: :commentable
+```
+
+## Features / Trade-offs
+
+| Feature                              | Status          | Notes                                                                 |
+|--------------------------------------|-----------------|-----------------------------------------------------------------------|
+| UUIDv7 generation                    | Automatic       | Uses `SecureRandom.uuid_v7` (very good randomness + monotonicity)     |
+| PostgreSQL 18+ native `uuidv7()`     | Not used        | Fallback approach — more universal, no extensions needed             |
+| SQLite support                       | Full            | No native function → app-side generation works great                  |
+| Index locality / performance         | Very good       | UUIDv7 is monotonic → almost as good as sequential IDs                |
+| Zero config after install            | Yes (mostly)    | Except Action Text / Active Storage migrations                        |
+| Works with Rails 7.1 – 8+            | Yes             | Tested conceptually up to Rails 8.1+                                  |
+
+## Why not use native PostgreSQL `uuidv7()`?
+
+While PostgreSQL 18+ has excellent native `uuidv7()` support, the **fallback approach** was chosen for maximum compatibility:
+
+- Works on SQLite without changes
+- Works on older PostgreSQL versions
+- No need to manage database extensions
+- Zero risk when switching databases or in CI/test environments
+
+You can still add native PostgreSQL defaults manually if you want maximum performance — the gem's fallback is safe and will simply be ignored.
+
+## Development
+
+### Devcontainer Setup
+
+This project includes a devcontainer configuration for VS Code. To get started:
+
+1. Open the project in VS Code
+2. When prompted, click "Reopen in Container" (or run `Dev Containers: Reopen in Container` from the command palette)
+3. The devcontainer will set up Ruby 3.3, Rails, and all dependencies automatically
+
+### Running Tests
+
+The project includes a comprehensive test suite that runs against both SQLite and PostgreSQL.
+
+```bash
+# Run all tests (SQLite + PostgreSQL)
+./bin/test
+
+# Run tests for specific database
+DB=sqlite ./bin/test      # SQLite only
+DB=postgres ./bin/test    # PostgreSQL only
+```
+
+### Code Quality
+
+```bash
+# Run RuboCop for style checking
+./bin/rubocop
+
+# Auto-fix RuboCop offenses
+./bin/rubocop -a
+```
+
+### Building the Gem
+
+```bash
+# Build the gem
+gem build rails_uuid_pk.gemspec
+
+# Install locally for testing
+gem install rails-uuid-pk-0.1.0.gem
+```
+
+### Database Setup
+
+For PostgreSQL testing, ensure PostgreSQL is running and accessible. The test suite uses these environment variables:
+- `DB_HOST` (defaults to localhost)
+- `RAILS_ENV=test_postgresql` for PostgreSQL tests
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/seouri/rails-uuid-pk.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/models/concerns/has_uuidv7_primary_key.rb

@@ -0,0 +1,17 @@
+# app/models/concerns/has_uuidv7_primary_key.rb
+# (this file is copied by the generator - you can modify it later if needed)
+
+module HasUuidv7PrimaryKey
+  extend ActiveSupport::Concern
+
+  included do
+    before_create :assign_uuidv7_if_needed, if: -> { id.nil? }
+  end
+
+  private
+
+  def assign_uuidv7_if_needed
+    return if id.present?
+    self.id = SecureRandom.uuid_v7
+  end
+end

data/lib/generators/rails_uuid_pk/install/install_generator.rb

@@ -0,0 +1,45 @@
+module RailsUuidPk
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs rails-uuid-pk: sets uuid primary key + includes UUIDv7 concern"
+
+      def add_concern_file
+        copy_file "has_uuidv7_primary_key.rb",
+                  "app/models/concerns/has_uuidv7_primary_key.rb"
+      end
+
+      def show_next_steps
+        say "\nrails-uuid-pk was successfully installed!", :green
+
+        say "\n⚠️  IMPORTANT - Action Text & Active Storage compatibility", :red
+        say "─────────────────────────────────────────────────────────────"
+        say "When you run any of these commands:"
+        say "  rails action_text:install"
+        say "  rails active_storage:install"
+        say ""
+        say "You **MUST** manually edit the generated migration and add:"
+        say ""
+        say "  t.references :record, null: false, polymorphic: true, index: false, type: :uuid"
+        say ""
+        say "Without this change you'll get type mismatch errors (bigint vs uuid)."
+        say "This is a Rails limitation - see Rails guides for details."
+        say "─────────────────────────────────────────────────────────────\n"
+
+        say "\nRecommended next steps:", :yellow
+        say "  1. Add to ApplicationRecord (if you prefer explicit include):"
+        say "     class ApplicationRecord < ActiveRecord::Base"
+        say "       primary_abstract_class"
+        say "       include HasUuidv7PrimaryKey"
+        say "     end\n"
+
+        say "  2. Or keep relying on Railtie automatic include (recommended for most cases)\n"
+
+        say "  3. Now you can run:", :cyan
+        say "     rails g model User name:string email:string\n"
+        say "     → will create table with uuid primary key + automatic uuidv7\n"
+      end
+    end
+  end
+end

data/lib/generators/rails_uuid_pk/install/templates/has_uuidv7_primary_key.rb

@@ -0,0 +1,17 @@
+# app/models/concerns/has_uuidv7_primary_key.rb
+# (this file is copied by the generator - you can modify it later if needed)
+
+module HasUuidv7PrimaryKey
+  extend ActiveSupport::Concern
+
+  included do
+    before_create :assign_uuidv7_if_needed, if: -> { id.nil? }
+  end
+
+  private
+
+  def assign_uuidv7_if_needed
+    return if id.present?
+    self.id = SecureRandom.uuid_v7
+  end
+end

data/lib/rails_uuid_pk/concern.rb

@@ -0,0 +1,18 @@
+module RailsUuidPk
+  module HasUuidv7PrimaryKey
+    extend ActiveSupport::Concern
+
+    included do
+      before_create :assign_uuidv7_if_needed, if: -> { id.nil? }
+    end
+
+    private
+
+    def assign_uuidv7_if_needed
+      # Skip if id was already set (manual set, bulk insert with ids, etc)
+      return if id.present?
+
+      self.id = SecureRandom.uuid_v7
+    end
+  end
+end

data/lib/rails_uuid_pk/railtie.rb

@@ -0,0 +1,40 @@
+module RailsUuidPk
+  class Railtie < ::Rails::Railtie
+    initializer "rails-uuid-pk.generators" do |app|
+      app.config.generators do |g|
+        g.orm :active_record, primary_key_type: :uuid
+      end
+    end
+
+    initializer "rails-uuid-pk.configure_database" do |app|
+      # For SQLite, use SQL schema format since schema.rb has issues with UUID types
+      if app.config.database_configuration&.dig(Rails.env, "adapter") == "sqlite3"
+        app.config.active_record.schema_format = :sql
+      end
+    end
+
+    initializer "rails-uuid-pk.include_concern" do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.include RailsUuidPk::HasUuidv7PrimaryKey
+      end
+    end
+
+    initializer "rails-uuid-pk.configure_type_map" do
+      ActiveSupport.on_load(:active_record) do
+        if ActiveRecord::Base.connection.adapter_name == "SQLite"
+          # Define a custom UUID type for SQLite that reports as :uuid
+          uuid_type = Class.new(ActiveRecord::Type::String) do
+            def type
+              :uuid
+            end
+          end.new
+
+          # Map 'uuid' SQL type to our custom UUID type
+          ActiveRecord::Base.connection.send(:type_map).register_type "uuid" do |sql_type|
+            uuid_type
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_uuid_pk/version.rb

@@ -0,0 +1,3 @@
+module RailsUuidPk
+  VERSION = "0.1.0"
+end

data/lib/rails_uuid_pk.rb

@@ -0,0 +1,6 @@
+require "rails_uuid_pk/version"
+require "rails_uuid_pk/concern"
+require "rails_uuid_pk/railtie"
+
+module RailsUuidPk
+end

data/lib/tasks/rails_uuid_pk_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_uuid_pk do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: rails-uuid-pk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joon Lee
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.3
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.9.0
+description: Automatically use UUIDv7 for all primary keys in Rails applications.
+  Works with PostgreSQL and SQLite, zero configuration required.
+email:
+- seouri@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/concerns/has_uuidv7_primary_key.rb
+- lib/generators/rails_uuid_pk/install/install_generator.rb
+- lib/generators/rails_uuid_pk/install/templates/has_uuidv7_primary_key.rb
+- lib/rails_uuid_pk.rb
+- lib/rails_uuid_pk/concern.rb
+- lib/rails_uuid_pk/railtie.rb
+- lib/rails_uuid_pk/version.rb
+- lib/tasks/rails_uuid_pk_tasks.rake
+homepage: https://github.com/seouri/rails-uuid-pk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seouri/rails-uuid-pk
+  source_code_uri: https://github.com/seouri/rails-uuid-pk
+  changelog_uri: https://github.com/seouri/rails-uuid-pk/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Dead-simple UUIDv7 primary keys for Rails apps
+test_files: []