Szymon Fiedler

The timezone bug that hid in plain sight for months

2026-02-05T12:02:35Z

The timezone bug that hid in plain sight for months

We recently fixed a bug in a financial platform's data sync that had been silently causing inconsistencies for months. The bug was elegant in its simplicity: checking DST status for "now" when converting historical dates.

The broken code

I found this while debugging a different sync issue — the real bug turned out to be hiding in a helper method I wasn't even looking at.

def self.date_to_utc(value, timezone_key)
  offset = Time.now.in_time_zone(TIMEZONE_MAP.fetch(timezone_key)).formatted_offset
  Time.new(*value.to_s.split('-').map(&:to_i), 0, 0, 0, offset).utc
end

Looks reasonable, right? Get the timezone offset, create a Time object, convert to UTC.

The problem: Time.now.in_time_zone().formatted_offset gets the offset for right now, then applies it to any date being converted.

Why this breaks

Run this in December (EST, UTC-5):

date_to_utc(Date.new(2023, 6, 20), :eastern)
# Gets -05:00 offset, but June 20 should be EDT (-04:00)
# Result: off by one hour

Run the same code in June (EDT, UTC-4):

date_to_utc(Date.new(2023, 6, 20), :eastern)
# Gets -04:00 offset, correct for June
# Result: works fine

Same input, different output depending on when you run it. Your tests pass in summer, fail in winter. Data syncs would occasionally miss records or pull wrong date ranges, depending on DST periods.

The fix

def self.date_to_utc(value, timezone_key)
  tz = ActiveSupport::TimeZone[TIMEZONE_MAP.fetch(timezone_key)]
  tz.local(value.year, value.month, value.day, 0, 0, 0).utc
end

ActiveSupport::TimeZone#local handles DST correctly for the specific date being converted. June dates always get EDT, January dates always get EST, regardless of when the code runs.

The test that exposed it

Before touching the implementation, I wrote a test to confirm my suspicion — and it failed immediately.

it 'produces consistent results regardless of system timezone' do
  date = Date.new(2023, 6, 20)
  expected = Time.new(2023, 6, 20, 4, 0, 0, 'UTC')

  %w[UTC Asia/Tokyo America/Los_Angeles].each do |tz|
    Time.use_zone(tz) do
      expect(described_class.date_to_utc(date, :eastern)).to eq(expected)
    end
  end
end

This test runs the same conversion in UTC, Tokyo, and LA timezones. The old implementation would produce different results depending on system timezone and time of year.

Impact

We caught this before it caused visible production issues, but the potential impact for a financial data integration was significant: off-by-one-hour shifts during DST transitions could cause missed records in date-range queries and validation mismatches between systems.

Lessons

Never use Time.now for calculations on other dates. If you need timezone info for a specific date, use that date.
Test with explicit timezone manipulation. Don't rely on your system's timezone matching production.
DST transitions are sneaky. A bug that manifests only during certain months can survive code review and testing.
Know your tools: ActiveSupport::TimeZone

Stop using DateTime in 2026 (unless you work for UNESCO)

2026-01-14T14:08:58Z

Stop using DateTime in 2026 (unless you work for UNESCO)

DateTime has been considered deprecated in Ruby since 3.0. It's 2026. Why are people still using it?

During a recent code review, we found this:

whatever.starts_at = DateTime.now

When asked why DateTime instead of Time, the response was: "DateTime handles a wider range of dates."

That was partially true. In 2008. On 32-bit systems.

DateTime's range advantage died in Ruby 1.9.2

Before Ruby 1.9.2 (released in 2010), Time was limited by the system's time_t type — typically 32-bit signed integer covering 1901-2038. DateTime had a much wider range.

Ruby 1.9.2 changed this. Time started using a signed 63-bit integer representing nanoseconds since epoch, giving it a range of 1823-2116. For dates outside this range, Time uses Bignum or Rational — slower, but it works.

The practical range advantage is gone.

Remember Rails 4.2?

Pepperidge Farm Remembers. Some time ago when upgrading Rails app from 4.2 to 5.0, the test suite fortunately failed. The culprit was surprising: DateTime#utc changed its return type.

Rails 4.2:

DateTime.now.utc.class
# => DateTime

Rails 5.0:

DateTime.now.utc.class # => Time

This broke several Dry::Struct objects with strict type definitions expecting DateTime. But instead of "fixing" the types, we asked a better question: why were we using DateTime at all?

Rails 5's breaking change to DateTime#utc wasn't a bug — it was a nudge. It was telling you: stop using this class.

Struggling with upgrades? We have a solution for you.

The UNESCO problem

There's actually one legitimate use case for DateTime: historical calendar reforms.

From Ruby's own documentation:

It's a common misconception that William Shakespeare and Miguel de Cervantes died on the same day in history - so much so that UNESCO named April 23 as World Book Day because of this fact. However, because England hadn't yet adopted the Gregorian Calendar Reform (and wouldn't until 1752) their deaths are actually 10 days apart.

Ruby's Time uses a proleptic Gregorian calendar — it projects the Gregorian calendar backwards, ignoring historical reality. October 10, 1582 doesn't exist in Italy (Pope Gregory XIII removed 10 days that October), but Ruby happily creates that timestamp.

DateTime can handle different calendar reform dates:

shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)

(shakespeare - cervantes).to_i # => 10 days apart

For cataloging historical artifacts or dealing with pre-1752 dates across different countries, DateTime is your tool.

For literally everything else — which is 99.99% of applications — it's the wrong choice.

Norbert Wójtowicz gave an excellent talk about calendars at wroclove.rb covering exactly these issues.

`DateTime`’s actual problems

No timezone support. DateTime doesn't handle timezones.

DateTime.now
# => #<DateTime: 2026-01-14T13:00:00+00:00>
# Why +00:00 when my system is CET (+01:00)?

Incompatible with Rails. ActiveSupport extends Time with timezone support. DateTime? Barely.

Time.current   # ✅ Respects Rails.application.config.time_zone
DateTime.now   # ❌ Uses system timezone, ignores Rails config

Confusing arithmetic:

Time.now + 1      # => 1 second later
DateTime.now + 1  # => 1 day later

This has caused bugs. Many bugs.

Ignores DST. DateTime doesn't track daylight saving time. If you use DateTime for anything involving timezones, you will have bugs.

Performance. Time is faster. Noticeably.

Why people still use it

"We've always used it"

The code was written in 2009. It's 2026. Update it.

"I need to store dates without time"

Use Date. That's what it's for.

Date.current  # ✅ Rails.application.config.time_zone aware

"The library I'm using returns DateTime"

Convert immediately:

legacy_gem.fetch_date.to_time.in_time_zone

What to use instead

For timestamps: Time.current or Time.zone.now

For dates: Date.current

For parsing: Time.zone.parse('2026-01-14 13:00:00')

The only exception

If you're cataloging historical documents, artifacts, or working with dates before calendar reforms in different countries, DateTime is your tool. You need to track which calendar reform date applies.

For everything else — modern applications, APIs, databases — use Time.

DateTime is deprecated for a reason.

References

Rewrite with Confidence: Validating Business Rules Through Isolated Testing

2025-12-22T20:04:19Z

Rewrite with Confidence: Validating Business Rules Through Isolated Testing

A few months back, our team at Arkency faced a challenge that many Rails developers might recognize. We needed to implement a new flow at Lemonade that would eventually replace a legacy process — but with three major constraints that couldn't be compromised: user experience, cost efficiency, and avoiding technical debt.

The stakes were high. Any discrepancies between systems would impact customers and potentially create legal issues in the insurance domain. We had just three months to understand, replicate, and improve a complex flow that had evolved organically over years. And we needed to break free from obsolete data structures while preserving essential business rules embedded in a codebase with over 1 million lines of code.

Traditional approaches wouldn't work. Full test coverage would take months we didn't have. What we needed was a methodology to systematically identify, isolate, and verify each business rule independently of its implementation.

We needed a way to rewrite with confidence.

The Context: Insurtech at Scale

If you had asked me three years ago if insurtech could be exciting, I would have probably laughed. But it can be.

Lemonade is an innovative insurance company that hit $1 billion in premiums just 10 years after founding. It took other well-established insurance brands 40–60 years to reach that milestone. Even companies like Microsoft, Netflix, Salesforce, and Tesla needed more time to achieve that.

What a thrill for @lemonade_inc to be in the 𝘛𝘳𝘦𝘴 𝘊𝘰𝘮𝘮𝘢𝘴 Club! I’m not particularly moved by a car “with doors that open like 𝘵𝘩𝘪𝘴 👐”, but I’m definitely exhilarated by the ride so far, and can’t wait for our #Next10X! 🙌🏻🚀🎉 https://t.co/HKpgfyFO7Y
— Daniel Schreiber (@daschreiber) March 25, 2025

When we joined Lemonade three years ago, their Director of Engineering shared a story that perfectly illustrated the stakes of our work. They once had an issue with roof coverage in one of their product lines and had to hire a legal team for a six-month sprint to fix things. The legal costs exceeded the entire IT budget.

We couldn't break things. We had to be 100% sure that the new flow provided the same outcome.

The Architecture: A Rails Monolith Under Transformation

Lemonade used a Rails monolith as their foundation — my favorite architecture. There's no coincidence they became successful. Over the past few years, they've been transforming to a microservices architecture, with new product lines released using their internal framework. But all home and renters insurance is still handled within the Rails monolith.

Our scope was clear: implement a new quote flow for HO4 (renters insurance) in the US that would produce identical underwriting results to the legacy system.

Understanding the Problem

The God Model

Like many mature Rails applications, the system had a God model — Quote — that accumulated responsibilities over time:

class Quote < ApplicationRecord
  serialize :data
  serialize :answers

  enum :status,
       {
         pending: 'pending',
         stubbed: 'stubbed',
         bindable: 'bindable',
         uw_declined: 'uw_declined',
       },
       default: 'pending'
end

The business raised a valid point: "We don't want pending and stubbed Quotes in the system." Pending represented abandoned quotes with no value. Stubbed meant the system couldn't make a risk assessment, usually due to third-party issues. This data model pollution required filtering at different levels:

class Quote < ApplicationRecord
  scope :not_pending, lambda do 
    where.not(status: :pending)
  end
end

We all have such excluding scopes in our apps — don't pretend you don't.

This was especially problematic for the Data Science team. Without filtering these quotes, their models would be far from accurate.

The Data Complexity

The Quote model contained two serialized columns with deeply nested data. Here's just a glimpse of what we were dealing with:

data:
  :locale:
    :region: US
    :language: en
  :client_uuid: 30a1377e-5f06-4e6f-878b-41564c2e1221
  :user_logged_in: false
  :flags:
    - :send_pdf_sample_docs
    - :tenant_pet_damage_activated
  # ... and dozens more attributes

The answers hash was even more complex, containing everything from address components to user preferences to tracking data.

Why Traditional Approaches Failed

We initially tried static analysis to figure out which Quote attributes were necessary for the underwriting process. We quickly realized this was impossible — too many branches in the code. Imagine: every US state has its own regulations affecting insurance products. Multiply this by product editions that change over time due to legal concerns or business needs. We also share the data model and flow with home insurance.

Then we tried using Module#prepend to instrument Quote accessors and track which data was involved. This gave us better overview but was still overwhelming.

And we hadn't even touched the HTTP communication part — all the first-party and third-party calls required for underwriting, coverage selection, deductible calculation, and premium determination.

What About Other Approaches?

We considered several alternatives before settling on our solution.

Shadow traffic was an interesting option. This technique involves routing live production traffic to both the existing backend and a new shadow backend simultaneously. The shadow backend processes requests without affecting users, while comparison mechanisms validate behavior. Tools like nginx plugins or Zalando's Skipper can handle this elegantly.

However, shadow traffic came with significant drawbacks for our use case:

Substantial infrastructure work and ongoing costs
Potential compliance issues using production data in non-production environments
Need to implement complex comparison mechanisms
Difficulty avoiding side effects when dealing with stateful operations and third-party APIs

The infrastructure overhead alone would have consumed a significant portion of our three-month deadline.

The Solution: Testing on Production

Here's where we took an unconventional approach. Instead of trying to replicate production conditions in a test environment, we decided to test directly on production — but safely.

The Brave New Flow

The key architectural change was simple but profound: instead of creating a Quote at the beginning of the flow and updating it on every step, we'd receive all the data gathered by the frontend client and perform our task at the very end.

This meant:

No more pending quotes
No more stubbed quotes
Only bindable or uw_declined as final states
Much cleaner data model

Implementing the Sampling Mechanism

We built a sampling system using Ruby's prepend to non-invasively inject our verification code:

class RentersUsQuoteSampler
  module AroundFilter
    def run_prepare_for_preview(quote)
      if RentersUsQuoteSampler.conditions_met_for_sampling?(quote)
        RentersUsQuoteSampler.sampled(quote) { super }
      else
        super
      end
    end
  end
end

This allowed us to intercept the underwriting process for specific quotes without affecting the normal flow.

What We Sampled

For each qualifying quote, we captured:

Quote state before underwriting - The raw quote data as it entered the process
Quote state after underwriting - The complete quote with pricing, deductible, and coverage
Address data - All location information
HTTP interactions - Every external API call made during the process

class RentersUsQuoteSampler  
  def self.sampled(quote)
    address = Address.lemonade.find_by(quote_id: quote.id)
    before_quote = to_sample(quote)

    TyphoeusRecorder.start_recording
    begin
      result = yield
      typhoeus_requests = TyphoeusRecorder.recorded_requests
    ensure
      TyphoeusRecorder.stop_recording
    end

    Record.create!(
      quote_before: before_quote,
      address: to_sample(address),
      quote_after: to_sample(quote),
      typhoeus_requests: typhoeus_requests,
    )
    result
  rescue => e
    ::Sentry.capture_exception(e, hint: { ignore_exclusions: true })
  end
end

Recording HTTP Interactions

Lemonade used Typhoeus as the HTTP client for microservices and third-party communication. Fortunately, Typhoeus provides a callback system:

class RentersUsQuoteSampler  
  module TyphoeusRecorder
    RECORD_PROC = ->(response) do
      @@typhoeus_requests.merge!(serialize_request(response))
    end

    def self.start_recording
      @@typhoeus_requests = {}
      ::Typhoeus.on_complete(&RECORD_PROC)
    end

    def self.stop_recording
      ::Typhoeus.on_complete.delete(RECORD_PROC)
      @@typhoeus_requests = nil
    end

    def self.serialize_request(response)
      {
        {
          base_url: response.request.base_url,
          params: response.request.options[:params],
          method: response.request.options[:method],
          body: response.request.options[:body],
        } => { 
          code: response.code,
          body: response.body,
        },
      }
    end
  end
end

This gave us perfect request-response pairs to use as stubs during verification.

The Verification Process

Sampling and verification were separate processes, allowing us to:

Collect samples from production continuously
Run verification asynchronously
Re-run verification after code fixes
Iterate until we achieved parity

Leaving No Trace

The critical requirement was not polluting production with duplicate quotes:

class RentersUsQuoteDtoVerifier
  def with_rollback
    ActiveRecord::Base.transaction do
      yield
      raise ActiveRecord::Rollback
    end
  end
end

But there was a gotcha: background jobs. We needed to ensure no jobs were scheduled within our rolled-back transaction.

After Commit Handling

This feature became built-in to Rails 7.2, but we weren't there yet. Fortunately, one of the best things about working at Arkency is that if you need a solution, there's a good chance we've solved it before — like in RailsEventStore or our blog posts from 9 years before Rails introduced it.

module AfterCommitRunner
  def self.call(&schedule_proc)
    transaction = ActiveRecord::Base.connection.current_transaction

    if transaction.joinable?
      transaction.add_record(async_record(schedule_proc))
    else
      schedule_proc.call
    end
  end

  def self.async_record(schedule_proc)
    AsyncRecord.new(schedule_proc)
  end

  class AsyncRecord
    def initialize(schedule_proc)
      @schedule_proc = schedule_proc
    end

    def committed!(*) = schedule_proc.call
    def rolledback!(*) = nil
    def before_committed!() = nil

    attr_reader :schedule_proc
  end
end

This allowed us to queue jobs only after successful commits, not within rolled-back transactions.

HTTP Stubbing Strategy

We needed to stub all external HTTP calls to avoid:

Mutating state in other microservices
Making expensive third-party API calls
Affecting external systems (like credit scores)
Rate limiting issues

First, we blocked all Typhoeus requests:

def with_http_stubs_mechanism
  callback = ->(req) do
    req.block_connection = true
    req
  end
  Typhoeus.before.prepend(callback)
  yield
ensure
  Typhoeus.before.delete(callback)
  Typhoeus::Expectation.clear
end

Then we used our recorded requests as stubs:

def with_common_http_stubs
  http_stubs.each do |req, res|
    Typhoeus
      .stub(req[:base_url], req[:params])
      .and_return(Typhoeus::Response.new(**res))
  end

  yield
end

Handling Edge Cases

Some libraries used net/http directly, which wasn't easy to stub. For AWS S3 clients, we used Ruby's metaprogramming capabilities:

def with_no_verisk_persistence
  old_const = Storage::IamS3Resource
  no_writes_iam_resource = Class.new do
    extend old_const

    def self.put(*) = 'http://example.org'
    def self.presigned_url(*) = 'http://example.org'
  end
  Storage.send(:remove_const, :IamS3Resource)
  Storage.const_set(:IamS3Resource, no_writes_iam_resource)
  yield
ensure
  Storage.send(:remove_const, :IamS3Resource)
  Storage.const_set(:IamS3Resource, old_const)
end

This allowed us to override behavior while still downloading resources from S3 (assuming GETs don't mutate state).

The Complete Verification Flow

Putting it all together:

def sample_remake
  sample_remake = nil

  with_rollback do
    with_http_stubs_mechanism do
      with_common_http_stubs do
        with_bouncer_stubs do
          with_census_block_stubs do
            with_no_segment do
              with_no_verisk_persistence do
                with_no_promises do
                  with_no_impressions do
                    remake = mk_quote
                    Chat::Quote.run_prepare_for_preview(remake)
                    sample_remake = RentersUsQuoteSampler.to_sample(remake)
                  end
                end
              end
            end
          end
        end
      end
    end
  end

  sample_remake
end

Yes, the nesting looks deep, but each wrapper handled a specific concern. We could experiment safely as many times as needed.

Comparing Results

We used the super_diff gem to identify discrepancies:

def verify 
  tuple_to_compare.reduce(:==)
end

def diff
  SuperDiff.diff(*tuple_to_compare)
end

Example output when things didn't match:

{
-  "status" => "bindable",
+  "status" => "pending",
   "product" => "iso",
   "form" => "ho4",
-  "edition" => "E240716",
+  "edition" => "E240618",
   # ...
}

This worked beautifully for nested structures, which was crucial for our case.

The Results

After implementing this methodology, we achieved:

Fewer questions asked - Simplified the customer flow
Cleaner data model - Eliminated obsolete quote states
Identical outcomes - 100% parity with legacy underwriting
Confidence to ship - No surprises in production

The project leader shared across the organization:

"This is part of one of the best releases I have ever experienced."

There was even a panic moment when he reached out on a Friday evening before both our ski vacations — but it was just to thank the team for the exceptional release quality.

Key Takeaways

This approach worked because we:

Separated collection from verification — Continuous sampling with async verification
Treated production as the specification — No need to replicate complex environments
Isolated tests from side effects — Transaction rollbacks and HTTP stubbing
Iterated until perfect — Fixed issues and re-verified until parity achieved
Leveraged Ruby's strengths — Metaprogramming made complex stubbing manageable

The methodology is applicable beyond insurance or quote systems. Anytime you need to rewrite complex business logic while ensuring behavioral parity, consider:

Can you sample real production behavior?
Can you replay it safely in isolation?
Can you compare results programmatically?
Can you iterate until perfect?

When refactoring mission-critical business logic, traditional testing might not be enough. Sometimes the best test suite is production itself — as long as you can verify without breaking things.

Prefer watching?

This post is based on author’s conference talk delivered at wroclove.rb 2025 in Wrocław, Poland and EuRuKo 2025 in Viana do Castelo, Portugal.

This methodology emerged from real-world necessity at Lemonade. We're grateful for their trust in letting us solve this challenge and share the solution with the Ruby community.

The Joy of a Single-Purpose Class: From String Mutation to Message Composition

2025-10-30T14:24:50Z

The Joy of a Single-Purpose Class: From String Mutation to Message Composition

Recently I started the process of upgrading rather big Rails application to latest Ruby 3.4. I noticed a lot of warnings related to string literal mutation:

warning: literal string will be frozen in the future (run with --debug-frozen-string-literal for more information)

Ruby has both mutable and immutable strings

Let's read fxn's explanation on this:

In Ruby 3.4, by default, if a file does not have the magic comment and a string object that was instantiated with a literal gets mutated, Ruby still allows the mutation, but it now issues a warning

I was able to notice this early since my colleague Piotr took care about not tuning out the Ruby deprecation warnings.

This article won’t be about benefits of freezing string literals, but if you’re curious about this topic, you should read this gist by fxn with care and the article about Past, Present and Future of Frozen String Literal by byroot if you want a deep dive into details.

Problem with string literal mutation in our code

I noticed that there’s noticeable amount of deprecation messages related to modifying future frozen string literals coming from one module. It was the one responsible for producing and delivering Slack messages related to customer support, billing, frauds, etc. All the things that improve day-to-day operations in a serious business. 100+ methods representing messages to be delivered to various channels.

The messages were composed in a few ways:

module Slack
  module Billing
    BILLING_CHANNEL_NAME = 'billing'.freeze

    extend self

    def invoice_sent(invoice)
      message = ':postbox: *Invoice sent to customer*'
      message << " | #{invoice.customer_name}"
      message << " | #{invoice.customer_email}"
      message << " | <#{inovice.url}|#{invoice.number}>"

      send_message(BILLING_CHANNEL_NAME, message)
    end

    def payment_received(payment, locale)
      message = payment_text(payment, locale)
      message.push("\n Invoice: #{payment.invoice_number}")
      message.push("\n Customer: #{payment.customer_name}")

      send_message(BILLING_CHANNEL_NAME, message)
    end

    private

    def payment_text(payment, locale)
      text = ':moneybag: *Payment Received*'
      text << " | #{format_amount(payment.amount, locale)}"
      text << " | #{payment.channel}"

      text
    end

    def format_amount(amount, locale)
      number_to_currency(amount, locale: locale)
    end

    def send_message(channel_name, message)
      Client.deliver_message(channel: channel_name, message: message)
    end
  end
end

Respective messages produced would be:

:postbox: | *Inovice sent to customer* | Jane Doh | jan.doh@example.com | <https://fancyurl.example.com|KAKADUDU123>

and

:moneybag: *Payment Received* | $123.45 | Credit card
Invoice: KAKADUDU123
Customer: Jane Doh

Noticing the pattern

After reviewing around 100 methods delivering different messages, I instantly noticed the pattern and thought: Ok, I can deal with that easily with a help of Array and improve this repeatable, manual text decorations like " | " or "\n".

+ # frozen_string_literal: true
+ 
 module Slack
   module Billing
     BILLING_CHANNEL_NAME = 'billing'

     extend self

     def invoice_sent(invoice)
-      message = ':postbox: *Invoice sent to customer*'
-      message << " | #{invoice.customer_name}"
-      message << " | #{invoice.customer_email}"
-      message << " | <#{inovice.url}|#{invoice.number}"
+      message = [':postbox: *Invoice sent to customer*']
+      message << invoice.customer_name
+      message << invoice.customer_email
+      message << "<#{inovice.url}|#{invoice.number}>"

-      send_message(BILLING_CHANNEL_NAME, message)
+      send_message(BILLING_CHANNEL_NAME, message.join(" | "))
     end

     def payment_received(payment, locale)
-      message = payment_text(payment, locale)
-      message.push("\n Invoice: #{payment.invoice_number}")
-      message.push("\n Customer: #{payment.customer_name}")
+      message = [payment_text(payment, locale)]
+      message.push("Invoice: #{payment.invoice_number}")
+      message.push("Customer: #{payment.customer_name}")

-      send_message(BILLING_CHANNEL_NAME, messsage)
+      send_message(BILLING_CHANNEL_NAME, message.join("\n")) 
     end

     private

     def payment_text(payment, locale)
-      text = ':moneybag: *Payment Received*'
-      text << " | #{format_amount(payment.amount, locale)}"
-      text << " | #{payment.channel}"
+      text = [':moneybag: *Payment Received*']
+      text << format_amount(payment.amount)
+      text << payment.channel

-      text
+      text.join(" | ")
     end

     def format_amount(amount, locale)
       number_to_currency(amount, locale: locale)
     end

     def send_message(channel_name, message)
       Slack::Client.deliver_message(channel: channel_name, message: message)
     end
   end
 end

What we’ve gained by this refactoring:

No string literal mutation, so there will be no warnings on Ruby 3.4 and potential issues in the future
Less repeatable code, no artisanal text delimiter crafting
We still used the same methods for composing message as both String and Array provide << and push methods. I wanted to keep this code similar to previous implementation without any radical changes so other maintainers would be instantly familiarized with it.

Improve the code

I’m sick of primitive obsession in the codebase. I don’t like all those Array related internals exposed, irrelevant in the context of building a message. We operate on a very simple example here, multiply this 50 times, add even more complex methods to that.

What if we introduced dedicated object which:

produces strings in an immutable manner
hides all the separator plumbing as most of the 100+ messages use | to separate message parts
deals with empty strings
has API similar to current implementation
allows composition like current implementation

Let’s look at the implementation:

# frozen_string_literal: true

module Slack
  class Message
    DELIMITER = ' | '

    def initialize(*parts, delimiter: DELIMITER)
      @delimiter = delimiter
      @message = parts
    end

    def <<(message_part) = @message << message_part
    def to_s = @message.compact_blank.join(@delimiter)

    alias_method :to_str, :to_s
    alias_method :push, :<<
  end
end

Benefits of ActiveSupport

What’s important to notice is the fact that it’s a Rails and we benefit from ActiveSupport` here, specifically:

compact_blank in an explicit manner
and blank? in an implicit way as Object extension

Otherwise we would need to put a bit more effort into our class:

def to_s
  @message
    .compact
    .reject { |part| part.respond_to?(:empty?) && part.empty? }
    .join(@delimiter)
end

It could be split into private method, but I like the explicitness compact_blank provides and I’m fine with using it.

Pass a single string or multiple as an argument

The *parts parameter leverages Ruby's splat operator to automatically collect all positional arguments into an array under @messages. This gives us a flexible constructor without forcing callers to wrap arguments in array literals.

Slack::Message.new('kaka').to_s
=> "kaka"

Slack::Message.new('kaka', 'dudu').to_s
=> "kaka | dudu"

Append our message using different methods

message = Slack::Message.new('kaka')
message << 'dudu'
message.to_s
=> "kaka | dudu"

message = Slack::Message.new('kaka')
message.push 'dudu'
message.to_s
=> "kaka | dudu"

Default delimiter, but still customizable

Slack::Message.new('kaka', 'dudu').to_s
=> "kaka | dudu"

Slack::Message.new('kaka', 'dudu', delimiter: "\n").to_s
=> "kaka\ndudu"

Compose various `Slack::Message` object with different delimiters

Slack::Message.new('kaka', Slack::Message.new('dudu', 'foo', delimiter: " — ")).to_s
=> "kaka | dudu — foo"

msg = Slack::Message.new('kaka', delimiter: "\n")
msg << Slack::Message.new('dudu', 'foo', delimiter: ' ~ ')
msg.to_s
=> "kaka\ndudu ~ foo"

The magic happens through the to_str alias. When @message.join(@delimiter) is called, Ruby's Array#join implicitly calls to_str on each element (it would fallback to to_s if not defined). Since to_str is aliased to to_s, nested Slack::Message objects get automatically stringified.

This recursive flattening happens transparently because to_str signals to Ruby that our object can be treated as a string in implicit contexts.

Final refactoring

 # frozen_string_literal: true

 module Slack
   module Billing
     BILLING_CHANNEL_NAME = 'billing'

     extend self

     def invoice_sent(invoice)
-      message = [':postbox: *Invoice sent to customer*']
-      message << invoice.customer_name
-      message << invoice.customer_email
-      message << "<#{inovice.url}|#{invoice.number}>"
+      message = Message.new(':postbox: *Invoice sent to customer*')
+      message << invoice.customer_name
+      message << invoice.customer_email
+      message << "<#{inovice.url}|#{invoice.number}"

-      send_message(BILLING_CHANNEL_NAME, message.join(" | "))
+      send_message(BILLING_CHANNEL_NAME, message))
     end

     def payment_received(payment, locale)
-      message = [payment_text(payment, locale)]
-      message.push("Invoice: #{payment.invoice_number}")
-      message.push("Customer: #{payment.customer_name}")
+      message = Message.new(payment_text(payment, locale), delimiter: "\n")
+      message.push("Invoice: #{payment.invoice_number}")
+      message.push("Customer: #{payment.customer_name}")

-      send_message(BILLING_CHANNEL_NAME, messsage.join("\n"))
+      send_message(BILLING_CHANNEL_NAME, message)
     end

     private

     def payment_text(payment, locale)
-      text = [':moneybag: *Payment Received*']
-      text << format_amount(payment.amount, locale)
-      text << payment.channel
+      text = Message.new(':moneybag: *Payment Received*')
+      text << format_amount(payment.amount, locale)
+      text << payment.channel

-      text.join(" | ")
+      text
     end

     def format_amount(amount, locale)
       number_to_currency(amount, locale: locale)
     end

     def send_message(channel_name, message)
-      Slack::Client.deliver_message(channel: channel_name, message: message)
+      Slack::Client.deliver_message(channel: channel_name, message: message.to_s)
     end
   end
 end

I can’t remember the last time I had so much joy introducing such a simple, single-purpose class. In such moments you rediscover the true beauty of Ruby.

Summary

The class name Message nicely reveals its intent. We’re composing some message here.
There’s no need for artisanal delimiter orchestration
Our object composes nicely from different pieces
Output is predictable and immutable
frozen string literal warnings are gone

Stop concatenating URLs with strings — Use proper tools instead

2025-07-01T14:10:21Z

Stop concatenating URLs with strings — Use proper tools instead

How many times have you seen code like this in a Ruby application?

base_url = "https://api.example.com"
endpoint = "/users"
user_id = params[:id]

full_url = "#{base_url}#{endpoint}/#{user_id}

At first glance, it looks harmless, but it hides several traps that can lead to hard–to–debug errors.

Problems with Naive URL Concatenation

1. Double or missing slashes

base_url = "https://api.example.com/" # has trailing hash
endpoint = "/users" # has leading hash

url = "#{base_url}{#endpoint}"
# => "https://api.example.com//users"

Double slash is likely not desired. While most servers will handle it, this looks unprofessional.

base_url = "https://api.example.com" # no trailing hash
endpoint = "users" # no leading hash

url = "#{base_url}{#endpoint}"
# => "https://api.example.comusers"

TLD concatenated with path is not a thing we’re looking for.

2. Improper parameter escaping

query = "hello world"
url = "https://api.example.com/search?q=#{query}"
# => "https://api.example.com/search?q=hello world"
# space is not properly encoded

3. Protocol and port issues

host = "localhost:3000"
path = "/api/v1/users"

url = "https://#{host}#{path}"

What if host already contains protocol?

Solutions

1. Ruby’s URI

Ruby has a built–in URI class that solves most of these problems:

require "uri"

base = URI("https://api.example.com")
base.path = "/users"
base.query = URI.encode_www_form(q: "hello world", limit: 10)

puts base.to_s
# => "https://api.example.com/users?q=hello+world&limit=10"

Let’s join some paths:

base_url = URI("https://api.example.com/api/v1/")
URI.join(base_url, "users", "123")
# => #<URI::HTTPS https://api.example.com/api/v1/users/123>

More advanced URI example

class ApiClient
  def initialize(base_url)
    @base_url = URI(base_url)
  end

  def build_url(path, query_params = {})
    uri = @base_url.dup
    uri.path = File.join(uri.path, path)
    uri.query = URI.encode_www_form(query_params) unless query_params.empty?
    uri.to_s
  end
end

client = ApiClient.new("https://api.example.com/v1")
client.build_url("users/123", { include: "profile", format: "json" })
# => https://api.example.com/v1/users/123?include=profile&format=json

2. Pathname for local paths

If you’re working with file paths or local URLs, Pathname can be helpful:

require "pathname"

base_bath = Pathname.new("/var/www/uploads")
user_folder = "user_123"
filename = "avatar.jpg"

full_path = base_path.join(user_folder, filename)
# => #<Pathname:/var/www/uploads/user_123/avatar.jpg>

URI("file://#{full_path}")
# => #<URI::File file:///var/www/uploads/user_123/avatar.jpg>

One more cool trick with pathname is / method (alias for +):

Pathname.new("/var") / "www" / "uploads"
# => #<Pathname:/var/www/uploads>

3. Addresable gem

For more advanced use cases, consider the addressable gem:

require "addressable/uri"

uri = Addressable::URI.new(
  scheme: "https",
  host: "api.example.com",
  path: "users/123",
  query_values: {
    includes: ["profile", "posts"],
    format: "json"
  }
)

puts uri.to_s
# => "https://api.example.com/users/123?includes[]=profile&includes[]=posts&format=json"

4. Rails URL helpers

In Rails applications, use built–in helpers instead of string concatenation whenever possible:

# Instead of:
base_url = "https://myapp.com"
url = "#{base_url}/users/#{user.id}/posts/#{post.id}"

# Use this
url = user_post_url(user, post, host: "https://myapp.com")

# Or this
url = api_v1_user_url(user, host: request.base_url)

5. Test URL building

You might think that having test can catch these URL building issues and you would be partially right. However, many developers stub their HTTP client methods directly:

allow(http_client).to receieve(:get).and_return(mock_response)

This test won’t catch URL formatting issues.

When you stub the HTTP client method itself, malformed ULRs slip through because stub intercepts the call regardless of what URL was passed. A better approach is using WebMock, which sets expectations on the actual URLs being requested:

stub_request(:get, "https://api.example.com/users/123")
  .to_return(status: 200, body: response_json)

WebMock will fail if the URL is malformed
This will catch URL building errors:

double slashes
missing slashes
unescaped parameters

WebMock forces you to be explicit about the exact URLs your code should generated, making URL building bugs much more visible during test runs.

Summary

Concatenating URLs with strings is a recipe for trouble. Instead:

Use URI for basic URL building scenarios
Leverage Pathname for local file paths
Consider addressable for advanced use cases
Utilize Rails URL helpers in Rails applications
Always escape parameters using URI.encode_www_form
Test your external http calls

Your code will be more reliable, easier to maintain and less prone to URL formatting errors.

Installing Precompiled Native Gems with bundle lock --add-platform

2025-04-04T07:27:12Z

Installing Precompiled Native Gems with bundle lock --add-platform

There's a great chance that your Ruby app occasionally explodes during bundle install because of native extensions. There's an even greater chance that it happens with nokogiri, ffi or some other notorious gem with C extensions. The problem gets worse when you're working across different operating systems or upgrading Ruby versions. Let's fix this once and for all.

My problem with native gems

As we perform a ton of Ruby and Rails upgrades across different projects at arkency, we were struck by those issues many times.

My main concern with native gems is that they create unnecessary friction in your development and deployment workflow:

Every single bundle install takes ages if compilation has to occur
Ruby version upgrades? Prepare to recompile everything
Different OS than your teammates? Enjoy your unique set of errors
CI pipeline running slow? Blame those C extensions
YJIT performance gains are limited with C extensions

This last point is often overlooked. Ruby’s YJIT (Yet Another Just–In–Time compiler) can significantly speed up your application, but it works best with pure Ruby code. C extensions bypass the Ruby VM, which means YJIT can’t optimize them. The more your app relies on native extensions, the fewer benefits you’ll see from YJIT. With Ruby 3.3, YJIT can be enabled with the --yjit flag, so you’re potentially missing out on free performance gains, but Rails will do it for you.

Btw. here’s excellent article on speeding up Ruby by rewriting C... in Ruby.

It’s particularly frustrating on deployment. You’ve built a beautiful containerized setup, but still need to install build dependencies just to compile the same gems over and over. Your Docker images are bloated with compilers and dev headers that serve no purpose in production.

It’s not a new problem

What inspired me to share this solution with you is a recent chat with my friend, especially this part:

Recently I had to implement a tiny backend app. I dusted off Rails and everything was the same. Same commands, same gems, even nokogiri crashed the same way during bundle install like 10 years ago...

It doesn’t have to be that way, I thought.

Bundler, the hero we need

Here it comes: bundle lock --add-platform.

This command tells Bundler to resolve dependencies for platforms other than your current one and store that information in your Gemfile.lock. When these platforms provide precompiled versions, Bundler will use them instead of trying to compile from source.

The --add-platform option has been available since Bundler 2.2.0, so make sure you’re running a recent version . This can be easily checked with bundle -v.

If for some reason your Gemfile.lock is lacking PLATFORMS section, e.g. you’re upgrading good’ol app, you should follow next steps.

If your Gemfile.lock has PLATFORMS present, but it’s lacking the specific platform you run your app on, you should follow my article.

What are the PLATFORMS?

The answer is simple and lives on your machine:

➜  gem help platform
RubyGems platforms are composed of three parts, a CPU, an OS, and a
version.  These values are taken from values in rbconfig.rb.  You can view
your current platform by running `gem environment`.

RubyGems matches platforms as follows:

  * The CPU must match exactly unless one of the platforms has
    "universal" as the CPU or the local CPU starts with "arm" and the gem's
    CPU is exactly "arm" (for gems that support generic ARM architecture).
  * The OS must match exactly.
  * The versions must match exactly unless one of the versions is nil.

For commands that install, uninstall and list gems, you can override what
RubyGems thinks your platform is with the --platform option.  The platform
you pass must match "#{cpu}-#{os}" or "#{cpu}-#{os}-#{version}".  On mswin
platforms, the version is the compiler version, not the OS version.  (Ruby
compiled with VC6 uses "60" as the compiler version, VC8 uses "80".)

For the ARM architecture, gems with a platform of "arm-linux" should run on a
reasonable set of ARM CPUs and not depend on instructions present on a limited
subset of the architecture.  For example, the binary should run on platforms
armv5, armv6hf, armv6l, armv7, etc.  If you use the "arm-linux" platform
please test your gem on a variety of ARM hardware before release to ensure it
functions correctly.

Example platforms:

  x86-freebsd        # Any FreeBSD version on an x86 CPU
  universal-darwin-8 # Darwin 8 only gems that run on any CPU
  x86-mswin32-80     # Windows gems compiled with VC8
  armv7-linux        # Gem complied for an ARMv7 CPU running linux
  arm-linux          # Gem compiled for any ARM CPU running linux

When building platform gems, set the platform in the gem specification to
Gem::Platform::CURRENT.  This will correctly mark the gem with your ruby's
platform.

Prerequisites

Modern tooling

Make sure you have recent Bundler and Rubygems, just to avoid hiccups and benefit from improvements:

gem install bundler
gem update --system

If new version of bundler has been installed, make sure to let your Gemfile.lock to be aware of it:

bundle update --bundler

git add Gemfile.lock
git commit -m "Updated bundler"

Precompiled gem versions available for your platform

I recommend going to Rubygems page and checking versions page of a desired gem, let’s use nokogiri as an example.

For the day of writing this post, 1.18.7 is the most recent version. You’ll see raw version (compiled on your machine):

1.18.7 March 31, 2025 (4.16 MB)

along with precompiled ones:

1.18.7 March 31, 2025 x86_64-linux-gnu (3.88 MB)
1.18.7 March 31, 2025 arm-linux-gnu (3.25 MB)
1.18.7 March 31, 2025 aarch64-linux-gnu (3.8 MB)
1.18.7 March 31, 2025 arm-linux-musl (3.44 MB)
1.18.7 March 31, 2025 x86_64-linux-musl (3.87 MB)
1.18.7 March 31, 2025 arm64-darwin (6.23 MB)
1.18.7 March 31, 2025 x86_64-darwin (6.4 MB)
1.18.7 March 31, 2025 aarch64-linux-musl (3.77 MB)
1.18.7 March 31, 2025 java (9.88 MB)
1.18.7 March 31, 2025 x64-mingw-ucrt (6.02 MB)

Updated `Gemfile.lock` with platform–specific dependencies

The rule of thumb for me is adding platforms below:

bundle lock --add-platform arm64-darwin
Writing lockfile to /Users/fidel/code/Gemfile.lock
bundle lock --add-platform x86_64-darwin
Writing lockfile to /Users/fidel/code/Gemfile.lock
bundle lock --add-platform x86_64-linux
Writing lockfile to /Users/fidel/code/Gemfile.lock

bundle install

git add Gemfile.lock
git commit -m "Use precompiled gems for all the platforms"

The example above covers the most common platforms for Rails development:

Intel/AMD Linux (most servers)
Apple Silicon (M1/M2/M3/M4 and counting Macs)
Intel Macs — as not everyone is running cutting–edge hardware

Obviously, you can add any other platform that you need.

Enjoy no surprises during deployment or next Ruby upgrade.

Forget everything I’ve told you so far

If you’re running a modern Bundler, it will do the platform job for you:

➜  cat Gemfile
source "http://rubygems.org"

gem "nokogiri"

➜  bundle
Fetching gem metadata from http://rubygems.org/.......
Resolving dependencies...
Fetching nokogiri 1.18.7 (arm64-darwin)
Installing nokogiri 1.18.7 (arm64-darwin)
Bundle complete! 1 Gemfile dependency, 3 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

➜  cat Gemfile.lock
GEM
  remote: http://rubygems.org/
  specs:
    nokogiri (1.18.7-aarch64-linux-gnu)
      racc (~> 1.4)
    nokogiri (1.18.7-aarch64-linux-musl)
      racc (~> 1.4)
    nokogiri (1.18.7-arm-linux-gnu)
      racc (~> 1.4)
    nokogiri (1.18.7-arm-linux-musl)
      racc (~> 1.4)
    nokogiri (1.18.7-arm64-darwin)
      racc (~> 1.4)
    nokogiri (1.18.7-x86_64-darwin)
      racc (~> 1.4)
    nokogiri (1.18.7-x86_64-linux-gnu)
      racc (~> 1.4)
    nokogiri (1.18.7-x86_64-linux-musl)
      racc (~> 1.4)
    racc (1.8.1)

PLATFORMS
  aarch64-linux-gnu
  aarch64-linux-musl
  arm-linux-gnu
  arm-linux-musl
  arm64-darwin
  x86_64-darwin
  x86_64-linux-gnu
  x86_64-linux-musl

DEPENDENCIES
  nokogiri

BUNDLED WITH
   2.6.5

See, I didn’t even need to lock platforms manually. However, it added all the platforms this particular gem is available for. Except Windows and Java ones — coincidence? ;)

But I think that less is more and I prefer keeping Gemfile.lock as minimal as possible. And yes, there’s a command for that:

bundle lock --remove-platform x86_64-linux-musl
Writing lockfile to /Users/fidel/code/Gemfile.lock
bundle lock --remove-platform aarch64-linux-gnu
Writing lockfile to /Users/fidel/code/Gemfile.lock
bundle lock --remove-platform aarch64-linux-musl
Writing lockfile to /Users/fidel/code/Gemfile.lock
bundle lock --remove-platform arm-linux-musl
Writing lockfile to /Users/fidel/code/Gemfile.lock
bundle lock --remove-platform arm-linux-gnu
Writing lockfile to /Users/fidel/code/Gemfile.lock

➜  cat Gemfile.lock
GEM
  remote: http://rubygems.org/
  specs:
    nokogiri (1.18.7-arm64-darwin)
      racc (~> 1.4)
    nokogiri (1.18.7-x86_64-darwin)
      racc (~> 1.4)
    nokogiri (1.18.7-x86_64-linux-gnu)
      racc (~> 1.4)
    racc (1.8.1)

PLATFORMS
  arm64-darwin
  x86_64-darwin
  x86_64-linux-gnu

DEPENDENCIES
  nokogiri

BUNDLED WITH
   2.6.5

It removed PLATFORMS entries and sufficient gems specifications we aren’t planning on using.

Ok, but why should I do that? — you might ask. And here’s the answer:

you won’t be downloading obsolete gem versions on your CI or production deployment
you save your bandwidth
you make RubyGems.org happy by not pulling unnecessary stuff from their CDN

Enjoy your fast and predictable builds 🖖

Rails: when "nothing changed" is the best feature

2025-04-03T19:42:38Z

Rails: when "nothing changed" is the best feature

Recently, I had a chat with a friend of mine, who used to do Rails back in the days. For the last ~10 years he’s focused on mobile development. I was curious what are his observations and asked if he’s happy with his decision or maybe he actually misses web development.

He replied:

I miss doing backend, but I’m disgusted with web development. I’m too old to chase every new framework to do the same thing in every new ES flavor of JS... Jumping around npm, yarn, pnpm, bun or whatever is cool this quarter...

But then he followed:

Recently I had to implement a tiny backend app. I dusted off Rails and everything was the same. Same commands, same gems, even nokogiri crashed the same way during bundle install, just like 10 years ago...

For me it’s an impressive story about boring software. Boring software that’s highly regarded. I absolutely love Rails longevity.

Low learning curve for returnees

Someone who worked with Rails in 2010 can pick up a Rails application in 2025 and still recognize core patterns, conventions and commands. It all remained fundamentally similar.

Knowledge retention

The skills developers build working with Rails tend to stay relevant for years, which is rare in the fast–moving web development world.

Team flexibility

New team members who have Rails experience can become productive quickly without extensive onboarding.

Documentation stability

Solutions and patterns documented years ago often still apply, creating a rich knowledge base that remains useful.

Reduced "framework fatigue"

While Rails has evolved, it hasn’t required developers to completely relearn their workflow every quarter or two like JS ecosystem does.

This stability creates enormous practical value. It means companies can maintain Rails applications for the long term without constantly rewriting them to keep up with framework changes. It also means the pool of developers who can work on a Rails project is broader, including those who may have been away from Rails for years but can quickly get back up to speed.

From a domain modeling perspective, this stability means you can focus on evolving your business logic and domain models without constantly rebuilding the technical foundation underneath them.

I smile to myself every time I see a JS app team implementing from scratch a framework feature that is simply available in Rails. Apparently, not everyone gets a chance to work with a mature web framework.

How to add index to a big table of your Rails app

2024-06-13T11:16:29Z

How to add index to a big table of your Rails app

When your application is successful, some of the tables can grow pretty big — I’m looking at you users table. If you’re curious enough, you periodically check how your database performs. If any slow query pops up in the metrics, there’s a great chance that some index is missing.

State of the DB engines

While most modern database engines can create indexes in an asynchronous, non–blocking manner, it’s good to get familiar with all the exceptions from this rule. I highly recommend reading the documentation of PostgreSQL, MySQL. I’m not sure about SQLite here as the documentation doesn’t clearly state that. However, my quick chit–chat with LLM may give you some insights.

What’s the problem then?

As you already know CREATE INDEX statement will be handled asynchronously by the database if appropriate algorithm is used. This means that no reads, writes and update will be blocked.

Typically, for the Rails application, you’ll run a migration via Ruby process during deployment, using all the goodies from ActiveRecord::Migration class and its surroundings.

Let’s imagine the database schema like that:

ActiveRecord::Schema[7.1].define(version: 2024_06_13_121701) do
  create_table "users", force: :cascade do |t|
    t.string "email"
    t.boolean "active"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
  end
end

Imagine you want to quickly find all those users which didn’t activate the account:

User.where(active: false)

If you have enough users, speaking of dozens or hundreds of millions, doing full table scan could simply kill the database performance. Full table scan happens when database has no index to use and need to check every row whether it meets the criteria.

I will stick with PostreSQL in the examples if not stated otherwise.

Obvious solution

Let’s add the index then:

➜  trololo git:(master) bin/rails g migration AddIndexOnActiveUsers
      invoke  active_record
      create    db/migrate/20240613121751_add_index_on_active_users.rb

Implementation:

# PostgreSQL
class AddIndexOnActiveUsers < ActiveRecord::Migration[7.1]
  disable_ddl_transaction!

  def change
    add_index :users, :active, algorithm: :concurrently
  end
end

# MySQL
class AddIndexOnActiveUsers < ActiveRecord::Migration[7.1]
  def change
    add_index :users, :active, algorithm: :inplace
  end
end

Let’s run it:

➜  trololo git:(master) bin/rails db:migrate
== 20240613121751 AddIndexOnActiveUsers: migrating ============================
-- add_index(:users, :active)
   -> 0.0013s
== 20240613121751 AddIndexOnActiveUsers: migrated (0.0013s) ===================

Ok, it was quite fast, right? That’s correct for your dev machine, not necessarily for the production setup. Now magnify this time 0.0013s by 6 or 7 orders of magnitude if your table is big enough:

➜  trololo git:(master) bin/rails db:migrate
== 20240613121751 AddIndexOnActiveUsers: migrating ============================
-- add_index(:users, :active)
   -> 13000.4928s
== 20240613121751 AddIndexOnActiveUsers: migrated (0.0013s) ===================

I’ll do the maths for you: 1300.4928s means 21 minutes 40.49 seconds. But it can be even longer — don’t ask me how I found about this.

While the process of migration will end up eventually, the migration blocking any other deployments to your application during this time may be unacceptable for various reasons:

you cannot release any other change to production until migration completes
something other goes wrong and you need to rapidly deploy a hotfix, but you can’t since the deployment is blocked by long running migration™
process manager on a deployment machine may expect output within, e.g. 5 minutes. Long running migration will get killed in such scenario.

What to do then?

Simply skip the migration body for RAILS_ENV=production:

class AddIndexOnActiveUsers < ActiveRecord::Migration[7.1]
  disable_ddl_transaction!

  def change
    add_index :users, :active, algorithm: :concurrently, if_not_exists: true unless Rails.env.production?
  end
end

The migration will be executed on production environment, but will have no effect on your database. schema.rb or structure.sql (depending on what you use) will be aligned. Sufficient entry will also appear in schema_migrations table. All the developers will have index added on their local databases, test environment will be aligned too.

But Hey, where’s my index on production?! you might ask. And that’s a pretty valid question. What you’ll need is a way to run a rails runner or rake task on production. Depending on the capabilities you have, you might choose to:

Run it within bin/rails console:

# PostgreSQL
ActiveRecord::Migration.add_index :users, :active, algorithm: :concurrently, if_not_exists: true

# MySQL
ActiveRecord::Migration.add_index :users, :active, algorithm: :inplace, if_not_exists: true

Do the same via bin/rails runner:

# PostgreSQL
bin/rails r "ActiveRecord::Migration.add_index :users, :active, algorithm: :concurrently, if_not_exists: true"

#MySQL
bin/rails r "ActiveRecord::Migration.add_index :users, :active, algorithm: :inplace, if_not_exists: true"

Last, but not least, implement a Rake task. It has the advantage that it has to be committed to the repository so you don’t lose the history what’s happened:

# PostgreSQL
namespace :indexes do
  task add_index_on_active_users: :environment do
    ActiveRecord::Migration.add_index :users, :active, algorithm: :concurrently, if_not_exists: true
  end
end

# MySQL
namespace :indexes do
  task add_index_on_active_users: :environment do
    ActiveRecord::Migration.add_index :users, :active, algorithm: :inplace, if_not_exists: true
  end
end

Execute it with bin/rails indexes:add_index_on_active_users.

For the last option it’s also easy to enhance it with logging to easily identify execution in Grafana, Datadog or any other tool you use for your logs.

namespace :indexes do
  task add_index_on_active_users: :environment do
    Rails.logger.info("task indexes:add_index_on_active_users started")

    ActiveRecord::Migration.add_index :users, :active, algorithm: :concurrently, if_not_exists: true

    Rails.logger.info("task indexes:add_index_on_active_users finished”)
  end
end

Tiny details

If you’re aware enough, you probably spotted if_not_exists: true flag. We like idempotence and that’s the reason. If anyone runs this task again, nothing will happen. If you prefer to see ActiveRecord::StatementInvalid instead, feel free to skip it.

As mentioned in the preface, to use appropriate algorithm for index creation algorithm: :concurrently for PostgreSQL and algorithm: inplace for MySQL has to be specified.

There’s another quirk for PostgreSQL:

Another difference is that a regular CREATE INDEX command can be performed within a transaction block, but CREATE INDEX CONCURRENTLY cannot.

Each Rails migration execution is wrapped within transaction. To disable this behavior, you need to use disable_ddl_transaction! method within your migration. Otherwise, following error will pop up:

bin/rails aborted!
StandardError: An error has occurred, this and all later migrations canceled: (StandardError)

PG::ActiveSqlTransaction: ERROR:  CREATE INDEX CONCURRENTLY cannot run inside a transaction block
/Users/fidel/code/fidel/trololo/db/migrate/20240613121751_add_index_on_active_users.rb:5:in `change'

Caused by:
ActiveRecord::StatementInvalid: PG::ActiveSqlTransaction: ERROR:  CREATE INDEX CONCURRENTLY cannot run inside a transaction block (ActiveRecord::StatementInvalid)
/Users/fidel/code/fidel/trololo/db/migrate/20240613121751_add_index_on_active_users.rb:5:in `change'

Caused by:
PG::ActiveSqlTransaction: ERROR:  CREATE INDEX CONCURRENTLY cannot run inside a transaction block (PG::ActiveSqlTransaction)
/Users/fidel/code/fidel/trololo/db/migrate/20240613121751_add_index_on_active_users.rb:5:in `change'
Tasks: TOP => db:migrate
(See full trace by running task with --trace)

However, it’s not a problem for our custom script or Rake task run on production environment.

Replace aasm with Rails Enum today

2024-03-29T22:36:29Z

Replace aasm with Rails Enum today

There’s a great chance that your Rails app contains one of the gems providing so called state machine implementation. There’s even a greater chance that it will be aasm formerly known as acts_as_state_machine. Btw. Who remembers acts_as_hasselhoff? — ok, boomer. The aasm does quite a lot when included into your ActiveRecord model — the question is do you really need all those things?

My problem with aasm

I was struck by reckless use of this gem so many times that first thing I do after joining a new project is running cat Gemfile | grep aasm and here comes the meme which I made ~1.5 years ago:

My main concern with use of this gem is that you probably don’t need all the features it offers. More features means more temptation to use them. Greater use across the codebase means more coupling to external library which can be incompatible with upcoming Rails versions, blocking you from upgrade or making it pretty costly. You have to read yet another changelog to check if there aren’t any breaking changes or some subtle behavior change running your serious business application into problems.

Next thing is that it promotes patterns like callbacks which I personally see as a huge problem within complex rails applications. I prefer explicit code, callbacks aren’t such. Ackchyually callbacks are a part of the framework, I know, but let’s leave this discussion for another place in time.

It’s also struggle for all the IDEs, Language Server Providers to find definitions of methods defined by aasm’s DSL and you are forced to use grep, read the code carefully and decide whether those active! method comes from or where my pending scope is defined.

I’ve recently learned that it also autogenerates constants for each state so I don’t have to. I’ve recently spotted Transaction::STATUS_FAILED somewhere, it took quite some time to figure out the origin of this constant which wasn’t explicitly defined within the Transaction class.

Those free lunches can be tasty, but eventually you will be forced to pay for them.

Last, but not least, having attribute like state or status often suggest poor design in your codebase, but that’s a totally different story.

Starting point

Nine years old legacy Rails app backing very successful business. Let’s have a look at some of the details:

-> ruby -v
ruby 3.3.0 (2023-12-25 revision 5124f9ac75)

-> bin/rails r "p Rails.version"
"7.1.3.2"

-> bundle list | wc -l
319

-> rg include\ AASM -l | wc -l
33

Few uses of model.aasm.states.map(&:name)

Two uses of SwitchRequest.aasm.states_for_select to provide options for some <select> tags.

Rails, the white knight

As a Rails developer, you’re probably familiar with enum which was introduced in Rails 6.0 and allowed to declare an attribute where the values map to integers in the database. It evolved a bit with next framework versions, but Rails 7.1 finally brought all the features required to replace all of the aasm uses in the codebase I’m currently working on.

Let’s make use of this simple class as an example for our further work:

class Transaction < ApplicationRecord
  include AASM

  PROCESSING = :processing
  FAILED = :failed
  SUCCESSFUL = :successful
  CANCELED = :canceled

  aasm column: :status do
    state PROCESSING, initial: true
    state FAILED
    state SUCCESSFUL
    state CANCELED
  end
end

What’s required to get exact the same behavior

Scopes like Transaction.successful to query all the transactions having status successful — we can have those for free from ActiveRecord::Enum.
Instance methods to:
- check whether our object’s status is successful? — enum got you covered
- change the status to successful and run save! as we got used to it — same here, enum will do it’s job here if you call transaction.successful!
Set desired initial state for new objects — this can be done by providing default keyword argument to enum method, like default: PROCESSING.
Values need to be stored as strings, not as integers in the db — it’s possible since Rails 7.0
Hopefully there were no transitions or guards in state machines in our application — yet another reason to not employ aasm — but I can image implementing it with ActiveRecord::Dirty quite easy. Or even better, implement this behavior as a higher level abstracion and keep you model dummy in this matter.
No callbacks either, yay!
Constants containing all the possible states were already in place, so those defined by aasm, like STATUS_PROCESSING, STATUS_SUCCESSFUL and so on were something nobody asked for.

Validation of the provided value

There’s slight difference in default enum behavior. If the provided a value doesn’t match specified values, you will be struck with ArgumentError when trying to assign one.

As mentioned earlier, in Rails 7.1 there’s a possibility to provide validate: true keyword argument. Enum will behave exactly the same as aasm in this manner which checks the validity of provided value before save resulting in ActiveRecord::RecordInvalid instead.

Show me the code

class Transaction < ApplicationRecord
    PROCESSING = :processing
    FAILED = :failed
    SUCCESSFUL = :successful
    CANCELED = :canceled

    enum :status,
         { processing: PROCESSING,
           failed: FAILED,
           successful: SUCCESSFUL,
           canceled: CANCELED
         }.transform_values(&:to_s),
         default: PROCESSING.to_s,
         validate: true
end

That’s it. Quit clean and understandable, isn’t it?

The values quirk

There’s one quirk, you’ve probably already noticed: transform_values(&:to_s). I was quite confused what’s going on when I’ve provided symbols as values initially. Let’s see how the code looked like before:

class Transaction < ApplicationRecord
    PROCESSING = :processing
    FAILED = :failed
    SUCCESSFUL = :successful
    CANCELED = :canceled

    enum :status,
         { processing: PROCESSING,
           failed: FAILED,
           successful: SUCCESSFUL,
           canceled: CANCELED
         },
         default: PROCESSING,
         validate: true
end

The documentation hasn’t clearly stated that values should be strings. The example used String values, but there was no clear expectation about that. However, when saving the object, status became nil at some point, despite assigning ”successful” value.

I wrote a dummy app and test for this specific case aside from the main application I was working on. To be 100% sure that there’s no other factor influences this behavior:

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'

  gem 'activerecord'
  gem 'sqlite3'
  gem 'minitest'
end

require 'active_record'
require 'sqlite3'
require 'minitest/autorun'

begin
  db_name = 'enum_test.sqlite3'.freeze

  SQLite3::Database.new(db_name)
  ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: db_name)
  ActiveRecord::Schema.define do
    create_table :transactions, force: true do |t|
      t.string :status
    end
  end

  class Transaction < ActiveRecord::Base
    PROCESSING = :processing
    FAILED = :failed
    SUCCESSFUL = :successful
    CANCELED = :canceled

    enum :status,
         { processing: PROCESSING,
           failed: FAILED,
           successful: SUCCESSFUL,
           canceled: CANCELED
         },
         default: PROCESSING,
         validate: true
  end

  class TestTransaction < Minitest::Test
    def test_enum_behavior
      transaction = Transaction.new(status: :successful)
      assert_equal 'successful', transaction.status

      transaction.save!
      assert_equal 'successful', transaction.reload.status
    end
  end
ensure
  Dir.glob(db_name + '*').each { |file| File.delete(file) }
end

Result:

ruby enum.rb
-- create_table(:transactions, {:force=>true})
   -> 0.0076s
Run options: --seed 3038

# Running:

F

Finished in 0.013456s, 74.3163 runs/s, 148.6326 assertions/s.

  1) Failure:
TestTransaction#test_enum [enum.rb:44]:
Expected: "successful"
  Actual: nil

1 runs, 2 assertions, 1 failures, 0 errors, 0 skips

Ok, so the value is correctly set, but it disappears when save! is called. After quick session with debugger I was able to figure out that undesired change from "successful" to nil happens inside Enum::EnumType#deserialize method. Generic ActiveModel::Type::Value class which is a parent for the ActiveRecord::Enum::EnumType describes the purpose of deserialize method like that:

Converts a value from database input to the appropriate ruby type. The return value of this method will be returned from ActiveRecord::AttributeMethods::Read#read_attribute. The default implementation just calls Value#cast.

Let’s have a look at our specific scenario:

# value = "successful"
# mapping = ActiveSupport::HashWithIndifferentAccess.new({
#  "processing" => :processing,
#  "failed" => :failed,
#  "successful" => :successful,
#  "canceled" => :canceled,
# })
# subtype = ActiveModel::Type::String instance

def deserialize(value)
  mapping.key(subtype.deserialize(value))
end

What exactly happens:

subtype.deserialize(value) returns ”successful”
mapping is asked to return a key for ”successful” value, but there is no such in the hash, there’s a Symbol :succesful — yikes
deserialize("successful") returns nil instead of "successful"

Probably a single line in the docs like: Don’t put symbols as values when defining the enum would do the job and save my time and potentially many other confused developers. What’s even more puzzling is the fact that you can provide default value as a Symbol, you can assign a value which is a Symbol and it will be stored as a String, which is understandable, but the definition has to contain string values — hence the .transform_values(&:to_s) trick.

However, why use symbols to define possible state?, you may ask. Because it’s a requirement of aasm. State has to be Symbol or object responding to #name method. If you provide String, you’ll see nice NoMethodError because it doesn’t respond to name.

You know what’s even funnier? Database returns String when asked for Transactions#status. Serializing it to JSON will also turn it into String as JSON doesn’t implement symbols. I could imagine more scenarios when constant casting from Symbol to String back and forth happen without any particular reason. But that’s exactly how 3rd party gem (AASM) drives your architectural decisions.

We can do even better

If you aren’t using scopes, you can simply disable them with scopes: false.

Same goes for instance methods like succesful! or failed?, those can be disabled with instance_methods: false.

Most of the models that was rewritten required both, but whenever it was possible I disabled both of the features.

Occurrences of Model.aasm.states.map(&:name) are replaceable by Model.statuses.values.

Model.aasm.states_for_select helper can be replaced with Model.statuses.values.map { |name, value| [I18n.l(name), value] }. Extract this to one of your helpers. Maybe you don’t need to call I18n at all and simple humanize will be enough.

Now it’s your turn.

The most underused pattern in Ruby

2023-08-31T17:04:08Z

The most underused pattern in Ruby

Recently one of the RailsEventStore users posted an issue that one wanted to use RES on a Postgres database with PostGIS extension. Migration generator used to setup tables for events and streams was failing with UnsupportedAdapter error.

In RailsEventStore we supported to date PostgreSQL, MySQL2 and SQLite adapters representing given database engines. But if you want to make use of mentioned PostGIS extension, you need install additional activerecord-postgis-adapter and set adapter: postgis in database.yml. Our code relied on value returned by:

ActiveRecord::Base.connection.adapter_name.downcase
=> "postgis"

I thought — Ok, that's an easy fix, PostGIS is just an extension, we need to treat it like Postgres internally when generating migration. Same data types should be allowed.

Easy fix, requiring a lot of changes

This easy fix required me to change 8 files (4 with implementation and 4 with tests). Something is not ok here — I thought. So let's look through each of them:

I had to add postgis to the list of SUPPORTED_ADAPTERS in VerifyAdapter class

  module RubyEventStore
    module ActiveRecord
      UnsupportedAdapter = Class.new(StandardError)

      class VerifyAdapter
-       SUPPORTED_ADAPTERS = %w[mysql2 postgresql sqlite].freeze
+       SUPPORTED_ADAPTERS = %w[mysql2 postgresql postgis sqlite].freeze

        def call(adapter)
          raise UnsupportedAdapter, "Unsupported adapter" unless supported?(adapter)
        end

        private

        private_constant :SUPPORTED_ADAPTERS

        def supported?(adapter)
          SUPPORTED_ADAPTERS.include?(adapter.downcase)
        end
      end
    end
  end

Then I had to extend case statement in ForeignKeyOnEventIdMigrationGenerator#each_migration method

  module RubyEventStore
    module ActiveRecord
      class ForeignKeyOnEventIdMigrationGenerator
        def call(database_adapter, migration_path)
          VerifyAdapter.new.call(database_adapter)
          each_migration(database_adapter) do |migration_name|
            path = build_path(migration_path, migration_name)
            write_to_file(path, migration_code(database_adapter, migration_name))
          end
        end

        private

        def each_migration(database_adapter, &block)
          case database_adapter
-         when "postgresql"
+         when "postgresql", "postgis"
            [
              'add_foreign_key_on_event_id_to_event_store_events_in_streams',
              'validate_add_foreign_key_on_event_id_to_event_store_events_in_streams'
            ]
          else
            ['add_foreign_key_on_event_id_to_event_store_events_in_streams']
          end.each(&block)
        end

        def absolute_path(path)
          File.expand_path(path, __dir__)
        end

        def migration_code(database_adapter, migration_name)
          migration_template(template_root(database_adapter), migration_name).result_with_hash(migration_version: migration_version)
        end

        def migration_template(template_root, name)
          ERB.new(File.read(File.join(template_root, "#{name}_template.erb")))
        end

        def template_root(database_adapter)
          absolute_path("./templates/#{template_directory(database_adapter)}")
        end

        def template_directory(database_adapter)
          TemplateDirectory.for_adapter(database_adapter)
        end

        def migration_version
          ::ActiveRecord::Migration.current_version
        end

        def timestamp
          Time.now.strftime("%Y%m%d%H%M%S")
        end

        def write_to_file(path, migration_code)
          File.write(path, migration_code)
        end

        def build_path(migration_path, migration_name)
          File.join("#{migration_path}", "#{timestamp}_#{migration_name}.rb")
        end
      end
    end
  end

Same goes for Rails version of migration generator

  begin
    require "rails/generators"
  rescue LoadError
  end

  if defined?(Rails::Generators::Base)
    module RubyEventStore
      module ActiveRecord
        class RailsForeignKeyOnEventIdMigrationGenerator < Rails::Generators::Base
          class Error < Thor::Error
          end

          namespace "rails_event_store_active_record:migration_for_foreign_key_on_event_id"

          source_root File.expand_path(File.join(File.dirname(__FILE__), "../generators/templates"))

          def initialize(*args)
            super

            VerifyAdapter.new.call(adapter)
          rescue UnsupportedAdapter => e
            raise Error, e.message
          end

          def create_migration
            case adapter
-           when "postgresql"
+           when "postgresql", "postgis"
              template "#{template_directory}add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
                       "db/migrate/#{timestamp}_add_foreign_key_on_event_id_to_event_store_events_in_streams.rb"
              template "#{template_directory}validate_add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
                       "db/migrate/#{timestamp}_validate_add_foreign_key_on_event_id_to_event_store_events_in_streams.rb"
            else
              template "#{template_directory}add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
                       "db/migrate/#{timestamp}_add_foreign_key_on_event_id_to_event_store_events_in_streams.rb"
            end
          end

          private

          def adapter
            ::ActiveRecord::Base.connection.adapter_name.downcase
          end

          def migration_version
            ::ActiveRecord::Migration.current_version
          end

          def timestamp
            Time.now.strftime("%Y%m%d%H%M%S")
          end

          def template_directory
            TemplateDirectory.for_adapter(adapter)
          end
        end
      end
    end
  end

What is important, both of the migrators used VerifyAdapter class (and two other migrators too).

TemplateDirectory class also suffered from primitive obsession and it was used by all of the migrators too.

  module RubyEventStore
    module ActiveRecord
      class TemplateDirectory
        def self.for_adapter(database_adapter)
          case database_adapter.downcase
-         when "postgresql"
+         when "postgresql", "postgis"
            "postgres/"
          when "mysql2"
            "mysql/"
          end
        end
      end
    end
  end

There was also one more place — VerifyDataTypeForAdapter which was composed of VerifyAdapter, adding verification of data types available to given database engine.

Here we go again, another checks of string values, but in a more specific context:

# frozen_string_literal: true

module RubyEventStore
  module ActiveRecord
    InvalidDataTypeForAdapter = Class.new(StandardError)

    class VerifyDataTypeForAdapter
      SUPPORTED_POSTGRES_DATA_TYPES = %w[binary json jsonb].freeze
      SUPPORTED_MYSQL_DATA_TYPES = %w[binary json].freeze
      SUPPORTED_SQLITE_DATA_TYPES = %w[binary].freeze

      def call(adapter, data_type)
        VerifyAdapter.new.call(adapter)
        raise InvalidDataTypeForAdapter, "MySQL2 doesn't support #{data_type}" if is_mysql2?(adapter) && !SUPPORTED_MYSQL_DATA_TYPES.include?(data_type)
        raise InvalidDataTypeForAdapter, "sqlite doesn't support #{data_type}" if is_sqlite?(adapter) && supported_by_sqlite?(data_type)
        raise InvalidDataTypeForAdapter, "PostgreSQL doesn't support #{data_type}" unless supported_by_postgres?(data_type)
      end

      private

      private_constant :SUPPORTED_POSTGRES_DATA_TYPES, :SUPPORTED_MYSQL_DATA_TYPES, :SUPPORTED_SQLITE_DATA_TYPES

      def is_sqlite?(adapter)
        adapter.downcase.eql?("sqlite")
      end

      def is_mysql2?(adapter)
        adapter.downcase.eql?("mysql2")
      end

      def supported_by_sqlite?(data_type)
        !SUPPORTED_SQLITE_DATA_TYPES.include?(data_type)
      end

      def supported_by_postgres?(data_type)
        SUPPORTED_POSTGRES_DATA_TYPES.include?(data_type)
      end
    end
  end
end

I've noticed the pattern

at start we need to check whether given adapter is allowed (PostgreSQL, MySQL, SQLite)
we need to verify certain data types for given adapters to be aligned with database engines
then we have to made a decision to generate specific migration for given data type
migration template directory depends on adapter type

Let's do it

Having all this within a dedicated Value Object would allow reducing number of decision trees in the code, checking the same primitives on and on.

Something like:

DatabaseAdapter.from_string("postgres")
=> DatabaseAdapter::PostgreSQL.new

DatabaseAdapter.from_string("bazinga")
=> UnsupportedAdapter: "bazinga" (RubyEventStore::ActiveRecord::UnsupportedAdapter)

DatabaseAdapter.from_string("sqlite", "jsonb")
=> SQLite doesn't support "jsonb". Supported types are: binary. (RubyEventStore::ActiveRecord::InvalidDataTypeForAdapter)

After few iterations we ended up with the implementation below:

# frozen_string_literal: true

module RubyEventStore
  module ActiveRecord
    UnsupportedAdapter = Class.new(StandardError)
    InvalidDataTypeForAdapter = Class.new(StandardError)

    class DatabaseAdapter
      NONE = Object.new.freeze

      class PostgreSQL < self
        SUPPORTED_DATA_TYPES = %w[binary json jsonb].freeze

        def adapter_name
          "postgresql"
        end

        def template_directory
          "postgres/"
        end
      end

      class MySQL < self
        SUPPORTED_DATA_TYPES = %w[binary json].freeze

        def adapter_name
          "mysql2"
        end

        def template_directory
          "mysql/"
        end
      end

      class SQLite < self
        SUPPORTED_DATA_TYPES = %w[binary].freeze

        def adapter_name
          "sqlite"
        end
      end

      def initialize(adapter_name, data_type)
        raise UnsupportedAdapter if instance_of?(DatabaseAdapter)

        validate_data_type!(data_type)

        @data_type = data_type
      end

      attr_reader :data_type

      def supported_data_types
        self.class::SUPPORTED_DATA_TYPES
      end

      def eql?(other)
        other.is_a?(DatabaseAdapter) && adapter_name.eql?(other.adapter_name)
      end

      alias == eql?

      def hash
        DatabaseAdapter.hash ^ adapter_name.hash
      end

      def template_directory
      end

      def self.from_string(adapter_name, data_type = NONE)
        raise NoMethodError unless eql?(DatabaseAdapter)

        case adapter_name.to_s.downcase
        when "postgresql", "postgis"
          PostgreSQL.new(data_type)
        when "mysql2"
          MySQL.new(data_type)
        when "sqlite"
          SQLite.new(data_type)
        else
          raise UnsupportedAdapter, "Unsupported adapter: #{adapter_name.inspect}"
        end
      end

      private

      def validate_data_type!(data_type)
        if !data_type.eql?(NONE) && !supported_data_types.include?(data_type)
          raise InvalidDataTypeForAdapter,
                "#{class_name} doesn't support #{data_type.inspect}. Supported types are: #{supported_data_types.join(", ")}."
        end
      end

      def class_name
        self.class.name.split("::").last
      end
    end
  end
end

DatabaseAdadpter acts like a parent class to all the specific adapters. Specific adapters contain lists of supported_data_types to access those by client classes and render informative error messages if selected data is not supported by given database engine. They can also tell how the template_directory is named for given adapter.

We have a single entry with DatabaseAdapter.from_string which accepts adapter_name and optionally data_type which are both validated when creating an instance of specific adapter.

What's the outcome?

Three utility classes could be removed:

VerifyAdapter
VerifyDataTypeForAdapter
TemplateDirectory

Four classes and two rake tasks were simplified since the Value Object carriers all the necessary information for them to proceed:

ForeignKeyOnEventIdMigrationGenerator

  module RubyEventStore
    module ActiveRecord
      class ForeignKeyOnEventIdMigrationGenerator
-       def call(database_adapter, migration_path)
-         VerifyAdapter.new.call(database_adapter)
+       def call(database_adapter_name, migration_path)
+         database_adapter = DatabaseAdapter.from_string(database_adapter_name)
          each_migration(database_adapter) do |migration_name|
            path = build_path(migration_path, migration_name)
            write_to_file(path, migration_code(database_adapter, migration_name))


        def each_migration(database_adapter, &block)
          case database_adapter
-         when "postgresql", "postgis"
+         when DatabaseAdapter::PostgreSQL
            [
              'add_foreign_key_on_event_id_to_event_store_events_in_streams',
              'validate_add_foreign_key_on_event_id_to_event_store_events_in_streams'

RailsForeignKeyOnEventIdMigrationGenerator

        def initialize(*args)
          super

-         VerifyAdapter.new.call(adapter)
+         @database_adapter = DatabaseAdapter.from_string(adapter_name)
        rescue UnsupportedAdapter => e
          raise Error, e.message
        end

        def create_migration
-         case adapter
-         when "postgresql", "postgis"
-           template "#{template_directory}add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
+         case @database_adapter
+         when DatabaseAdapter::PostgreSQL
+           template "#{@database_adapter.template_directory}add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
                     "db/migrate/#{timestamp}_add_foreign_key_on_event_id_to_event_store_events_in_streams.rb"
-           template "#{template_directory}validate_add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
+           template "#{@database_adapter.template_directory}validate_add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
                     "db/migrate/#{timestamp}_validate_add_foreign_key_on_event_id_to_event_store_events_in_streams.rb"
          else
-           template "#{template_directory}add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
+           template "#{@database_adapter.template_directory}add_foreign_key_on_event_id_to_event_store_events_in_streams_template.erb",
                     "db/migrate/#{timestamp}_add_foreign_key_on_event_id_to_event_store_events_in_streams.rb"
          end
        end

        private

-       def adapter
-         ::ActiveRecord::Base.connection.adapter_name.downcase
+       def adapter_name
+         ::ActiveRecord::Base.connection.adapter_name
        end


-       def template_directory
-         TemplateDirectory.for_adapter(adapter)
-       end

MigrationGenerator

  module RubyEventStore
    module ActiveRecord
      class MigrationGenerator
-       DATA_TYPES = %w[binary json jsonb].freeze
- 
-       def call(data_type, database_adapter, migration_path)
-         raise ArgumentError, "Invalid value for data type. Supported for options are: #{DATA_TYPES.join(", ")}." unless DATA_TYPES.include?(data_type)
-         VerifyDataTypeForAdapter.new.call(database_adapter, data_type)
- 
-         migration_code = migration_code(data_type, database_adapter)
+       def call(database_adapter, migration_path)
+         migration_code = migration_code(database_adapter)
          path = build_path(migration_path)
          write_to_file(migration_code, path)
          path


-       def migration_code(data_type, database_adapter)
-         migration_template(template_root(database_adapter), "create_event_store_events").result_with_hash(migration_version: migration_version, data_type: data_type)
+       def migration_code(database_adapter)
+         migration_template(template_root(database_adapter), "create_event_store_events").result_with_hash(migration_version: migration_version, data_type: database_adapter.data_type)
        end

        def template_root(database_adapter)
-         absolute_path("./templates/#{template_directory(database_adapter)}")
-       end
- 
-       def template_directory(database_adapter)
-         TemplateDirectory.for_adapter(database_adapter)
+         absolute_path("./templates/#{database_adapter.template_directory}")
        end

RailsMigrationGenerator

      class Error < Thor::Error
      end

-     DATA_TYPES = %w[binary json jsonb].freeze
-
      namespace "rails_event_store_active_record:migration"

      source_root File.expand_path(File.join(File.dirname(__FILE__), "../generators/templates"))


        type: :string,
        default: "binary",
        desc:
-         "Configure the data type for `data` and `meta data` fields in Postgres migration (options: #{DATA_TYPES.join("/")})"
+         "Configure the data type for `data` and `meta data` fields in migration (options: #{DatabaseAdapter::PostgreSQL.new.supported_data_types.join(", ")})"
      )

      def initialize(*args)
        super

-       if DATA_TYPES.exclude?(data_type)
-         raise Error, "Invalid value for --data-type option. Supported for options are: #{DATA_TYPES.join(", ")}."
-       end
-
-       VerifyDataTypeForAdapter.new.call(adapter, data_type)
-     rescue InvalidDataTypeForAdapter, UnsupportedAdapter => e
+       @database_adapter = DatabaseAdapter.from_string(adapter_name, data_type)
+     rescue UnsupportedAdapter => e
+       raise Error, e.message
+     rescue InvalidDataTypeForAdapter
+       raise Error,
+             "Invalid value for --data-type option. Supported for options are: #{DatabaseAdapter.from_string(adapter_name).supported_data_types.join(", ")}."
      end

      def create_migration
-       template "#{template_directory}create_event_store_events_template.erb", "db/migrate/#{timestamp}_create_event_store_events.rb"
+       template "#{@database_adapter.template_directory}create_event_store_events_template.erb",
                 "db/migrate/#{timestamp}_create_event_store_events.rb"
      end

      private

-     def template_directory
-       TemplateDirectory.for_adapter(adapter)
-     end

      def data_type
        options.fetch("data_type")
      end

-     def adapter
-       ::ActiveRecord::Base.connection.adapter_name.downcase
+     def adapter_name
+       ::ActiveRecord::Base.connection.adapter_name
      end

db:migrations:copy and db:migrations:add_foreign_key_on_event_id

  task "db:migrations:copy" do
    data_type =
      ENV["DATA_TYPE"] || raise("Specify data type (binary, json, jsonb): rake db:migrations:copy DATA_TYPE=json")
    ::ActiveRecord::Base.establish_connection(ENV["DATABASE_URL"])
-   database_adapter = ::ActiveRecord::Base.connection.adapter_name
+   database_adapter =
+     RubyEventStore::ActiveRecord::DatabaseAdapter.from_string(::ActiveRecord::Base.connection.adapter_name, data_type)

    path =
-     RubyEventStore::ActiveRecord::MigrationGenerator.new.call(
-       data_type,
-       database_adapter,
-       ENV["MIGRATION_PATH"] || "db/migrate"
-     )
+     RubyEventStore::ActiveRecord::MigrationGenerator.new.call(database_adapter, ENV["MIGRATION_PATH"] || "db/migrate")

    puts "Migration file created #{path}"
  end
  @@ -30,7 +27,8 @@ desc "Generate migration for adding foreign key on event_store_events_in_streams
  task "db:migrations:add_foreign_key_on_event_id" do
    ::ActiveRecord::Base.establish_connection(ENV["DATABASE_URL"])

-   path = RubyEventStore::ActiveRecord::ForeignKeyOnEventIdMigrationGenerator.new.call(ENV["MIGRATION_PATH"] || "db/migrate")
+   path =
+     RubyEventStore::ActiveRecord::ForeignKeyOnEventIdMigrationGenerator.new.call(ENV["MIGRATION_PATH"] || "db/migrate")

    puts "Migration file created #{path}"
  end

We could reduce branching and remove numerous private methods in those.

The tests of above classes simplified a lot and are now focused on core responsibilities of the classes rather than checking which data types are compatible with given adapter.

New adapter, not a big deal

Soon, there will be new MySQL adapter in Rails 7.1 called Trilogy. It would be cool to cover this case already.

The only thing which we had to do in this case, was to change one line of code and add single line of test — since we already owned a good abstraction:

  module RubyEventStore
    module ActiveRecord
      class DatabaseAdapter
        def self.from_string(adapter_name, data_type = NONE)
          raise NoMethodError unless eql?(DatabaseAdapter)
          case adapter_name.to_s.downcase
          when "postgresql", "postgis"
            PostgreSQL.new(data_type)
-         when "mysql2"
+         when "mysql2", "trilogy"
            MySQL.new(data_type)
          when "sqlite"
            SQLite.new(data_type)
          else
            raise UnsupportedAdapter, "Unsupported adapter: #{adapter_name.inspect}"
          end
        end
      end
    end
  end


+ expect(DatabaseAdapter.from_string("Trilogy")).to eql(DatabaseAdapter::MySQL.new)

Trilogy is an adapter for MySQL, there's no difference from our perspective, we want to treat it as such.

Summary

If you're curious on the full process, here's the PR with the introduction of DatabaseAdapter value object. The code is 100% covered with mutation testing thanks to mutant.

I believe that Value Object is a totally underused pattern in Ruby ecosystem. That's why I wanted to provide yet another example which differs from typical Money one you usually see.

It's a great tool to reduce complexity of your code by removing unnecessary or repeatable branching.

Szymon Fiedler

The timezone bug that hid in plain sight for months

The timezone bug that hid in plain sight for months

The broken code

Why this breaks

The fix

The test that exposed it

Impact

Lessons

Stop using DateTime in 2026 (unless you work for UNESCO)

Stop using DateTime in 2026 (unless you work for UNESCO)

DateTime's range advantage died in Ruby 1.9.2

Remember Rails 4.2?

The UNESCO problem

DateTime’s actual problems

Why people still use it

What to use instead

The only exception

References

Rewrite with Confidence: Validating Business Rules Through Isolated Testing

Rewrite with Confidence: Validating Business Rules Through Isolated Testing

The Context: Insurtech at Scale

The Architecture: A Rails Monolith Under Transformation

Understanding the Problem

The God Model

The Data Complexity

Why Traditional Approaches Failed

What About Other Approaches?

The Solution: Testing on Production

The Brave New Flow

Implementing the Sampling Mechanism

What We Sampled

Recording HTTP Interactions

The Verification Process

Leaving No Trace

After Commit Handling

HTTP Stubbing Strategy

Handling Edge Cases

The Complete Verification Flow

Comparing Results

The Results

Key Takeaways

Prefer watching?

The Joy of a Single-Purpose Class: From String Mutation to Message Composition

The Joy of a Single-Purpose Class: From String Mutation to Message Composition

Ruby has both mutable and immutable strings

Problem with string literal mutation in our code

Noticing the pattern

Improve the code

Benefits of ActiveSupport

Pass a single string or multiple as an argument

Append our message using different methods

Default delimiter, but still customizable

Compose various Slack::Message object with different delimiters

Final refactoring

Summary

Stop concatenating URLs with strings — Use proper tools instead

Stop concatenating URLs with strings — Use proper tools instead

Problems with Naive URL Concatenation

1. Double or missing slashes

2. Improper parameter escaping

3. Protocol and port issues

Solutions

1. Ruby’s URI

More advanced URI example

2. Pathname for local paths

3. Addresable gem

4. Rails URL helpers

5. Test URL building

Summary

Installing Precompiled Native Gems with bundle lock --add-platform

Installing Precompiled Native Gems with bundle lock --add-platform

My problem with native gems

It’s not a new problem

Bundler, the hero we need

What are the PLATFORMS?

Prerequisites

Modern tooling

Precompiled gem versions available for your platform

Updated Gemfile.lock with platform–specific dependencies

`DateTime`’s actual problems

Compose various `Slack::Message` object with different delimiters

Updated `Gemfile.lock` with platform–specific dependencies