Familia - 2.0
Organize and store Ruby objects in Valkey/Redis. A powerful Ruby ORM (of sorts) for Valkey/Redis.
Familia provides a flexible and feature-rich way to interact with Valkey using Ruby objects. It’s designed to make working with Valkey as natural as working with Ruby classes, while offering advanced features for complex data management.
Quick Start
1. Installation
```bash # Add to Gemfile gem ‘familia’, ‘>= 2.0.0’
Or install directly
gem install familia ```
2. Configure Connection
```ruby # config/initializers/familia.rb (Rails) # or at the top of your script
require ‘familia’
Basic configuration
Familia.uri = ‘redis://localhost:6379/0’
Or with authentication
Familia.uri = ‘redis://user:password@localhost:6379/0’ ```
3. Create Your First Model
ruby
class User < Familia::Horreum
identifier_field :email
field :email
field :name
field :created_at
end
4. Basic Operations
```ruby # Create user = User.new(email: ‘alice@example.com’, name: ‘Alice’) user.save
Find
user = User.load(‘alice@example.com’)
Update
user.name = ‘Alice Smith’ user.save
Check existence
User.exists?(‘alice@example.com’) #=> true ```
Prerequisites
- Ruby: 3.4+ (3.4+ recommended)
- Valkey/Redis: 6.0+
- Gems:
redis(automatically installed)
Usage Examples
Creating and Saving Objects
ruby
flower = Flower.create(name: "Red Rose", token: "rrose")
flower.owners.push("Alice", "Bob")
flower.tags.add("romantic")
flower.metrics.increment("views", 1)
flower.props[:color] = "red"
flower.save
Retrieving and Updating Objects
ruby
rose = Flower.find_by_id("rrose")
rose.name = "Pink Rose"
rose.save
Using Safe Dump
ruby
user = User.create(username: "rosedog", first_name: "Rose", last_name: "Dog")
user.safe_dump
# => {id: "user:rosedog", username: "rosedog", full_name: "Rose Dog"}
Working with Time-based Data
ruby
metric = DailyMetric.new
metric.counter.increment # Increments the counter for the current hour
Bulk Operations
ruby
Flower.multiget("rrose", "tulip", "daisy")
Transactional Operations
ruby
user.transaction do |conn|
conn.set("user:#{user.id}:status", "active")
conn.zadd("active_users", Time.now.to_i, user.id)
end
Organizing Complex Models
For large applications, you can organize model complexity using custom features:
Self-Registering Features
```ruby # app/features/customer_management.rb module MyApp::Features::CustomerManagement Familia::Base.add_feature(self, :customer_management)
def self.included(base) base.extend(ClassMethods) end
module ClassMethods def create_with_validation(attrs) # Complex creation logic end end
def complex_business_method # Instance methods end end
models/customer.rb
class Customer < Familia::Horreum field :email, :name feature :customer_management # Clean model definition end ```
This keeps complex models organized while maintaining Familia’s clean, declarative style.
Conclusion
Familia provides a powerful and flexible way to work with Valkey-compatible in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.
For more information, visit: - Github Repository - RubyGems Page
Contributions are welcome! Feel free to submit a Pull Request.