Skip to content
Read only ActiveRecord-like interface to query static YAML files
Ruby
Branch: master
Clone or download
Latest commit 8bb0362 Jan 16, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Release 0.17.0 Jan 16, 2020
spec Improve the default_attributes option for better backward compatibility Jan 15, 2020
.gitignore
.rspec Ultra minimal version Feb 25, 2014
.travis.yml Update tested ruby versions Jan 15, 2020
Gemfile Ultra minimal version Feb 25, 2014
LICENSE.txt
README.md Include JSON backend by default Jan 3, 2020
Rakefile
frozen_record.gemspec Relax dev dependency on bundler Feb 5, 2019

README.md

FrozenRecord

Build Status Code Climate Coverage Status Gem Version

ActiveRecord-like interface for read only access to static data files.

Installation

Add this line to your application's Gemfile:

gem 'frozen_record'

And then execute:

$ bundle

Or install it yourself as:

$ gem install frozen_record

Models definition

Just like with ActiveRecord, your models need to inherits from FrozenRecord::Base:

class Country < FrozenRecord::Base
end

But you also have to specify in which directory your data files are located. You can either do it globaly

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

Or per model:

class Country < FrozenRecord::Base
  self.base_path = '/path/to/some/directory'
end

You can also specify a custom backend. Backends are classes that know how to load records from a static file. By default FrozenRecord expects an YAML file, but this option can be changed per model:

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

Custom backends

A custom backend must implement the methods filename and load as follows:

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

Query interface

FrozenRecord aim to replicate only modern ActiveRecord querying interface, and only the non "string typed" ones.

e.g

# Supported query interfaces
Country.
  where(region: 'Europe').
  where.not(language: 'English').
  order(id: :desc).
  limit(10).
  offset(2).
  pluck(:name)

# Non supported query interfaces
Country.
  where('region = "Europe" AND language != "English"').
  order('id DESC')

Scopes

Basic scope :symbol, lambda syntax is now supported in addition to class method syntax.

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

  def self.republics
    where(king: nil)
  end

  def self.part_of_nato
    where(nato: true)
  end
end

Country.european.republics.part_of_nato.order(id: :desc)

Supported query methods

  • where
  • where.not
  • order
  • limit
  • offset

Supported finder methods

  • find
  • first
  • last
  • to_a
  • exists?

Supported calculation methods

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

Configuration

Reloading

By default the YAML files are parsed once and then cached in memory. But in development you might want changes to be reflected without having to restart your application.

For such cases you can set auto_reloading to true either globally or on a model basis:

FrozenRecord::Base.auto_reloading = true # Activate reloading for all models
Country.auto_reloading # Activate reloading for `Country` only

Testing

Testing your FrozenRecord-backed models with test fixtures is made easier with:

require 'frozen_record/test_helper'

# During test/spec setup
test_fixtures_base_path = 'alternate/fixture/path'
FrozenRecord::TestHelper.load_fixture(Country, test_fixtures_base_path)

# During test/spec teardown
FrozenRecord::TestHelper.unload_fixtures

Here's a Rails-specific example:

require "test_helper"
require 'frozen_record/test_helper'

class CountryTest < ActiveSupport::TestCase
  setup do
    test_fixtures_base_path = Rails.root.join(%w(test support fixtures))
    FrozenRecord::TestHelper.load_fixture(Country, test_fixtures_base_path)
  end

  teardown do
    FrozenRecord::TestHelper.unload_fixtures
  end

  test "countries have a valid name" do
  # ...

Contributors

FrozenRecord is a from scratch reimplementation of a Shopify project from 2007 named YamlRecord. So thanks to:

You can’t perform that action at this time.