rails-uuid-pk 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93efad36dbc0fb3ab34a2a348a5dad4ae0cb75c3f6f62bf7da4580146fbcccb3
-  data.tar.gz: df2a8e217103e1c732c894fd4ab48333e149e8a42a1a92a08bb023d72673ffa3
+  metadata.gz: cda21a747f154d1863e741ecce9b44855009bc202b11524be1a48911c6945ee2
+  data.tar.gz: f513b130b54f7d2230a13aa53bd60b707174005eff1bb792c0380a9d2b80a885
 SHA512:
-  metadata.gz: '09577137b7dbdd2b488260130f6afd4473292d06fb6646e141176de11a425f243b95ae3c43b8e69e89a7fcf3cb6b72d3f6cdb3b9794b56bf884c05895e4822de'
-  data.tar.gz: 9a5818221c1251cb137e61a30045fb98a0957af248f9f3e5908e5e9fb6f8d74d4de84dfb60d40135d60028d4d679070c8d295174990f8cc990f58752841a33f0
+  metadata.gz: 44070a3cf56eca32a1e83abdb83fa084abcb8c6042d2a2e06f3314bcfbf9df4e12a2794a5fab1e7d50d589455f2242dbf7e141618cd2b2b721b76be92ddfdc0f
+  data.tar.gz: 04ca3df41f44ca36bba89849a5c2a515481417b28b995670ecb93fb7a87a90abe5d9bf74bdb1b3a31c109a28127df2b9478bd63adbfa83fb5d0011e0b334a872

data/CHANGELOG.md

@@ -5,6 +5,73 @@ 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.8.0] - 2026-01-12
+
+### Changed
+- **Refactored UUID Type Registration**: Moved from global type map registration to connection-specific registration for improved precision and database compatibility
+- **Enhanced Type Mapping Precision**: UUID types now only map to specific `varchar(36)` and `uuid` SQL types, preventing hijacking of standard string columns
+- **Improved Adapter Extensions**: Enhanced MySQL and SQLite adapter extensions with dedicated `register_uuid_types` methods and proper initialization hooks
+
+### Added
+- **String Column Protection Test**: Added test to ensure standard string columns are not incorrectly mapped to UUID type
+
+### Technical Details
+- Updated Railtie to use `ActiveSupport.on_load` hooks for cleaner adapter extension prepending
+- Implemented connection-aware UUID type registration during adapter initialization and connection setup
+- Enhanced migration helpers compatibility and type detection robustness
+
+## [0.7.0] - 2026-01-12
+
+### Added
+- **SECURITY.md**: Comprehensive security documentation covering UUIDv7-specific security considerations
+  - Cryptographic security analysis with timestamp exposure details
+  - Database security implications and foreign key considerations
+  - Performance-security trade-offs analysis
+  - Security vulnerability reporting process
+  - Side-channel attack vectors and mitigation strategies
+  - Compliance considerations (GDPR, HIPAA, etc.)
+  - Security testing recommendations and monitoring guidelines
+- **ARCHITECTURE.md**: Comprehensive architecture documentation
+  - Core design principles and architectural decisions
+  - App-level vs database-level UUID generation analysis
+  - Database compatibility rationale and trade-offs
+  - Migration performance implications and caching strategies
+  - Database replication and backup considerations
+  - ORM and query builder integration details
+  - Error handling and resilience patterns
+  - Future evolution and extensibility points
+- **PERFORMANCE.md**: Comprehensive performance documentation in dedicated file
+  - UUID generation throughput metrics and cryptographic security details
+  - Database-specific performance characteristics (PostgreSQL, MySQL, SQLite)
+  - Index performance analysis comparing 36-byte UUIDs vs 4-byte integers
+  - Scaling recommendations for tables of different sizes (<1M, 1M-10M, >10M records)
+  - UUIDv7 vs UUIDv4 performance trade-offs with detailed comparison tables
+  - Index fragmentation and cache locality analysis
+  - Production monitoring and optimization guidelines
+- **README.md**: Streamlined with concise performance overview and link to PERFORMANCE.md
+- **Comprehensive UUIDv7 Correctness Testing**: Added extensive test suite validating UUIDv7 compliance
+  - RFC 9562 version and variant bits validation
+  - Timestamp monotonicity and collision resistance testing
+  - Format consistency and edge case handling
+  - Statistical randomness quality analysis
+  - Cross-database compatibility verification
+
+### Changed
+- **Schema Dumper Compatibility**: Replaced fragile `caller` detection with Rails version-aware schema type handling
+  - Rails 8.1+: Uses `:uuid` type in schema dumps for native UUID support
+  - Rails 8.0.x: Uses `:string` type to avoid "Unknown type 'uuid'" errors
+  - Future-proof design that adapts to Rails version changes
+  - Added comprehensive test coverage for schema dumping behavior
+
+### Fixed
+- **Schema Dumping Fragility**: Eliminated dependency on Rails internal `caller` stack inspection
+- **Rails Version Compatibility**: Robust handling of UUID types across different Rails versions
+
+### Security
+- Enhanced security posture with professional security documentation
+- Clear vulnerability disclosure process for responsible reporting
+- UUID-specific security guidance for enterprise adoption
+
 ## [0.6.0] - 2026-01-12
 
 ### Added

data/README.md

@@ -25,7 +25,7 @@ Automatically use UUID v7 for **all primary keys** in Rails applications. Works
 Add to your `Gemfile`:
 
 ```ruby
-gem "rails-uuid-pk", "~> 0.6"
+gem "rails-uuid-pk", "~> 0.8"
 ```
 
 Then run:
@@ -90,6 +90,24 @@ end
 | 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**: ~10,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 |
+
+**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
+
+For comprehensive performance analysis, scaling strategies, and optimization guides, see [PERFORMANCE.md](PERFORMANCE.md).
+
 ## Why not use native PostgreSQL `uuidv7()`?
 
 While PostgreSQL 18+ has excellent native `uuidv7()` support, the **fallback approach** was chosen for maximum compatibility:
@@ -105,12 +123,39 @@ You can still add native PostgreSQL defaults manually if you want maximum perfor
 
 ### Devcontainer Setup
 
-This project includes a devcontainer configuration for VS Code. To get started:
+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
 
+#### 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
+
+# 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.
@@ -156,6 +201,10 @@ For database testing, ensure the respective databases are running and accessible
 
 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).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).

data/lib/rails_uuid_pk/mysql2_adapter_extension.rb

@@ -5,5 +5,20 @@ module RailsUuidPk
         uuid: { name: "varchar", limit: 36 }
       )
     end
+
+    def register_uuid_types(m = type_map)
+      m.register_type(/varchar\(36\)/i) { RailsUuidPk::Type::Uuid.new }
+      m.register_type("uuid") { RailsUuidPk::Type::Uuid.new }
+    end
+
+    def initialize_type_map(m = type_map)
+      super
+      register_uuid_types(m)
+    end
+
+    def configure_connection
+      super
+      register_uuid_types
+    end
   end
 end

data/lib/rails_uuid_pk/railtie.rb

@@ -16,17 +16,31 @@ module RailsUuidPk
     end
 
     initializer "rails-uuid-pk.native_types" do
+      ActiveSupport.on_load(:active_record_sqlite3adapter) do
+        prepend RailsUuidPk::Sqlite3AdapterExtension
+      end
+
+      ActiveSupport.on_load(:active_record_mysql2adapter) do
+        prepend RailsUuidPk::Mysql2AdapterExtension
+      end
+    end
+
+    config.after_initialize do
       ActiveSupport.on_load(:active_record) do
-        case ActiveRecord::Base.connection.adapter_name
-        when "SQLite"
-          require "active_record/connection_adapters/sqlite3_adapter"
-          ActiveRecord::ConnectionAdapters::SQLite3Adapter.prepend(RailsUuidPk::Sqlite3AdapterExtension)
-        when "MySQL"
-          begin
-            require "active_record/connection_adapters/mysql2_adapter"
-            ActiveRecord::ConnectionAdapters::Mysql2Adapter.prepend(RailsUuidPk::Mysql2AdapterExtension)
-          rescue LoadError
-            # MySQL adapter not available
+        if ActiveRecord::Base.connected?
+          ActiveRecord::Base.connection_handler.connection_pool_list.each do |pool|
+            connections = if pool.respond_to?(:connections)
+                            pool.connections
+            else
+                            # Fallback or older rails
+                            [ pool.connection ] rescue []
+            end
+
+            connections.each do |conn|
+              if conn.respond_to?(:register_uuid_types)
+                conn.register_uuid_types
+              end
+            end
           end
         end
       end
@@ -54,13 +68,6 @@ module RailsUuidPk
 
     def self.register_uuid_type(adapter)
       ActiveRecord::Type.register(:uuid, RailsUuidPk::Type::Uuid, adapter: adapter)
-
-      # Get the connection-specific type map
-      type_map = ActiveRecord::Base.connection.send(:type_map)
-      # Map varchar(36) or varchar SQL type to our custom UUID type
-      type_map.register_type(/varchar/i) { RailsUuidPk::Type::Uuid.new }
-      # Also map "uuid" SQL type for direct lookups
-      type_map.register_type("uuid") { RailsUuidPk::Type::Uuid.new }
     end
   end
 end

data/lib/rails_uuid_pk/sqlite3_adapter_extension.rb

@@ -5,5 +5,21 @@ module RailsUuidPk
         uuid: { name: "varchar", limit: 36 }
       )
     end
+
+    def register_uuid_types(m = type_map)
+      puts "[RailsUuidPk] 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
+
+    def initialize_type_map(m = type_map)
+      super
+      register_uuid_types(m)
+    end
+
+    def configure_connection
+      super
+      register_uuid_types
+    end
   end
 end

data/lib/rails_uuid_pk/type.rb

@@ -2,12 +2,12 @@ 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
+        # Rails 8.1+ supports UUID types in schema dumping
+        # Earlier versions need :string to avoid "Unknown type 'uuid'" errors
+        if rails_supports_uuid_in_schema?
           :uuid
+        else
+          :string
         end
       end
 
@@ -42,6 +42,13 @@ module RailsUuidPk
       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
+
+      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
+        rails_version = Gem::Version.new(Rails::VERSION::STRING)
+        rails_version >= Gem::Version.new("8.1.0")
+      end
     end
   end
 end

data/lib/rails_uuid_pk/version.rb

@@ -1,3 +1,3 @@
 module RailsUuidPk
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-uuid-pk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Joon Lee