rails-uuid-pk 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a1e3ae77afb9d7050fab7a90ea7596b18894cb00006e36e0dd391bc3a1b1194
-  data.tar.gz: b28a4b0918db5a7285ad8db6af0e0243a862f781c6476daf1954c282b97475ae
+  metadata.gz: 3eb01e2f1dc8ef76a90110c9d6ef882f79cfc6584395129046d404f116be94e3
+  data.tar.gz: 7aa3b43c50beb54b037428f0abf36f4df642968eb0ba368bfe57328bcea2f8cf
 SHA512:
-  metadata.gz: 63f0882a6e7e8f50b35811b81b9efbd75a25ebaa7eadf2b20a75610a14eeb25a4e10635bd39565756d428585609989aabf418dd5486bc361199f49d0fa9eaffb
-  data.tar.gz: 7055f26c0c87e83e3af48e3cb08b75cc2582af0de4c3c5706af1ca595468bbf77ba4fa3a9eddc2da05c4f471233c5d1d3debfed2cb0e935ecd1679fb41b97d51
+  metadata.gz: '09b2676618355ede8b113e7693e8c1673e1f8c32888f0027ab97fd82c81713af5b2f55b995d565f4445465c8c27ce53c4a42fe4f2247017e6c2cf4a0083af9e7'
+  data.tar.gz: 967f36d838dfd8e649a8674cce0a29642f39ee0e1a45dc70c4f66a1597abf65591c71cb434d97fb21affccf337337a04f2602e9fe470d43a464f3b5c2eca2298

data/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.4.0] - 2026-01-10
+
+### Added
+- **MySQL 8.0+ support**: Full MySQL compatibility with VARCHAR(36) UUID storage
+- MySQL2 adapter extension for native database type mappings
+- MySQL-specific type handling and schema dumping support
+- Comprehensive MySQL test suite with performance and edge case testing
+- CI pipeline support for MySQL 8.0 testing
+- Updated documentation to include MySQL setup and compatibility notes
+
+### Changed
+- Updated project description to reflect support for PostgreSQL, MySQL, and SQLite
+- Enhanced test runner to support all three database adapters
+- Updated development environment setup to include MySQL configuration
+- Expanded database coverage from 2 to 3 major Rails database adapters
+
+### Technical Details
+- Added `lib/rails_uuid_pk/mysql2_adapter_extension.rb` for MySQL adapter integration
+- Extended Railtie with MySQL-specific type mappings and adapter detection
+- Enhanced migration helpers compatibility with MySQL VARCHAR(36) column detection
+- Added MySQL performance testing (bulk operations, concurrent access, memory efficiency)
+- Implemented MySQL edge case testing (long table names, special characters)
+- Updated CI workflow with MySQL 8.0 service configuration
+
+## [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

@@ -1,7 +1,7 @@
 # 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.
+Works great with **PostgreSQL 18+**, **MySQL 8.0+**, 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)
@@ -12,7 +12,10 @@ Works great with **PostgreSQL 18+** and **SQLite 3.51+** — zero extra extensio
 - 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)
+- Works perfectly on **PostgreSQL 18+**, **MySQL 8.0+**, and **SQLite** (and older versions too)
+- **PostgreSQL**: Uses native `UUID` column types with full database support
+- **MySQL**: Uses `VARCHAR(36)` with custom ActiveRecord type handling
+- **SQLite**: Uses `VARCHAR(36)` with custom ActiveRecord type handling
 - Zero database extensions needed
 - Minimal and maintainable — no monkey-patching hell
 
@@ -21,7 +24,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 +60,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,46 +67,36 @@ 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                                                                 |
 |--------------------------------------|-----------------|-----------------------------------------------------------------------|
 | 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                  |
+| PostgreSQL support                   | Full            | Native `UUID` column types with full database support                |
+| MySQL 8.0+ support                   | Full            | Uses `VARCHAR(36)` with custom ActiveRecord type handling            |
+| SQLite support                       | Full            | Uses `VARCHAR(36)` with custom ActiveRecord type handling            |
 | 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()`?
@@ -131,15 +122,16 @@ This project includes a devcontainer configuration for VS Code. To get started:
 
 ### Running Tests
 
-The project includes a comprehensive test suite that runs against both SQLite and PostgreSQL.
+The project includes a comprehensive test suite that runs against SQLite, PostgreSQL, and MySQL.
 
 ```bash
-# Run all tests (SQLite + PostgreSQL)
+# Run all tests (SQLite + PostgreSQL + MySQL)
 ./bin/test
 
 # Run tests for specific database
 DB=sqlite ./bin/test      # SQLite only
 DB=postgres ./bin/test    # PostgreSQL only
+DB=mysql ./bin/test       # MySQL only
 ```
 
 ### Code Quality
@@ -164,9 +156,10 @@ 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:
+For database testing, ensure the respective databases are running and accessible. The test suite uses these environment variables:
 - `DB_HOST` (defaults to localhost)
 - `RAILS_ENV=test_postgresql` for PostgreSQL tests
+- `RAILS_ENV=test_mysql` for MySQL tests
 
 ## Contributing
 

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/mysql2_adapter_extension.rb

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

data/lib/rails_uuid_pk/railtie.rb

@@ -17,6 +17,19 @@ module RailsUuidPk
             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
+        elsif ActiveRecord::Base.connection.adapter_name == "MySQL"
+          # Register the UUID type with ActiveRecord for MySQL
+          ActiveRecord::Type.register(:uuid, RailsUuidPk::Type::Uuid, adapter: :mysql2)
+
+          # Map varchar SQL type to our custom UUID type (since that's how UUID columns are stored in MySQL)
+          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
@@ -30,6 +43,15 @@ module RailsUuidPk
       ActiveRecord::ConnectionAdapters::SQLite3Adapter.prepend(RailsUuidPk::Sqlite3AdapterExtension)
     end
 
+    initializer "rails-uuid-pk.mysql_native_types" do
+      begin
+        require "active_record/connection_adapters/mysql2_adapter"
+        ActiveRecord::ConnectionAdapters::Mysql2Adapter.prepend(RailsUuidPk::Mysql2AdapterExtension)
+      rescue LoadError
+        # MySQL adapter not available, skip MySQL-specific initialization
+      end
+    end
+
 
 
     initializer "rails-uuid-pk.schema_format" do |app|
@@ -42,5 +64,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.4.0"
 end

data/lib/rails_uuid_pk.rb

@@ -2,6 +2,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/mysql2_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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Joon Lee
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.7
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -51,8 +65,8 @@ dependencies:
     - - "~>"
       - !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.
+description: Automatically use UUID v7 for all primary keys in Rails applications.
+  Works with PostgreSQL, MySQL, and SQLite, zero configuration required.
 email:
 - seouri@gmail.com
 executables: []
@@ -68,6 +82,8 @@ 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/mysql2_adapter_extension.rb
 - lib/rails_uuid_pk/railtie.rb
 - lib/rails_uuid_pk/sqlite3_adapter_extension.rb
 - lib/rails_uuid_pk/type.rb
@@ -96,5 +112,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Dead-simple UUIDv7 primary keys for Rails apps
+summary: Dead-simple UUID v7 primary keys for Rails apps
 test_files: []