DEV Community: Albin Yesudasan (Albi)

Building a Mini ORM with Ruby Metaprogramming: A Deep Dive into Active Record Pattern

Albin Yesudasan (Albi) — Tue, 25 Mar 2025 16:15:39 +0000

Code Writes Code

Object-Relational Mapping (ORM) frameworks like ActiveRecord are fundamental to modern web development, but have you ever wondered how they work under the hood? In this post, I'll walk you through building a minimal ORM using Ruby's powerful metaprogramming features. We'll create a system that handles basic database operations, associations, and even callbacks - all while storing data in CSV files for simplicity.

Mini ORM GitHub Repository

The Core Foundation

At the heart of our Mini ORM is the MiniRecord class, which serves as the base class for our models. Let's look at how we define our models:

class User < MiniRecord
  column :name, String.new
  column :email, String.new
  has_many :posts

  before_save :test_before_save
  after_save :test_after_save

  def test_before_save
    puts 'before save is working'
  end

  def test_after_save
    puts 'after save is working'
  end
end

class Post < MiniRecord
  column :title, String.new
  column :content, String.new
  column :user_id, 0
  belongs_to :user
end

This clean, declarative syntax hides a lot of metaprogramming magic happening behind the scenes. Let's dive into how it works.

The Magic of Dynamic Method Creation

One of the most powerful features of our Mini ORM is the dynamic creation of methods for associations. Here's how we implement belongs_to and has_many relationships:

def self.belongs_to(name)
  define_method(name) do
    foreign_key_value = send("#{name}_id")
    Object.const_get(name.to_s.capitalize).find(foreign_key_value)
  end

  define_method("#{name}=") do |obj|
    send("#{name}_id=", obj&.id)
  end
end

def self.has_many(name)
  singular_name = name.to_s.singularize
  define_method(name) do
    Object.const_get(singular_name.capitalize).where("#{self.class.name.downcase}_id" => id)
  end
end

This code uses define_method to dynamically create instance methods at runtime. When you declare belongs_to :user in the Post class, it automatically creates two methods:

user - Returns the associated User object
user= - Sets the relationship and updates the foreign key

Callbacks System

Our ORM implements a simple but effective callback system:

def self.before_save(method)
  @before_save_callbacks ||= []
  @before_save_callbacks << method
end

def self.after_save(method)
  @after_save_callbacks ||= []
  @after_save_callbacks << method
end

def self.run_callbacks(type, instance)
  callbacks = instance.class.instance_variable_get("@#{type}_callbacks")
  callbacks&.each { |callback| instance.send(callback) }
end

This system uses class instance variables to store callback methods and send to dynamically invoke them at the appropriate time.

Dynamic Column Definition

The column method is another excellent example of metaprogramming:

def self.column(name, type)
  @columns ||= {}
  @columns[name] = type
  attr_accessor name

  define_singleton_method("find_by_#{name}") do |value|
    return unless value.is_a?(Integer) || value.is_a?(String) || name.blank?
    find(name.to_sym => value)
  end
end

This method does three things:

Stores column information in a class variable
Creates getter and setter methods using attr_accessor
Dynamically defines finder methods like find_by_email or find_by_title

Data Persistence

While not strictly metaprogramming, our persistence layer shows how we can use Ruby's reflection capabilities to save and retrieve data:

def save
  self.class.run_callbacks(:before_save, self)
  self.class.create_table unless File.exist?(self.class.csv_file_path)
  data = CSV.table(self.class.csv_file_path)

  if @id
    data.each do |row|
      if row[:id] == @id
        self.class.columns.keys.each { |col| row[col] = send(col) }
        break
      end
    end
  else
    @id = data.any? ? data.max_by { |row| row[:id] }[:id] + 1 : 1
    data << [@id, *attribute_values]
  end

  File.open(self.class.csv_file_path, "w") { |f| f.write(data.to_csv) }
  self.class.run_callbacks(:after_save, self)
  self
end

Using the Mini ORM

Using our ORM is straightforward and similar to ActiveRecord:

# Create tables
Post.drop_table
Post.create_table

# Create and save records
last_user = User.last
post = Post.new
post.title = "Mini Orm"
post.content = "Orm With CSV"
post.user = last_user
post.save

Breaking It Down Visually

Lets create a detailed flowchart showing exactly how the User.create method executes, from the initial call to final save.

User.create(name: "John Deo", email:"john@example.com")

Understanding Ruby Metaprogramming: Common Questions

After building this Mini ORM, several interesting questions arise about how Ruby's metaprogramming features work under the hood. Let's explore some of these fundamental concepts.

Q: How Does Method Creation Work with `send`?

When we use code like this in our ORM:

user.send("name=", "John Doe")

A common question is: Where does the name= method come from? The answer lies in how our column method works:

def self.column(name, type)
  @columns ||= {}
  @columns[name] = type
  attr_accessor name  # This creates our getter and setter methods
end

The magic happens during class loading time. When Ruby first reads your User class definition:

class User < MiniRecord
  column :name, String.new  # This executes immediately during class loading
end

The attr_accessor :name line creates two methods:

# What attr_accessor creates behind the scenes
def name      # Getter
  @name
end

def name=(value)  # Setter
  @name = value
end

These methods are created before your program starts running, which is why they're available when you later use send to call them.

Q: How Does Ruby's Assignment Syntax Work?

When we write:

user.name = "John Doe"

It looks like we're directly assigning a value, but we're actually not! This is Ruby's syntactic sugar at work. Ruby automatically transforms this assignment syntax into a method call. These three lines are exactly equivalent:

user.name = "John Doe"              # Style 1: Assignment syntax
user.send("name=", "John Doe")      # Style 2: Explicit method call
user.method("name=").call("John Doe") # Style 3: Even more explicit

This is why attr_accessor only needs to create two methods (name and name=). When Ruby sees the assignment syntax (object.something = value), it automatically converts it into a method call to the something= method.

Q: What's the Difference Between `define_singleton_method` and `define_method`?

These two metaprogramming tools create different types of methods:

define_method creates instance methods (methods available on instances of the class)
define_singleton_method creates class methods (methods available on the class itself)

Here's how we use both in our ORM:

class MiniRecord
  # Creates an instance method - each Post or User instance will have this
  define_method(name) do
    foreign_key_value = send("#{name}_id")
    Object.const_get(name.to_s.capitalize).find(foreign_key_value)
  end

  # Creates a class method - available on Post or User class itself
  define_singleton_method("find_by_#{name}") do |value|
    find(name.to_sym => value)
  end
end

This leads to different usage patterns:

# Instance methods (from define_method)
post = Post.new
post.user               # Works - instance method
post.user = some_user   # Works - instance method

# Class methods (from define_singleton_method)
Post.find_by_title("Hello")  # Works - class method
Post.where(author: "John")   # Works - class method

Think of it this way:

Instance methods answer "What can this specific record do?"
Class methods answer "What can the User/Post class do?"

In our ORM:

Instance methods handle record-specific operations like getting associated records (post.user) or saving data (post.save)
Class methods handle class-level operations like finding records (Post.find_by_title) or creating tables (Post.create_table)

Understanding these metaprogramming concepts helps us appreciate how Ruby makes it possible to create such elegant and intuitive APIs. While the magic might seem complex at first, it follows logical patterns that make our code both powerful and maintainable.

Conclusion

Building this Mini ORM demonstrates the power of Ruby's metaprogramming features. Through method_missing, define_method, and class instance variables, we've created a flexible system that provides much of the convenience of larger ORMs while remaining simple enough to understand.

The key metaprogramming concepts we've used include:

Dynamic method definition with define_method
Class instance variables for storing metadata
Method delegation using send
Constant lookup with Object.const_get
Runtime class modification

While this implementation uses CSV files for storage, the same principles could be applied to build an ORM for any database system. The real power lies in Ruby's metaprogramming capabilities, which allow us to write clean, declarative code that gets transformed into powerful functionality at runtime.

Building a Custom DSL for RSpec: How I Reduced Testing Boilerplate by 77%

Albin Yesudasan (Albi) — Fri, 21 Mar 2025 16:22:05 +0000

Testing is essential for reliable software, but it can become a significant burden when tests grow verbose and repetitive.

In our Ruby application, we take testing seriously. Every feature, every change, no matter how small, requires comprehensive tests. This is especially important for our license management functionality, which is heavily backend-driven and handles critical business logic.

As our application evolved, writing tests for state license functionality became increasingly burdensome. Each test required:

Setting up state licenses with proper attributes for different user types and states
Creating specific contexts for validation testing
Manually progressing licenses through multiple renewal cycles
Creating certification records and connecting them to tests
Writing expectations for task generation, date validation, and credit calculations

For a single test case, we often needed 30-50 lines of setup code. For comprehensive tests covering multiple cycles and certification scenarios, the line count would balloon to hundreds. The problem wasn't just the volume of code but also its repetitive nature – we were writing nearly identical setup code across dozens of files.

The Journey to a Solution

Phase 1: Shared Examples

Our first attempt at improving the situation was using RSpec's shared examples. This helped reduce duplication by extracting common testing patterns into reusable components. While this was a step in the right direction, it still required significant boilerplate code in each test file. The cognitive load remained high, and onboarding new developers to write these tests was challenging.

Phase 2: Domain-Specific Language

After hitting the limits of shared examples, I realized we needed something more transformative. What if, instead of adapting our tests to RSpec's general-purpose syntax, we created a language specifically designed for our testing domain?

The idea of a Domain-Specific Language (DSL) seemed perfect. A well-designed DSL could:

Express test intent clearly, mirroring how we talk about licenses in real life
Hide implementation details behind simple, declarative statements
Make tests readable to non-developers
Dramatically reduce the code needed to test complex scenarios

The Design Approach

To design an effective DSL, I needed to understand how our team thinks about and verifies licenses. Rather than starting with the implementation details, I started with the mental model.

When our team tests a license manually or designs verification procedures, they follow a specific flow:

Create a license for a specific provider type and state
Verify the license validates correctly with appropriate dates
Check that the right tasks are generated for the current cycle
Upload certifications and check if tasks complete properly
Advance to the next renewal cycle and repeat the process

This flow became the foundation for the DSL structure. Each concept would become a block in the language, with a clear hierarchical relationship:

license → cycles → tasks/certifications/exemptions

By mirroring this conceptual model, the DSL would feel natural to anyone familiar with how our licenses work.

Cutting the Fat

Our DSL extends RSpec using Ruby's metaprogramming capabilities. Here's a high-level overview of how it works:

1. Integration with RSpec

The DSL integrates with RSpec through a module that we include in test files:

# In spec/support/state_license_testing_dsl.rb
module StateLicenseTestingDSL
  extend ActiveSupport::Concern

  module ClassMethods
    def validate_state_license(&block)
      # Implementation
    end

    def state_license(description, &block)
      # Implementation
    end
  end

  def self.included(base)
    base.extend(ClassMethods)

    RSpec.configure do |config|
      config.include StateLicenseTestingDSL, type: :state_license
    end
  end
end

2. Test File Structure

Tests using the DSL start with a standard RSpec describe block, but with a special type: :state_license metadata that activates our DSL:

RSpec.describe 'Tasks::StateLicenses::NursePractitioner::Dc', type: :state_license do
  # DSL blocks go here
end

The DSL extracts information from the describe string itself, parsing out the provider type (NursePractitioner) and state (Dc) to avoid repetitive declarations.

3. Builder Pattern for Test Structure

Behind the scenes, the DSL uses a builder pattern to construct tests:

class StateLicenseBuilder
  attr_reader :name, :initial_date, :expiry_date, :cycles

  def initialize(description, user_type, state, &block)
    @name = description
    @cycles = []
    @user_type = user_type
    @state = state
    instance_eval(&block) if block_given?
  end

  def initial_date(date)
    @initial_date = date
  end

  def expiry_date(date)
    @expiry_date = date
  end

  def cycle(number, description = nil, &block)
    cycle = CycleBuilder.new(number, description, &block)
    @cycles << cycle
    cycle
  end
end

This pattern allows us to capture test configurations declaratively and then generate appropriate RSpec contexts and examples.

The core of the DSL consists of several builder classes that translate the declarative test language into the actual RSpec tests:

StateLicenseValidationBuilder: Handles validation of license dates
StateLicenseBuilder: Creates licenses and manages the primary structure
CycleBuilder: Manages license cycles and their expectations
CertificationBuilder: Creates and links certifications to tasks
ContextBuilder: Supports custom contexts for special cases

These builders interpret the DSL blocks and generate appropriate RSpec tests behind the scenes.

The Results: A Dramatic Transformation

Before: Traditional RSpec Testing

context 'Expiry date validation' do
  context 'Expiry date is at the end of month' do
    before do
      @state_license = build(:state_license,
                             state: 'TX',
                             license_number: '1234',
                             user: @user,
                             initial_date: '01/05/2022',
                             date_of_expiry: '31/05/2023',
                             user_type: 'BehavioralHealth',
                             flags: {
                               license_types: 'LBSW',
                             })
    end
    it 'valid state license' do
      expect(@state_license).to be_valid
    end
  end

  context 'Expiry date is not at the end of month' do
    before do
      @state_license = build(:state_license,
                             state: 'TX',
                             license_number: '1234',
                             user: @user,
                             initial_date: '01/05/2022',
                             date_of_expiry: '25/05/2024',
                             user_type: 'BehavioralHealth',
                             flags: {
                               license_types: 'LBSW',
                             })
    end
    it 'Invalid state license' do
      expect(@state_license).to_not be_valid
    end
  end
end

Old Approach (34 lines of code):

After: DSL-Powered Testing

validate_state_license do
  valid initial_date: '01/01/2023', expiry_date: '30/09/2024'
  not_valid initial_date: '01/01/2023', expiry_date: '20/09/2024'
end

New DSL Approach (4 lines of code):

Behind the Scenes: How It Works

Let's peek under the hood at one key component of the DSL—the validation testing implementation:

def validate_state_license(&block)
  user_type, state = parse_describe_string(self.name)

  builder = StateLicenseValidationBuilder.new(&block)

  context "License date validations" do
    let!(:user) do
      create(USER_TYPE_MAPPINGS[user_type])
    end

    let(:state_license_attrs) do
      {
        state: state,
        license_number: '12345',
        user: user
      }
    end

    # Test valid date combinations
    builder.valid_dates.each_with_index do |date_pair, index|
      context "Valid date combination #{index + 1}" do
        it "should accept initial_date: #{date_pair[:initial_date]}, expiry_date: #{date_pair[:expiry_date]}" do
          license = build(:state_license,
                         state_license_attrs.merge(
                           initial_date: date_pair[:initial_date],
                           date_of_expiry: date_pair[:expiry_date]
                         ))

          expect(license).to be_valid
        end
      end
    end

    # Test invalid date combinations
    builder.invalid_dates.each_with_index do |date_pair, index|
      context "Invalid date combination #{index + 1}" do
        # Test implementation
      end
    end
  end
end

This method:

Parses the describe string to extract user type and state
Creates a builder to collect validation cases
Dynamically generates contexts and examples for each validation scenario
Runs the appropriate expectations automatically

Overall, we achieved a code reduction of approximately 77%. A typical test file that required over 200 lines was reduced to just 49 lines while maintaining the same test coverage.

Lessons Learned: Building Effective DSLs

Through this process, I learned several key lessons about creating effective DSLs:

1. Start With the Mental Model, Not the Implementation

Rather than forcing our testing needs into an existing framework's paradigm, I designed the language to match how our team actually thinks about the domain. This made the DSL intuitive and reduced the learning curve.

2. Hide Implementation Details, Expose Intent

The DSL abstracts away the "how" of testing (setting up factories, creating associations, etc.) and focuses on the "what" (validating dates, checking task generation). This makes tests more readable and maintainable.

3. Make the Common Case Easy, the Uncommon Case Possible

The DSL focuses on the most common testing patterns, making them extremely concise. For edge cases or special requirements, it provides escape hatches through custom contexts and blocks.

4. Design for Readability

Every aspect of the syntax was chosen to make tests readable to both developers and non-technical stakeholders. The structure mirrors natural language descriptions of what's being tested.

5. Provide Sensible Defaults

Where possible, the DSL makes reasonable assumptions, reducing the amount of configuration needed. For example, it automatically extracts the user type and state from the test description, removing the need to specify them repeatedly.

6. Leverage Ruby's Metaprogramming

Several Ruby features made this DSL possible:

instance_eval for executing blocks in the builder's context
method_missing to handle flexible syntax options
Active Support's concern module for clean code organization
Dynamic method creation for specialized test helpers

Results and Benefits

The impact of this DSL has been substantial:

Code Reduction: Our state license tests are now 77% smaller on average
Improved Readability: Tests clearly express their intent without setup noise
Faster Test Writing: New tests can be written in minutes rather than hours
Better Test Coverage: The consistency encourages testing edge cases
Living Documentation: The tests serve as clear documentation of business rules

Conclusion: When to Build a DSL

Creating a custom DSL isn't always the right answer, but it can be transformative when:

You have repetitive testing patterns across many files
Test setup obscures the actual behavior being tested
Your domain has clear concepts that can be abstracted
The testing burden is reducing team velocity

If you're drowning in boilerplate test code or finding it hard to maintain comprehensive test coverage, a well-designed DSL can dramatically improve your testing experience.

By approaching the problem from a domain-driven perspective and leveraging Ruby's metaprogramming capabilities, you can create a testing language that speaks directly to your application's concepts, making tests both easier to write and more valuable as documentation.