rails-uuid-pk 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e1ef0fefbc7527b8c728500ad6280dd8f3fd8ab1aaf3c7fe708b952c8bae326
-  data.tar.gz: db36f10be02bbac2fe2befb4993489a3b9ad346e4b798a0af1a885c89bd883f4
+  metadata.gz: d9552cdab44f5a5a6a4b699e12dc31ee13917ff74f0752f32e823dffed24e2e0
+  data.tar.gz: 6ddd7862945d8b13939be92990241539d93eaf754d6c47f2733d66eb2e29597e
 SHA512:
-  metadata.gz: d16161f270f32d71e76cb02339954bf3abd378f1d6a652ebfde0f5ab85e44147a1216969dc5b9e47f1a25bc89a37487bdc63dd983d67941c4de0f53c325b699e
-  data.tar.gz: f4720b5cbd0d71bbdb78fd2157b09bbe6a886264f9b4460274a00cef3141ba18b6fa0c5afaf7b66354bffb2dc49ea92165f6729fe4c1c5c43f8b84985ca61232
+  metadata.gz: 72fb9c050567562c0d01793d801d7633d45b26851734cb069b2e70ee74d8bf3387e515f50cb771fdbb46f8ad9b4cb767058739bad45050134ba710a8f6290201
+  data.tar.gz: ed3b396026fe6edc6485720d6d80af4d5fd11138652fea133515fcb8d931d9d38cf981553a46689121201922ee41b6fad5829c42c06783109b930b06acf41fda

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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
+- SQLite schema dumping support for UUID primary keys using Ruby format
+- Custom UUID type implementation for ActiveRecord type casting and validation
+- SQLite3 adapter extension for native UUID database type definitions
+
+### Changed
+- Switched SQLite schema format from SQL to Ruby for improved compatibility and standard Rails behavior
+- Updated test suite to expect Ruby schema format for SQLite databases
+
 ## [0.1.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

@@ -6,34 +6,50 @@ module RailsUuidPk
       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
+    initializer "rails-uuid-pk.configure_type_map", after: "active_record.initialize_database" do
+      ActiveSupport.on_load(:active_record) do
+        if ActiveRecord::Base.connection.adapter_name == "SQLite"
+          # Register the UUID type with ActiveRecord
+          ActiveRecord::Type.register(:uuid, RailsUuidPk::Type::Uuid, adapter: :sqlite3)
+
+          # Map varchar SQL type to our custom UUID type (since that's how UUID columns are stored in SQLite)
+          ActiveRecord::Base.connection.send(:type_map).register_type(/varchar/i) do |sql_type|
+            RailsUuidPk::Type::Uuid.new
+          end
+
+          # Also map "uuid" SQL type to our custom UUID type for direct lookups
+          ActiveRecord::Base.connection.send(:type_map).register_type "uuid" do |sql_type|
+            RailsUuidPk::Type::Uuid.new
+          end
+        end
       end
     end
 
+    initializer "rails-uuid-pk.native_types" do
+      require "active_record/connection_adapters/sqlite3_adapter"
+      ActiveRecord::ConnectionAdapters::SQLite3Adapter.prepend(RailsUuidPk::Sqlite3AdapterExtension)
+    end
+
+
+
+    initializer "rails-uuid-pk.schema_format" do |app|
+      # Ensure schema_format is set to :ruby for SQLite (default in Rails)
+      app.config.active_record.schema_format ||= :ruby
+    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
+    initializer "rails-uuid-pk.migration_helpers" 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
+        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

data/lib/rails_uuid_pk/sqlite3_adapter_extension.rb

@@ -0,0 +1,9 @@
+module RailsUuidPk
+  module Sqlite3AdapterExtension
+    def native_database_types
+      super.merge(
+        uuid: { name: "varchar", limit: 36 }
+      )
+    end
+  end
+end

data/lib/rails_uuid_pk/type.rb

@@ -0,0 +1,47 @@
+module RailsUuidPk
+  module Type
+    class Uuid < ActiveRecord::Type::String
+      def type
+        # Return :string during schema dumping to avoid "Unknown type 'uuid'" errors
+        # Return :uuid for normal operation and tests
+        if caller.any? { |c| c.include?("schema_dumper") }
+          :string
+        else
+          :uuid
+        end
+      end
+
+      def deserialize(value)
+        return if value.nil?
+        cast(value)
+      end
+
+      def cast(value)
+        return if value.nil?
+        return value if value.is_a?(String) && valid?(value)
+
+        if value.respond_to?(:to_s)
+          str = value.to_s
+          return str if valid?(str)
+        end
+
+        # Allow invalid UUIDs to be stored (for backward compatibility and manual id assignment)
+        value.to_s
+      end
+
+      def serialize(value)
+        cast(value)
+      end
+
+      def changed_in_place?(raw_old_value, new_value)
+        cast(raw_old_value) != cast(new_value)
+      end
+
+      private
+
+      def valid?(value)
+        value.match?(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+      end
+    end
+  end
+end

data/lib/rails_uuid_pk/version.rb

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

data/lib/rails_uuid_pk.rb

@@ -1,5 +1,7 @@
 require "rails_uuid_pk/version"
 require "rails_uuid_pk/concern"
+require "rails_uuid_pk/type"
+require "rails_uuid_pk/sqlite3_adapter_extension"
 require "rails_uuid_pk/railtie"
 
 module RailsUuidPk

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-uuid-pk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Joon Lee
@@ -68,7 +68,10 @@ 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
 - lib/rails_uuid_pk/version.rb
 - lib/tasks/rails_uuid_pk_tasks.rake
 homepage: https://github.com/seouri/rails-uuid-pk