familia 2.0.0.pre.pre → 2.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92ee81bd30cdbcb84de0e72a26bde44a170efcd6578d81bdd47458aee37f52be
-  data.tar.gz: 4127847dbc955df3e6a7c7a3dd616dd3438da046f8703a59c734399697cf8903
+  metadata.gz: e104394eac8f785cc87da94119810cf0634d9c4b26e0c37bbf9682a64223637c
+  data.tar.gz: 91d80c9e21c48e0e50867a0296ac7bfee93f800ca23905369d2e0e47f41e6a03
 SHA512:
-  metadata.gz: 87f8ff4b5423771ce6c1c93640cd3e83ea1e9beb023c130896878bed64fd61341ac18b365641bd7c30310fafdcf1b31569ca726dbaedf5c7ec23d308805b3305
-  data.tar.gz: d76036d625a604014380a67e5765263c2ea51bb608da09344a57fb4cf8386ae724499bb27e352c7d7133d15ae16a052dcb27ea262943cb509662666c72983d13
+  metadata.gz: a50739960222cae1f8e66cc1e6ece4bf023d18d23ad141acd80c5a9b22387d99be22111459da2a34a7b22b45361d57311dd943ee3cc595e081a8fbf36ef81abf
+  data.tar.gz: dc330db28c720538589341ceb3a914687c83efe5d3ead5f892953c6bdf36882c08468f00e031a767758ae7887cfb3525df9224b5852804ef50739eac403ae333

data/Gemfile

@@ -6,7 +6,8 @@ gemspec
 
 group :test do
   if ENV['LOCAL_DEV']
-    gem 'tryouts', path: '../../d/tryouts'
+    gem 'tryouts', path: '../tryouts'
+    gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
     gem 'tryouts', '~> 3.1.1', require: false
   end
@@ -15,7 +16,6 @@ group :test do
   gem 'stackprof'
 end
 
-
 group :development, :test do
   # byebug only works with MRI
   gem 'byebug', '~> 11.0', require: false if RUBY_ENGINE == 'ruby'
@@ -25,4 +25,5 @@ group :development, :test do
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'yard', '~> 0.9', require: false
+  gem 'irb', '~> 1.15.2', require: false
 end

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre.pre)
+    familia (2.0.0.pre2)
       benchmark
       connection_pool
       csv
       logger
       redis (>= 4.8.1, < 6.0)
       stringio (~> 3.1.1)
-      uri-redis (~> 1.3)
+      uri-valkey (~> 1.4)
 
 GEM
   remote: https://rubygems.org/
@@ -21,8 +21,15 @@ GEM
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
     csv (3.3.5)
+    date (3.4.1)
     diff-lcs (1.6.2)
     drydock (0.6.9)
+    erb (5.0.2)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
     json (2.13.0)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
@@ -35,6 +42,9 @@ GEM
     parser (3.3.8.0)
       ast (~> 2.4.1)
       racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
     prism (1.4.0)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -42,13 +52,21 @@ GEM
     pry-byebug (3.10.1)
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
+    psych (5.2.6)
+      date
+      stringio
     racc (1.8.1)
     rainbow (3.1.1)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
     redis (5.4.1)
       redis-client (>= 0.22.0)
     redis-client (0.25.1)
       connection_pool
     regexp_parser (2.10.0)
+    reline (0.6.2)
+      io-console (~> 0.5)
     rexml (3.4.1)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
@@ -101,7 +119,7 @@ GEM
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
-    uri-redis (1.3.0)
+    uri-valkey (1.4.0)
     yard (0.9.37)
 
 PLATFORMS
@@ -112,6 +130,7 @@ DEPENDENCIES
   byebug (~> 11.0)
   concurrent-ruby (~> 1.3.5)
   familia!
+  irb (~> 1.15.2)
   kramdown
   pry-byebug (~> 3.10.1)
   rubocop

data/bin/irb

@@ -1,3 +1,3 @@
 #!/bin/bash
 
-irb -ruri/redis -Ilib -r familia -Itry -r helpers/test_helpers
+irb -Ilib -r familia -Itry -r helpers/test_helpers

data/docs/connection_pooling.md

@@ -1,317 +1,192 @@
 # Connection Pooling with Familia
 
-Familia uses a flexible connection provider pattern that allows you to implement connection pooling in your application. This guide shows how to configure connection pools for optimal performance with multiple logical databases.
+Familia uses a connection provider pattern for efficient connection pooling. This guide shows how to configure pools for optimal performance with multiple logical databases.
 
 ## Key Concepts
 
-1. **Connection Provider Contract**: When you provide a `connection_provider`, it MUST return connections already on the correct logical database. Familia will NOT issue SELECT commands after receiving a connection from the provider.
+- **Connection Provider Contract**: Your provider MUST return connections already on the correct logical database. Familia will NOT issue SELECT commands.
+- **URI-based Selection**: Familia passes normalized URIs (e.g., `redis://localhost:6379/2`) encoding the logical database.
+- **One Pool Per Database**: Each unique logical database requires its own connection pool.
 
-2. **URI-based Selection**: Familia passes normalized URIs (e.g., `redis://localhost:6379/2`) to your provider, encoding the logical database in the URI.
+## Basic Setup
 
-3. **One Pool Per Database**: Since Familia models can use different logical databases, you typically need one connection pool per unique database.
-
-## Basic Connection Pool Setup
-
-### Example 1: Simple Connection Pool
+### Simple Connection Pool
 
 ```ruby
 require 'connection_pool'
-require 'familia'
 
 class MyApp
-  def self.setup_familia_pools
-    @pools = {}
-    
-    Familia.connection_provider = lambda do |uri|
-      parsed = URI.parse(uri)
-      pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
-      
-      # Create a pool for each unique database
-      @pools[pool_key] ||= ConnectionPool.new(size: 10, timeout: 5) do
-        Redis.new(
-          host: parsed.host,
-          port: parsed.port,
-          db: parsed.db || 0  # Connection created with correct DB
-        )
-      end
-      
-      # Return a connection from the pool
-      @pools[pool_key].with { |conn| conn }
+  @pools = {}
+
+  Familia.connection_provider = lambda do |uri|
+    parsed = URI.parse(uri)
+    pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
+
+    @pools[pool_key] ||= ConnectionPool.new(size: 10, timeout: 5) do
+      Redis.new(
+        host: parsed.host,
+        port: parsed.port,
+        db: parsed.db || 0
+      )
     end
+
+    @pools[pool_key].with { |conn| conn }
   end
 end
 ```
 
-### Example 2: Advanced Pooling with Different Configurations
+### Multi-Database Configuration
 
 ```ruby
 class MyApp
-  # Different pool sizes based on expected traffic
   POOL_CONFIGS = {
-    0 => { size: 20, timeout: 5 },  # High-traffic main database
-    1 => { size: 5, timeout: 5 },   # Low-traffic analytics database
-    2 => { size: 10, timeout: 5 },  # Medium-traffic cache database
-    3 => { size: 5, timeout: 5 }    # Session database
-  }
-  
-  def self.setup_familia_pools
-    @pools = {}
-    
-    Familia.connection_provider = lambda do |uri|
-      parsed = URI.parse(uri)
-      db = parsed.db || 0
-      pool_key = "#{parsed.host}:#{parsed.port}/#{db}"
-      
-      @pools[pool_key] ||= begin
-        config = POOL_CONFIGS[db] || { size: 5, timeout: 5 }
-        ConnectionPool.new(**config) do
-          Redis.new(host: parsed.host, port: parsed.port, db: db)
-        end
+    0 => { size: 20 },  # Main database
+    1 => { size: 5 },   # Analytics
+    2 => { size: 10 }   # Cache
+  }.freeze
+
+  @pools = {}
+
+  Familia.connection_provider = lambda do |uri|
+    parsed = URI.parse(uri)
+    db = parsed.db || 0
+    pool_key = "#{parsed.host}:#{parsed.port}/#{db}"
+
+    @pools[pool_key] ||= begin
+      config = POOL_CONFIGS[db] || { size: 5 }
+      ConnectionPool.new(timeout: 5, **config) do
+        Redis.new(host: parsed.host, port: parsed.port, db: db)
       end
-      
-      @pools[pool_key].with { |conn| conn }
     end
+
+    @pools[pool_key].with { |conn| conn }
   end
 end
 ```
 
-### Example 3: Using with Puma/Multi-threaded Servers
+### Production Setup with Roda
 
 ```ruby
-# In config/initializers/familia.rb
+# config/familia.rb
+class FamiliaPoolManager
+  include Singleton
 
-# Global connection pools shared across threads
-$redis_pools = {}
-$pool_mutex = Mutex.new
+  def initialize
+    @pools = {}
+  end
 
-Familia.connection_provider = lambda do |uri|
-  parsed = URI.parse(uri)
-  pool_key = parsed.to_s
-  
-  # Thread-safe pool creation
-  $pool_mutex.synchronize do
-    $redis_pools[pool_key] ||= ConnectionPool.new(
-      size: ENV.fetch('RAILS_MAX_THREADS', 5).to_i,
+  def get_connection(uri)
+    parsed = URI.parse(uri)
+    pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
+
+    @pools[pool_key] ||= ConnectionPool.new(
+      size: pool_size_for_environment,
       timeout: 5
     ) do
       Redis.new(
         host: parsed.host,
         port: parsed.port,
         db: parsed.db || 0,
-        timeout: 1,  # Connection timeout
+        timeout: 1,
         reconnect_attempts: 3
       )
     end
-  end
-  
-  $redis_pools[pool_key].with { |conn| conn }
-end
-```
-
-### Example 4: Using with Sidekiq
-
-```ruby
-# Sidekiq has its own connection pool management
-# This example shows how to share pools between Sidekiq and web processes
 
-class RedisConnectionPools
-  include Singleton
-  
-  def initialize
-    @pools = {}
-    @mutex = Mutex.new
+    @pools[pool_key].with { |conn| conn }
   end
-  
-  def get_connection(uri)
-    parsed = URI.parse(uri)
-    pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
-    
-    pool = @mutex.synchronize do
-      @pools[pool_key] ||= ConnectionPool.new(
-        size: determine_pool_size,
-        timeout: 5
-      ) do
-        Redis.new(
-          host: parsed.host,
-          port: parsed.port,
-          db: parsed.db || 0
-        )
-      end
-    end
-    
-    pool.with { |conn| conn }
-  end
-  
+
   private
-  
-  def determine_pool_size
+
+  def pool_size_for_environment
     if defined?(Sidekiq)
-      # Sidekiq workers need more connections
       Sidekiq.options[:concurrency] + 2
     else
-      # Web processes need fewer connections
-      ENV.fetch('RAILS_MAX_THREADS', 5).to_i
+      ENV.fetch('WEB_CONCURRENCY', 5).to_i + 2
     end
   end
 end
 
-# Configure Familia
+# Configure at application startup
 Familia.connection_provider = lambda do |uri|
-  RedisConnectionPools.instance.get_connection(uri)
+  FamiliaPoolManager.instance.get_connection(uri)
+end
+
+# In your Roda app
+class App < Roda
+  plugin :hooks
+
+  before do
+    # Familia pools are automatically used via connection_provider
+  end
 end
 ```
 
 ## Model Configuration
 
-Models can specify different logical databases:
+Configure models to use different logical databases:
 
 ```ruby
-# Models using different logical databases
 class Customer < Familia::Horreum
   self.logical_database = 0  # Main application data
-  field :name
-  field :email
+  field :name, :email
 end
 
 class Analytics < Familia::Horreum
-  self.logical_database = 1  # Analytics data  
-  field :event_type
-  field :timestamp
+  self.logical_database = 1  # Analytics data
+  field :event_type, :timestamp
 end
 
 class Session < Familia::Horreum
   self.logical_database = 2  # Session/cache data
   feature :expiration
   default_expiration 1.hour
-  field :user_id
-  field :data
-end
-
-# Models can share the same logical database
-class Order < Familia::Horreum
-  self.logical_database = 0  # Shares DB with Customer
-  field :customer_id
-  field :total
+  field :user_id, :data
 end
 ```
 
-## Performance Optimization
-
-### Avoiding SELECT Command Overhead
-
-Without proper pooling configuration, each Redis operation might issue a SELECT command:
+## Performance Benefits
 
+Without connection pooling, each operation triggers database switches:
 ```
-# Bad: Without connection provider
 SET key value     # Connection on DB 0
 SELECT 2          # Switch to DB 2
 SET key2 value2   # Now on DB 2
 SELECT 0          # Switch back
-GET key           # Now on DB 0
 ```
 
-With the connection provider pattern:
-
+With proper pooling, connections stay on the correct database:
 ```
-# Good: With connection provider  
-SET key value     # Connection already on correct DB
-SET key2 value2   # Different connection, already on correct DB
-GET key           # Original connection, still on correct DB
+SET key value     # Connection already on DB 0
+SET key2 value2   # Different connection, already on DB 2
 ```
 
-### Pool Sizing Guidelines
-
-1. **Web Applications**: `pool_size = number_of_threads + buffer`
-   ```ruby
-   size: ENV.fetch('RAILS_MAX_THREADS', 5).to_i + 2
-   ```
+## Pool Sizing Guidelines
 
-2. **Background Jobs**: `pool_size = concurrency + buffer`
-   ```ruby
-   size: Sidekiq.options[:concurrency] + 5
-   ```
+- **Web Applications**: `threads + 2`
+- **Background Jobs**: `concurrency + 2`
+- **High Traffic DBs**: Scale up based on usage patterns
 
-3. **Mixed Workloads**: Size based on the logical database's usage pattern
-   ```ruby
-   POOL_CONFIGS = {
-     0 => { size: 20 },  # High-traffic main DB
-     1 => { size: 5 },   # Low-traffic analytics
-     2 => { size: 15 }   # Medium-traffic cache
-   }
-   ```
-
-## Testing Your Configuration
+## Testing and Debugging
 
+Enable debug mode to verify correct database selection:
 ```ruby
-# Test helper to verify pools are working correctly
-class ConnectionPoolTester
-  def self.test_pools
-    # Create test models using different databases
-    class TestModel0 < Familia::Horreum
-      self.logical_database = 0
-      field :value
-    end
-    
-    class TestModel1 < Familia::Horreum  
-      self.logical_database = 1
-      field :value
-    end
-    
-    # Test concurrent access
-    threads = 10.times.map do |i|
-      Thread.new do
-        100.times do |j|
-          # This should use the pool for DB 0
-          TestModel0.create(value: "thread-#{i}-#{j}")
-          
-          # This should use the pool for DB 1
-          TestModel1.create(value: "thread-#{i}-#{j}")
-        end
-      end
-    end
-    
-    threads.each(&:join)
-    puts "Pool test completed successfully"
-  end
-end
-```
-
-## Monitoring and Debugging
-
-Enable debug mode to verify connection providers are returning connections on the correct database:
-
-```ruby
-Familia.debug = true  # Logs warnings if provider returns wrong DB
+Familia.debug = true
 ```
 
-Monitor pool usage:
-
+Test concurrent access:
 ```ruby
-# Add monitoring to your connection provider
-Familia.connection_provider = lambda do |uri|
-  pool = get_pool_for(uri)
-  
-  # Log pool statistics
-  Rails.logger.info "Pool stats: #{pool.size} size, #{pool.available} available"
-  
-  pool.with { |conn| conn }
+threads = 10.times.map do |i|
+  Thread.new do
+    100.times { |j| MyModel.create(value: "test-#{i}-#{j}") }
+  end
 end
+threads.each(&:join)
 ```
 
-## Common Pitfalls
-
-1. **Not returning DB-ready connections**: Your provider MUST return connections already on the correct database.
-
-2. **Creating too many pools**: Ensure you're keying pools correctly to avoid creating duplicate pools for the same database.
-
-3. **Forgetting thread safety**: Pool creation should be thread-safe in multi-threaded environments.
-
-4. **Incorrect pool sizing**: Monitor your connection usage and adjust pool sizes accordingly.
-
-## Summary
+## Best Practices
 
-- Familia delegates connection management to your application via `connection_provider`
-- Providers must return connections already on the correct logical database
-- Use the `connection_pool` gem for robust pooling
-- Create one pool per unique logical database
-- Monitor and tune pool sizes based on your workload
+- Return connections already on the correct database
+- Use one pool per unique logical database
+- Implement thread-safe pool creation
+- Monitor pool usage and adjust sizes accordingly
+- Use the `connection_pool` gem for production reliability

data/familia.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'logger'
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
-  spec.add_dependency 'uri-redis', '~> 1.3'
+  spec.add_dependency 'uri-valkey', '~> 1.4'
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/familia/connection.rb

@@ -107,7 +107,7 @@ module Familia
         # Provider MUST return connection already on the correct database
         parsed_uri = normalize_uri(uri)
         connection = connection_provider.call(parsed_uri.to_s)
-        
+
         # In debug mode, verify the provider honored the contract
         if Familia.debug? && connection.respond_to?(:client)
           current_db = connection.client.db
@@ -116,7 +116,7 @@ module Familia
             Familia.warn "Connection provider returned connection on DB #{current_db}, expected #{expected_db}"
           end
         end
-        
+
         return connection
       end
 
@@ -231,7 +231,7 @@ module Familia
     # Provides explicit access to a Database connection.
     #
     # This method is useful when you need direct access to a connection
-    # for operations not covered by other methods. The connection is 
+    # for operations not covered by other methods. The connection is
     # properly managed and returned to the pool (if using connection_provider).
     #
     # @yield [Redis] A Database connection

data/lib/familia/version.rb

@@ -3,6 +3,6 @@
 module Familia
   # Version information for the Familia
   unless defined?(Familia::VERSION)
-    VERSION = '2.0.0-pre'
+    VERSION = '2.0.0.pre2'
   end
 end

data/lib/familia.rb

@@ -2,7 +2,7 @@
 
 require 'json'
 require 'redis'
-require 'uri/redis'
+require 'uri/valkey'
 require 'connection_pool'
 
 require_relative 'familia/core_ext'

data/try/core/connection_try.rb

@@ -9,7 +9,7 @@ Familia.debug = false
 
 ## Familia has default URI
 Familia.uri
-#=:> URI::Redis
+#=:> URI::Generic
 
 ## Default URI points to localhost database server
 Familia.uri.to_s

data/try/core/familia_try.rb

@@ -12,8 +12,8 @@ Bone.related_fields.keys # consistent b/c hashes are ordered
 #=> [:owners, :tags, :metrics, :props, :value]
 
 ## Familia has a uri
-Familia.uri.class
-#=> URI::Redis
+Familia.uri
+#=:> URI::Generic
 
 ## Familia has a uri as a string
 Familia.uri.to_s

data/try/models/customer_try.rb

@@ -136,7 +136,7 @@ Customer.instances.logical_database
 
 ## Customer.logical_database returns the correct database number
 Customer.instances.uri.to_s
-#=> 'redis://127.0.0.1/15/'
+#=> 'redis://127.0.0.1/15'
 
 
 # Teardown

data/try/models/datatype_base_try.rb

@@ -93,9 +93,8 @@ db
 
 ## DataType has uri method
 timeline = @sample_obj.timeline
-uri = timeline.uri
-uri.class.name
-#=> "URI::Redis"
+timeline.uri
+#=:> URI::Generic
 
 # Cleanup
 @sample_obj.destroy!

data/try/pooling/connection_pool_test_try.rb

@@ -22,7 +22,7 @@ Familia.connection_provider = lambda do |uri|
       db: parsed.db || 0
     )
   end
-  
+
   @pools[uri].with { |conn| conn }
 end
 
@@ -270,4 +270,4 @@ Familia.connection_provider = original_provider
 @captured_uris.any? { |uri| uri.include?('redis://') }
 #=> true
 
-puts "Connection pool tests completed successfully!"
+puts "Connection pool tests completed successfully!"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.pre
+  version: 2.0.0.pre2
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -100,19 +100,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 3.1.1
 - !ruby/object:Gem::Dependency
-  name: uri-redis
+  name: uri-valkey
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.4'
 description: 'Familia: An ORM for Valkey-compatible databases in Ruby.. Organize and
   store ruby objects in Valkey/Redis'
 email: gems@solutious.com