rails-uuid-pk 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cda21a747f154d1863e741ecce9b44855009bc202b11524be1a48911c6945ee2
-  data.tar.gz: f513b130b54f7d2230a13aa53bd60b707174005eff1bb792c0380a9d2b80a885
+  metadata.gz: 712bd0217dd06a7b87d855696311146bc08bd1ee9f45b52ce1ece11a251a284c
+  data.tar.gz: 8d702575c6177fe8074ea8b88bb650b72d785e83645b02a0a41ace3ea048cc76
 SHA512:
-  metadata.gz: 44070a3cf56eca32a1e83abdb83fa084abcb8c6042d2a2e06f3314bcfbf9df4e12a2794a5fab1e7d50d589455f2242dbf7e141618cd2b2b721b76be92ddfdc0f
-  data.tar.gz: 04ca3df41f44ca36bba89849a5c2a515481417b28b995670ecb93fb7a87a90abe5d9bf74bdb1b3a31c109a28127df2b9478bd63adbfa83fb5d0011e0b334a872
+  metadata.gz: 78d45ed25bc2ab1cedc26d2bb64df821ddc1f4e99bf06cc65d3ac595d87a9bad365e458de8ef8c280ee4518cc96d0c5373dc3e569d364f30f2ad0b700cffc029
+  data.tar.gz: d1230736212301ebf5b6d9816fa3c1cd05c92c095290153437cffb9db3ef6340d040553736c370a895aa4ab99c472e0f09503fa6f4e1347b98a442274bbbed12

data/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.9.0] - 2026-01-14
+
+### Added
+- **Logging and Observability Framework**: Added comprehensive logging infrastructure for production debugging and monitoring
+  - `RailsUuidPk.logger` and `RailsUuidPk.log` methods with Rails logger integration
+  - Debug logging for UUID assignment tracking in models
+  - Debug logging for foreign key type detection in migrations
+  - Debug logging for database adapter UUID type registration
+  - Production-ready logging with configurable log levels
+- **Comprehensive CI/CD Pipeline**: Enterprise-grade continuous integration with security scanning, multi-version testing, performance monitoring, and automated quality assurance
+  - Dependency vulnerability scanning with `bundler-audit`
+  - Code coverage reporting with `simplecov` and Codecov integration
+  - Multi-Ruby testing (3.3, 3.4, 4.0) across PostgreSQL 18, MySQL 9, and SQLite
+  - Performance benchmarking with automated `bin/benchmark` script
+  - Job dependencies for efficient CI execution and faster failure detection
+- **Enhanced Database Support**: Updated to latest database versions (PostgreSQL 18, MySQL 9) for optimal performance and compatibility
+- **Improved Executable Scripts**: Professional-grade command-line tools with comprehensive error handling, progress feedback, and documentation
+  - `bin/coverage`: Enhanced with proper error handling and user feedback
+  - `bin/benchmark`: Renamed from `bin/performance` following standard naming conventions
+- **Ruby 4.0 Compatibility**: Fixed all compatibility issues including benchmark warnings and dependency management
+
+### Improved
+- **Code Quality**: Replaced `puts` statements with proper logging infrastructure
+- **Debugging Support**: Enhanced observability for troubleshooting production issues
+- **Log Aggregation**: Compatible with existing Rails logging and monitoring systems (Datadog, CloudWatch, etc.)
+
+### Documentation
+- **Bulk Operations Awareness**: Added comprehensive documentation about bulk operations limitation across README.md, ARCHITECTURE.md, PERFORMANCE.md, and AGENTS.md, clarifying that `Model.import` and `Model.insert_all` bypass callbacks and require explicit UUID assignment
+- **YARD API Documentation**: Added comprehensive YARD documentation to all core library files, achieving 100% documentation coverage with detailed method descriptions, parameter specifications, usage examples, and cross-references for improved developer experience
+
+### Changed
+- **Dependency Management**: Moved CI and development tools to `gemspec` for consistency and proper gem packaging
+- **Script Naming**: Renamed `bin/performance` to `bin/benchmark` following industry standards
+- **CI Workflow**: Comprehensive pipeline with security, testing, coverage, and performance validation
+- **Database Versions**: Updated to PostgreSQL 18 and MySQL 9 for cutting-edge support
+
+### Security
+- **Enhanced Timestamp Privacy Documentation**: Added explicit privacy consideration warning in SECURITY.md about UUIDv7 timestamp exposure, clarifying that UUIDv7 includes a timestamp component that reveals approximate record creation time and advising against use when creation timestamps must be hidden
+
+### Technical Details
+- Added `bundler-audit`, `simplecov`, `benchmark-ips`, and `benchmark` as development dependencies
+- Implemented Ruby 4.0 compatibility fixes for SecureRandom and benchmark libraries
+- Enhanced CI matrix with 9 test combinations across multiple Ruby and database versions
+- Added comprehensive error handling and logging to executable scripts
+- Implemented job dependencies in GitHub Actions for optimal CI performance
+- Added logging framework in `lib/rails_uuid_pk.rb` with Rails logger fallback
+- Implemented debug logging in `concern.rb` for UUIDv7 assignment tracking
+- Added debug logging in `migration_helpers.rb` for foreign key type detection
+- Enhanced adapter extensions with proper logging instead of console output
+- All logging uses structured format with `[RailsUuidPk]` prefix for easy filtering
+- Added `yard` as development dependency for automated documentation generation
+
 ## [0.8.0] - 2026-01-12
 
 ### Changed

data/README.md

@@ -7,6 +7,7 @@ Automatically use UUID v7 for **all primary keys** in Rails applications. Works
 [![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)
+[![CI](https://img.shields.io/github/actions/workflow/status/seouri/rails-uuid-pk/ci.yml?branch=main&style=flat-square)](https://github.com/seouri/rails-uuid-pk/actions)
 
 ## Why this gem?
 
@@ -19,13 +20,14 @@ Automatically use UUID v7 for **all primary keys** in Rails applications. Works
 - **SQLite**: Uses `VARCHAR(36)` with custom ActiveRecord type handling
 - Zero database extensions needed
 - Minimal and maintainable — no monkey-patching hell
+- Production-ready logging for debugging and monitoring
 
 ## Installation
 
 Add to your `Gemfile`:
 
 ```ruby
-gem "rails-uuid-pk", "~> 0.8"
+gem "rails-uuid-pk", "~> 0.9"
 ```
 
 Then run:
@@ -108,6 +110,16 @@ end
 
 For comprehensive performance analysis, scaling strategies, and optimization guides, see [PERFORMANCE.md](PERFORMANCE.md).
 
+## Bulk Operations
+
+**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.
+
+```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
+```
+
 ## Why not use native PostgreSQL `uuidv7()`?
 
 While PostgreSQL 18+ has excellent native `uuidv7()` support, the **fallback approach** was chosen for maximum compatibility:
@@ -164,10 +176,25 @@ The project includes a comprehensive test suite that runs against SQLite, Postgr
 # 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
@@ -187,7 +214,7 @@ DB=mysql ./bin/test       # MySQL only
 gem build rails_uuid_pk.gemspec
 
 # Install locally for testing
-gem install rails-uuid-pk-0.1.0.gem
+gem install rails-uuid-pk-0.9.0.gem
 ```
 
 ### Database Setup

data/lib/rails_uuid_pk/concern.rb

@@ -1,4 +1,28 @@
+# frozen_string_literal: true
+
 module RailsUuidPk
+  # Provides automatic UUIDv7 primary key generation for ActiveRecord models.
+  #
+  # This concern is automatically included in all ActiveRecord::Base models
+  # via the Railtie, requiring no manual configuration. It uses a before_create
+  # callback to assign UUIDv7 values to the primary key only when the id is nil.
+  #
+  # @example Automatic UUIDv7 generation
+  #   class User < ApplicationRecord
+  #     # Automatically gets UUIDv7 id on create
+  #     # No additional code needed!
+  #   end
+  #
+  #   user = User.create
+  #   user.id # => "018f8c5d-1234-7abc-9def-123456789abc"
+  #
+  # @example Manual ID assignment (overrides automatic generation)
+  #   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
+  # @see RailsUuidPk::Railtie
+  # @see https://www.rfc-editor.org/rfc/rfc9562.html RFC 9562 (UUIDv7)
   module HasUuidv7PrimaryKey
     extend ActiveSupport::Concern
 
@@ -8,11 +32,20 @@ module RailsUuidPk
 
     private
 
+    # Assigns a UUIDv7 to the primary key if not already set.
+    #
+    # This method is called automatically before creating a record if the id is nil.
+    # It uses Ruby 3.3+'s SecureRandom.uuid_v7 for cryptographically secure UUID generation.
+    #
+    # @return [void]
+    # @note This method is private and should not be called directly
     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
+      uuid = SecureRandom.uuid_v7
+      RailsUuidPk.log(:debug, "Assigned UUIDv7 #{uuid} to #{self.class.name}")
+      self.id = uuid
     end
   end
 end

data/lib/rails_uuid_pk/migration_helpers.rb

@@ -1,6 +1,48 @@
+# frozen_string_literal: true
+
 module RailsUuidPk
+  # Migration helpers for automatic foreign key type detection.
+  #
+  # This module provides smart migration helpers that automatically detect when
+  # foreign key columns should use UUID types based on the referenced table's
+  # primary key type. It extends ActiveRecord's migration DSL to provide seamless
+  # UUID foreign key support.
+  #
+  # @example Automatic UUID foreign key detection
+  #   create_table :posts do |t|
+  #     t.references :user  # Automatically uses :uuid type if users.id is UUID
+  #     t.string :title
+  #   end
+  #
+  # @example Polymorphic associations
+  #   create_table :comments do |t|
+  #     t.references :commentable, polymorphic: true  # Uses :uuid if app uses UUIDs
+  #   end
+  #
+  # @example Explicit type override (respects user choice)
+  #   create_table :posts do |t|
+  #     t.references :user, type: :integer  # Uses :integer even if users.id is UUID
+  #   end
+  #
+  # @see RailsUuidPk::Railtie
   module MigrationHelpers
+    # Migration helper methods for references and foreign keys.
+    #
+    # This module extends ActiveRecord's migration classes to automatically
+    # determine appropriate foreign key types based on the referenced table's
+    # primary key type.
     module References
+      # Creates a reference column with automatic type detection.
+      #
+      # Automatically sets the column type to :uuid if the referenced table
+      # uses UUID primary keys, unless the type is explicitly specified.
+      #
+      # @param args [Array<String, Symbol>] Arguments passed to the original references method
+      # @param options [Hash] Options hash for the reference column
+      # @option options [String, Symbol] :to_table The table being referenced (defaults to pluralized ref_name)
+      # @option options [Symbol] :type The column type (:integer, :bigint, :uuid)
+      # @option options [Boolean] :polymorphic Whether this is a polymorphic association
+      # @return [void]
       def references(*args, **options)
         ref_name = args.first
         ref_table = options.delete(:to_table) || ref_name.to_s.pluralize
@@ -12,34 +54,121 @@ module RailsUuidPk
         current_type = options[:type]
         if (current_type.nil? || current_type == :integer || current_type == :bigint) &&
            (uuid_primary_key?(ref_table) || (options[:polymorphic] && application_uses_uuid_primary_keys?))
+          RailsUuidPk.log(:debug, "Setting foreign key #{ref_name} to UUID type (referencing #{ref_table})")
           options[:type] = :uuid
         end
 
         super(*args, **options)
       end
 
+      # Adds a reference column to an existing table with automatic type detection.
+      #
+      # @param table_name [String, Symbol] The name of the table to add the reference to
+      # @param ref_name [String, Symbol] The name of the reference column
+      # @param options [Hash] Options hash for the reference column
+      # @option options [String, Symbol] :to_table The table being referenced (defaults to pluralized ref_name)
+      # @option options [Symbol] :type The column type (:integer, :bigint, :uuid)
+      # @option options [Boolean] :polymorphic Whether this is a polymorphic association
+      # @return [void]
       def add_reference(table_name, ref_name, **options)
         ref_table = options.delete(:to_table) || ref_name.to_s.pluralize
 
         current_type = options[:type]
         if (current_type.nil? || current_type == :integer || current_type == :bigint) &&
            (uuid_primary_key?(ref_table) || (options[:polymorphic] && application_uses_uuid_primary_keys?))
+          RailsUuidPk.log(:debug, "Setting foreign key #{ref_name} to UUID type (referencing #{ref_table})")
           options[:type] = :uuid
         end
 
         super(table_name, ref_name, **options)
       end
 
+      # Checks if the application is configured to use UUID primary keys globally.
+      #
+      # @return [Boolean] true if the application uses UUID primary keys by default
+      # @note This checks Rails generator configuration for primary_key_type
       def application_uses_uuid_primary_keys?
         # Check if the application is configured to use UUID primary keys globally
-        defined?(Rails) && Rails.application.config.generators.options[:active_record]&.[](:primary_key_type) == :uuid
+        return false unless defined?(Rails) && Rails.application&.config&.generators&.options
+
+        active_record_config = Rails.application.config.generators.options[:active_record]
+        active_record_config.is_a?(Hash) && active_record_config[:primary_key_type] == :uuid
+      end
+
+      # Module-level access to application_uses_uuid_primary_keys? for testing.
+      #
+      # This method is exposed for testing purposes only and should not be used
+      # in production code. It creates a temporary instance to access the instance method.
+      #
+      # @return [Boolean] true if the application uses UUID primary keys by default
+      # @api private
+      # @note For testing only - do not use in production code
+      def self.application_uses_uuid_primary_keys?
+        # Create a dummy class to include the module and call the method
+        dummy_class = Class.new { include RailsUuidPk::MigrationHelpers::References }
+        dummy_class.new.application_uses_uuid_primary_keys?
       end
 
+      # Module-level access to uuid_primary_key? for testing.
+      #
+      # This method is exposed for testing purposes only and should not be used
+      # in production code. It creates a temporary instance to access the private method.
+      #
+      # @param table_name [String, Symbol] The name of the table to check
+      # @param mock_conn [Object] Optional mock connection for testing
+      # @return [Boolean] true if the table's primary key is a UUID type
+      # @api private
+      # @note For testing only - do not use in production code
+      def self.test_uuid_primary_key?(table_name, mock_conn = nil)
+        # Create a dummy class to include the module and make the method public for testing
+        dummy_class = Class.new do
+          include RailsUuidPk::MigrationHelpers::References
+          # For testing, provide a connection method that returns the mock_conn
+          define_method(:connection) { mock_conn } if mock_conn
+          # Make the private method public for testing
+          public :uuid_primary_key?
+        end
+        instance = dummy_class.new
+        instance.instance_variable_set(:@conn, mock_conn) if mock_conn
+        instance.uuid_primary_key?(table_name)
+      end
+
+      # Module-level access to find_primary_key_column for testing.
+      #
+      # This method is exposed for testing purposes only and should not be used
+      # in production code. It creates a temporary instance to access the private method.
+      #
+      # @param table_name [String, Symbol] The name of the table
+      # @param conn [ActiveRecord::ConnectionAdapters::AbstractAdapter] The database connection
+      # @return [ActiveRecord::ConnectionAdapters::Column, nil] The primary key column or nil
+      # @api private
+      # @note For testing only - do not use in production code
+      def self.test_find_primary_key_column(table_name, conn)
+        # Create a dummy class to include the module and make the method public for testing
+        dummy_class = Class.new do
+          include RailsUuidPk::MigrationHelpers::References
+          # For testing, provide a connection method that returns the conn
+          define_method(:connection) { conn }
+          # Make the private method public for testing
+          public :find_primary_key_column
+        end
+        instance = dummy_class.new
+        instance.find_primary_key_column(table_name, conn)
+      end
+
+      # Alias for references method (ActiveRecord compatibility)
       alias_method :belongs_to, :references
+
+      # Alias for add_reference method (ActiveRecord compatibility)
       alias_method :add_belongs_to, :add_reference
 
       private
 
+      # Checks if a table uses UUID primary keys.
+      #
+      # @param table_name [String, Symbol] The name of the table to check
+      # @return [Boolean] true if the table's primary key is a UUID type
+      # @note Results are cached during migration execution for performance
       def uuid_primary_key?(table_name)
         # Cache results for the duration of the migration process to improve performance
         @uuid_pk_cache ||= {}
@@ -53,6 +182,11 @@ module RailsUuidPk
         @uuid_pk_cache[table_name] = !!(pk_column && pk_column.sql_type.downcase.match?(/\A(uuid|varchar\(36\))\z/))
       end
 
+      # Finds the primary key column for a given table.
+      #
+      # @param table_name [String, Symbol] The name of the table
+      # @param conn [ActiveRecord::ConnectionAdapters::AbstractAdapter] The database connection
+      # @return [ActiveRecord::ConnectionAdapters::Column, nil] The primary key column or nil
       def find_primary_key_column(table_name, conn)
         pk_name = conn.primary_key(table_name)
         return nil unless pk_name

data/lib/rails_uuid_pk/mysql2_adapter_extension.rb

@@ -1,21 +1,52 @@
+# frozen_string_literal: true
+
 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.
+  #
+  # @example Automatic type mapping
+  #   # MySQL tables with VARCHAR(36) columns are automatically treated as UUIDs
+  #   create_table :users do |t|
+  #     t.column :id, :uuid  # Maps to VARCHAR(36) in MySQL
+  #   end
+  #
+  # @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
 
+    # 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.
+    #
+    # @return [void]
     def configure_connection
       super
       register_uuid_types

data/lib/rails_uuid_pk/railtie.rb

@@ -1,11 +1,41 @@
+# frozen_string_literal: true
+
 module RailsUuidPk
+  # Rails integration for automatic UUIDv7 primary key generation.
+  #
+  # This Railtie automatically configures Rails applications to use UUID primary keys
+  # by including the HasUuidv7PrimaryKey concern in all ActiveRecord models and setting
+  # up proper database type mappings and migration helpers.
+  #
+  # The railtie performs the following integrations:
+  # - Configures Rails generators to use UUID primary keys
+  # - Registers UUID types for SQLite and MySQL adapters
+  # - Includes UUIDv7 generation concern in all models
+  # - Adds smart migration helpers for foreign key type detection
+  # - Sets appropriate schema format for UUID compatibility
+  #
+  # @example Automatic configuration
+  #   # No configuration needed - everything works automatically
+  #   class User < ApplicationRecord
+  #     # Primary key is automatically UUIDv7
+  #   end
+  #
+  # @see RailsUuidPk::HasUuidv7PrimaryKey
+  # @see RailsUuidPk::MigrationHelpers
   class Railtie < ::Rails::Railtie
+    # Configures Rails generators to use UUID primary keys by default.
+    #
+    # This initializer sets the default primary_key_type to :uuid for all
+    # newly generated models and migrations.
     initializer "rails-uuid-pk.generators" do |app|
       app.config.generators do |g|
         g.orm :active_record, primary_key_type: :uuid
       end
     end
 
+    # Configures type mappings for SQLite and MySQL adapters.
+    #
+    # Registers the custom UUID type for adapters that don't have native UUID support.
     initializer "rails-uuid-pk.configure_type_map", after: "active_record.initialize_database" do
       ActiveSupport.on_load(:active_record) do
         adapter_name = ActiveRecord::Base.connection.adapter_name
@@ -15,6 +45,10 @@ module RailsUuidPk
       end
     end
 
+    # Extends database adapters with UUID type support.
+    #
+    # Prepends adapter-specific extensions to add native UUID type definitions
+    # and type registration methods.
     initializer "rails-uuid-pk.native_types" do
       ActiveSupport.on_load(:active_record_sqlite3adapter) do
         prepend RailsUuidPk::Sqlite3AdapterExtension
@@ -25,6 +59,10 @@ module RailsUuidPk
       end
     end
 
+    # Ensures UUID types are registered on all database connections.
+    #
+    # This runs after Rails initialization to register UUID types on any
+    # existing or future database connections.
     config.after_initialize do
       ActiveSupport.on_load(:active_record) do
         if ActiveRecord::Base.connected?
@@ -46,26 +84,43 @@ module RailsUuidPk
       end
     end
 
+    # Sets the schema format to Ruby for UUID compatibility.
+    #
+    # Ruby schema format is required for proper UUID type handling across
+    # different database adapters and Rails versions.
     initializer "rails-uuid-pk.schema_format" do |app|
       app.config.active_record.schema_format ||= :ruby
     end
 
+    # Includes the UUIDv7 generation concern in all ActiveRecord models.
+    #
+    # This automatically adds UUIDv7 primary key generation to all models
+    # without requiring any changes to existing code.
     initializer "rails-uuid-pk.include_concern" do
       ActiveSupport.on_load(:active_record) do
         ActiveRecord::Base.include RailsUuidPk::HasUuidv7PrimaryKey
       end
     end
 
+    # Adds smart migration helpers for automatic foreign key type detection.
+    #
+    # Prepends the References module to ActiveRecord migration classes to
+    # automatically detect when foreign keys should use UUID types.
     initializer "rails-uuid-pk.migration_helpers" do
       ActiveSupport.on_load(:active_record) do
         require "rails_uuid_pk/migration_helpers"
 
+        ActiveRecord::Migration.prepend(RailsUuidPk::MigrationHelpers::References)
         ActiveRecord::ConnectionAdapters::TableDefinition.prepend(RailsUuidPk::MigrationHelpers::References)
         ActiveRecord::ConnectionAdapters::Table.prepend(RailsUuidPk::MigrationHelpers::References)
         ActiveRecord::ConnectionAdapters::AbstractAdapter.prepend(RailsUuidPk::MigrationHelpers::References)
       end
     end
 
+    # Registers the custom UUID type with ActiveRecord's type registry.
+    #
+    # @param adapter [Symbol] The database adapter (:sqlite, :mysql)
+    # @return [void]
     def self.register_uuid_type(adapter)
       ActiveRecord::Type.register(:uuid, RailsUuidPk::Type::Uuid, adapter: adapter)
     end

data/lib/rails_uuid_pk/sqlite3_adapter_extension.rb

@@ -1,24 +1,56 @@
+# frozen_string_literal: true
+
 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.
+  #
+  # @example Automatic type mapping
+  #   # SQLite tables with VARCHAR(36) columns are automatically treated as UUIDs
+  #   create_table :users do |t|
+  #     t.column :id, :uuid  # Maps to VARCHAR(36) in SQLite
+  #   end
+  #
+  # @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
 
+    # 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)
-      puts "[RailsUuidPk] Registering UUID types on #{m.class}"
+      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.
+    #
+    # @return [void]
     def configure_connection
-      super
+      # 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
   end

data/lib/rails_uuid_pk/type.rb

@@ -1,6 +1,28 @@
+# frozen_string_literal: true
+
 module RailsUuidPk
+  # Custom ActiveRecord types for UUID handling.
+  #
+  # This module provides custom type classes that handle UUID serialization,
+  # deserialization, and schema dumping with proper Rails version compatibility.
   module Type
+    # Custom UUID type for ActiveRecord.
+    #
+    # This type extends ActiveRecord::Type::String to provide UUID-specific
+    # handling with Rails version-aware schema dumping. It ensures proper
+    # UUID validation and formatting while maintaining backward compatibility.
+    #
+    # @example Automatic type handling
+    #   class User < ApplicationRecord
+    #     # id column automatically uses this type
+    #   end
+    #
+    # @see https://api.rubyonrails.org/classes/ActiveRecord/Type/String.html
     class Uuid < ActiveRecord::Type::String
+      # Returns the appropriate schema type symbol for the current Rails version.
+      #
+      # @return [Symbol] :uuid for Rails 8.1+, :string for earlier versions
+      # @note Rails 8.1+ supports native :uuid type in schema dumping
       def type
         # Rails 8.1+ supports UUID types in schema dumping
         # Earlier versions need :string to avoid "Unknown type 'uuid'" errors
@@ -11,11 +33,22 @@ module RailsUuidPk
         end
       end
 
+      # Deserializes a value from the database.
+      #
+      # @param value [Object] The raw value from the database
+      # @return [String, nil] The deserialized UUID string or nil
       def deserialize(value)
         return if value.nil?
         cast(value)
       end
 
+      # Casts a value to a UUID string.
+      #
+      # Accepts valid UUID strings and converts other values to strings.
+      # Invalid UUIDs are allowed for backward compatibility.
+      #
+      # @param value [Object] The value to cast
+      # @return [String, nil] The cast UUID string or nil
       def cast(value)
         return if value.nil?
         return value if value.is_a?(String) && valid?(value)
@@ -29,20 +62,58 @@ module RailsUuidPk
         value.to_s
       end
 
+      # Serializes a value for database storage.
+      #
+      # @param value [Object] The value to serialize
+      # @return [String, nil] The serialized value or nil
       def serialize(value)
         cast(value)
       end
 
+      # Casts a value for database storage (ActiveRecord compatibility).
+      #
+      # @param value [Object] The value to cast for database storage
+      # @return [String, nil] The cast value or nil
+      def type_cast_for_database(value)
+        serialize(value)
+      end
+
+      # Casts a value from the database (ActiveRecord compatibility).
+      #
+      # @param value [Object] The value from the database
+      # @return [String, nil] The cast value or nil
+      def type_cast_from_database(value)
+        deserialize(value)
+      end
+
+      # Checks if two values are different for change detection.
+      #
+      # Compares the original values to determine if they represent different data,
+      # which is used by ActiveRecord for dirty tracking.
+      #
+      # @param raw_old_value [Object] The old raw value from the database
+      # @param new_value [Object] The new value being compared
+      # @return [Boolean] true if the values are different
       def changed_in_place?(raw_old_value, new_value)
-        cast(raw_old_value) != cast(new_value)
+        # Compare original values for change detection
+        raw_old_value != new_value
       end
 
       private
 
+      # Validates if a string is a properly formatted UUID.
+      #
+      # @param value [String] The string to validate
+      # @return [Boolean] true if the string matches UUID format
       def valid?(value)
+        return false if value.nil?
         value.match?(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
       end
 
+      # Checks if the current Rails version supports UUID types in schema dumping.
+      #
+      # @return [Boolean] true if Rails 8.1 or later
+      # @note Rails 8.1+ allows :uuid in schema files, earlier versions require :string
       def rails_supports_uuid_in_schema?
         # Rails 8.1+ supports UUID types in schema dumping
         # Earlier versions (8.0.x) need :string to avoid "Unknown type 'uuid'" errors

data/lib/rails_uuid_pk/version.rb

@@ -1,3 +1,12 @@
+# frozen_string_literal: true
+
 module RailsUuidPk
-  VERSION = "0.8.0"
+  # The version of the rails-uuid-pk gem.
+  #
+  # Follows semantic versioning (MAJOR.MINOR.PATCH).
+  #
+  # @return [String] The current version
+  # @example
+  #   RailsUuidPk::VERSION # => "0.9.0"
+  VERSION = "0.9.0"
 end

data/lib/rails_uuid_pk.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails_uuid_pk/version"
 require "rails_uuid_pk/concern"
 require "rails_uuid_pk/type"
@@ -5,5 +7,69 @@ require "rails_uuid_pk/sqlite3_adapter_extension"
 require "rails_uuid_pk/mysql2_adapter_extension"
 require "rails_uuid_pk/railtie"
 
+# Rails UUID Primary Key
+#
+# A Rails gem that automatically uses UUIDv7 for all primary keys in Rails applications.
+# This gem provides seamless integration with Rails generators, automatic UUIDv7 generation,
+# and support for PostgreSQL, MySQL, and SQLite databases.
+#
+# @example Installation
+#   # Add to Gemfile
+#   gem 'rails-uuid-pk'
+#
+#   # All models automatically get UUIDv7 primary keys
+#   class User < ApplicationRecord
+#     # id will be automatically assigned a UUIDv7 on create
+#   end
+#
+# @example Migration with foreign keys
+#   # Foreign key types are automatically detected
+#   create_table :posts do |t|
+#     t.references :user, null: false  # Automatically uses :uuid type
+#     t.string :title
+#   end
+#
+# @see RailsUuidPk::HasUuidv7PrimaryKey
+# @see RailsUuidPk::Railtie
+# @see https://github.com/seouri/rails-uuid-pk
 module RailsUuidPk
+  # The prefix used for all log messages.
+  #
+  # @return [String] The log message prefix
+  LOG_PREFIX = "[RailsUuidPk]"
+
+  # Returns the logger instance for this gem.
+  #
+  # Uses Rails.logger if available and not nil, otherwise creates a new Logger instance.
+  #
+  # @return [Logger] The logger instance
+  # @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 = Logger.new($stdout) unless @logger.is_a?(Logger)
+    @logger
+  end
+
+  # Sets the logger instance for this gem.
+  #
+  # @param logger [Logger] The logger instance to use
+  # @example
+  #   RailsUuidPk.logger = Rails.logger
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  # Logs a message at the specified level.
+  #
+  # @param level [Symbol] The log level (:debug, :info, :warn, :error, :fatal)
+  # @param message [String] The message to log
+  # @example
+  #   RailsUuidPk.log(:info, "UUID assigned successfully")
+  def self.log(level, message)
+    logger.send(level, "#{LOG_PREFIX} #{message}")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-uuid-pk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Joon Lee
@@ -65,6 +65,76 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.9.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 description: Automatically use UUID v7 for all primary keys in Rails applications.
   Works with PostgreSQL, MySQL, and SQLite, zero configuration required.
 email: