rails-uuid-pk 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c8d9367ce6e034ff5ecc94e41e482b38e56f0886fd7cbbcb73a43bd948e3f96
-  data.tar.gz: 972cf5ee47c2c0ca1120decb6f35e16da2e62d9b2e2d2cee8b171fb883bdc003
+  metadata.gz: 0ef202d7fd8ed44687383011c2306cdafc16fc9a05505270c270a753d4fd4a33
+  data.tar.gz: fd9416e86ae299c7d693fcba9bc0e71d179940cd4e1e29dbd4bfc892e30e0248
 SHA512:
-  metadata.gz: fd95a444a62a9b337c0c6033530fe75db6e0873750bb8e43f1ac47a6bfdee4443b5139c9f79aa4b432752fcfdd54a32adfca598e6a1dfe5669b8085c2eb2b7cf
-  data.tar.gz: ad6c1eb9f0fed6a62b15930fca2a1e67b09d0c4940314f5fca8032e130637619105159b49f5dd37e96ceb2ccff7ad057ff30b81ae044a2d864e752dec748dde3
+  metadata.gz: 4f675cb556f985b0060cc34297182d5dbe1860a05cce42ce1b8de62e4b5f4ea89b07ae84669615dbb109d6f4c4bc0779c6a90bcaf9b0af3cc1b8d42b8588f8cc
+  data.tar.gz: 9ac0c2032a0036bc9a5a7441391f30b3991c0557446605ac1bb9b35a100e8fdb9cad565443536ef4b833f3c7c0793ff085b51996e1d75a5e018472ff4edd92af

data/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.12.0] - 2026-01-17
+
+### Changed
+- **Refactored Database Adapter Extensions**: Eliminated 152 lines of duplicated code (97% similarity) between MySQL and SQLite adapter extensions by introducing a shared `UuidAdapterExtension` module
+  - Created `lib/rails_uuid_pk/uuid_adapter_extension.rb` with common UUID type support functionality
+  - Refactored `Mysql2AdapterExtension` and `Sqlite3AdapterExtension` to include the shared module
+  - Maintained SQLite-specific transaction-aware connection configuration while standardizing all other UUID handling logic
+  - Improved code maintainability and reduced duplication from 156 lines to 99 lines total (37% reduction)
+
+### Technical Details
+- Added shared `UuidAdapterExtension` module containing `native_database_types`, `valid_type?`, `register_uuid_types`, `initialize_type_map`, `configure_connection`, and `type_to_dump` methods
+- Updated `Mysql2AdapterExtension` to include shared module with minimal override for `configure_connection`
+- Updated `Sqlite3AdapterExtension` to include shared module while preserving transaction-aware `configure_connection` implementation
+- Added require statement for new shared module in main library file
+- All existing functionality preserved with identical test suite results (119 tests, 0 failures, 0 errors)
+
+## [0.11.0] - 2026-01-16
+
+### Added
+- **`use_integer_primary_key` opt-out functionality**: Added ability to opt out of automatic UUIDv7 primary key generation for specific models
+  - New `use_integer_primary_key` class method allows models to use traditional integer auto-incrementing primary keys
+  - **Important**: When opting out, developers must modify the generated migration to change `id: :uuid` to `id: :integer` for the table schema
+  - Migration helpers automatically detect mixed primary key types and set appropriate foreign key types
+  - Comprehensive test coverage for opt-out behavior and mixed primary key scenarios
+  - Full interoperability between UUID and integer primary key models
+  - Updated documentation with opt-out usage examples
+
+### Documentation
+- **README Minimization**: Streamlined README.md from ~250 to 112 lines (55% reduction) by moving development content to dedicated DEVELOPMENT.md
+- **DEVELOPMENT.md**: Created comprehensive development guide covering setup, testing, contribution guidelines, and project structure
+- **AGENTS.md Enhancement**: Added prominent "Documentation Maintenance" section with critical instructions for keeping all documentation files (AGENTS.md, ARCHITECTURE.md, CHANGELOG.md, DEVELOPMENT.md, PERFORMANCE.md, README.md, SECURITY.md) up-to-date
+- **Improved Documentation Organization**: Better separation of user-facing and developer-facing content with proper cross-references
+
+### Technical Details
+- Added `ClassMethods` module to `RailsUuidPk::HasUuidv7PrimaryKey` with `use_integer_primary_key` and `uses_uuid_primary_key?` methods
+- Modified callback condition to check `self.class.uses_uuid_primary_key?` for opt-out support
+- Enhanced migration helpers to handle mixed UUID/integer primary key environments
+- **Refactored logger initialization**: Simplified `RailsUuidPk.logger` method from multiple redundant assignments to single `||=` expression for improved readability and maintainability
+- Added comprehensive unit tests in `test/uuid/opt_out_test.rb` covering:
+  - Opt-out method functionality and flag setting
+  - Callback skipping for opted-out models
+  - Mixed primary key scenarios with proper foreign key type detection
+  - Inheritance behavior and subclass overrides
+- Added integration tests for mixed primary key scenarios in migration helpers
+- Updated configuration tests to verify opt-out functionality
+
+### Fixed
+- **Documentation URI**: Updated documentation URI in gemspec to include version number for proper RubyDoc.info linking
+
 ## [0.10.0] - 2026-01-15
 
 ### Added

data/README.md

@@ -13,13 +13,8 @@ Automatically use UUID v7 for **all primary keys** in Rails applications. Works
 
 - 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 **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
+- Works perfectly on PostgreSQL, MySQL, and SQLite
 - Zero database extensions needed
-- Minimal and maintainable — no monkey-patching hell
 - Production-ready logging for debugging and monitoring
 
 ## Installation
@@ -27,7 +22,7 @@ Automatically use UUID v7 for **all primary keys** in Rails applications. Works
 Add to your `Gemfile`:
 
 ```ruby
-gem "rails-uuid-pk", "~> 0.10"
+gem "rails-uuid-pk", "~> 0.12"
 ```
 
 Then run:
@@ -40,198 +35,78 @@ That's it! The gem automatically enables UUIDv7 primary keys for all your models
 
 ## Usage
 
-After installation, **every new model** you generate will get a `uuid` primary key with automatic UUIDv7 values:
+After installation, **every new model** automatically gets a `uuid` primary key with 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
+### Opting Out of UUID Primary Keys
 
-### Action Text & Active Storage
+For specific models, you can opt out:
 
-When you install Action Text or Active Storage:
+```ruby
+class LegacyModel < ApplicationRecord
+  use_integer_primary_key
+  # Uses integer auto-incrementing primary key instead of UUIDv7
+end
 
-```bash
-rails action_text:install
-rails active_storage:install
+# Migration must also use :integer
+create_table :legacy_models, id: :integer do |t|
+  t.string :name
+end
 ```
 
-The generated migrations seamlessly integrate with UUID primary keys. Rails-uuid-pk's smart migration helpers automatically detect UUID primary keys in referenced tables and set the appropriate `type: :uuid` for foreign keys.
-
-### Polymorphic associations
-
-Polymorphic associations work seamlessly with UUID primary keys. Whether you're using Action Text's `record` references or custom polymorphic associations, the migration helpers automatically detect the parent table's primary key type and set the correct foreign key type.
-
-For example, this migration will automatically use `type: :uuid` when the parent models have UUID primary keys:
+Migration helpers automatically detect mixed primary key types and set appropriate foreign key types:
 
 ```ruby
-create_table :comments do |t|
-  t.references :commentable, polymorphic: true
+# 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
 ```
 
-## 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             |
-| 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             | Migration helpers automatically handle foreign key types             |
-| Works with Rails 7.1 – 8+            | Yes             | Tested conceptually up to Rails 8.1+                                  |
-
-## Performance Overview
-
-**Generation**: ~800,000 UUIDs/second with cryptographic security and monotonic ordering
-
-| Database | Storage | Index Performance | Notes |
-|----------|---------|-------------------|--------|
-| **PostgreSQL** | Native UUID (16B) | Excellent | Optimal performance |
-| **MySQL** | VARCHAR(36) (36B) | Good | 2.25x storage overhead |
-| **SQLite** | VARCHAR(36) (36B) | Good | Good for development |
+## Important Compatibility Notes
 
-**Key Advantages**:
-- **UUIDv7 outperforms UUIDv4** in most scenarios due to monotonic ordering
-- **Better index locality** than random UUIDs with reduced fragmentation
-- **Efficient range queries** for time-based data access
-- **Production-ready scaling** with proper indexing and monitoring
+### Action Text & Active Storage
 
-For comprehensive performance analysis, scaling strategies, and optimization guides, see [PERFORMANCE.md](PERFORMANCE.md).
+When installing Action Text or Active Storage, migrations automatically integrate with UUID primary keys - no changes needed.
 
-## Bulk Operations
+### Polymorphic associations
 
-**Important**: Bulk operations like `Model.import` bypass ActiveRecord callbacks, so UUIDs won't be automatically generated for bulk-inserted records. Use explicit UUID assignment or a custom bulk import method if needed.
+Polymorphic associations work seamlessly with UUID primary keys. Foreign key types are automatically detected.
 
-```ruby
-# Manual UUID assignment for bulk operations
-users = [{ name: "Alice", id: SecureRandom.uuid_v7 }, { name: "Bob", id: SecureRandom.uuid_v7 }]
-User.insert_all(users) # Bypasses callbacks, requires explicit IDs
-```
+## Performance & Architecture
 
-## Why not use native PostgreSQL `uuidv7()`?
+UUIDv7 provides excellent performance with monotonic ordering and reduced index fragmentation compared to UUIDv4.
 
-While PostgreSQL 18+ has excellent native `uuidv7()` support, the **fallback approach** was chosen for maximum compatibility:
+- **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
 
-- 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
+For detailed performance analysis and optimization guides, see [PERFORMANCE.md](PERFORMANCE.md).
 
-You can still add native PostgreSQL defaults manually if you want maximum performance — the gem's fallback is safe and will simply be ignored.
+For architecture decisions and design rationale, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Development
 
-### Devcontainer Setup
-
-This project includes a devcontainer configuration for VS Code (highly recommended, as it automatically sets up Ruby 3.3, Rails, PostgreSQL, MySQL, and SQLite in an isolated environment). 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
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions, testing, and contribution guidelines.
 
-#### Devcontainer CLI
-
-For terminal-based development or automation, you can use the Devcontainer CLI. The devcontainer will be built and started automatically when you run the exec commands.
-
-##### Installation
-
-- **MacOS**: `brew install devcontainer`
-- **Other systems**: `npm install -g @devcontainers/cli`
-
-##### Usage
-
-Run commands inside the devcontainer:
-
-```bash
-# Install dependencies
-devcontainer exec --workspace-folder . bundle install
+## Security
 
-# Run tests
-devcontainer exec --workspace-folder . ./bin/test
-
-# Run code quality checks
-devcontainer exec --workspace-folder . ./bin/rubocop
-
-# Interactive shell
-devcontainer exec --workspace-folder . bash
-```
-
-### Running Tests
-
-The project includes a comprehensive test suite that runs against SQLite, PostgreSQL, and MySQL.
-
-```bash
-# Run all tests (SQLite + PostgreSQL + MySQL)
-./bin/test
-
-# Run tests with coverage reporting
-./bin/coverage
-
-# Run performance benchmarks
-./bin/benchmark
-
-# Run tests for specific database
-DB=sqlite ./bin/test      # SQLite only
-DB=postgres ./bin/test    # PostgreSQL only
-DB=mysql ./bin/test       # MySQL only
-
-# Run specific test file
-./bin/test test/uuid/generation_test.rb
-
-# Run specific test file with specific database
-DB=sqlite ./bin/test test/uuid/type_test.rb
-
-# Run multiple specific test files
-./bin/test test/uuid/generation_test.rb test/uuid/type_test.rb
-```
-
-### 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.10.0.gem
-```
-
-### Database Setup
-
-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
+For security considerations and vulnerability reporting, see [SECURITY.md](SECURITY.md).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/seouri/rails-uuid-pk.
-
-Please see our [Security Policy](SECURITY.md) for information about reporting security vulnerabilities.
-
-For detailed architecture documentation, design decisions, and technical rationale, see [ARCHITECTURE.md](ARCHITECTURE.md).
+Bug reports and pull requests welcome on GitHub. See [DEVELOPMENT.md](DEVELOPMENT.md) for contribution guidelines.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).
+MIT License - see [MIT-LICENSE](MIT-LICENSE) for details.

data/lib/rails_uuid_pk/concern.rb

@@ -20,14 +20,49 @@ module RailsUuidPk
   #   user = User.new(id: "custom-uuid")
   #   user.save # Uses the custom UUID, not auto-generated
   #
-  # @note UUIDs are only assigned when id is nil to allow manual ID assignment
+  # @example Opting out of UUID primary keys
+  #   class LegacyModel < ApplicationRecord
+  #     use_integer_primary_key
+  #     # Uses integer auto-incrementing primary key instead of UUIDv7
+  #   end
+  #
+  # @note UUIDs are only assigned when id is nil and the model uses UUID primary keys
   # @see RailsUuidPk::Railtie
   # @see https://www.rfc-editor.org/rfc/rfc9562.html RFC 9562 (UUIDv7)
   module HasUuidv7PrimaryKey
     extend ActiveSupport::Concern
 
     included do
-      before_create :assign_uuidv7_if_needed, if: -> { id.nil? }
+      before_create :assign_uuidv7_if_needed, if: -> { id.nil? && self.class.uses_uuid_primary_key? }
+    end
+
+    # Class methods for models using HasUuidv7PrimaryKey.
+    module ClassMethods
+      # Opt out of automatic UUIDv7 primary key generation for this model.
+      #
+      # When called, the model will use Rails' default primary key behavior
+      # (typically integer auto-incrementing) instead of UUIDv7 generation.
+      #
+      # @example
+      #   class LegacyModel < ApplicationRecord
+      #     use_integer_primary_key
+      #   end
+      #
+      # @note Subclasses do NOT inherit this setting. Each class must explicitly opt out.
+      # @return [void]
+      def use_integer_primary_key
+        singleton_class.instance_variable_set(:@uses_integer_primary_key, true)
+      end
+
+      # Check if this model uses UUID primary keys.
+      #
+      # Returns false if the model has opted out via use_integer_primary_key,
+      # true otherwise (default behavior).
+      #
+      # @return [Boolean] true if model uses UUID primary keys, false otherwise
+      def uses_uuid_primary_key?
+        !singleton_class.instance_variable_get(:@uses_integer_primary_key)
+      end
     end
 
     private

data/lib/rails_uuid_pk/mysql2_adapter_extension.rb

@@ -4,8 +4,8 @@ module RailsUuidPk
   # MySQL adapter extension for UUID type support.
   #
   # This module extends ActiveRecord's MySQL2 adapter to provide native UUID
-  # type support. Since MySQL doesn't have a native UUID type, it maps UUIDs
-  # to VARCHAR(36) columns and registers the custom UUID type handlers.
+  # type support. It includes the shared UUID adapter extension functionality
+  # and provides MySQL-specific connection configuration.
   #
   # @example Automatic type mapping
   #   # MySQL tables with VARCHAR(36) columns are automatically treated as UUIDs
@@ -13,65 +13,17 @@ module RailsUuidPk
   #     t.column :id, :uuid  # Maps to VARCHAR(36) in MySQL
   #   end
   #
+  # @see RailsUuidPk::UuidAdapterExtension
   # @see RailsUuidPk::Type::Uuid
   # @see https://dev.mysql.com/doc/refman/8.0/en/data-types.html
   module Mysql2AdapterExtension
-    # Defines native database types for MySQL UUID support.
-    #
-    # @return [Hash] Database type definitions including UUID mapping
-    def native_database_types
-      super.merge(
-        uuid: { name: "varchar", limit: 36 }
-      )
-    end
-
-    # Checks if a type is valid for this adapter.
-    #
-    # Overrides ActiveRecord's valid_type? to recognize the custom UUID type.
-    #
-    # @param type [Symbol] The type to check
-    # @return [Boolean] true if the type is valid
-    def valid_type?(type)
-      return true if type == :uuid
-      super
-    end
-
-    # Registers UUID type handlers in the adapter's type map.
-    #
-    # @param m [ActiveRecord::ConnectionAdapters::AbstractAdapter::TypeMap] The type map to register with
-    # @return [void]
-    def register_uuid_types(m = type_map)
-      RailsUuidPk.log(:debug, "Registering UUID types on #{m.class}")
-      m.register_type(/varchar\(36\)/i) { RailsUuidPk::Type::Uuid.new }
-      m.register_type("uuid") { RailsUuidPk::Type::Uuid.new }
-    end
-
-    # Initializes the type map with UUID type registrations.
-    #
-    # @param m [ActiveRecord::ConnectionAdapters::AbstractAdapter::TypeMap] The type map to initialize
-    # @return [void]
-    def initialize_type_map(m = type_map)
-      super
-      register_uuid_types(m)
-    end
+    include UuidAdapterExtension
 
     # Configures the database connection with UUID type support.
     #
     # @return [void]
     def configure_connection
       super
-      register_uuid_types
-    end
-
-    # Overrides type dumping to properly handle UUID columns.
-    #
-    # @param column [ActiveRecord::ConnectionAdapters::Column] The column to dump
-    # @return [Array] The type and options for the schema dump
-    def type_to_dump(column)
-      if column.type == :uuid
-        return [ :uuid, {} ]
-      end
-      super
     end
   end
 end

data/lib/rails_uuid_pk/sqlite3_adapter_extension.rb

@@ -4,8 +4,9 @@ module RailsUuidPk
   # SQLite adapter extension for UUID type support.
   #
   # This module extends ActiveRecord's SQLite3 adapter to provide native UUID
-  # type support. Since SQLite doesn't have a native UUID type, it maps UUIDs
-  # to VARCHAR(36) columns and registers the custom UUID type handlers.
+  # type support. It includes the shared UUID adapter extension functionality
+  # and provides SQLite-specific connection configuration, including transaction-aware
+  # connection setup.
   #
   # @example Automatic type mapping
   #   # SQLite tables with VARCHAR(36) columns are automatically treated as UUIDs
@@ -13,67 +14,22 @@ module RailsUuidPk
   #     t.column :id, :uuid  # Maps to VARCHAR(36) in SQLite
   #   end
   #
+  # @see RailsUuidPk::UuidAdapterExtension
   # @see RailsUuidPk::Type::Uuid
   # @see https://www.sqlite.org/datatype3.html
   module Sqlite3AdapterExtension
-    # Defines native database types for SQLite UUID support.
-    #
-    # @return [Hash] Database type definitions including UUID mapping
-    def native_database_types
-      super.merge(
-        uuid: { name: "varchar", limit: 36 }
-      )
-    end
-
-    # Checks if a type is valid for this adapter.
-    #
-    # Overrides ActiveRecord's valid_type? to recognize the custom UUID type.
-    #
-    # @param type [Symbol] The type to check
-    # @return [Boolean] true if the type is valid
-    def valid_type?(type)
-      return true if type == :uuid
-      super
-    end
-
-    # Registers UUID type handlers in the adapter's type map.
-    #
-    # @param m [ActiveRecord::ConnectionAdapters::AbstractAdapter::TypeMap] The type map to register with
-    # @return [void]
-    def register_uuid_types(m = type_map)
-      RailsUuidPk.log(:debug, "Registering UUID types on #{m.class}")
-      m.register_type(/varchar\(36\)/i) { RailsUuidPk::Type::Uuid.new }
-      m.register_type("uuid") { RailsUuidPk::Type::Uuid.new }
-    end
-
-    # Initializes the type map with UUID type registrations.
-    #
-    # @param m [ActiveRecord::ConnectionAdapters::AbstractAdapter::TypeMap] The type map to initialize
-    # @return [void]
-    def initialize_type_map(m = type_map)
-      super
-      register_uuid_types(m)
-    end
+    include UuidAdapterExtension
 
     # Configures the database connection with UUID type support.
     #
+    # SQLite-specific implementation that avoids calling super inside transactions,
+    # as PRAGMA statements cannot be executed inside transactions in SQLite.
+    #
     # @return [void]
     def configure_connection
       # Only call super if not inside a transaction, as PRAGMA statements
       # cannot be executed inside transactions in SQLite
       super unless open_transactions > 0
-      register_uuid_types
-    end
-
-    # Overrides type dumping to properly handle UUID columns.
-    #
-    # @param column [ActiveRecord::ConnectionAdapters::Column] The column to dump
-    # @return [Array] The type and options for the schema dump
-    def type_to_dump(column)
-      if column.type == :uuid
-        return [ :uuid, {} ]
-      end
-      super
     end
   end
 end

data/lib/rails_uuid_pk/uuid_adapter_extension.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RailsUuidPk
+  # Shared UUID adapter extension for database adapters.
+  #
+  # This module provides common UUID type support functionality that can be
+  # included by specific database adapter extensions (MySQL, SQLite, etc.).
+  # Since most databases don't have native UUID types, it maps UUIDs to
+  # VARCHAR(36) columns and registers the custom UUID type handlers.
+  #
+  # @example Automatic type mapping
+  #   # Database tables with VARCHAR(36) columns are automatically treated as UUIDs
+  #   create_table :users do |t|
+  #     t.column :id, :uuid  # Maps to VARCHAR(36) in supported databases
+  #   end
+  #
+  # @see RailsUuidPk::Type::Uuid
+  module UuidAdapterExtension
+    # Defines native database types for UUID support.
+    #
+    # @return [Hash] Database type definitions including UUID mapping
+    def native_database_types
+      super.merge(
+        uuid: { name: "varchar", limit: 36 }
+      )
+    end
+
+    # Checks if a type is valid for this adapter.
+    #
+    # Overrides ActiveRecord's valid_type? to recognize the custom UUID type.
+    #
+    # @param type [Symbol] The type to check
+    # @return [Boolean] true if the type is valid
+    def valid_type?(type)
+      return true if type == :uuid
+      super
+    end
+
+    # Registers UUID type handlers in the adapter's type map.
+    #
+    # @param m [ActiveRecord::ConnectionAdapters::AbstractAdapter::TypeMap] The type map to register with
+    # @return [void]
+    def register_uuid_types(m = type_map)
+      RailsUuidPk.log(:debug, "Registering UUID types on #{m.class}")
+      m.register_type(/varchar\(36\)/i) { RailsUuidPk::Type::Uuid.new }
+      m.register_type("uuid") { RailsUuidPk::Type::Uuid.new }
+    end
+
+    # Initializes the type map with UUID type registrations.
+    #
+    # @param m [ActiveRecord::ConnectionAdapters::AbstractAdapter::TypeMap] The type map to initialize
+    # @return [void]
+    def initialize_type_map(m = type_map)
+      super
+      register_uuid_types(m)
+    end
+
+    # Configures the database connection with UUID type support.
+    #
+    # This method should be overridden by including adapters to handle
+    # database-specific connection configuration requirements.
+    #
+    # @return [void]
+    def configure_connection
+      super
+      register_uuid_types
+    end
+
+    # Overrides type dumping to properly handle UUID columns.
+    #
+    # @param column [ActiveRecord::ConnectionAdapters::Column] The column to dump
+    # @return [Array] The type and options for the schema dump
+    def type_to_dump(column)
+      if column.type == :uuid
+        return [ :uuid, {} ]
+      end
+      super
+    end
+  end
+end

data/lib/rails_uuid_pk/version.rb

@@ -7,6 +7,6 @@ module RailsUuidPk
   #
   # @return [String] The current version
   # @example
-  #   RailsUuidPk::VERSION # => "0.10.0"
-  VERSION = "0.10.0"
+  #   RailsUuidPk::VERSION # => "0.12.0"
+  VERSION = "0.12.0"
 end

data/lib/rails_uuid_pk.rb

@@ -3,6 +3,7 @@
 require "rails_uuid_pk/version"
 require "rails_uuid_pk/concern"
 require "rails_uuid_pk/type"
+require "rails_uuid_pk/uuid_adapter_extension"
 require "rails_uuid_pk/sqlite3_adapter_extension"
 require "rails_uuid_pk/mysql2_adapter_extension"
 require "rails_uuid_pk/railtie"
@@ -46,10 +47,7 @@ module RailsUuidPk
   # @example
   #   RailsUuidPk.logger.info("Custom message")
   def self.logger
-    return @logger if @logger
-
-    rails_logger = defined?(Rails.logger) && Rails.logger
-    @logger = rails_logger || Logger.new($stdout)
+    @logger ||= ((defined?(Rails.logger) && Rails.logger) || Logger.new($stdout))
     @logger = Logger.new($stdout) unless @logger.is_a?(Logger)
     @logger
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-uuid-pk
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Joon Lee
@@ -154,6 +154,7 @@ files:
 - lib/rails_uuid_pk/railtie.rb
 - lib/rails_uuid_pk/sqlite3_adapter_extension.rb
 - lib/rails_uuid_pk/type.rb
+- lib/rails_uuid_pk/uuid_adapter_extension.rb
 - lib/rails_uuid_pk/version.rb
 - lib/tasks/rails_uuid_pk_tasks.rake
 homepage: https://github.com/seouri/rails-uuid-pk
@@ -163,7 +164,7 @@ 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
-  documentation_uri: https://www.rubydoc.info/gems/rails-uuid-pk
+  documentation_uri: https://www.rubydoc.info/gems/rails-uuid-pk/0.12.0
 rdoc_options: []
 require_paths:
 - lib