FrozenRecord

Use FrozenRecord::TestHelper to load and unload test fixtures during your test suite setup and teardown.

require 'frozen_record/test_helper'

# Setup
FrozenRecord::TestHelper.load_fixture(Country, 'path/to/fixtures')

# Teardown
FrozenRecord::TestHelper.unload_fixtures

To use FrozenRecord in your application, add the gem to your Gemfile:

gem 'frozen_record'

Then run bundle. Alternatively, you can install it directly via the command line:

$ gem install frozen_record

Models must inherit from FrozenRecord::Base. You must specify a base_path where your data files are located. This can be set globally for all models or specifically for each model class.

FrozenRecord includes built-in backends for YAML (default) and JSON.

class Country < FrozenRecord::Base
end

# Global base path
FrozenRecord::Base.base_path = '/path/to/some/directory'

# Per-model base path
class Country < FrozenRecord::Base
  self.base_path = '/path/to/some/directory'
end

To prevent accidental performance issues with large unindexed datasets, you can set a limit on how many records FrozenRecord is allowed to scan. If a query exceeds this limit, an error is raised.

This can be set globally or per model using max_records_scan.

FrozenRecord::Base.max_records_scan = 500

By default, data files are parsed once and cached in memory. To reflect changes in your data files without restarting your application, enable auto_reloading.

• Set auto_reloading = true globally to affect all models.
• Set auto_reloading on a specific model class to affect only that model.
• For manual reloading, call load_records(force: true) on the model class.

FrozenRecord::Base.auto_reloading = true
# Or per model
Country.auto_reloading = true

You can define scopes using either the scope :symbol, lambda syntax or by defining class methods. Scopes allow you to chain reusable query logic.

class Country < FrozenRecord::Base
  scope :european, -> { where(continent: 'Europe' ) }

  def self.republics
    where(king: nil)
  end
end

# Usage
Country.european.republics

By default, querying is a linear search (O(n)). For larger datasets or frequent queries, you can define indices using add_index.

Limitations:

• Composite index keys are not supported.
• The primary key is not indexed by default.

class Country < FrozenRecord::Base
  add_index :name, unique: true
  add_index :continent
end

You can use a custom backend by assigning a class to self.backend. A custom backend must implement two methods:

1. filename(model_name): Returns the filename as a String.
2. load(file_path): Reads the file and returns records as an Array of Hash objects.

class Country < FrozenRecord::Base
  self.backend = FrozenRecord::Backends::Json
end

module MyCustomBackend
  extend self

  def filename(model_name)
    # Returns the file name as a String
  end

  def load(file_path)
    # Reads file and returns records as an Array of Hash objects
  end
end

The attribute method allows you to convert raw data into a custom class. The target class must implement a self.load(value) method that takes the raw value and returns the deserialized object.

class Size = Struct.new(:length, :width, :depth) do
  def self.load(value)
    new(*value.split('x'))
  end
end

class Country < FrozenRecord::Base
  attribute :size, Size
end

FrozenRecord provides a modern, non-string-typed Active Record-like querying interface.

Supported query methods:

• where(hash_or_range)
• where.not(hash)
• order(column: direction)
• limit(n)
• offset(n)

Supported finder methods:

• find, first, last, to_a, exists?

Supported calculation methods:

• count, pluck, ids, minimum, maximum, sum, average

Note: String-based queries (e.g., where('region = "Europe"')) are not supported.

Country.
  where(region: 'Europe').
  where.not(language: 'English').
  where(population: 10_000_000..).
  order(id: :desc).
  limit(10).
  offset(2).
  pluck(:name)