rails-uuid-pk 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a1e3ae77afb9d7050fab7a90ea7596b18894cb00006e36e0dd391bc3a1b1194
-  data.tar.gz: b28a4b0918db5a7285ad8db6af0e0243a862f781c6476daf1954c282b97475ae
+  metadata.gz: d9552cdab44f5a5a6a4b699e12dc31ee13917ff74f0752f32e823dffed24e2e0
+  data.tar.gz: 6ddd7862945d8b13939be92990241539d93eaf754d6c47f2733d66eb2e29597e
 SHA512:
-  metadata.gz: 63f0882a6e7e8f50b35811b81b9efbd75a25ebaa7eadf2b20a75610a14eeb25a4e10635bd39565756d428585609989aabf418dd5486bc361199f49d0fa9eaffb
-  data.tar.gz: 7055f26c0c87e83e3af48e3cb08b75cc2582af0de4c3c5706af1ca595468bbf77ba4fa3a9eddc2da05c4f471233c5d1d3debfed2cb0e935ecd1679fb41b97d51
+  metadata.gz: 72fb9c050567562c0d01793d801d7633d45b26851734cb069b2e70ee74d8bf3387e515f50cb771fdbb46f8ad9b4cb767058739bad45050134ba710a8f6290201
+  data.tar.gz: ed3b396026fe6edc6485720d6d80af4d5fd11138652fea133515fcb8d931d9d38cf981553a46689121201922ee41b6fad5829c42c06783109b930b06acf41fda

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.3.0] - 2026-01-09
+
+### Added
+- Migration helpers that automatically detect and set UUID foreign key types
+- Smart `references` method that inspects database schema to determine primary key types
+- Automatic UUID type assignment for polymorphic associations when using global UUID primary keys
+- Comprehensive test coverage for migration helper functionality
+
+### Changed
+- Eliminated need for manual editing of Action Text and Active Storage migrations
+- Updated install generator message to reflect automatic foreign key type handling
+- Updated README.md to document the improved zero-config experience
+- Changed "Zero config after install" status from "Yes (mostly)" to "Yes"
+
+### Removed
+- Manual migration editing requirement for Action Text & Active Storage compatibility
+
 ## [0.2.0] - 2026-01-07
 
 ### Added

data/README.md

@@ -13,6 +13,8 @@ Works great with **PostgreSQL 18+** and **SQLite 3.51+** — zero extra extensio
 - 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)
+- **PostgreSQL**: Uses native `UUID` column types with full database support
+- **SQLite**: Uses `VARCHAR(36)` with custom ActiveRecord type handling
 - Zero database extensions needed
 - Minimal and maintainable — no monkey-patching hell
 
@@ -21,7 +23,7 @@ Works great with **PostgreSQL 18+** and **SQLite 3.51+** — zero extra extensio
 Add to your `Gemfile`:
 
 ```ruby
-gem "rails-uuid-pk", "~> 0.1"
+gem "rails-uuid-pk", "~> 0.3"
 ```
 
 Then run:
@@ -57,8 +59,6 @@ User.create!(name: "Alice")  # ← id is automatically a proper UUIDv7
 
 ### 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
@@ -66,37 +66,25 @@ 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:
+The generated migrations will **automatically use the correct foreign key types** when referencing tables with UUID primary keys. No manual editing required!
 
-- `PG::DatatypeMismatch` errors
-- Duplicate key violations on uniqueness indexes
-- Association failures
+This works because rails-uuid-pk includes smart migration helpers that detect the primary key type of referenced tables and automatically set `type: :uuid` for foreign keys.
 
-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.
+### Polymorphic associations
 
-### Other polymorphic associations
+**Polymorphic associations** (like Action Text's `record` references) will automatically use the correct foreign key type based on the referenced table's primary key. If the parent model uses UUID primary keys, the foreign key will be UUID type.
 
-Any **custom polymorphic** association you create manually should also explicitly use `type: :uuid` if the parent models use UUID primary keys.
+For **custom polymorphic associations**, the migration helpers will also automatically detect and set the correct type:
 
 ```ruby
-# Good
-has_many :comments, as: :commentable, foreign_key: { type: :uuid }
-
-# Risky (may cause type mismatch)
-has_many :comments, as: :commentable
+# This will automatically use type: :uuid if the parent models have UUID primary keys
+create_table :comments do |t|
+  t.references :commentable, polymorphic: true
+end
 ```
 
+No manual `type: :uuid` specification needed!
+
 ## Features / Trade-offs
 
 | Feature                              | Status          | Notes                                                                 |
@@ -105,7 +93,7 @@ has_many :comments, as: :commentable
 | 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                        |
+| Zero config after install            | Yes             | Migration helpers automatically handle foreign key types             |
 | Works with Rails 7.1 – 8+            | Yes             | Tested conceptually up to Rails 8.1+                                  |
 
 ## Why not use native PostgreSQL `uuidv7()`?

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

@@ -13,18 +13,15 @@ module RailsUuidPk
       def show_next_steps
         say "\nrails-uuid-pk was successfully installed!", :green
 
-        say "\n⚠️  IMPORTANT - Action Text & Active Storage compatibility", :red
+        say "\n✅ Action Text & Active Storage compatibility", :green
         say "─────────────────────────────────────────────────────────────"
-        say "When you run any of these commands:"
+        say "Migration helpers now automatically handle foreign key types!"
+        say "When you run:"
         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 "The generated migrations will automatically use the correct UUID types"
+        say "for foreign keys. No manual editing required!"
         say "─────────────────────────────────────────────────────────────\n"
 
         say "\nRecommended next steps:", :yellow

data/lib/rails_uuid_pk/migration_helpers.rb

@@ -0,0 +1,45 @@
+module RailsUuidPk
+  module MigrationHelpers
+    module References
+      def references(*args, **options)
+        ref_name = args.first
+        ref_table = options.delete(:to_table) || ref_name.to_s.pluralize
+
+        # Only set UUID type if not already explicitly set by user
+        # Rails sets type: :integer by default, so we override that
+        # But if user explicitly set a different type, we respect it
+        if (uuid_primary_key?(ref_table) || (options[:polymorphic] && application_uses_uuid_primary_keys?)) && options[:type] == :integer
+          options[:type] = :uuid
+        end
+
+        super
+      end
+
+      def application_uses_uuid_primary_keys?
+        # Check if the application is configured to use UUID primary keys globally
+        Rails.application.config.generators.options[:active_record]&.[](:primary_key_type) == :uuid
+      end
+
+      alias_method :belongs_to, :references
+
+      private
+
+      def uuid_primary_key?(table_name)
+        conn = @conn || @base || (respond_to?(:connection) ? connection : nil)
+        return false unless conn&.table_exists?(table_name)
+
+        pk_column = find_primary_key_column(table_name, conn)
+        return false unless pk_column
+
+        pk_column.sql_type.downcase.match?(/\A(uuid|varchar\(36\))\z/)
+      end
+
+      def find_primary_key_column(table_name, conn)
+        pk_name = conn.primary_key(table_name)
+        return nil unless pk_name
+
+        conn.columns(table_name).find { |c| c.name == pk_name }
+      end
+    end
+  end
+end

data/lib/rails_uuid_pk/railtie.rb

@@ -42,5 +42,15 @@ module RailsUuidPk
         ActiveRecord::Base.include RailsUuidPk::HasUuidv7PrimaryKey
       end
     end
+
+    initializer "rails-uuid-pk.migration_helpers" do
+      ActiveSupport.on_load(:active_record) do
+        require "rails_uuid_pk/migration_helpers"
+
+        # Include migration helpers for all database adapters
+        ActiveRecord::ConnectionAdapters::TableDefinition.prepend(RailsUuidPk::MigrationHelpers::References)
+        ActiveRecord::ConnectionAdapters::Table.prepend(RailsUuidPk::MigrationHelpers::References)
+      end
+    end
   end
 end

data/lib/rails_uuid_pk/version.rb

@@ -1,3 +1,3 @@
 module RailsUuidPk
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-uuid-pk
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Joon Lee
@@ -68,6 +68,7 @@ files:
 - 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/migration_helpers.rb
 - lib/rails_uuid_pk/railtie.rb
 - lib/rails_uuid_pk/sqlite3_adapter_extension.rb
 - lib/rails_uuid_pk/type.rb