StaticRecord¶ ↑

<img src=“https://badge.fury.io/rb/static-record.svg” alt=“Gem Version” /> <img src=“https://codeclimate.com/github/hchevalier/static_record/badges/gpa.svg” /> <img src=“https://codeclimate.com/github/hchevalier/static_record/badges/coverage.svg” /> <img src=“https://travis-ci.org/hchevalier/static_record.svg?branch=master” alt=“Build Status” />

StaticRecord allows you to perform ActiveRecord-like queries over ruby files.

Those files act as immutable database records that only developers can alter.

You can use it when you need several files inheriting a base class.

Installation¶ ↑

Add this to your Gemfile:

gem 'static-record', require: 'static_record'

and run the bundle install command.

The ‘require’ part is important so that Rails autoloads the library correctly.

Getting Started¶ ↑

Base class¶ ↑

Create your base class inheriting from StaticRecord::Base.

class Article < StaticRecord::Base
  # Declare in which table Articles will be store (always in file db/static_records.sqlite3)
  table       :articles

  # Declare at which path "article" files can be found
  path        Rails.root.join('app', 'models', 'articles', '**', '*.rb')

  # Optionnal, declare which column can be used as the primary key (must be unique)
  # .find will only be available if a primary key is defined
  primary_key :name

  # You can specify default values for each column of your static records
  # Just create a class method with name: default_<attribute_name>
  def self.default_author
    'Default author'
  end

  # You can override any attribute value
  # Just create a class method with name: override_<attribute_name>
  def self.override_cover(cover)
    return cover if cover.to_s.include?('/')
    Rails.root.join('public', 'default_cover_path', cover)
  end

  # Specify which "article" attributes can be queried over with their types
  columns     name:     :string,
              author:   :string,
              rank:     :integer,
              cover:    :string,
              category  :static_record
end

At each application startup, an SQLite3 database will be created to store this class’ children.

Available column types are

• :string

• :integer

• :boolean

• :float

• :static_record

Child class¶ ↑

Create has many child class as you want.

class ArticleOne < Article
  # Define the attributes that will be available for your StaticRecord queries
  attribute :name, 'Article One'
  attribute :author, 'The author'
  attribute :rank, 2
  attribute :cover, Rails.root.join('public', 'articles', 'one.jpg')

  # Define the references to other StaticRecords
  # These ones can be queried over after a jointure
  reference :category, Category.find('Category One')

  # Your class can be used as any other Ruby class
  def initialize
    @an_instance_variable
    super
  end

  def my_instance_method
  end

  def self.my_class_method
  end
end

Queries¶ ↑

In your code, you can perform queries like this one:

Article.where(name: ‘Article Two’).or.where(‘rank >= 2’).limit(2).offset(3)

I tried to implement as much of ActiveRecord’s query interface as I could.

There is still a lot of work before everything is available, but I chose to release the gem nevertheless.

Here is a full list:

• where

  • Article.where(name: ‘Article One’, author: ‘The author’)

  • Article.where(name: [‘Article One’, ‘Article Two’])

  • Article.where(name: ‘Article One’).where(author: ‘The author’)

  • Article.where(“name = ‘Article One’”)

  • Article.where(“name = ?”, ‘Article One’)

  • Article.where(“name = :name”, name: ‘Article One’)

• find (only if a primary key has been set)

  • Article.find(‘Article One’)

• find_by

  • Article.find_by(author: ‘The author’)

• joins

  • Article.joins(:categories).where(“categories.name = ‘Category One’”)

• not

  • Article.where.not(author: ‘The author’)

• or

  • Article.where(author: ‘The author’).or.where(author: ‘Another author’)

  • Article.where.not(name: ‘Article One’).or.where.not(author: ‘The author’)

• all

  • Article.where(author: ‘The author’).all

  • Article.all

• take

  • Article.take

  • Article.take(3)

• first

  • Article.first

  • Article.first(3)

• last

  • Article.last

  • Article.last(3)

• limit

  • Article.limit(5)

• offset

  • Article.limit(3).offset(2)

• order

  • Article.order(:rank) # Use ASC ordering

  • Article.order([:rank, :name]) # Use ASC ordering for both columns

  • Article.order(rank: :asc)

  • Article.order(rank: :desc, name: :asc)

  • Article.order(“rank DESC”)

IDs¶ ↑

Records are being assigned an ID in the SQLite3 database when inserted.

As the database is recreated at each application startup and IDs depend on the insertion order, I advise you to rely on another column if you want to hardcode a specific record somewhere in your app.

References¶ ↑

ActiveRecord¶ ↑

A migration helper allows your ActiveRecord models to reference a StaticRecord.

In a migration, use:

def change
  bind_static_record :users, :article
end

In your model, you can use

has_static_record :article

You can now do

u = User.first
u.article = Article.find('Article One')
u.save

u = User.first
u.article

If you don’t want to name your column with the same name than your StaticRecord base, you can do as follow

# In the migration
def change
  bind_static_record :users, :any_column_name
end

# In the model
has_static_record :any_column_name, class_name: 'Article'

StaticRecord¶ ↑

You can also use ‘reference’ instead of ‘attribute’ to have your StaticRecords reference other ones.

You must use type :static_record when declaring your column!

class Article < StaticRecord::Base
  table       :articles
  path        Rails.root.join('app', 'models', 'articles', '**', '*.rb')
  primary_key :name

  columns     name:     :string,
              category  :static_record
end

class ArticleOne < Article
  attribute   :name, 'Article one'
  reference   :category, Category.find('Category One')
end

You can query them like this

Article.where(category: Category.find('Category One'))
Article.joins(Category).where("categories.name = 'Category One'")
Article.joins("categories").where("categories.name = 'Category One'")

Questions?¶ ↑

If you have any question or doubt regarding StaticRecord which you cannot find the solution to in the documentation, you can send me an email. I’ll try to answer in less than 24 hours.

Bugs?¶ ↑

If you find a bug please add an issue on GitHub or fork the project and send a pull request.

Future¶ ↑

• Better documentation

• Generators

• Improve jointures