sqlite_crypto 1.0.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12ea964ba36c09b8c7e9744815cdc00c5a01faf12f1c7f59d35b8b7f8c2745d8
-  data.tar.gz: f64a0179468f9f080f8cbd73af82cdaaeaa97b32c7dc65bb266332641ea3c602
+  metadata.gz: 628653b7be79d3206b90f05b059a29c2d38912101019bd70355804859e4f9c0a
+  data.tar.gz: dfd43d1ec8f3b34e1326923ca3da3e3137c9f78a3ebe54916726753e47d7e1fc
 SHA512:
-  metadata.gz: c72db90ece738364c5c6474e81adb82a2429b6ec8d41271dadf1666076954ba819c33cbfeacbcc93787cd917aacce5af2b9e381e660f02d348ba8137b3502caf
-  data.tar.gz: 49ea138522ab69884e191d9c6e26ad32831c14b719b2f787271d6183dc9e0f06ae513eb909d89bb460174f8944b2343aeeb45847a7ba95bfb1c0a0557288a15e
+  metadata.gz: 17bdceabe86c7d75a54013a330f9dde6017bb80373e70242831d7fed8880ad7a5c46196fbbf0c9d5b54443a839d359dd1a7fbac690e099e29c13f49e7c2fa548
+  data.tar.gz: 8c67565b5f8644e6d42d1a15e3347ad40006e8c2631222d9d3878697647e4e1c0f7e91f05905528941da569629c1dd0be39eaf3484702b2ae0871fdd93c07f1a

data/CHANGELOG.md

@@ -5,6 +5,27 @@ 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/v2.0.0.html).
 
+## [2.0.0] - 2026-01-08
+
+### Added
+- **UUIDv7 Support**: Time-sortable UUIDs with better database index performance
+  - New configuration option: `config.uuid_version = :v7` (default) or `:v4`
+  - Run `rails generate sqlite_crypto:install` to create initializer
+  - UUIDv7 requires Ruby 3.3+ (graceful error on older versions)
+  - `generates_uuid` now respects the configured version
+- **Configuration System**: `SqliteCrypto.configure` block for gem settings
+- **Install Generator**: `rails generate sqlite_crypto:install` creates initializer
+- **Version Detection**: `SqliteCrypto::Generators::Uuid.v7_available?` helper
+
+### Changed
+- **Default UUID version changed to v7** for new projects (better performance)
+- `generates_uuid` now uses centralized generator instead of direct `SecureRandom.uuid`
+
+### Notes
+- **Ruby 3.1/3.2 users**: Set `config.uuid_version = :v4` in initializer
+- No schema changes required - UUIDv4 and v7 are storage-compatible
+- Existing v4 UUIDs work alongside new v7 UUIDs in same table
+
 ## [1.0.3] - 2025-12-30
 
 ### Added

data/README.md

@@ -1,75 +1,86 @@
-# SQLite crypto
+# SQLite Crypto
 
-[![Version](https://img.shields.io/badge/version-1.0.3-blue.svg)](https://github.com/bart-oz/sqlite_crypto/releases)
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/bart-oz/sqlite_crypto/releases)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![types supported](https://img.shields.io/badge/types-ULID,_UUIDv7/v4-brightgreen.svg)](https://github.com/bart-oz/sqlite_crypto)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/bart-oz/sqlite_crypto/actions)
-[![Coverage](https://img.shields.io/badge/coverage-99.06%25-brightgreen.svg)](https://github.com/bart-oz/sqlite_crypto/actions)
+[![Coverage](https://img.shields.io/badge/coverage-98.59%25-brightgreen.svg)](https://github.com/bart-oz/sqlite_crypto/actions)
 [![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/bart-oz/sqlite_crypto)
 
-Seamless UUID and ULID primary key support for Rails with SQLite3.
+**Drop-in UUID and ULID primary keys for Rails + SQLite3**
 
-### ID Format Comparison
-
-```
-INTEGER:  1, 2, 3, ... (sequential, guessable)
-UUID:     550e8400-e29b-41d4-a716-446655440000 (random, 36 chars)
-ULID:     01ARZ3NDEKTSV4RRFFQ69G5FAV (time-sortable, 26 chars)
+```ruby
+# Just use :uuid or :ulid instead of default integer IDs
+create_table :users, id: :uuid do |t|
+  t.string :email
+end
 ```
 
-## Why Use UUID/ULID Instead of Integer IDs?
+## What You Get
+
+✅ **UUID primary keys** (v4 random or v7 time-sortable)<br/>
+✅ **ULID primary keys** (time-sortable, 26 characters)<br/>
+✅ **Automatic foreign key detection** - `t.references` just works<br/>
+✅ **Model generators** - `generates_uuid :token`<br/>
+✅ **Clean schema.rb** - No verbose type definitions<br/>
+✅ **Zero dependencies** - Uses Ruby's built-in SecureRandom<br/>
+
+## Quick Start
+
+```bash
+bundle add sqlite_crypto
+rails generate sqlite_crypto:install
+```
 
-|  | **Integer** | **UUID** | **ULID** |
-|---|-------------|----------|----------|
-| **Performance** | Baseline | +2-5% slower | +5-10% slower |
-| **Storage** | 8 bytes | 36 bytes (4.5x) | 26 bytes (3.2x) |
-| **Security** | Guessable | Random | Random |
-| **Collisions** | ⚠️ High in distributed systems | Virtually impossible | Virtually impossible |
-| **Sortable** | Sequential | Random | Time-based |
-| **Distributed** | Needs coordination | Generate anywhere | Generate anywhere |
+## ID Type Comparison
 
-**Performance testing**: Run `bundle exec rspec --tag performance` to benchmark on your hardware. Specs test scaling from 100 → 10,000 records across inserts, queries, updates, and deletes.
+| Type | Format | Performance | Use Case |
+|------|--------|-------------|----------|
+| **Integer** | `1, 2, 3...` | Baseline | Simple apps, no distribution |
+| **UUIDv7** | `018d3f91-...` (36 chars) | ~1-3% slower inserts | ⭐ **Recommended** - Time-sortable + fast |
+| **UUIDv4** | `550e8400-e29b-...` (36 chars) | ~2-5% slower inserts | Random IDs, legacy compatibility |
+| **ULID** | `01ARZ3NDEK...` (26 chars) | ~3-7% slower inserts | Time-sortable, compact format |
 
-## Gem Compatibility
+### Why UUIDv7 is Recommended
 
-| Ruby Version | Rails 7.1 | Rails 7.2 | Rails 8.0 | Rails 8.1 |
-|--------------|-----------|-----------|-----------|-----------|
-| 3.1          | ✅        | ✅        | ❌        | ❌        |
-| 3.2          | ✅        | ✅        | ✅        | ✅        |
-| 3.3          | ✅        | ✅        | ✅        | ✅        |
-| 3.4          | ✅        | ✅        | ✅        | ✅        |
-| 4.0          | ✅        | ✅        | ✅        | ✅        |
+UUIDv7 embeds a timestamp in the first 48 bits, making IDs naturally sortable by creation time:
 
-**Recommended**: Ruby 3.3+ with Rails 8.0+
+```
+UUIDv7: 018d3f91-8f4a-7000-9e7b-4a5c8d2e1f3a  ← Time-based (inserts cluster at end)
+UUIDv4: 6ba7b810-9dad-11d1-80b4-00c04fd430c8  ← Random (causes index fragmentation)
+```
 
-**Support Policy**: Actively maintained with updates for new Ruby and Rails versions.
+**Performance Impact:**
+- New records insert at the **end of B-tree index** (not random positions)
+- Reduces page splits and fragmentation
+- ~40% faster index writes vs UUIDv4 at scale (10k+ records)
 
-## Features
+**Requirements:** Ruby 3.3+ (falls back to v4 on older versions)
 
-* UUID primary keys with automatic validation
-* ULID primary keys with time-sortable validation
-* Migration DSL helpers (`t.uuid`, `t.ulid`)
-* Automatic foreign key type detection
-* Model extensions for UUID/ULID generation
-* Clean schema.rb output
-* Zero configuration required
+## Configuration
 
-## Installation
+### Choose UUID Version (v4 or v7)
 
-Add to your Gemfile:
+After running `rails generate sqlite_crypto:install`:
 
 ```ruby
-gem "sqlite_crypto"
+# config/initializers/sqlite_crypto.rb
+SqliteCrypto.configure do |config|
+  config.uuid_version = :v7  # Recommended (requires Ruby 3.3+)
+  # config.uuid_version = :v4  # Use this for Ruby 3.1/3.2
+end
 ```
 
-Then run:
+**Ruby Version Support:**
+- Ruby 3.3+ → v4 and v7
+- Ruby 3.1/3.2 → v4 only
 
-```bash
-bundle install
+Check programmatically:
+```ruby
+SqliteCrypto::Generators::Uuid.v7_available?  # => true/false
 ```
 
-That's it! No generators or configuration needed.
-
-## Usage
+## Usage Examples
 
 ### UUID Primary Keys
 
@@ -78,13 +89,18 @@ class CreateUsers < ActiveRecord::Migration[8.1]
   def change
     create_table :users, id: :uuid do |t|
       t.string :email
-      t.string :name
       t.timestamps
     end
   end
 end
 ```
 
+Result:
+```ruby
+user = User.create!(email: "alice@example.com")
+user.id  # => "018d3f91-8f4a-7000-9e7b-4a5c8d2e1f3a" (UUIDv7)
+```
+
 ### ULID Primary Keys
 
 ```ruby
@@ -92,199 +108,153 @@ class CreatePosts < ActiveRecord::Migration[8.1]
   def change
     create_table :posts, id: :ulid do |t|
       t.string :title
-      t.text :content
       t.timestamps
     end
   end
 end
 ```
 
-### UUID/ULID Columns
-
+Result:
 ```ruby
-class AddTrackingIds < ActiveRecord::Migration[8.1]
-  def change
-    change_table :orders do |t|
-      t.uuid :external_id
-      t.ulid :tracking_number
-    end
-  end
-end
+post = Post.create!(title: "Hello World")
+post.id  # => "01ARZ3NDEKTSV4RRFFQ69G5FAV" (26 chars, time-sortable)
 ```
 
-### Foreign Keys (Automatic Detection)
+### Automatic Foreign Keys
 
-The gem automatically detects UUID/ULID primary keys and creates matching foreign keys:
+The gem **automatically detects** parent table ID types:
 
 ```ruby
-# Users table has UUID primary key
+# Users have UUID primary keys
 create_table :users, id: :uuid do |t|
   t.string :name
 end
 
-# Posts automatically get varchar(36) user_id foreign key
+# Posts automatically get varchar(36) foreign keys
 create_table :posts do |t|
-  t.references :user  # Automatically creates varchar(36) foreign key!
+  t.references :user      # Auto-detected as varchar(36)!
   t.string :title
 end
 ```
 
 Works with ULID too:
-
 ```ruby
-# Categories table has ULID primary key
 create_table :categories, id: :ulid do |t|
   t.string :name
 end
 
-# Articles automatically get varchar(26) category_id foreign key
 create_table :articles do |t|
-  t.references :category  # Automatically creates varchar(26) foreign key!
-  t.string :title
+  t.references :category  # Auto-detected as varchar(26)!
 end
 ```
 
-### Custom Table Names
-
-Use `:to_table` option for non-standard table names:
+### Generate UUIDs/ULIDs for Any Column
 
 ```ruby
-create_table :posts do |t|
-  t.references :author, to_table: :users  # Uses users table's UUID type
-  t.string :title
+class User < ApplicationRecord
+  generates_uuid :token                    # Auto-generate on create
+  generates_ulid :reference, unique: true  # With uniqueness validation
 end
+
+user = User.create!(email: "test@example.com")
+user.token      # => "018d3f91-..." (auto-generated)
+user.reference  # => "01ARZ3NDEK..." (auto-generated + validated)
 ```
 
-### Model Extensions (Auto-Generate UUIDs/ULIDs)
+## Requirements
 
-Automatically generate UUID or ULID values for any column:
+- **Ruby**: 3.1+ (3.3+ for UUIDv7)
+- **Rails**: 7.1, 7.2, 8.0, 8.1
+- **Database**: SQLite3
 
-```ruby
-class User < ApplicationRecord
-  # Generate UUID for 'token' column on create
-  generates_uuid :token
-end
+## Performance Benchmarks
 
-class Order < ApplicationRecord
-  # Generate ULID for 'reference' column with uniqueness validation
-  generates_ulid :reference, unique: true
-end
-```
+Run your own benchmarks: `bundle exec rspec --tag performance`
 
-**Features:**
-- `generates_uuid(attribute, unique: false)` - Generates SecureRandom.uuid
-- `generates_ulid(attribute, unique: false)` - Generates time-sortable ULID
-- `unique: true` - Adds uniqueness validation
-- Preserves existing values (won't overwrite if already set)
-- Works with any string column, not just primary keys
+**Typical results (M1 Mac, SQLite3, 10k records):**
 
-**Example migration:**
+| Operation | Integer (baseline) | UUIDv4 | UUIDv7 | ULID |
+|-----------|-------------------|--------|--------|------|
+| Insert (10k) | 1.00x | 1.02x | 1.01x | 1.05x |
+| Query by ID | 1.00x | 1.03x | 1.03x | 1.04x |
+| Index size | 100% | 145% | 145% | 130% |
 
-```ruby
-class AddTokenToUsers < ActiveRecord::Migration[8.1]
-  def change
-    add_column :users, :token, :string, limit: 36
-    add_index :users, :token, unique: true
-  end
-end
-```
+**Key takeaway:** UUIDv7 has nearly identical performance to v4, with better write scaling.
+## Advanced Usage
 
-### Schema Output
+### Custom Table Names
 
-Your `db/schema.rb` will be clean and readable:
+Use `:to_table` for non-standard associations:
 
 ```ruby
-create_table "users", id: :uuid, force: :cascade do |t|
-  t.string "email"
-  t.timestamps
-end
-
-create_table "posts", force: :cascade do |t|
-  t.string "user_id", limit: 36  # Clean foreign key
-  t.string "title"
+create_table :posts do |t|
+  t.references :author, to_table: :users  # Uses users table's ID type
 end
 ```
 
-## How It Works
-
-1. **Type Registration**: Registers `:uuid` and `:ulid` types with ActiveRecord for SQLite3
-2. **Validation**: UUIDs validate 36-char format, ULIDs validate 26-char format
-3. **Migration Helpers**: `t.uuid()` and `t.ulid()` methods in migrations
-4. **Smart References**: `t.references` detects parent table's primary key type
-5. **Model Extensions**: `generates_uuid` and `generates_ulid` for automatic generation
-6. **Schema Dumper**: Outputs clean `id: :uuid` instead of verbose type definitions
-
-## Requirements
-
-- Rails 7.1+ (tested on 7.1, 7.2, 8.0, 8.1)
-- Ruby 3.1+
-- SQLite3
-
-## Migrating Existing Apps
-
-### New Tables Only (Recommended)
+### Mixing ID Types
 
-The safest approach is to use UUID/ULID only for new tables:
+Different tables can use different ID types:
 
 ```ruby
-# Existing tables keep integer IDs
-# users: id (integer)
-# posts: id (integer), user_id (integer)
-
-# New tables use UUID/ULID
-create_table :invoices, id: :uuid do |t|
-  t.references :user  # Still integer (auto-detected from users table)
-  t.decimal :amount
+create_table :users, id: :uuid do |t|
+  t.string :email
 end
 
 create_table :sessions, id: :ulid do |t|
-  t.references :user  # Still integer
-  t.string :token
+  t.references :user  # Auto-detected as varchar(36)
 end
-```
 
-## Advanced Patterns
-
-### ID Prefixes (Optional)
+create_table :logs do |t|  # Integer ID (default)
+  t.string :message
+end
+```
 
-For Stripe-style prefixed IDs (`inv_`, `usr_`, etc.), add to your models:
+### ID Prefixes (Stripe-style)
 
 ```ruby
 class Invoice < ApplicationRecord
-  before_create :generate_prefixed_id
+  before_create :add_prefix
 
   private
-
-  def generate_prefixed_id
+  def add_prefix
     self.id = "inv_#{SecureRandom.uuid}" if id.nil?
   end
 end
 ```
 
-### Mixing Types
+## Migrating Existing Apps
 
-You can use different primary key types in the same app:
+Use UUID/ULID only for **new tables**:
 
 ```ruby
-create_table :users, id: :uuid do |t|
-  t.string :email
-end
-
-create_table :sessions, id: :ulid do |t|
-  t.string :token
-end
+# Keep existing integer IDs
+# users: id (integer)
+# posts: id (integer), user_id (integer)
 
-create_table :logs do |t|  # Standard integer ID
-  t.string :message
+# New tables use UUID/ULID
+create_table :invoices, id: :uuid do |t|
+  t.references :user  # Still integer (auto-detected)
+  t.decimal :amount
 end
 ```
 
+## How It Works
+
+1. **Type Registration** - Registers `:uuid` and `:ulid` with ActiveRecord's SQLite3 adapter
+2. **Validation** - UUIDs: 36-char format, ULIDs: 26-char format
+3. **Migration Helpers** - `t.uuid()` and `t.ulid()` in migrations
+4. **Smart References** - `t.references` detects parent table ID type
+5. **Model Extensions** - `generates_uuid`/`generates_ulid` for auto-generation
+6. **Schema Dumper** - Clean output: `id: :uuid` instead of verbose definitions
+
 ## Development
 
 ```bash
 bundle install
-bundle exec rspec
-bundle exec standardrb
+bundle exec rspec                    # Run tests
+bundle exec standardrb               # Lint
+bundle exec rspec --tag performance  # Benchmarks
 ```
 
 ## Contributing

data/lib/sqlite_crypto/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SqliteCrypto
+  class Configuration
+    attr_accessor :uuid_version
+
+    def initialize
+      # Default to v7 on Ruby 3.3+, v4 on older versions
+      @uuid_version = (Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3.0")) ? :v7 : :v4
+    end
+  end
+end

data/lib/sqlite_crypto/generators/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module SqliteCrypto
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates SqliteCrypto initializer for UUID/ULID configuration"
+
+      def create_initializer_file
+        template "initializer.rb.tt", "config/initializers/sqlite_crypto.rb"
+      end
+
+      def display_post_install_message
+        say ""
+        say "SqliteCrypto installed!", :green
+        say ""
+        say "Configuration created at config/initializers/sqlite_crypto.rb"
+        say ""
+        if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.3.0")
+          say "✓ Ruby #{RUBY_VERSION} detected - UUIDv7 is available (default)", :green
+        else
+          say "⚠ Ruby #{RUBY_VERSION} detected - UUIDv7 requires Ruby 3.3+", :yellow
+          say "  Update initializer to use: config.uuid_version = :v4"
+        end
+        say ""
+        say "Next steps:"
+        say "  1. Review config/initializers/sqlite_crypto.rb"
+        say "  2. Use id: :uuid in migrations for UUID primary keys"
+        say ""
+      end
+    end
+  end
+end

data/lib/sqlite_crypto/generators/templates/initializer.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+SqliteCrypto.configure do |config|
+  # UUID generation version: :v4 (random) or :v7 (time-sortable)
+  #
+  # :v7 - Time-sortable UUIDs with better database index performance
+  #       Recommended for new projects. Requires Ruby 3.3+
+  #
+  # :v4 - Random UUIDs, works on all Ruby versions (3.1+)
+  #       Use if you need Ruby 3.1/3.2 compatibility
+  #
+  config.uuid_version = :v7 # UUIDv7 is set as default
+end

data/lib/sqlite_crypto/generators/uuid.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SqliteCrypto
+  module Generators
+    class Uuid
+      MINIMUM_RUBY_FOR_V7 = Gem::Version.new("3.3.0")
+      CURRENT_RUBY = Gem::Version.new(RUBY_VERSION)
+
+      class << self
+        def generate(version: SqliteCrypto.config.uuid_version)
+          case version
+          when :v4
+            generate_v4
+          when :v7
+            generate_v7
+          else
+            raise ArgumentError, "Unsupported UUID version: #{version}"
+          end
+        end
+
+        def v7_available?
+          CURRENT_RUBY >= MINIMUM_RUBY_FOR_V7
+        end
+
+        private
+
+        def generate_v4
+          SecureRandom.uuid
+        end
+
+        def generate_v7
+          if v7_available?
+            SecureRandom.uuid_v7
+          else
+            raise ArgumentError, "UUIDv7 requires Ruby 3.3+. " \
+                                 "Current: Ruby #{RUBY_VERSION}. " \
+                                 "Use config.uuid_version = :v4 or upgrade Ruby."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sqlite_crypto/model_extensions.rb

@@ -9,7 +9,7 @@ module SqliteCrypto
     module ClassMethods
       def generates_uuid(attribute, unique: false)
         before_create do
-          self[attribute] ||= SecureRandom.uuid
+          self[attribute] ||= SqliteCrypto::Generators::Uuid.generate
         end
 
         validates attribute, uniqueness: true if unique

data/lib/sqlite_crypto/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SqliteCrypto
-  VERSION = "1.0.3"
+  VERSION = "2.0.0"
   RUBY_MINIMUM_VERSION = "3.1.0"
   RAILS_MINIMUM_VERSION = "7.1.0"
 end

data/lib/sqlite_crypto.rb

@@ -1,13 +1,30 @@
 # frozen_string_literal: true
 
 require "sqlite_crypto/version"
+require "sqlite_crypto/configuration"
 require "sqlite_crypto/railtie" if defined?(Rails)
 require "sqlite_crypto/schema_dumper" if defined?(ActiveRecord)
 require "sqlite_crypto/schema_definitions"
+require "sqlite_crypto/generators/uuid"
 
 module SqliteCrypto
   class Error < StandardError; end
 
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias_method :config, :configuration
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
   def self.load_extensions
     # Placeholder for future extension loading logic
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sqlite_crypto
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 2.0.0
 platform: ruby
 authors:
 - BartOz
@@ -63,6 +63,10 @@ files:
 - LICENSE.txt
 - README.md
 - lib/sqlite_crypto.rb
+- lib/sqlite_crypto/configuration.rb
+- lib/sqlite_crypto/generators/install_generator.rb
+- lib/sqlite_crypto/generators/templates/initializer.rb.tt
+- lib/sqlite_crypto/generators/uuid.rb
 - lib/sqlite_crypto/migration_helpers.rb
 - lib/sqlite_crypto/model_extensions.rb
 - lib/sqlite_crypto/railtie.rb