Module: Familia::Horreum::ManagementMethods

Includes:
RelatedFieldsManagement
Defined in:
lib/familia/horreum/management.rb

Overview

ManagementMethods - Class-level methods for Horreum model management

This module is extended into classes that include Familia::Horreum, providing class methods for database operations and object management (e.g., Customer.create, Customer.find_by_id)

Key features:

  • Includes RelatedFieldsManagement for DataType field handling
  • Provides utility methods for working with Database objects

Instance Method Summary collapse

Methods included from RelatedFieldsManagement

#attach_class_related_field, #attach_instance_related_field

Instance Method Details

#all(suffix = nil) ⇒ Object 



512
513
514
515
516
 
# File 'lib/familia/horreum/management.rb', line 512

def all(suffix = nil)
  suffix ||= self.suffix
  # objects that could not be parsed will be nil
  find_keys(suffix).filter_map { |k| find_by_key(k) }
end

#any? ⇒ Boolean

Note:

For authoritative check, use #scan_any? (production-safe) or #keys_any? (blocking)

Checks if any tracked instances exist (fast, from instances sorted set).

This method provides O(1) performance by querying the instances sorted set. However, objects deleted outside Familia may leave stale entries.

Examples:

User.create(email: 'test@example.com')
User.any?  #=> true

Returns:

  • (Boolean) —

    true if instances sorted set is non-empty

See Also:



609
610
611
 
# File 'lib/familia/horreum/management.rb', line 609

def any?
  count.positive?
end

#config_name ⇒ String

Converts the class name into a string that can be used to look up configuration values. This is particularly useful when mapping familia models with specific database numbers in the configuration.

Familia::Horreum::DefinitionMethods#config_name

Examples:

V2::Session.config_name => 'session'

Returns:

  • (String) —

    The underscored class name as a string



89
90
91
92
93
 
# File 'lib/familia/horreum/management.rb', line 89

def config_name
  return nil if name.nil?

  name.demodularize.snake_case
end

#count ⇒ Integer Also known as: size, length

Note:

For authoritative count, use #scan_count (production-safe) or #keys_count (blocking)

Returns the number of tracked instances (fast, from instances sorted set).

This method provides O(1) performance by querying the instances sorted set, which is automatically maintained when objects are created/destroyed through Familia. However, objects deleted outside Familia (e.g., direct Redis commands) may leave stale entries.

Examples:

User.create(email: 'test@example.com')
User.count  #=> 1

Returns:

  • (Integer) —

    Number of instances in the instances sorted set

See Also:



536
537
538
 
# File 'lib/familia/horreum/management.rb', line 536

def count
  instances.count
end

#create! {|hobj| ... } ⇒ Object

Note:

The behavior of this method depends on the implementation of #new,

exists?, and #save in the class and its superclasses.

Creates and persists a new instance of the class.

This method serves as a factory method for creating and persisting new instances of the class. It combines object instantiation, existence checking, and persistence in a single operation.

The method is flexible in accepting both positional and keyword arguments:

  • Positional arguments (*args) are passed directly to the constructor.
  • Keyword arguments (**kwargs) are passed as a hash to the constructor.

After instantiation, the method checks if an object with the same identifier already exists. If it does, a Familia::RecordExistsError exception is raised to prevent overwriting existing data.

Finally, the method saves the new instance returns it.

Examples:

Creating an object with keyword arguments

User.create(name: "John", age: 30)

Creating an object with positional and keyword arguments (not recommended)

Product.create("SKU123", name: "Widget", price: 9.99)

Parameters:

  • args (Array) —

    Variable number of positional arguments to be passed to the constructor.

  • kwargs (Hash) —

    Keyword arguments to be passed to the constructor.

Yields:

  • (hobj)

Returns:

  • (Object) —

    The newly created and persisted instance.

Raises:

See Also:



57
58
59
60
61
62
63
64
65
66
 
# File 'lib/familia/horreum/management.rb', line 57

def create!(...)
  hobj = new(...)
  hobj.save_if_not_exists!

  # If a block is given, yield the created object
  # This allows for additional operations on successful creation
  yield hobj if block_given?

  hobj
end

#dbkey(identifier, suffix = self.suffix) ⇒ Object 



503
504
505
506
507
508
509
510
 
# File 'lib/familia/horreum/management.rb', line 503

def dbkey(identifier, suffix = self.suffix)
  if identifier.to_s.empty?
    raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}"
  end

  identifier &&= identifier.to_s
  Familia.dbkey(prefix, identifier, suffix)
end

#destroy!(identifier, suffix = nil) ⇒ Boolean

Destroys an object in Database with the given identifier.

This method is part of Familia's high-level object lifecycle management. While delete! operates directly on dbkeys, destroy! operates at the object level and is used for ORM-style operations. Use destroy! when removing complete objects from the system, and delete! when working directly with dbkeys.

Examples:

User.destroy!(123)  # Removes user:123:object from Valkey/Redis

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object to destroy.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix).

Returns:

  • (Boolean) —

    true if the object was successfully destroyed, false otherwise.

Raises:



417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
 
# File 'lib/familia/horreum/management.rb', line 417

def destroy!(identifier, suffix = nil)
  suffix ||= self.suffix
  raise Familia::NoIdentifier, "#{self} requires non-empty identifier" if identifier.to_s.empty?

  objkey = dbkey identifier, suffix

  # Execute all deletion operations within a transaction
  transaction do |conn|
    # Clean up related fields first to avoid orphaned keys
    if relations?
      Familia.trace :DESTROY_RELATIONS!, nil, "#{self} has relations: #{related_fields.keys}" if Familia.debug?

      # Create a temporary instance to access related fields.
      # Pass identifier in constructor so init() sees it and can set dependent fields.
      identifier_field_name = self.identifier_field
      temp_instance = identifier_field_name ? new(identifier_field_name => identifier.to_s) : new

      related_fields.each do |name, _definition|
        obj = temp_instance.send(name)
        Familia.trace :DESTROY_RELATION!, name, "Deleting related field #{name} (#{obj.dbkey})" if Familia.debug?
        conn.del(obj.dbkey)
      end
    end

    # Delete the main object key
    ret = conn.del(objkey)
    Familia.trace :DESTROY!, nil, "#{objkey} #{ret.inspect}" if Familia.debug?
  end
end

#exists?(identifier, suffix = nil) ⇒ Boolean

Checks if an object with the given identifier exists in the database.

This method constructs the full dbkey using the provided identifier and suffix, then checks if the key exists in the database.

Examples:

User.exists?(123)  # Returns true if user:123:object exists in Valkey/Redis

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix).

Returns:

  • (Boolean) —

    true if the object exists, false otherwise.

Raises:



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/familia/horreum/management.rb', line 387

def exists?(identifier, suffix = nil)
  raise NoIdentifier, 'Empty identifier' if identifier.to_s.empty?

  suffix ||= self.suffix

  objkey = dbkey identifier, suffix

  ret = dbclient.exists objkey
  Familia.trace :EXISTS, nil, "#{objkey} #{ret.inspect}" if Familia.debug?

  # Handle Redis::Future objects during transactions
  return ret if ret.is_a?(Redis::Future)

  ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method.
end

#familia_name ⇒ Object

Familia::Horreum::DefinitionMethods#familia_name

Examples:

V2::Session.config_name => 'Session'



99
100
101
102
103
 
# File 'lib/familia/horreum/management.rb', line 99

def familia_name
  return nil if name.nil?

  name.demodularize
end

#find_by_dbkey(objkey, check_exists: true) ⇒ Object? Also known as: find_by_key

Note:

When check_exists: false, HGETALL on non-existent keys returns {} which we detect and return nil (not an empty object instance).

Retrieves and instantiates an object from Database using the full object key.

This method can operate in two modes:

Safe mode (check_exists: true, default):

  1. First checks if the key exists with EXISTS command
  2. Returns nil immediately if key doesn't exist
  3. If exists, retrieves data with HGETALL and instantiates object
  4. Best for: Single object lookups, defensive code
  5. Commands: 2 per object (EXISTS + HGETALL)

Optimized mode (check_exists: false):

  1. Directly calls HGETALL without EXISTS check
  2. Returns nil if HGETALL returns empty hash (key doesn't exist)
  3. Otherwise instantiates object with returned data
  4. Best for: Bulk operations, performance-critical paths, when keys likely exist
  5. Commands: 1 per object (HGETALL only)
  6. Reduction: 50% fewer Redis commands

Examples:

Safe mode (default)

User.find_by_key("user:123")  # 2 commands: EXISTS + HGETALL

Optimized mode (skip existence check)

User.find_by_key("user:123", check_exists: false)  # 1 command: HGETALL

Parameters:

  • objkey (String) —

    The full dbkey for the object.

  • check_exists (Boolean) (defaults to: true) —

    Whether to check key existence before HGETALL (default: true). When false, skips EXISTS check for better performance but still returns nil for non-existent keys (detected via empty hash).

Returns:

  • (Object, nil) —

    An instance of the class if the key exists, nil otherwise.

Raises:

  • (ArgumentError) —

    If the provided key is empty.



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/familia/horreum/management.rb', line 142

def find_by_dbkey(objkey, check_exists: true)
  raise ArgumentError, 'Empty key' if objkey.to_s.empty?

  if check_exists
    # Safe mode: Check existence first (original behavior)
    # We use a lower-level method here b/c we're working with the
    # full key and not just the identifier.
    does_exist = dbclient.exists(objkey).positive?

    Familia.debug "[find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
    Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey

    # This is the reason for calling exists first. We want to definitively
    # and without any ambiguity know if the object exists in the database. If it
    # doesn't, we return nil. If it does, we proceed to load the object.
    # Otherwise, hgetall will return an empty hash, which will be passed to
    # the constructor, which will then be annoying to debug.
    unless does_exist
      cleanup_stale_instance_entry(objkey)
      return nil
    end
  else
    # Optimized mode: Skip existence check
    Familia.debug "[find_by_key] #{self} from key #{objkey} (check_exists: false)"
    Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey
  end

  obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
  Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{objkey}: #{obj.inspect}"

  # Always check for empty hash to handle race conditions where the key
  # expires between EXISTS check and HGETALL (when check_exists: true),
  # or simply doesn't exist (when check_exists: false).
  if obj.empty?
    cleanup_stale_instance_entry(objkey)
    return nil
  end

  # Create instance and deserialize fields using shared helper method
  instantiate_from_hash(obj)
end

#find_by_identifier(identifier, suffix: nil, check_exists: true) ⇒ Object? Also known as: find_by_id

Retrieves and instantiates an object from Database using its identifier.

This method constructs the full dbkey using the provided identifier and suffix, then delegates to find_by_key for the actual retrieval and instantiation.

It's a higher-level method that abstracts away the key construction, making it easier to retrieve objects when you only have their identifier.

Examples:

Safe mode (default)

User.find_by_id(123)  # 2 commands: EXISTS + HGETALL

Optimized mode

User.find_by_id(123, check_exists: false)  # 1 command: HGETALL

Custom suffix

Session.find_by_id('abc', suffix: :session)

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix). Keyword parameter for consistency with check_exists.

  • check_exists (Boolean) (defaults to: true) —

    Whether to check key existence before HGETALL (default: true). See find_by_dbkey for details.

Returns:

  • (Object, nil) —

    An instance of the class if found, nil otherwise.



237
238
239
240
241
242
243
244
245
246
 
# File 'lib/familia/horreum/management.rb', line 237

def find_by_identifier(identifier, suffix: nil, check_exists: true)
  suffix ||= self.suffix
  return nil if identifier.to_s.empty?

  objkey = dbkey(identifier, suffix)

  Familia.debug "[find_by_id] #{self} from key #{objkey})"
  Familia.trace :FIND_BY_ID, nil, objkey if Familia.debug?
  find_by_dbkey objkey, check_exists: check_exists
end

#find_keys(suffix = '*') ⇒ Array<String>

Finds all keys in Database matching the given suffix pattern.

This method searches for all dbkeys that match the given suffix pattern. It uses the class's dbkey method to construct the search pattern.

Examples:

User.find  # Returns all keys matching user:*:object
User.find('active')  # Returns all keys matching user:*:active

Parameters:

  • suffix (String) (defaults to: '*') —

    The suffix pattern to match (default: '*').

Returns:

  • (Array<String>) —

    An array of matching dbkeys.



459
460
461
 
# File 'lib/familia/horreum/management.rb', line 459

def find_keys(suffix = '*')
  dbclient.keys(dbkey('*', suffix)) || []
end

#instantiate_from_hash(obj_hash) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

This method:

  1. Allocates a new instance without calling initialize
  2. Initializes related DataType fields
  3. Deserializes and assigns field values from the hash

Instantiates an object from a hash of field values.

This is an internal helper method used by find_by_dbkey, load_multi, and load_multi_by_keys to eliminate code duplication. Not intended for direct use.

Parameters:

  • obj_hash (Hash) —

    Hash of field names to serialized values from Redis

Returns:

  • (Object) —

    Instantiated object with deserialized fields



677
678
679
680
681
682
 
# File 'lib/familia/horreum/management.rb', line 677

def instantiate_from_hash(obj_hash)
  instance = allocate
  instance.send(:initialize_relatives)
  instance.send(:initialize_with_keyword_args_deserialize_value, **obj_hash)
  instance
end

#key_prefix ⇒ String

Returns the key prefix for this class including the delimiter.

Centralizes key prefix generation to prevent bugs from manual string interpolation across the codebase.

Examples:

User.key_prefix  #=> "user:"

Returns:

  • (String) —

    The prefix with delimiter (e.g., "customer:")



484
485
486
 
# File 'lib/familia/horreum/management.rb', line 484

def key_prefix
  "#{prefix}#{Familia.delim}"
end

#keys_any?(filter = '*') ⇒ Boolean

Note:

For production-safe authoritative check, use #scan_any?

Checks if any objects exist using blocking KEYS command (production-dangerous).

⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution. It scans ALL keys in the database and should NEVER be used in production.

Examples:

User.keys_any?       #=> true  (any User objects)
User.keys_any?('a*') #=> true  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Key pattern to match (default: '*')

Returns:

  • (Boolean) —

    true if any matching keys exist in Redis

See Also:



629
630
631
 
# File 'lib/familia/horreum/management.rb', line 629

def keys_any?(filter = '*')
  keys_count(filter).positive?
end

#keys_count(filter = '*') ⇒ Integer

Note:

For production-safe authoritative count, use #scan_count

Returns authoritative count using blocking KEYS command (production-dangerous).

⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution. It scans ALL keys in the database and should NEVER be used in production.

Examples:

User.keys_count       #=> 1  (all User objects)
User.keys_count('a*') #=> 1  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Key pattern to match (default: '*')

Returns:

  • (Integer) —

    Number of matching keys in Redis

See Also:



558
559
560
 
# File 'lib/familia/horreum/management.rb', line 558

def keys_count(filter = '*')
  dbclient.keys(dbkey(filter)).compact.size
end

#load_multi(identifiers, suffix = nil) ⇒ Array<Object> Also known as: load_batch

Note:

Returns nil for non-existent keys (maintains same contract as find_by_id)

Note:

Objects are returned in the same order as input identifiers

Note:

Empty/nil identifiers are skipped and return nil in result array

Loads multiple objects by their identifiers using pipelined HGETALL commands.

This method provides significant performance improvements for bulk loading by:

  1. Batching all HGETALL commands into a single Redis pipeline
  2. Eliminating network round-trip overhead
  3. Skipping individual EXISTS checks (like check_exists: false)

Performance characteristics:

  • Standard approach: N objects × 2 commands (EXISTS + HGETALL) = 2N round trips
  • check_exists: false: N objects × 1 command (HGETALL) = N round trips
  • load_multi: 1 pipeline with N commands = 1 round trip
  • Improvement: Up to 2N× faster for bulk operations

Examples:

Load multiple users efficiently

users = User.load_multi([123, 456, 789])
# 1 pipeline with 3 HGETALL commands instead of 6 individual commands

Filter out nils

existing_users = User.load_multi(ids).compact

Parameters:

  • identifiers (Array<String, Integer>) —

    Array of identifiers to load

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in dbkeys (default: class suffix)

Returns:

  • (Array<Object>) —

    Array of instantiated objects (nils for non-existent)



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/familia/horreum/management.rb', line 279

def load_multi(identifiers, suffix = nil)
  suffix ||= self.suffix
  return [] if identifiers.empty?

  # Build list of valid keys and track their original positions
  valid_keys = []
  valid_positions = []

  identifiers.each_with_index do |identifier, idx|
    next if identifier.to_s.empty?

    valid_keys << dbkey(identifier, suffix)
    valid_positions << idx
  end

  Familia.trace :LOAD_MULTI, nil, "Loading #{identifiers.size} objects" if Familia.debug?

  # Pipeline all HGETALL commands
  multi_result = pipelined do |pipeline|
    valid_keys.each do |objkey|
      pipeline.hgetall(objkey)
    end
  end

  # Extract results array from MultiResult
  results = multi_result.results

  # Map results back to original positions
  objects = Array.new(identifiers.size)
  valid_positions.each_with_index do |pos, result_idx|
    obj_hash = results[result_idx]

    # Skip empty hashes (non-existent keys)
    next if obj_hash.nil? || obj_hash.empty?

    # Instantiate object using shared helper method
    objects[pos] = instantiate_from_hash(obj_hash)
  end

  objects
end

#load_multi_by_keys(objkeys) ⇒ Array<Object>

Note:

Returns nil for empty/nil keys, maintaining position alignment with input array

Loads multiple objects by their full dbkeys using pipelined HGETALL commands.

This is a lower-level variant of load_multi that works directly with dbkeys instead of identifiers. Useful when you already have the full keys.

Examples:

Load objects by full keys

keys = ["user:123:object", "user:456:object"]
users = User.load_multi_by_keys(keys)

Parameters:

  • objkeys (Array<String>) —

    Array of full dbkeys to load

Returns:

  • (Array<Object>) —

    Array of instantiated objects (nils for non-existent)

See Also:



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/familia/horreum/management.rb', line 338

def load_multi_by_keys(objkeys)
  return [] if objkeys.empty?

  Familia.trace :LOAD_MULTI_BY_KEYS, nil, "Loading #{objkeys.size} objects" if Familia.debug?

  # Track which positions have valid keys to maintain result array alignment
  valid_positions = []
  objkeys.each_with_index do |objkey, idx|
    valid_positions << idx unless objkey.to_s.empty?
  end

  # Pipeline all HGETALL commands for valid keys
  multi_result = pipelined do |pipeline|
    objkeys.each do |objkey|
      next if objkey.to_s.empty?
      pipeline.hgetall(objkey)
    end
  end

  # Extract results array from MultiResult
  results = multi_result.results

  # Map results back to original positions
  objects = Array.new(objkeys.size)
  valid_positions.each_with_index do |pos, result_idx|
    obj_hash = results[result_idx]

    # Skip empty hashes (non-existent keys)
    next if obj_hash.nil? || obj_hash.empty?

    # Instantiate object using shared helper method
    objects[pos] = instantiate_from_hash(obj_hash)
  end

  objects
end

#multiget ⇒ Object 



68
69
70
 
# File 'lib/familia/horreum/management.rb', line 68

def multiget(...)
  rawmultiget(...).filter_map { |json| Familia::JsonSerializer.parse(json) }
end

#rawmultiget(*hids) ⇒ Object 



72
73
74
75
76
77
78
 
# File 'lib/familia/horreum/management.rb', line 72

def rawmultiget(*hids)
  hids.collect! { |hobjid| dbkey(hobjid) }
  return [] if hids.compact.empty?

  Familia.trace :MULTIGET, nil, "#{hids.size}: #{hids}" if Familia.debug?
  dbclient.mget(*hids)
end

#scan_any?(filter = '*') ⇒ Boolean Also known as: any!

Note:

For fast check (potentially stale), use #any?

Checks if any objects exist using non-blocking SCAN command (production-safe).

This method uses cursor-based SCAN iteration to check for matching keys without blocking Redis. Safe for production use and returns early on first match.

Examples:

User.scan_any?       #=> true  (any User objects)
User.scan_any?('a*') #=> true  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Key pattern to match (default: '*')

Returns:

  • (Boolean) —

    true if any matching keys exist in Redis

See Also:



649
650
651
652
653
654
655
656
657
658
659
660
 
# File 'lib/familia/horreum/management.rb', line 649

def scan_any?(filter = '*')
  pattern = dbkey(filter)
  cursor = "0"

  loop do
    cursor, keys = dbclient.scan(cursor, match: pattern, count: 100)
    return true unless keys.empty?
    break if cursor == "0"
  end

  false
end

#scan_count(filter = '*') ⇒ Integer Also known as: count!

Note:

For fast count (potentially stale), use #count

Returns authoritative count using non-blocking SCAN command (production-safe).

This method uses cursor-based SCAN iteration to count matching keys without blocking Redis. Safe for production use as it processes keys in chunks.

Examples:

User.scan_count       #=> 1  (all User objects)
User.scan_count('a*') #=> 1  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Key pattern to match (default: '*')

Returns:

  • (Integer) —

    Number of matching keys in Redis

See Also:



578
579
580
581
582
583
584
585
586
587
588
589
590
 
# File 'lib/familia/horreum/management.rb', line 578

def scan_count(filter = '*')
  pattern = dbkey(filter)
  count = 0
  cursor = "0"

  loop do
    cursor, keys = dbclient.scan(cursor, match: pattern, count: 1000)
    count += keys.size
    break if cursor == "0"
  end

  count
end

#scan_pattern(match_suffix = suffix) ⇒ String

Returns the SCAN pattern for finding all objects of this class.

Centralizes SCAN pattern generation to ensure consistency across rebuild strategies and other key enumeration operations.

Examples:

User.scan_pattern           #=> "user:*:object"
User.scan_pattern('active') #=> "user:*:active"

Parameters:

  • match_suffix (String) (defaults to: suffix) —

    The suffix to match (default: class suffix)

Returns:

  • (String) —

    The SCAN pattern (e.g., "customer:*:object")



499
500
501
 
# File 'lib/familia/horreum/management.rb', line 499

def scan_pattern(match_suffix = suffix)
  "#{prefix}:*:#{match_suffix}"
end