Migrating Guide: v1.x to v2.0.0-pre

This guide covers migrating from Familia v1.x to the v2.0.0-pre foundation release.

Overview

The v2.0.0-pre series represents a major modernization of Familia with:

• Complete API redesign for clarity and consistency
• Valkey compatibility alongside Valkey/Redis support
• Ruby 3.4+ modernization with improved thread safety
• New connection pooling architecture

Step-by-Step Migration

1. Update Connection Configuration

Before (v1.x):

Familia.connect('redis://localhost:6379/0')

After (v2.0.0-pre):

Familia.configure do |config|
  config.redis_uri = 'redis://localhost:6379/0'
  config.connection_pool = true
end

2. Migrate Identifier Declarations

Before (v1.x):

class User < Familia::Base
  identifier :user_id
end

After (v2.0.0-pre):

class User < Familia::Horreum
  identifier_field :user_id
end

3. Update Feature Activations

Before (v1.x):

class User < Familia::Base
  include Familia::Features::Expiration
end

After (v2.0.0-pre):

class User < Familia::Horreum
  feature :expiration
end

4. Review Method Calls

Several methods were renamed for consistency:

v1.x Method	v2.0.0-pre Method	Notes
delete	destroy	More semantic naming
exists	exists?	Ruby predicate convention
dump	serialize	Clearer intent

Breaking Changes

• Familia::Base replaced by Familia::Horreum
• Connection configuration moved to block-based setup
• Feature inclusion changed from include to feature declarations
• Several method names updated for consistency

Next Steps

After completing the foundation migration:

1. Review Security Feature Adoption for encrypted fields
2. See Architecture Migration for persistence improvements
3. Explore Relationships Migration for the new relationship system