DEV Community: Yashika Vijayvargiya

Rate Limiting in Rails 8.1: Protect Your APIs Without Rack::Attack

Yashika Vijayvargiya — Mon, 02 Nov 2026 10:41:02 +0000

Have you ever wondered what happens when someone sends hundreds of requests to your login endpoint within a few seconds?

Without rate limiting, your application could face unnecessary database queries, excessive server load, brute-force login attempts, or API abuse.

Rate limiting helps control how frequently a client can access an endpoint within a specified time window.

The good news is that Rails provides a built-in rate_limit method, so you don't always need an additional gem to implement basic rate limiting.

Rails 8.1 also introduces a useful improvement: the scope: option, which allows multiple controllers to share the same rate-limit counter.

Let’s understand how it works with practical examples.

1. What Is Rate Limiting?

Rate limiting is a technique used to restrict the number of requests a client can make within a specific period.

For example:

Allow 5 login attempts within 3 minutes.
Allow 100 API requests per minute.
Allow 10 password reset requests within 15 minutes.

When a client exceeds the configured limit, the application rejects additional requests.

Usually, the server responds with:

HTTP 429 Too Many Requests

This helps protect application resources and reduces abuse.

2. Rails Built-in Rate Limiting

Rails provides the rate_limit class method in Action Controller.

You can configure it directly inside a controller without installing an additional gem.

Let’s consider a login endpoint.

# app/controllers/sessions_controller.rb

class SessionsController < ApplicationController
  rate_limit to: 5, within: 3.minutes, only: :create

  def create
    # Login authentication logic
  end
end

Let’s understand the configuration:

Option

Meaning

to: 5

Maximum 5 requests

within: 3.minutes

Within a 3-minute window

only: :create

Apply the limit only to the create action

By default, Rails identifies requests using the client’s IP address.

When the limit is exceeded, Rails raises ActionController::TooManyRequests, which Action Dispatch handles by returning HTTP 429.

3. Customize the Rate Limit Response

The default response might not be sufficient for an API application.

You can customize the response using the with: option.

class SessionsController < ApplicationController
  rate_limit to: 5,
             within: 3.minutes,
             only: :create,
             with: -> {
               render json: {
                 error: "Too many login attempts. Please try again later."
               }, status: :too_many_requests
             }

  def create
    # Login authentication logic
  end
end

Now, when a client exceeds the configured limit, the API returns a JSON error response.

Example:

{
  "error": "Too many login attempts. Please try again later."
}

With HTTP status:

429 Too Many Requests

This is particularly useful when building APIs consumed by React, mobile applications, or other external clients.

4. Rate Limit Based on User Instead of IP

By default, Rails applies rate limiting based on the request IP address.

But what if you want to apply limits per authenticated user?

You can customize the identifier using the by: option.

class Api::BaseController < ApplicationController
  rate_limit to: 100,
             within: 1.minute,
             by: -> { current_user&.id || request.remote_ip }
end

Here:

Authenticated users are identified by their user ID.
Unauthenticated requests are identified by their IP address.
Each identifier gets its own rate-limit counter.

This is useful when you want to provide individual API limits to authenticated users.

Important: If your application runs behind a proxy or load balancer, configure trusted proxy handling correctly. Otherwise, IP-based limits may not identify clients as expected.

5. What’s New in Rails 8.1? The scope: Option

This is one of the most useful improvements to the built-in rate-limiting functionality.

Before Rails 8.1, rate-limit counters were scoped to individual controller paths by default.

Consider an API application with two controllers:

Api::PostsController
Api::UsersController

Suppose both controllers have the following configuration:

rate_limit to: 100, within: 1.minute

By default, these controllers maintain separate counters.

This means a client could make:

100 requests to the posts endpoint.
100 requests to the users endpoint.

That’s 200 requests in total.

What if you want both controllers to share one common limit?

Rails 8.1 introduces the scope: option for this purpose.

Example: Shared rate limit across controllers

Create a common API controller:

# app/controllers/api_controller.rb

class ApiController < ApplicationController
  rate_limit to: 100,
             within: 1.minute,
             scope: "public_api"
end

Now inherit from it:

class Api::PostsController < ApiController
  def index
    render json: Post.all
  end
end

class Api::UsersController < ApiController
  def index
    render json: User.all
  end
end

Both controllers share the same rate-limit scope.

If a client makes 60 requests to the posts endpoint, only 40 requests remain for the users endpoint during the same rate-limit window.

The shared counter uses the same scope and client identifier.

Why is this useful?

Imagine an application exposing 20 public API endpoints. Instead of allowing 100 requests per endpoint, you can enforce a common limit across the entire API.

This gives you better control over overall API usage.

6. Multiple Rate Limits on the Same Controller

Sometimes one rate limit isn’t enough.

For example, you might want:

A short-term limit of 3 requests every 2 seconds.
A longer-term limit of 10 requests every 5 minutes.

Rails supports multiple rate limits on the same controller.

Use the name: option to distinguish them.

class SessionsController < ApplicationController
  rate_limit to: 3,
             within: 2.seconds,
             name: "short_term"
  rate_limit to: 10,
             within: 5.minutes,
             name: "long_term"
  def create
    # Login logic
  end
end

Each limit maintains its own counter.

This is useful when you want to prevent both sudden bursts of traffic and repeated requests over a longer period.

7. Where Does Rails Store Rate-Limit Counters?

An important question is: How does Rails remember how many requests a client has already made?

Rails uses an ActiveSupport::Cache store to maintain rate-limit counters.

By default, it uses the controller cache store, which falls back to the application’s configured cache store.

For a production application running on multiple servers, using a shared Redis cache can be useful.

Example:

class ApiController < ApplicationController
  RATE_LIMIT_STORE = ActiveSupport::Cache::RedisCacheStore.new(
    url: ENV["REDIS_URL"]
  )
  rate_limit to: 100,
             within: 1.minute,
             store: RATE_LIMIT_STORE
end

Now the rate-limit counters are stored in Redis.

Why does this matter?

Imagine your application runs on three application servers:

             Load Balancer
                   |
          -------------------
          | | |
        Server 1 Server 2 Server 3

If each server maintains its own independent counters, a client might bypass the intended limit by sending requests to different servers.

Using a shared Redis cache allows all three servers to access the same counters.

Make sure Redis is configured with appropriate availability, memory, and eviction settings for your production workload.

8. Rails Rate Limiting vs Rack::Attack

Before Rails introduced built-in rate limiting, developers commonly used gems such as Rack::Attack.

Does Rails’ built-in functionality mean you no longer need Rack::Attack?

Not necessarily.

For straightforward controller-level rate limiting, Rails’ built-in functionality is often sufficient.

If you need advanced request filtering, blocklists, safelists, or more complex throttling rules, Rack::Attack is still worth considering.

9. When Should You Use Rails Built-in Rate Limiting?

Here are some practical use cases:

Login endpoints

Prevent repeated login attempts that could indicate brute-force activity.

Password reset endpoints

Avoid excessive password reset requests.

Public APIs

Control how frequently clients can access your API.

Registration endpoints

Reduce automated account creation attempts.

Expensive operations

Protect endpoints that perform costly database queries or external API calls.

Remember that rate limiting is only one layer of application protection. You should also implement authentication, authorization, input validation, monitoring, and appropriate infrastructure-level protections.

Conclusion

Rails makes basic rate limiting easier by providing the rate_limit method directly in Action Controller.

With Rails 8.1, the new scope: option makes it possible to share rate-limit counters across multiple controllers.

The key takeaways:

Use rate_limit to restrict requests within a time window.
Use by: to customize client identification.
Use with: to customize the response.
Use scope: to share limits across controllers.
Use store: to configure a shared cache such as Redis.
Use name: when defining multiple limits on one controller.

You don’t always need an additional gem to protect your Rails endpoints from excessive requests.

Sometimes, the framework already provides the functionality you need.

Have you used Rails’ built-in rate limiting, or do you prefer Rack::Attack? Share your experience in the comments!

References

Rails 8.1: Using only_columns to Control Which Database Columns Active Record Uses

Yashika Vijayvargiya — Mon, 02 Nov 2026 09:08:17 +0000

When working with legacy databases or large Rails applications, a model may have more database columns than the application actually needs.

Some columns might belong to an older feature, a third-party integration, or a database structure shared by multiple applications.

Traditionally, Rails developers could use ignored_columns to tell Active Record which columns to ignore. With Rails 8.1, only_columns provides the opposite approach: explicitly list the columns a model should use.

Let’s understand how it works, how to test it in the Rails console, and when it can be useful.

1. What Is only_columns in Rails 8.1?

ActiveRecord::Base.only_columns allows you to specify the database columns that a model should recognize and use.

Instead of listing the columns you want to ignore, you list the columns you want Active Record to use.

Consider a users table with these columns:

id
name
email
phone
address
legacy_reference
external_customer_id
created_at
updated_at

Suppose your application only needs:

id
name
email
created_at
updated_at

You can explicitly define that list in your model.

2. How to Use only_columns

Let’s use a User model as an example.

app/models/user.rb

class User < ApplicationRecord
  self.only_columns = %w[
    id
    name
    email
    created_at
    updated_at
  ]
end

Now, Active Record uses the configured column list when defining model attributes and constructing SQL queries.

The database schema itself remains unchanged. The phone, address, legacy_reference, and external_customer_id columns still exist in the database.

The difference is that this model is configured to work with an explicitly defined subset of those columns.

3. Test It in the Rails Console

One of the easiest ways to understand this feature is to inspect the model directly.

Start the Rails console:

bin/rails console

Check the configured columns:

User.only_columns

Expected output:

["id", "name", "email", "created_at", "updated_at"]

You can also inspect the model’s recognized column names:

User.column_names

The result reflects the columns Active Record recognizes for this model, subject to the configured column list.

To inspect the attributes of a new record:

user = User.new

user.attributes.keys

The attribute list should reflect the configured columns rather than every column in the database table.

This is useful when debugging a model in the Rails console: you can check which columns the model is configured to use without changing the underlying database schema.

4. Why Is This Useful?

A. Working with legacy databases

Imagine you’re maintaining an application that has been running for several years.

Its database contains columns left behind by older features:

users
-----
id
name
email
old_subscription_id
legacy_status
deprecated_reference
created_at
updated_at

Your current application only needs the user’s basic information.

With only_columns, you can explicitly declare the columns that the model should use.

This makes the intended model schema easier to understand and can reduce accidental dependencies on legacy columns.

B. Working with shared database schemas

Some applications share a database with another service or application.

For example, your Rails application might use a customers table that also contains columns maintained by an external integration.

You may not want your application model to depend on every column in that shared table.

An explicit column list helps document the subset that your application expects to use.

Remember, this does not prevent other applications or direct SQL queries from accessing the remaining database columns.

C. Making schema changes safer

Database changes often require careful coordination between deployments.

Suppose you’re planning to remove an obsolete column.

Rather than immediately removing the column from the database, you can first update the application so its model no longer depends on it.

A possible rollout is:

Identify the columns the application actually needs.
Configure only_columns to list those columns.
Deploy the application and verify that it no longer depends on the obsolete column.
Check other applications, background jobs, reports, and database queries for dependencies.
Remove the obsolete column in a subsequent deployment when it is safe to do so.

This approach can make a schema migration easier to coordinate, especially when multiple application versions or services share a database.

However, only_columns does not automatically make a migration safe. You still need to verify that no other code depends on the column.

5. How Is only_columns Different from ignored_columns?

Rails already provides ignored_columns, so why introduce another option?

The difference is how you express your intention.

Using ignored_columns

class User < ApplicationRecord
  self.ignored_columns = %w[
    legacy_reference
    deprecated_reference
  ]
end

This tells Active Record to ignore the listed columns.

It’s convenient when most columns remain relevant and only a few need to be excluded.

Using only_columns

class User < ApplicationRecord
  self.only_columns = %w[
    id
    name
    email
    created_at
    updated_at
  ]
end

This explicitly lists the columns the model should use.

It’s convenient when you want to define a known subset rather than maintain a list of columns to exclude.

Feature

ignored_columns

only_columns

Approach

List columns to ignore

List columns to use

Best suited for

Excluding a small number of columns

Explicitly defining the model’s column set

Database schema

Unchanged

Can be combined with the other option?

No; use one approach per model

Choose the approach that best communicates your application’s intent.

6. Is only_columns a Security Feature?

No. This distinction is important.

Although only_columns restricts the columns Active Record uses for a model, it should not be treated as a security or authorization mechanism.

For example, suppose your users table contains:

id
name
email
admin
password_digest

Configuring a model to use only id, name, and email does not replace proper authorization, access control, or protection of sensitive information.

You should still implement appropriate authorization policies, validate permitted input, and protect sensitive attributes.

Use only_columns to control the model's expected database columns, not to enforce who can access data.

7. Things to Keep in Mind

Before adopting only_columns, consider the following:

Associations: Verify that the columns needed for association loading and joins are included.
Primary keys: Include the primary key or all required composite primary key columns.
Timestamps: Include created_at and updated_at if the model relies on them.
Background jobs and callbacks: Check whether callbacks or other application code depend on excluded attributes.
Schema changes: Confirm that other applications and queries no longer depend on a column before removing it from the database.
Rails version: Use a patched Rails release. Rails 8.1.4 includes a fix ensuring that only_columns is respected when constructing the SELECT clause. Earlier Rails 8.1 versions may not handle this correctly in all queries.

Also, test the behavior with your actual model and associations before applying it to production.

Conclusion

Rails 8.1’s only_columns provides an explicit way to tell Active Record which database columns a model should use.

It can be useful when working with legacy tables, shared schemas, and staged database changes.

The main takeaway is simple:

ignored_columns tells Rails what to leave out. only_columns tells Rails what to work with.

If you maintain Rails applications with evolving database schemas, this is a feature worth understanding and testing.

For more details, see the Rails 8.1 Release Notes and the Active Record ModelSchema API.

When to Choose Optimistic vs. Pessimistic Locking in Ruby on Rails

Yashika Vijayvargiya — Thu, 22 Oct 2026 12:35:59 +0000

Not every concurrent database update needs the same locking strategy.

Imagine two users trying to book the last available seat on a flight. Both see that the seat is available and click “Book” almost simultaneously. Without proper concurrency control, both requests might attempt to reserve the same seat.

Ruby on Rails provides two common locking strategies to handle these situations: optimistic locking and pessimistic locking.

But the important question isn’t just how they work. It’s when should you choose one over the other?

Let’s explore the differences through practical Rails examples.

1. When Should You Choose Optimistic Locking?

Choose optimistic locking when conflicts are relatively rare and you want to detect conflicting updates without locking a database record in advance.

Rails supports optimistic locking using a lock_version column.

Real-world example: Editing a product

Imagine two administrators editing the same product in an e-commerce application.

Admin A opens the product and sees its price as ₹500.
Admin B opens the same product and sees its price as ₹500.
Admin A changes the price to ₹550 and saves.
Admin B changes the price to ₹600 and attempts to save.

Without concurrency control, Admin B could overwrite Admin A’s update without realizing it.

With optimistic locking, Rails detects that the record has changed since Admin B loaded it and raises ActiveRecord::StaleObjectError.

Implementation in Rails

First, add a lock_version column:

class AddLockVersionToProducts < ActiveRecord::Migration[7.2]
  def change
    add_column :products, :lock_version,
               :integer, default: 0, null: false
  end
end

Rails automatically uses this column for optimistic locking.

product_a = Product.find(1)
product_b = Product.find(1)

product_a.update!(price: 550)
product_b.update!(price: 600)
# Raises ActiveRecord::StaleObjectError

The second update fails because the record’s version has changed.

Choose optimistic locking when:

Multiple users may edit the same record, but simultaneous updates are uncommon.
Users spend time editing forms before saving.
You want to detect stale updates instead of blocking other transactions.
Your application can ask users to reload or resolve conflicting changes.

Typical use cases: Product descriptions, user profiles, document editing, and administrative settings.

2. When Should You Choose Pessimistic Locking?

Choose pessimistic locking when concurrent operations are likely and conflicting updates must be serialized.

Instead of allowing multiple transactions to modify the same record and detecting conflicts afterward, pessimistic locking acquires a database lock before performing the critical operation.

Rails provides pessimistic locking through methods such as with_lock and lock.

Real-world example: Booking the last available seat

Imagine a flight has only one seat remaining. Two customers try to book it at nearly the same time.

The application must ensure that only one customer can successfully reserve that seat.

FlightSeat.transaction do
  seat = FlightSeat.lock.find(seat_id)
raise "Seat already booked" if seat.booked?
  seat.update!(booked: true)
end

The lock method issues a locking read, typically using SELECT ... FOR UPDATE on PostgreSQL. If another transaction already holds a conflicting row lock, the second transaction waits until that lock is released.

Once the first transaction commits, the second transaction can proceed and check the latest committed state. It then sees that the seat is booked and cannot reserve it again.

The lock is released when the transaction ends.

Choose pessimistic locking when:

Concurrent updates to the same record are likely.
An operation involves limited resources, such as seats, inventory, or account balances.
Conflicting operations must be serialized to maintain consistency.
Retrying failed operations would be expensive or difficult.

Typical use cases: Inventory deductions, seat reservations, financial balance updates, and processing shared resources.

3. Can You Use Both Locking Strategies in One Application?

Yes. Different operations can require different strategies.

For example, in an e-commerce application:

Editing product descriptions: Optimistic locking, because concurrent edits are relatively uncommon.
Reducing stock during checkout: Pessimistic locking when you need to serialize updates to a specific inventory row.
Updating account settings: Optimistic locking, especially when users edit forms over a longer period.
Allocating a limited resource: Pessimistic locking when competing transactions must check and claim the same resource safely.

Choose the strategy based on the operation’s concurrency characteristics and business requirements, rather than applying one locking strategy to every model.

4. What Should You Consider Before Choosing?

Before implementing either strategy, ask yourself these questions:

How frequently can conflicts occur? If simultaneous updates are rare, optimistic locking may be sufficient.
What happens if an update fails? If a user can safely reload and retry, optimistic locking is often appropriate.
Must the operation be serialized? If competing transactions must check and claim a resource in sequence, pessimistic locking may be a better fit.
How long will the transaction run? Keep pessimistic locking transactions short. Never hold a database lock while waiting for user input or making slow external HTTP calls.
What other safeguards are needed? Database constraints, atomic updates, and appropriate isolation levels can be essential regardless of the locking strategy.

Conclusion

The choice between optimistic and pessimistic locking depends on how your application handles concurrency.

Use optimistic locking when conflicts are uncommon and you can detect and resolve stale updates. Use pessimistic locking when concurrent operations must be serialized to protect shared resources.

The goal isn’t to lock everything. It’s to select the simplest concurrency-control strategy that preserves your application’s data integrity without unnecessarily reducing performance.

[Boost]

Yashika Vijayvargiya — Thu, 15 Oct 2026 08:59:36 +0000

Yashika Vijayvargiya

Sep 24

Your Rails Transaction Rolled Back. What Happened to the API Call, Email, or Job?

#database #opensource #rails #programming

7 min read

Git Merge vs Rebase: What Actually Happens to Your Commit History?

Yashika Vijayvargiya — Tue, 29 Sep 2026 07:03:15 +0000

If you’ve worked with Git for a while, you’ve probably seen commands like:

git merge main

and:

git rebase main

Both commands can be used to bring changes from one branch into another.

So a common question is:

If both merge and rebase bring my branch up to date, what’s actually the difference?

The short answer is:

Merge combines histories. Rebase rewrites your branch’s history by replaying your commits on top of another branch.

But that sentence alone isn’t enough to really understand the difference.

Let’s start from the beginning.

First, understand what a Git branch really is

Before comparing merge and rebase, let’s understand one important thing.

A Git branch is basically a movable pointer to a commit.

Suppose we have:

A → B → C
        ↑
       main

main currently points to commit C.

Now we create a feature branch:

A → B → C
        ↑
       main
        ↑
      feature

Both branches initially point to the same commit.

Now you make a change on the feature branch:

A → B → C → D
        ↑    ↑
       main feature

feature has moved forward, while main has stayed at C.

This is the basic idea behind Git branching.

Now let’s create a real situation

Imagine you’re working on a Rails application.

You create a branch:

git switch -c feature/login

At that moment:

A → B → C
        ↑
       main
        ↑
   feature/login

You make two commits:

A → B → C → D → E
        ↑   ↑
       main feature/login

Maybe:

D = Add login form
E = Add authentication logic

Meanwhile, another developer adds a change to main:

A → B → C → F
        ↑ ↑
       main

Now your repository looks like this:

More clearly:

              D → E feature/login
             /
A → B → C
             \
              F main

This is called diverged history.

Your feature branch and main have moved in different directions.

Now you need to bring main's changes into your feature branch.

That’s where merge and rebase come in.

Option 1: Git Merge

You are on your feature branch:

git switch feature/login

Then:

git merge main

Git takes the histories from both branches and creates a new merge commit when a true merge is required.

The history becomes:

              D → E
             /      \
A → B → C           M
             \     /
                F

M is the merge commit.

The important thing is:

Git keeps both histories as they actually happened.

Your feature work happened on one branch.

The main work happened on another branch.

The merge commit records that those two lines were brought together.

Git’s documentation describes merge as joining development histories and, for a true merge, creating a commit with both branch tips as parents.

What does the merge commit mean?

This is important for beginners.

Suppose you see:

A → B → C → F
        \
         D → E
              \
               M

You might wonder:

“What code is inside M?”

The merge commit represents the combined result of both branches.

Conceptually:

main changes
     +
feature changes
     ↓
combined result

The merge commit has two parents:

        M
       / \
      E   F

That is one of the important differences between merge and rebase.

Fast-forward merge

There is another situation beginners should know about.

Suppose main hasn't changed since you created your feature branch:

A → B → C
        ↑
       main
        \
         D → E
              ↑
           feature

If you run:

git switch main
git merge feature

Git doesn’t need to create a merge commit.

It can simply move main forward:

A → B → C → D → E
                ↑
             main
             feature

This is called a fast-forward merge.

There is no divergent history to combine.

Git simply moves the branch pointer forward. Git’s merge documentation distinguishes this from a true merge commit.

Option 2: Git Rebase

Now let’s go back to our original situation.

We have:

You are on:

feature/login

Instead of merging main, you can run:

git rebase main

This sounds complicated, but the basic idea is surprisingly simple.

Rebase takes your feature commits and replays them on top of the latest ** main.**

Git’s official documentation describes rebase as taking the changes introduced by commits on one branch and replaying them on another base.

So originally:

After:

git rebase main

Git effectively does this:

A → B → C → F → D' → E'

Now:

A → B → C → F → D' → E'
                  ↑ ↑
              new D new E

Your feature commits have been replayed on top of the latest main.

Wait… why are D and E now D’ and E’?

This is one of the most important concepts in understanding rebase.

You originally had:

D
E

After rebase, Git creates new commits based on the same changes:

D'
E'

They may contain the same code changes, but they are different Git commits.

Why?

Because a Git commit is not identified only by its code changes.

Its identity also depends on its parent and other metadata.

Before rebase:

C → D → E

After rebase:

C → F → D' → E'

Since D' has a different parent than D, its commit identity changes.

This is why rebase rewrites history.

The easiest way to remember it

Think of merge as:

“Let’s combine these two roads.”

And rebase as:

“Let’s move my road so it starts from the latest point on the other road.”

Merge

        D → E
      /      \
A → B → C     M
     \       /
       F ──

Rebase

Before:

        D → E
      /
A → B → C → F

After:

A → B → C → F → D' → E'

A real-world analogy

Imagine you’re writing a book.

You started writing Chapter 5 based on version 1 of the book.

Meanwhile, another writer updated Chapters 1–4.

You now have two choices.

Merge

You say:

“Let’s keep both versions of history and combine the work.”

The final history shows that two people worked in parallel and their work was combined later.

Rebase

You say:

“Let’s take my Chapter 5 changes and apply them to the newest version of Chapters 1–4.”

Now the history looks as though your Chapter 5 work happened after the latest version.

That’s essentially what rebase does to commits.

Merge vs Rebase at a glance

MergeRebaseCombines branchesYesYesCreates merge commitUsually, when histories divergeNo, not for the rebased commitsKeeps original branch historyYesNoRewrites commitsNoYesProduces linear historyNot necessarilyUsuallySafer for shared/published historyGenerallyRequires cautionUseful for cleaning local historyLess soYes

The biggest difference is history.

Does rebase change the final code?

This is another common beginner question.

Suppose both operations are performed correctly and conflicts are resolved consistently.

The final project files can be the same.

For example:

Merge result:

A → B → C → F → M


Rebase result:

A → B → C → F → D' → E'

The commit history is different, but the final snapshot can represent the same combined code.

Git’s documentation explicitly notes that the final snapshot can be the same while the history differs.

So the major difference isn’t:

“Which one gives me the correct code?”

It is:

“How do I want the project’s history to look?”

Why do developers like rebase?

One major reason is cleaner history.

Imagine your project has:

main
 ├── feature A
 ├── feature B
 ├── feature C
 └── feature D

If everyone frequently merges main into their feature branches, history can become filled with commits like:

Merge branch 'main' into feature/login
Merge branch 'main' into feature/login
Merge branch 'main' into feature/login

The history becomes harder to read.

With rebase, a developer can update their local feature branch:

git fetch origin
git rebase origin/main

and keep their own commits on top of the latest main.

The result can look much more linear:

A → B → C → D → E → F → G

rather than:

A → B → C ─────────────── M
         \              /
          D → E → F → G

Git’s documentation specifically notes that rebasing can produce a cleaner, linear history.

But if rebase is cleaner, why not always use it?

Because rebase rewrites history.

This is where beginners can get into trouble.

Imagine you’ve already pushed:

A → B → C → D

to GitHub.

Another developer has based their work on commit D.

Now you rebase your branch.

Git may create:

A → B → C → D'

D' is a new commit.

From Git’s perspective:

D ≠ D'

You have rewritten the branch’s history.

If you force-push that rewritten history, the other developer may have to deal with the changed commit ancestry.

That’s why rebasing shared/published branches requires caution. Git’s documentation recommends avoiding rebasing commits that have already been published unless you understand the consequences.

A simple rule for beginners

Remember this:

Rebase your private/local work. Be careful rebasing shared work.

For example:

feature/login

is your personal branch.

You can generally rebase it while you’re developing.

But:

main

is shared by the whole team.

Rewriting main history is usually a very different situation.

What happens when there is a conflict?

Both merge and rebase can have conflicts.

Suppose you changed:

def welcome_message
  "Welcome!"
end

and another branch changed the same lines:

def welcome_message
  "Welcome back!"
end

Git may not know which version you want.

You’ll see a conflict.

With merge:

git merge main

you resolve the conflict and then:

git add .
git commit

or use:

git merge --continue

depending on the merge state/workflow.

With rebase:

git rebase main

you resolve the conflict and then:

git add .
git rebase --continue

If you decide that you don’t want to continue the rebase:

git rebase --abort

Git provides --abort specifically to stop a rebase and attempt to restore the state from before the rebase.

Why can rebase feel harder during conflicts?

Because rebase processes your commits one at a time.

Imagine your feature has:

D → E → F

During rebase, Git essentially replays:

D'
E'
F'

If D conflicts, Git stops.

You resolve it.

Then:

git rebase --continue

Git moves to the next commit.

If E also conflicts, you resolve that one too.

So you may encounter multiple conflict resolutions during one rebase.

This happens because rebase replays the commits individually.

What happens during a merge conflict?

Merge generally considers the two branch tips and their common ancestor to combine the changes.

For example:

Git compares the relevant histories and attempts to produce one combined result.

If Git can’t automatically determine the correct result, it stops and asks you to resolve the conflict.

Git’s normal merge strategy is a three-way merge using the two branch tips and their merge base.

Rebase is not “better merge”

This is an important point.

You will sometimes hear:

“Always rebase. Merge is bad.”

That’s an oversimplification.

Merge and rebase solve related problems but have different effects on history.

Git’s own documentation doesn’t say that one is universally better. The appropriate choice depends on the project and team workflow.

A team may deliberately prefer merge commits because they want to preserve the history of how branches were integrated.

Another team may prefer a linear history because it makes the project easier to navigate.

Neither approach is universally correct.

Example: working on a feature in a team

Suppose you’re working on:

feature/payment

Meanwhile, main has received new changes.

You want the latest main changes before opening/updating your PR.

You can do:

git fetch origin
git rebase origin/main

Your history becomes:

main:
A → B → C → D

feature:
            E → F

After:

git rebase origin/main

you get:

A → B → C → D → E' → F'

Your feature commits now sit on top of the latest main.

What if you use merge instead?

You could instead do:

git fetch origin
git merge origin/main

The history could become:

          E → F
         / \
A → B → C → D → M

The branch contains the same combined work, but the history records the merge explicitly.

What does git pull --rebase mean?

You may also have seen:

git pull --rebase

This is another source of confusion.

Normally:

git pull

essentially does:

git fetch
+
integration

Depending on your configuration/options, that integration can use merge or rebase. Git documents git pull --rebase as fetching and then rebasing the local work onto the fetched branch.

So:

git pull --rebase

roughly means:

Get latest remote changes
        ↓
Put my local commits on top of them

For example:

Before:

remote: A → B → C
local:           \
                 D → E

After:

A → B → C → D' → E'

git pull vs git pull --rebase

This is a useful distinction:

Regular pull

Depending on configuration:

git pull

can integrate remote changes using merge.

You might get:

A → B → C ───── M
         \     /
          D → E

Pull with rebase

git pull --rebase

gives you:

A → B → C → D' → E'

Again, the goal is usually to avoid unnecessary merge commits in your local branch history.

What should a fresher use?

For someone new to Git, I recommend first becoming comfortable with merge.

Understand:

git switch
git fetch
git merge
git pull
git push

Once you understand branches and commits, learn rebase.

Why?

Because merge is conceptually closer to:

“These two branches have changes. Combine them.”

Rebase requires understanding:

“Take these existing commits and recreate them on a different base.”

Once that mental model clicks, rebase becomes much easier.

A simple decision guide

Use merge when:

You want to preserve the actual branching history.
The branch is shared by multiple developers.
You don’t want to rewrite existing history.
Your team prefers merge commits.
You are integrating a completed branch into another branch.

Example:

git switch main
git merge feature/login

Use rebase when:

You’re updating your own feature branch.
You want a cleaner linear history.
Your commits haven’t been shared yet.
Your team follows a rebase-based workflow.
You want to replay your work on top of the latest main.

Example:

git switch feature/login
git fetch origin
git rebase origin/main

One important warning about force push

After rebasing a branch that has already been pushed, you may need:

git push --force-with-lease

Notice that I used:

--force-with-lease

rather than:

--force

--force-with-lease provides an additional safety check so you don't blindly overwrite a remote branch that has moved unexpectedly.

But even with --force-with-lease, you should understand that you're rewriting the remote branch's history.

Don’t casually rebase and force-push a branch that other developers are actively using.

The easiest mental model

If you remember only one thing from this article, remember this:

Merge

Keep both histories and connect them.

      D → E
     /     \
A → B       M
     \     /
      F → G

Rebase

Take my commits and replay them on top of the latest base.

Before:

      D → E
     /
A → B → C → F

After:

A → B → C → F → D' → E'

Final comparison

Imagine you and another developer start from the same point:

A → B

You create:

C → D

They create:

E → F

With merge

Git says:

“You both worked from B. I’ll combine the two histories.”

        C → D
      /      \
A → B         M
      \       /
       E →  F

With rebase

Git says:

“I’ll take your C and D changes and replay them after E and F.”

A → B → E → F → C' → D'

That’s the core difference.

Conclusion

git merge and git rebase aren't simply two commands that do the same thing.

They represent two different approaches to history.

Merge preserves the branching story.

Rebase rewrites your branch so your commits appear on top of another branch.

If you’re working on your own feature branch, rebasing onto the latest main can give you a clean, linear history.

If you’re working with shared history where preserving existing commits and branch relationships matters, merging can be the safer choice.

The most important thing isn’t memorizing:

git merge

versus:

git rebase

It’s understanding what Git is doing to your commit graph.

Once you understand the graph, the commands become much easier to remember.

Quick cheat sheet

# Merge
git switch feature/login
git merge main

# Rebase
git switch feature/login
git rebase main

# Update remote information first
git fetch origin

# Rebase your feature onto remote main
git rebase origin/main

# Continue after resolving a rebase conflict
git add .
git rebase --continue

# Cancel an ongoing rebase
git rebase --abort

# Push rewritten history safely
git push --force-with-lease

Remember:

MERGE → combine histories

REBASE → replay commits on a new base

Your Rails Transaction Rolled Back. What Happened to the API Call, Email, or Job?

Yashika Vijayvargiya — Tue, 22 Sep 2026 10:00:38 +0000

A database transaction gives us a powerful guarantee:

Either the database changes succeed together, or they are rolled back.

But there is an important boundary that is easy to overlook.

A database transaction can roll back database changes. It cannot automatically roll back an HTTP request that has already reached another service, an email that has already been sent, or a background job that has already been enqueued.

Consider this:

User.transaction do
 user = User.create!(name: "Yashika") 
 WelcomeJob.perform_later(user.id) 

 raise ActiveRecord::Rollback 
end

The User record is rolled back.

But depending on when the job was enqueued, the background job may already exist in the queue.

Now the job can execute with an ID for a record that no longer exists.

The same class of problem can happen with external HTTP APIs and email delivery.

This is the problem I wanted to make easier to detect in Rails applications, so I built TransactionGuard.

The problem: database transactions don’t cover external side effects

A typical Rails transaction might look perfectly reasonable:

User.transaction do
 user = User.create! 
 SomeExternalApi.create_user(user) 
 WelcomeMailer.welcome(user).deliver_now
end

At first glance, everything looks like one atomic operation.

But it isn’t.

There are actually multiple systems involved:

┌──────────────────────┐

│ Rails Application │

└──────────┬───────────┘

│

ActiveRecord

transaction

│

┌────────────┴────────────┐

│ │

▼ ▼

Database changes External side effects

│

┌─────────────┼─────────────┐

│ │ │

▼ ▼ ▼

HTTP Email Job

The database can participate in the transaction.

The external systems generally cannot.

So if the transaction fails:

Database

↓

ROLLBACK

HTTP request

↓

Already sent

Email

↓

Already sent

Background job

↓

May already be queued

That’s where subtle production bugs can appear.

Imagine an application that creates a customer and then synchronizes that customer with an external CRM.

Customer.transaction do
 customer = Customer.create!(name: "Acme")
 CRMClient.create_customer(customer) 
 raise ActiveRecord::Rollback 
end

After the rollback:

Database: Customer does not exist
CRM: Customer may already exist

Now the application and the external service disagree.

This can become even harder to debug when the external operation is hidden inside a service object, callback, mailer, or job.

Why background jobs can be particularly tricky

Consider:

Order.transaction do
 order = Order.create! 
 OrderConfirmationJob.perform_later(order.id)
 raise ActiveRecord::Rollback 
end

The database transaction rolls back the order.

But the job enqueue is a separate operation.

The job may later execute:

OrderConfirmationJob.perform(order.id)

and discover that the order doesn’t exist.

TransactionGuard’s README demonstrates this exact class of problem: the database record can be rolled back while the job has already been enqueued.

The problem isn’t that background jobs are bad.

The problem is when they are triggered.

What about emails?

The same problem exists with email delivery.

For example:

User.transaction do 
 user = User.create! 
 UserMailer.welcome(user).deliver_now
 raise ActiveRecord::Rollback
end

The database operation can roll back after the email has already been delivered.

You can end up with:

Database:
User creation rolled back

Email:
Welcome email already delivered

This can create confusing user experiences and difficult-to-reproduce bugs.

TransactionGuard detects both deliver_now and deliver_later when they occur inside an ActiveRecord transaction.

So I built TransactionGuard

TransactionGuard is a Ruby/Rails gem that detects external side effects performed while an ActiveRecord transaction is open.

The current version detects:

HTTP requests through Net::HTTP
Email delivery through Action Mailer
ActiveJob enqueueing
ActiveJob immediate execution

The goal isn’t to automatically fix the code.

The goal is to make the problem visible during development and testing.

Repository:

https://github.com/yashika279/transaction_guard

How TransactionGuard works

The basic question is surprisingly simple:

TransactionGuard::Transaction.open?

If an ActiveRecord transaction is currently open, TransactionGuard can identify it and let the relevant detector report the external operation.

Conceptually:

External operation
       │
       ▼
Is TransactionGuard enabled?
       │
       ▼
Is an ActiveRecord transaction open?
       │
       ├── No → Continue normally
       │
       └── Yes
             │
             ▼
       Report the operation
             │
             ▼
       warn / raise

This keeps the responsibility focused:

TransactionGuard detects the potentially unsafe operation.

It doesn’t silently change your application’s behavior.

Detecting HTTP requests

One of the first detectors I implemented was for Net::HTTP.

For example:

User.transaction do
  Net::HTTP.get(URI("https://example.com"))
end

TransactionGuard detects the request because it occurs while the transaction is open.

The HTTP detector wraps common methods such as:GET POST PUT PATCH DELETE HEAD OPTIONS

GET
POST
PUT
PATCH
DELETE
HEAD
OPTIONS

Internally, the detector checks whether a transaction is open before reporting the operation.

There is also protection against reporting the same underlying request multiple times when one HTTP method eventually delegates to another internal method.

That matters because instrumentation should provide useful signals without producing a wall of duplicate warnings.

Detecting email delivery

The email detector covers:

UserMailer.welcome(user).deliver_now

and:

UserMailer.welcome(user).deliver_later

inside a transaction.

An important detail here is avoiding duplicate reporting.

deliver_later internally involves ActiveJob, but from the application's perspective the operation is an email delivery.

TransactionGuard therefore reports it as an email side effect instead of producing an additional warning for the internal ActiveJob enqueue.

Detecting ActiveJob operations

TransactionGuard also hooks into ActiveJob operations.

For example:

WelcomeJob.perform_later(user.id)

inside a transaction is reported as a job enqueue operation.

It also detects:

WelcomeJob.perform_now

as a job execution operation.

The current 0.1.0 implementation specifically targets ActiveJob APIs; direct Sidekiq, Resque, and similar non-ActiveJob APIs are outside the current detector scope.

Three modes: warn, raise, and off

I wanted the gem to be useful in different development workflows.

TransactionGuard currently supports three modes:

:warn :raise :off

The default mode is:

Warn mode

TransactionGuard.configure do |config|
  config.mode = :warn
end

The application continues running, but TransactionGuard reports the detected side effect.

This is useful when introducing the gem into an existing application because you can discover problematic code without immediately breaking development or tests.

Raise mode

For stricter enforcement:

TransactionGuard.configure do |config|
  config.mode = :raise
end

Now an unsafe external side effect causes TransactionGuard to raise an error.

This can be useful in tests when you want a transaction-side-effect violation to fail fast.

Off mode

Detection can also be disabled:

TransactionGuard.configure do |config|
  config.mode = :off
end

The Rails integration currently defaults to :warn in development and test, and :off in production.

Installation

Add the gem to your Gemfile:

gem "transaction_guard"

Then:

bundle install

For local development, you can also point Rails to a local checkout:

gem "transaction_guard", path: "../transaction_guard"

The project is open source and available under the MIT license.

What does the warning look like?

Suppose we have:

User.transaction do
  user = User.create!

  WelcomeJob.perform_later(user.id)
end

TransactionGuard can report that a job enqueue happened while an ActiveRecord transaction was open.

The important information is the operation and the caller location.

That makes the warning actionable:

Transaction detected external side effect:
Job enqueue

Caller:
app/services/users/create.rb:...

Instead of discovering the problem later through a production incident, you can catch it while developing or testing.

How should we fix these problems?

TransactionGuard intentionally doesn’t automatically move operations outside the transaction.

That’s an application design decision.

A common approach is to perform the external operation after the database transaction succeeds.

For example:

user = User.create!

User.transaction do
  user.update!(status: "active")
end

WelcomeJob.perform_later(user.id)

Rails also provides mechanisms such as after_commit, which can be appropriate when an operation should happen only after a successful database commit.

For more complex distributed workflows, patterns such as:

transactional outbox
reliable event publishing
post-commit job triggering

can be considered.

The important idea is:

Database transaction
        │
        ▼
Commit succeeds
        │
        ▼
External side effect

rather than:

Database transaction
        │
        ├── Database change
        │
        └── External side effect
                │
                ▼
          Transaction rolls back

TransactionGuard doesn’t decide which pattern your application should use. It tells you where the potentially unsafe boundary exists.

Why not just use after_commit everywhere?

after_commit is useful, but it isn't a universal solution.

Applications often have:

service objects
callbacks
mailers
background jobs
API clients
third-party integrations
shared libraries

An external operation can be introduced far away from the transaction that eventually rolls back.

The purpose of TransactionGuard is therefore not to replace Rails transaction patterns.

It provides a development-time safety net that helps identify these boundaries.

Current limitations

TransactionGuard is intentionally small in its first version.

The current 0.1.0 implementation focuses on:

Net::HTTP
Action Mailer
ActiveJob

Direct clients such as:

Faraday
HTTParty
httpx

are not directly hooked in the current version, although clients built on top of Net::HTTP may be detected. Similarly, direct Sidekiq and Resque APIs are not currently detected.

These are areas that can evolve as the project grows.

Testing the gem

The project uses RSpec for its test suite and RuboCop for code quality.

Run the tests with:

bundle exec rspec

Run RuboCop with:

bundle exec rubocop

The repository also includes integration coverage around the detectors.

What I learned building it

The interesting part of this project wasn’t just writing three detectors.

It was thinking about where the boundary of a database transaction actually ends.

In Rails, this code:

User.transaction do # ... end

can look like an atomic business operation.

But if that block interacts with systems outside the database, the operation is no longer truly atomic.

That distinction becomes especially important in applications that integrate with:

payment providers
CRMs
messaging platforms
email providers
analytics systems
background job queues
external APIs

A rollback can undo your database state.

It cannot necessarily undo what another system has already observed.

The bigger lesson

A transaction is not the same thing as a distributed transaction.

This:

User.transaction do
  user = User.create!
  ExternalAPI.create_user(user)
end

contains two different worlds:

        Database
           │
       transaction
           │
        rollback
           │
           X

       External API
           │
       request sent
           │
       cannot magically
       be rolled back

Once you recognize that boundary, you can make a deliberate architectural decision about what should happen before commit, after commit, or through a more reliable event-driven workflow.

That’s the problem TransactionGuard is designed to make visible.

Try TransactionGuard

If you’re working on a Rails application with external integrations, you can try the gem here:

GitHub: https://github.com/yashika279/transaction_guard

I’d especially like feedback on:

additional external side effects worth detecting
integrations with other HTTP clients
background job adapters
false positives
better reporting
Rails version compatibility

If you’ve ever had a transaction roll back while an email, API call, or background job had already escaped the transaction, this is exactly the kind of problem TransactionGuard is trying to catch earlier.

Originally published at https://railswithyashika.hashnode.dev on September 22, 2026.

Your AI Assistant Forgot You: Understanding Memory, Sessions, and OmniMemory

Yashika Vijayvargiya — Wed, 16 Sep 2026 11:00:34 +0000

OmniMemory Explained: Giving AI Coding Agents Persistent, Git-Aware Memory

Note: AI coding tools are evolving extremely quickly. OmniMemory is an actively developed open-source project, so commands, supported integrations, architecture, and behavior may change over time. This article is intended to create awareness and explain the ideas behind OmniMemory. Before installing or using it in a real project, always check the latest OmniMemory repository and documentation.

Introduction

AI coding assistants have become an important part of modern software development.

Tools such as Claude Code, Cursor, OpenCode, Windsurf, and other AI-powered development environments can understand your repository, modify files, run commands, write tests, and help you debug complicated problems.

But there is one problem that almost every AI coding workflow eventually runs into:

The AI forgets.

You may spend two hours explaining your architecture to an AI agent.

You might explain:

why a particular service exists
why a database query is written in a strange way
why a certain method must not be changed
why a particular workaround was introduced
how two services communicate
why a particular branch is implementing a specific approach

Then the session ends.

Later, you start another session and the AI doesn’t necessarily remember those decisions.

You explain everything again.

And sometimes, instead of asking, the AI simply guesses.

This is the problem OmniMemory is designed to address.

OmniMemory describes itself as a memory and context layer for coding agents that is persistent, branch-aware, Git-anchored, and local.

But what does that actually mean?

Let’s break it down.

The Problem: AI Coding Agents Have Short-Term Context

Before understanding OmniMemory, let’s understand the problem it is trying to solve.

Imagine you are working on a Rails application.

Your project contains:

app/
├── models/
├── services/
├── controllers/
├── jobs/
└── policies/

You ask your AI coding agent:

“Why are we using this service instead of calling Stripe directly from the controller?”

You explain:

“We originally had the Stripe call inside the controller, but webhook retries caused duplicate records. We moved it into this service because the service handles idempotency.”

The AI now understands the reason.

You continue working.

You make several changes.

Then the session ends.

The next day you start another conversation:

“Update the Stripe integration.”

The AI may inspect the code, but the reason behind the architecture might not be obvious from the code itself.

This is an important distinction:

Code tells you WHAT.

Documentation may tell you HOW.

Memory can tell you WHY.

That “why” is often the most valuable information.

Why Markdown Files Are Not Always Enough

A common solution is to create a file such as:

MEMORY.md

and manually write:

# Project Notes

- Stripe calls must go through PaymentService.
- Never call Stripe directly from controllers.
- Orders use pessimistic locking.
- Redis is used for distributed locks.

This works.

But it creates another problem.

The AI has to receive the entire document or search through it.

If the file becomes large, injecting everything into every prompt can increase context size and token usage.

You might end up with:

Prompt
  ↓
Entire MEMORY.md
  ↓
AI
  ↓
Actual question

That’s not ideal.

OmniMemory takes a different approach.

Instead of simply pushing all memory into every prompt, it maintains a local memory store and retrieves relevant information based on the current task. The project describes this as context-aware retrieval using a BM25F ranker, code-graph proximity, and citation feedback.

What Is OmniMemory?

At a high level:

OmniMemory is a persistent memory layer for AI coding agents.

It is designed to remember things such as:

decisions
facts
request/data flows
implementation gotchas
project-specific knowledge
architectural reasoning

The memory is not simply a collection of notes.

The project anchors memories to the codebase and Git history.

That gives the memory additional context about whether the information is still relevant.

The Four Important Ideas Behind OmniMemory

There are four concepts that are particularly important to understand.

1. Persistent Memory

The memory survives across AI sessions.

Instead of:

Session 1
   ↓
AI learns architecture
   ↓
Session ends
   ↓
Memory disappears

you can have:

Session 1
   ↓
AI learns architecture
   ↓
Memory stored
   ↓
Session 2
   ↓
Relevant memory retrieved

This is the fundamental idea behind the project.

2. Branch-Aware Memory

This is one of the more interesting parts of OmniMemory.

Software projects are rarely developed on only one branch.

You might have:

main
 ├── feature/payment-refactor
 ├── feature/search
 └── bugfix/checkout

Each branch may introduce different decisions.

For example:

main
  |
  +--- feature/payment-refactor
  | |
  | +--- PaymentService changed
  |
  +--- feature/search
          |
          +--- Elasticsearch introduced

A memory created while working on feature/search may not make sense when working on feature/payment-refactor.

OmniMemory therefore scopes memory around Git branches and tracks branch information. The repository describes merged branch memories as rolling into the base branch.

This is significantly more useful than treating the entire repository as one flat memory store.

3. Git-Anchored Memory

This is another major concept.

Imagine the AI remembers:

“The checkout calculation happens in CheckoutService."

But six months later you completely rewrite the checkout architecture.

If the AI blindly trusts the old memory, it can give you incorrect information.

That’s dangerous.

OmniMemory attempts to connect memory to the code it describes and check whether the relevant code has changed.

Its current implementation uses a code graph and Git information to perform symbol-level staleness checks. When tree-sitter isn’t available, it can fall back to file-level checking.

Conceptually:

Memory
  |
  +--- Code symbol
          |
          +--- Git history

If the relevant symbol changes, the memory can be identified as potentially stale.

This is much more useful than simply storing:

created_at: 2026-08-01

because time alone doesn’t tell you whether the information is still correct.

4. Local-First Architecture

OmniMemory is designed to operate locally.

The repository describes its core as using Python’s standard library and SQLite, with no API key required for the core functionality.

The architecture is essentially:

Your Repository
      |
      ↓
OmniMemory
      |
      ├── SQLite
      ├── Git information
      ├── Code graph
      └── Memory

The repository also describes the system as local-first, with no cloud memory store required for its core operation.

This can be particularly attractive for developers working with private repositories.

How OmniMemory Works

The repository summarizes its architecture as:

CAPTURE
   ↓
STORE
   ↓
RANK + INJECT + ENFORCE
   ↓
CHECK
   ↓
VISUALIZE

Let’s understand each stage.

Step 1: Capture

OmniMemory captures information from coding sessions.

The project describes deterministic harness events such as:

UserPromptSubmit
        ↓
     Inject
        ↓
   AI session
        ↓
   SessionEnd
        ↓
     Capture

This is important because memory capture isn’t supposed to depend entirely on the AI remembering to save something.

Step 2: Store

The captured information is stored locally.

The repository uses SQLite for its core storage.

Conceptually:

AI Session
    |
    ↓
Memory
    |
    ↓
SQLite

Each memory can contain contextual information about the project and branch.

Step 3: Retrieve Relevant Memory

This is where the system becomes more interesting.

Suppose you ask:

“Why does this service use Redis?”

You don’t want every memory in your project.

You want memories related to:

Redis
Service
Current file
Current symbols
Architecture

OmniMemory uses a BM25F-based ranking system with weighting across symbols, files, and prose. It also considers code-graph proximity and whether the agent has previously cited a memory.

So conceptually:

Your question
      |
      ↓
Memory search
      |
      ├── keyword relevance
      ├── symbol relevance
      ├── file relevance
      ├── code proximity
      └── previous citations
      |
      ↓
Relevant memories

The goal is to provide the AI with the useful memory , rather than everything the system knows.

BM25F Instead of Embeddings

This is worth highlighting.

Many modern AI retrieval systems immediately use vector embeddings.

OmniMemory’s README instead describes its retrieval system around BM25F and explicitly notes that it doesn’t require embeddings or an API key for this retrieval.

BM25 is a traditional information-retrieval technique based largely on lexical relevance.

The simplified idea is:

Query:
"Redis locking checkout"

        ↓

Search memories

        ↓

Rank memories containing relevant
terms and fields

        ↓

Return the most relevant memories

This can be particularly useful for developer knowledge because code contains many exact identifiers:

CheckoutService
RedisLock
PaymentService
Order

Exact symbol and file matching can be highly valuable.

Step 4: Inject Memory Into the AI Context

Once relevant memory is found, OmniMemory can inject it into the AI’s context.

The project describes a VERIFIED PROJECT MEMORY block and an enforcement mechanism where the agent is expected to cite memory it uses or acknowledge when information isn't available in memory.

The conceptual flow becomes:

Developer question
       ↓
OmniMemory searches
       ↓
Relevant memory
       ↓
AI receives memory
       ↓
AI answers

Why “Enforced Memory” Matters

Imagine the AI doesn’t know why a piece of code exists.

A dangerous AI behavior is:

“I think this was added because…”

That is a guess.

OmniMemory’s approach attempts to distinguish between remembered information and information that isn’t available in its memory.

This encourages a safer behavior:

Known from memory
        ↓
Cite it

Not known
        ↓
Say it isn't in memory

The repository specifically describes this as making the agent cite the memory it used or admit that something isn’t in memory rather than inventing it.

That distinction is extremely important for AI-assisted software development.

Step 5: Check Whether Memory Is Stale

Imagine we have:

Memory:

"PaymentService handles Stripe payment creation."

Then we refactor the application.

Now:

PaymentProcessor

handles the payment instead.

The old memory should no longer be trusted.

OmniMemory’s check command can compare memory anchors against the current Git/code graph state and flag stale memories.

The project describes this at the symbol level when the code graph is available.

That’s more precise than simply saying:

“The file changed, therefore the memory is invalid.”

Step 6: Clean Up Bad Memory

Memory can become dangerous if everything is stored forever.

Imagine your AI remembers:

"We use Redis for checkout locking."

Then you remove Redis completely.

If that memory remains forever, future AI sessions may receive incorrect information.

OmniMemory includes memory hygiene mechanisms intended to quarantine abandoned-branch and long-stale/uncited memories, while keeping hard deletion human-gated.

This creates an important lifecycle:

Memory created
      ↓
Memory used
      ↓
Memory verified
      ↓
Code changes
      ↓
Memory becomes stale
      ↓
Memory quarantined

The Code Graph

OmniMemory also builds a code graph.

The repository currently describes tree-sitter support for Python, JavaScript, and TypeScript, with a standard-library ast fallback for Python.

A simplified graph could look like:

OrderController
       |
       ↓
OrderService
       |
       ↓
PaymentService
       |
       ↓
StripeClient

Now imagine a memory is attached to:

PaymentService

If you’re currently editing:

OrderService

the graph can help determine that the PaymentService-related memory is nearby in the code relationship.

This provides another signal for memory retrieval.

The Local Dashboard

OmniMemory also provides a local UI.

The repository says omni-memory ui can be used to browse:

memory
documentation
knowledge graph
repository graph
branch graph

So instead of treating memory as a black box, you can inspect what the system has stored.

That’s useful because developers should be able to answer:

“What does my AI actually remember about this project?”

Installation

The repository currently recommends installing the CLI through pip:

pip install omni-memory-agent

For Claude Code, the project also provides a plugin installation approach. The current README shows:

/plugin marketplace add SinghAbhinav04/Omni-Memory
/plugin install omni-memory@singhabhinav

Because these commands may change as the project develops, always check the repository before following installation instructions from this article.

The Most Important Commands

After installation, the project currently distinguishes between two commands that are easy to confuse:

omni-memory build

and:

omni-memory bind

They are not the same.

build

build creates the memory and documentation from your repository.

The project describes it as capturing decisions, flows, and gotchas, building the code graph, and generating files such as:

MEMORY.md
api-map.md
linkup.md

bind

bind connects OmniMemory to your development environment.

It installs session hooks and writes the cross-IDE AGENTS.md.

It does not create the initial memory itself.

Recommended Initial Workflow

The repository currently suggests this general sequence:

pip install omni-memory-agent

omni-memory build

omni-memory bind

omni-memory ui

omni-memory doctor

The roles are:

build
 ↓
Create memory + docs

bind
 ↓
Connect memory to IDE

ui
 ↓
Inspect memory and graphs

doctor
 ↓
Check setup

The UI

Memory Graph

Does build Require an AI Model?

There is an important nuance here.

The project says build can use an agent/LLM to analyze the repository.

You can run it inside an AI IDE, or configure a model key.

The repository currently lists model-key support for Gemini, Anthropic, and OpenAI. Without an AI/model path, it can still build the code graph and heuristic documentation, but it won’t generate AI-written facts.

So:

OmniMemory core
      |
      ├── Local memory
      ├── SQLite
      ├── Git
      └── Code graph

Optional AI analysis
      |
      ├── Gemini
      ├── Anthropic
      └── OpenAI

This distinction is important.

OmniMemory itself isn’t the language model.

Useful Commands

The current CLI includes commands for several different workflows.

Memory

omni-memory recall "payment retry logic"

Searches memory.

omni-memory remember "PaymentService must be idempotent"

Adds a memory manually.

omni-memory forget <id>

Removes or manages a memory entry.

Branches

omni-memory branches

Allows you to inspect Git topology and branch-specific memory.

Keeping Memory Fresh

omni-memory map

Rebuilds the knowledge/code graph.

omni-memory check

Checks memory anchors against the codebase.

omni-memory gc --dry-run

Previews memory cleanup.

The current project also provides a usage command for inspecting the memory footprint per prompt.

What About Token Usage?

This is an interesting question for developers using paid AI models.

If you inject an enormous MEMORY.md into every prompt:

Prompt
+
50,000 tokens of project memory
+
Your actual question

you are potentially wasting context.

OmniMemory instead tries to retrieve only relevant memory.

Conceptually:

10,000 memories

        ↓

Relevant retrieval

        ↓

5 useful memories

        ↓

AI prompt

The project’s retrieval and usage tooling are designed around keeping the relevant memory footprint under control.

However, this should not be interpreted as a guaranteed percentage reduction in your AI bill.

Actual token consumption depends on:

the AI model
the coding agent
prompt size
repository size
retrieved memory
task complexity

OmniMemory vs a Simple MEMORY.md

Let’s compare the two approaches.

The important point isn’t that Markdown is bad.

Markdown is excellent for:

human documentation
project conventions
onboarding
architecture notes

OmniMemory is trying to solve a different problem:

machine-oriented persistent context for AI coding agents.

OmniMemory vs RAG

At a high level, OmniMemory may remind you of Retrieval-Augmented Generation (RAG).

Traditional RAG looks something like:

Documents
   ↓
Chunking
   ↓
Embeddings
   ↓
Vector database
   ↓
Similarity search
   ↓
LLM

OmniMemory takes a different approach for coding environments.

It emphasizes:

Memory
+
Git
+
Code symbols
+
Branch information
+
Lexical ranking
+
Code graph
+
Agent citations

The goal is not simply:

“Find text that looks similar.”

It is closer to:

“Find project knowledge that is relevant to what I’m currently changing.”

That distinction matters for software repositories.

A Real-World Rails Example

Imagine a Rails application with:

Order
Payment
Refund
Stripe
Sidekiq
Redis

You have an architectural rule:

Payment processing must be idempotent.

But the reason isn’t obvious from the code.

The reason is:

Stripe webhook
      ↓
Retry
      ↓
Same payment event
      ↓
Potential duplicate payment

So the team introduced an idempotency mechanism.

Six months later, another developer asks an AI:

“Can I remove this Redis lock?”

Without project memory, the AI might see the lock as unnecessary complexity.

With relevant project memory, the agent can retrieve:

Payment processing requires idempotency
because Stripe webhook retries can produce
duplicate processing.

Now the AI has architectural context.

This is where persistent project memory becomes useful.

Another Example: Open-Source Contributions

This is especially interesting for open-source projects.

Imagine you contribute to a large Rails repository.

During your first contribution, you learn:

Do not modify this service directly.
The event data is generated from YAML.
Run validate:all before submitting a PR.

A normal AI conversation might forget these details later.

Persistent project memory can help preserve this project-specific knowledge across sessions.

For developers contributing to large open-source repositories, this can be extremely useful.

Who Should Consider Using OmniMemory?

OmniMemory is particularly interesting if you:

Work on large repositories

Large repositories have more architectural context.

Work with AI coding agents every day

The more you rely on AI, the more useful persistent context can become.

Frequently switch branches

Branch-aware memory can prevent unrelated context from bleeding across branches.

Maintain long-running projects

Long-lived projects accumulate decisions and historical knowledge.

Work on open source

Project-specific conventions can take significant time to learn.

Frequently start new AI sessions

Persistent memory can reduce the need to repeatedly explain the same project context.

Who Probably Doesn’t Need It?

You probably don’t need a sophisticated memory layer for:

hello_world.py

or:

one-off script

or:

small coding exercise

If your project is tiny and the AI can understand everything from the repository in seconds, additional memory infrastructure may provide little benefit.

Potential Concerns

No tool should be adopted simply because it sounds interesting.

There are some things developers should consider.

1. Memory Can Be Wrong

Persistent memory is only useful if it remains accurate.

That’s why Git anchoring and stale-memory detection are important.

But you should still review what the system remembers.

2. AI-Generated Memory Needs Review

If an AI creates a memory about your architecture, that memory can itself be wrong.

A persistent wrong answer can be worse than no memory.

Always treat AI-generated project knowledge as something to verify.

3. The Project Is Actively Evolving

The repository is under active development.

Its current README lists several capabilities as implemented and others as roadmap items.

Therefore, don’t treat this article as a frozen specification.

The official repository is the source of truth for current behavior.

The Bigger Idea: AI Needs Long-Term Project Context

The interesting thing about OmniMemory isn’t just the CLI.

The bigger idea is:

AI coding agents need a memory system that understands software projects, not just text.

A software project contains relationships:

File
 ↓
Class
 ↓
Method
 ↓
Database
 ↓
Service
 ↓
External API

It also contains history:

Commit
 ↓
Refactor
 ↓
Decision
 ↓
New architecture

And it contains branches:

main
 ↓
feature
 ↓
experiments
 ↓
merge

A useful coding memory system needs to understand these relationships.

That is what makes OmniMemory interesting.

OmniMemory’s Architecture in One Diagram

At a high level, you can think about it like this:

┌───────────────────┐
                         │ Developer │
                         └─────────┬─────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │ AI Coding Agent │
                         └─────────┬─────────┘
                                   │
                         ┌─────────▼─────────┐
                         │ OmniMemory │
                         └─────────┬─────────┘
                                   │
             ┌─────────────────────┼─────────────────────┐
             │ │ │
             ▼ ▼ ▼
        ┌─────────┐ ┌──────────┐ ┌──────────┐
        │ SQLite │ │ Git │ │Code Graph│
        └─────────┘ └──────────┘ └──────────┘
             │ │ │
             └─────────────────────┼─────────────────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │ Relevant Memory │
                         └─────────┬─────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │ AI Context │
                         └───────────────────┘

This is the key concept to remember.

If you ran these today:

pip install omni-memory-agent

omni-memory build omni-memory bind omni-memory ui omni-memory doctor

then you should not need to run all of them again when your AI session ends or you open a new VS Code window.

You should normally just open your project and start using your AI assistant.

The important part is that you ran:

omni-memory bind

That is the step that connects the generated memory/context to your development environment.

When should you run omni-memory build again?

This is the one you’ll potentially use regularly.

For example, today you have:

Project ├── Rails app ├── locking implementation ├── tests └── architecture

You work for a few days and add significant new things:

Project ├── Rails app ├── locking implementation ├── tests ├── new payment system ├── new background-job architecture └── new API integration

Then run:

omni-memory build

to update the memory/documentation/code graph based on the newer state of your repository.

So think of it as:

Initial setup ↓ pip install ↓ omni-memory build ↓ omni-memory bind ↓ Use your AI normally ↓ New session ↓ Use AI normally ↓ Major project changes? ↓ omni-memory build One thing I'd recommend

After you’ve closed/reopened VS Code, run:

omni-memory doctor

once just to verify that everything is still connected.

If it says the setup is healthy, you don’t need to rebuild or bind again.

Also, omni-memory ui is not what makes the AI remember things; it’s primarily for browsing/inspecting the generated memory, docs, and code graph.

If you want, I can also explain exactly what Omni-Memory is storing, where that memory lives, and how your AI actually gets that memory when you start a new chat/session.

Final Thoughts

AI coding assistants are becoming increasingly capable.

But intelligence isn’t the only problem.

Context is the problem.

An AI can be extremely capable and still make a bad decision if it doesn’t know why your project was designed the way it was.

OmniMemory approaches this problem by combining:

persistent memory
Git provenance
branch awareness
code relationships
relevance ranking
stale-memory detection
memory hygiene
local storage
AI-agent integration

The most interesting part is that it doesn’t simply try to give the AI more context.

It tries to give the AI the right context at the right time.

That is a much more interesting problem.

And as AI coding agents become a larger part of everyday software development, persistent project memory could become an important part of the developer tooling ecosystem.

If you use Claude Code, Cursor, OpenCode, Windsurf, or another AI coding workflow, OmniMemory is worth understanding — even if you don’t immediately adopt it.

The project is actively evolving, so check the official repository for the latest installation instructions, supported integrations, commands, and roadmap before using it in your workflow.

Repository: https://github.com/SinghAbhinav04/Omni-Memory

Pessimistic Locking in Rails — Preventing Race Conditions in Production

Yashika Vijayvargiya — Wed, 16 Sep 2026 10:48:06 +0000

Introduction

In the previous article, we learned why databases need locking and how PostgreSQL uses MVCC (Multi-Version Concurrency Control) to allow multiple transactions to work simultaneously.

However, MVCC alone cannot prevent every concurrency issue.

Imagine an e-commerce application where there is only one product left in stock.

Two customers click “Buy Now” at almost the same time.

Without proper locking, both requests may purchase the same product.

This is where Pessimistic Locking becomes essential.

In this article, we’ll understand how pessimistic locking works in PostgreSQL and how Rails makes it easy to use in production applications.

What is Pessimistic Locking?

Definition

Pessimistic locking is a strategy where a transaction locks a row before modifying it , preventing other transactions from changing that row until the lock is released.

In simple words:

“I’m assuming someone else might modify this row, so I’m locking it first.”

Unlike optimistic locking, pessimistic locking assumes conflicts are likely and prevents them before they happen.

Why Do We Need Pessimistic Locking?

Consider a banking application.

Current balance:

$100

Two requests arrive simultaneously.

Transaction A:

account.balance -= 80
account.save!

Transaction B:

account.balance -= 50
account.save!

Without locking:

Balance = $100

↓

Transaction A reads $100

↓

Transaction B reads $100

↓

A saves $20

↓

B saves $50

↓

Final Balance = $50 ❌

Expected:

$100 - $80 - $50 = -$30

Actual:

$50

This is called a Lost Update.

How PostgreSQL Solves This

PostgreSQL provides

SELECT ... FOR UPDATE;

When a transaction executes:

SELECT *
FROM accounts
WHERE id = 1
FOR UPDATE;

that row becomes locked.

Any other transaction trying to update the same row must wait until the first transaction commits or rolls back.

Rails Pessimistic Locking

Rails exposes PostgreSQL row locking through several APIs.

1. lock

Example:

Account.transaction do
  account = Account.lock.find(params[:id])

  account.balance -= 80

  account.save!
end

Generated SQL:

BEGIN;

SELECT *
FROM accounts
WHERE id = 1
FOR UPDATE;

UPDATE accounts
SET balance = 20
WHERE id = 1;

COMMIT;

Notice:

FOR UPDATE

This is the important part.

Timeline

Without locking

Transaction A Transaction B

Read balance=100

                      Read balance=100

Update balance=20

                      Update balance=50

Final = 50 ❌

With locking

Transaction A Transaction B

Lock row

Read balance=100

Update balance=20

Commit

                      Wait...

                      Lock acquired

                      Read balance=20

                      Update balance=-30

Commit
Final = -30 ✅

2. lock!

If you already have the record:

account = Account.find(1)

account.lock!

account.balance -= 50

account.save!

Instead of querying again, Rails locks the existing record.

3. with_lock

This is the cleanest API.

account = Account.find(1)

account.with_lock do
  account.balance -= 50

  account.save!
end

Rails automatically:

starts a transaction
locks the row
executes the block
commits
releases the lock

Equivalent SQL:

BEGIN;

SELECT *
FROM accounts
WHERE id = 1
FOR UPDATE;

UPDATE accounts...

COMMIT;

Why with_lock is Preferred

Instead of:

Account.transaction do
  account = Account.lock.find(id)
end

You simply write:

account.with_lock do
  ...
end

Cleaner.

Safer.

Locking Multiple Rows

Example:

Product.transaction do
  products = Product.lock.where(category_id: 1)
  products.each do |product|
      product.update!(price: product.price * 1.1)
   end
end

All selected rows remain locked until the transaction completes.

NOWAIT

Sometimes you don’t want to wait.

Instead:

Product.lock("FOR UPDATE NOWAIT")

Generated SQL:

FOR UPDATE NOWAIT

If another transaction already owns the lock:

Instead of waiting,

PostgreSQL immediately raises an error.

Useful for:

payment processing
reservation systems
inventory

SKIP LOCKED

Another useful option.

Job.lock("FOR UPDATE SKIP LOCKED")

Instead of waiting,

locked rows are skipped.

Example:

Job 1 Locked

Job 2 Free

Job 3 Locked

Job 4 Free

Worker gets:

Job 2

Job 4

Very common in:

Sidekiq alternatives
queue systems
job schedulers

Real Production Example 1

Inventory Reservation

Product

Inventory = 1

Safe implementation

Product.transaction do
  product = Product.lock.find(id)
raise "Out of stock" if product.inventory.zero?
  product.inventory -= 1
  product.save!
end

No two users can purchase the last item simultaneously.

Real Production Example 2

Hotel Booking

Room:

Available

Without locking:

Two guests reserve the same room.

With locking:

Guest A locks the room.

Guest B waits.

Guest A confirms booking.

Guest B now sees:

Room unavailable

Real Production Example 3

Wallet Transfer

Wallet.transaction do
  wallet = Wallet.lock.find(id)
  wallet.balance -= amount
  wallet.save!
end

Prevents inconsistent balances.

Lock Duration

A common misconception:

People think locks remain forever.

Reality:

BEGIN

↓

Lock row

↓

Update

↓

COMMIT

↓

Lock released

Locks exist only during the transaction.

Things to Avoid

Long Transactions

Bad

User.transaction do
  user.lock!
  sleep 30
  user.update!
end

The row remains locked for 30 seconds.

Other users wait.

External API Calls Inside Transactions

Avoid:

User.transaction do
  user.lock!
  Stripe.charge(...)
  user.update!
end

Network calls increase lock duration.

Instead:

Stripe.charge(...)

User.transaction do
  user.lock!

  user.update!
end

Keep transactions as short as possible.

Advantages

✅ Prevents race conditions

✅ Prevents lost updates

✅ Guarantees data consistency

✅ Great for financial applications

✅ Works well for inventory systems

Disadvantages

❌ Transactions may block each other

❌ Can reduce throughput

❌ Long-running transactions hurt performance

❌ Deadlocks become possible

When Should You Use Pessimistic Locking?

Use it when:

Payment processing
Wallet balance
Inventory reservation
Ticket booking
Hotel reservation
Airline seats
Banking
Subscription renewals
Coupon redemption

Avoid it for:

Simple profile updates
Blog posts
User preferences

Interview Questions

Difference between lock, lock!, and with_lock

lock

Used while querying.

Account.lock.find(1)

lock!

Locks an already loaded record.

account.lock!

with_lock

Starts a transaction, locks the record, executes the block, and commits automatically.

account.with_lock do
  ...
end

What SQL does Rails generate?

SELECT *
FROM accounts
FOR UPDATE;

What happens if another transaction tries to update the same row?

It waits until the first transaction commits or rolls back.

When would you use SKIP LOCKED?

When building:

Job queues
Background workers
Task schedulers

where workers should continue processing available rows instead of waiting.

Key Takeaways

Pessimistic locking prevents concurrent modifications by locking rows before updates.
Rails supports it through lock, lock!, and with_lock.
PostgreSQL implements it using SELECT ... FOR UPDATE.
Keep transactions short to minimize lock contention.
Use features like NOWAIT and SKIP LOCKED when appropriate for advanced concurrency scenarios.
Pessimistic locking is ideal when data correctness is more important than maximizing concurrency.

Monolith vs Microservices: Architecture, Trade-offs, and How to Choose

Yashika Vijayvargiya — Wed, 09 Sep 2026 09:11:17 +0000

Introduction

When building a new application, one of the first architectural decisions a team faces is:

Should we build a monolith or use microservices?

The question sounds simple, but the answer isn’t.

Over the last decade, microservices have become one of the most discussed software architecture patterns. Many engineering teams moved from monolithic applications to microservices expecting better scalability, faster deployments, and greater flexibility.

But microservices also introduce significant complexity.

You now have multiple applications, multiple deployments, network communication, distributed failures, observability challenges, and often multiple databases.

A monolith, on the other hand, can be much simpler to develop, test, deploy, and operate.

So which one is better?

The answer is:

Neither is universally better. The right architecture depends on the application’s complexity, team structure, scalability requirements, and operational maturity.

In this article, we’ll explore:

What a monolithic architecture is
What microservices are
How the two architectures differ
Advantages and disadvantages of each
Database architecture
Scaling
Deployment
Testing
Failure handling
Team organization
Modular monoliths
When to choose each architecture
How companies can migrate from a monolith to microservices
Common microservices mistakes
A practical decision framework

What Is Software Architecture?

Before comparing monoliths and microservices, let’s understand what software architecture means.

Software architecture describes how the major components of an application are organized and how they interact with each other.

For example, an e-commerce application may contain:

Users
Products
Orders
Payments
Inventory
Notifications

The architectural question is:

How should these components be organized and communicate with each other?

A simple approach is to put everything into one application.

That’s a monolith.

Another approach is to split the application into multiple independently running services.

That’s microservices.

What Is a Monolithic Architecture?

A monolithic application is an application where most or all business functionality is developed, deployed, and operated as a single application.

For example:

E-Commerce Application
                         |
        ---------------------------------------
        | | | | |
       Users Products Orders Payments Inventory
        | | | | |
        ---------------------------------------
                         |
                      Database

The application may have many modules internally, but it is deployed as one unit.

For example, a Rails application might contain:

app/
├── models/
│ ├── user.rb
│ ├── product.rb
│ ├── order.rb
│ └── payment.rb
│
├── controllers/
│ ├── users_controller.rb
│ ├── products_controller.rb
│ ├── orders_controller.rb
│ └── payments_controller.rb
│
└── services/
    ├── payment_service.rb
    └── order_service.rb

All of these components run inside the same application.

How a Monolith Works

Suppose a customer places an order.

The request might look like:

Client
  |
  v
Rails Application
  |
  +--> Validate User
  |
  +--> Check Inventory
  |
  +--> Create Order
  |
  +--> Process Payment
  |
  +--> Send Notification
  |
  v
Database

Everything happens within the same application boundary.

The application can call another component directly:

OrderService.call(user, product)

There is no network request between these components.

This simplicity is one of the biggest advantages of a monolith.

Advantages of a Monolith

1. Simple Development

Developers work in one repository.

They don’t need to understand:

service discovery
API gateways
distributed tracing
message brokers
inter-service authentication

A developer can usually clone the repository and start working.

2. Simple Deployment

You deploy one application.

For example:

git push
   |
   v
CI/CD
   |
   v
Deploy application

With microservices, you may need to deploy multiple services independently.

3. Simple Communication

Inside a monolith:

payment.process(order)

With microservices:

Order Service
      |
      | HTTP/gRPC/message
      v
Payment Service

Network communication introduces latency and failure possibilities.

4. Easier Transactions

Suppose creating an order requires:

Creating an order
Updating inventory
Creating a payment record

In a monolith, these can potentially happen inside a single database transaction:

ApplicationRecord.transaction do
  order.save!
  inventory.update!
  payment.save!
end

If something fails:

Order created
Inventory updated
Payment fails
       |
       v
Rollback

The database can restore the previous state.

Distributed transactions across microservices are significantly more complicated.

5. Easier Debugging

If something fails:

Request
  ↓
Application
  ↓
Database

You can inspect one application’s logs and traces.

With microservices:

API Gateway
   ↓
Order Service
   ↓
Inventory Service
   ↓
Payment Service
   ↓
Notification Service

You may need to inspect logs from several services.

Disadvantages of a Monolith

Monoliths aren’t perfect.

As applications grow, problems can appear.

1. Large Codebase

A monolith can become difficult to understand.

Over time:

app/
├── users
├── orders
├── payments
├── inventory
├── reporting
├── notifications
├── subscriptions
├── analytics
└── ...

Everything exists in the same repository.

Without strong boundaries, modules can become tightly coupled.

2. Scaling the Entire Application

Suppose only the image-processing functionality needs more CPU.

With a traditional monolith:

Application
     |
     +--- Users
     +--- Orders
     +--- Payments
     +--- Images

You may have to scale the entire application.

You cannot independently scale only the image-processing component unless the architecture is designed for it.

3. Deployment Coupling

Suppose the payments team changes one small component.

If the entire application is deployed together, that change may go through the same deployment pipeline as everything else.

This can increase deployment risk.

4. Large Teams Can Become Difficult to Manage

Imagine 100 developers working in one repository.

You may encounter:

merge conflicts
long CI pipelines
unclear ownership
tightly coupled modules
coordination overhead

The problem isn’t necessarily that the application is a monolith.

The problem may be that the organization and architecture haven’t evolved together.

What Is a Microservices Architecture?

A microservices architecture divides an application into multiple independently deployable services.

Each service focuses on a specific business capability.

For example:

API Gateway
                         |
       -------------------------------------
       | | | |
       v v v v
    User Order Payment Inventory
   Service Service Service Service
       | | | |
       v v v v
    Database Database Database Database

Each service can:

have its own codebase
have its own deployment
have its own database
scale independently
be owned by a specific team

Example: E-Commerce Microservices

Consider an e-commerce platform.

Instead of:

E-Commerce Monolith

we might have:

User Service
Order Service
Product Service
Inventory Service
Payment Service
Notification Service

Each service owns a specific responsibility.

For example:

User Service

Responsible for:

registration
login
profiles
authentication

Product Service

Responsible for:

products
categories
pricing

Order Service

Responsible for:

orders
order lifecycle
order history

Payment Service

Responsible for:

payment processing
refunds
payment status

Notification Service

Responsible for:

emails
SMS
push notifications

The Most Important Microservices Principle

The goal is not:

“Split the application into many small applications.”

The goal is:

Create independently deployable services around meaningful business boundaries.

This distinction is important.

A system with 50 tiny services isn’t automatically better than a system with 5 well-designed services.

Advantages of Microservices

1. Independent Deployment

A payment service can be deployed without deploying the order service.

Payment Service
      |
      v
Deploy independently

This can enable teams to release features faster.

2. Independent Scaling

Suppose the order service receives significantly more traffic than the user service.

You can scale them independently:

User Service
Instances: 3

Order Service
Instances: 20

Payment Service
Instances: 5

3. Team Ownership

Different teams can own different services.

Team A → User Service
Team B → Order Service
Team C → Payment Service
Team D → Notification Service

This can reduce coordination between teams.

4. Technology Flexibility

Different services can potentially use different technologies.

For example:

User Service → Rails
Payment Service → Java
Recommendation → Python
Notification → Go

However, just because you can use multiple languages doesn’t mean you should.

Technology diversity introduces its own operational costs.

5. Fault Isolation

Suppose the recommendation service fails.

Ideally:

Recommendation Service ❌

Order Service ✅
Payment Service ✅
User Service ✅

The entire application doesn’t necessarily have to go down.

But this only works if services are designed with failure isolation in mind.

Disadvantages of Microservices

This is where many teams underestimate the cost.

1. Network Communication

Inside a monolith:

payment.process(order)

With microservices:

Order Service
      |
      | HTTP
      v
Payment Service

The network can fail.

Possible problems include:

timeout
connection failure
DNS failure
retry storms
latency
duplicate requests

Communication becomes a major architectural concern.

We’ll explore this in detail in the next article.

2. Distributed Transactions

Consider:

Order Service
     |
     +--> Inventory Service
     |
     +--> Payment Service

What happens if:

Order created ✅
Inventory updated ✅
Payment failed ❌

You can’t simply rollback all services using a normal database transaction.

This is one of the biggest differences between monolithic and distributed systems.

Solutions may involve:

Saga pattern
compensating transactions
event-driven architecture
idempotency

3. Debugging Becomes Harder

A single user request might travel through:

API Gateway
    ↓
Order Service
    ↓
Inventory Service
    ↓
Payment Service
    ↓
Notification Service

If the request fails, which service caused the problem?

You need tools such as:

centralized logging
distributed tracing
correlation IDs
metrics
monitoring

4. Operational Complexity

A monolith might require:

Application
Database
Redis

A microservices system might require:

10 Services
10 Databases
Message Broker
API Gateway
Service Discovery
Centralized Logging
Distributed Tracing
Monitoring
Secrets Management
CI/CD pipelines

The operational burden increases significantly.

5. Data Consistency

In a monolith, multiple modules can share a database.

With microservices, each service ideally owns its data.

Order Service
     |
 Orders DB

Payment Service
     |
 Payments DB

Now querying data across services becomes more complicated.

You can’t simply write:

SELECT *
FROM orders
JOIN payments
ON payments.order_id = orders.id;

because the tables may exist in completely different databases.

Shared Database vs Database per Service

This is one of the most important architectural decisions.

Shared Database

Order Service --------\
Payment Service ------- > PostgreSQL
Inventory Service ----/

It’s easier initially.

But services become coupled through the database.

One service might directly modify another service’s tables.

This weakens service boundaries.

Database per Service

Order Service
     |
 Orders DB

Payment Service
     |
 Payments DB

Inventory Service
     |
 Inventory DB

This provides stronger ownership.

But now cross-service queries and transactions become harder.

Monolith vs Microservices: Database Comparison

Area

Monolith

Microservices

Database

Usually shared

Usually owned by service

Transactions

Easier

More complex

Joins

Easy

Usually avoided across services

Consistency

Easier

Often eventual

Data ownership

Shared

Explicit

Reporting

Easier

Requires aggregation

Scaling Comparison

Suppose your application receives:

10,000 requests/second

A monolith can still scale.

For example:

Load Balancer
      |
 -----------------
 | | |
App App App

There is nothing inherently wrong with scaling a monolith horizontally.

Microservices simply allow more granular scaling.

Order Service → 20 instances
User Service → 5 instances
Payment Service → 10 instances

Therefore:

High traffic does not automatically mean you need microservices.

A well-designed monolith can handle significant scale.

Deployment Comparison

Monolith

Code
 ↓
Build
 ↓
Test
 ↓
Deploy
 ↓
Application

Usually one deployment pipeline.

Microservices

Order Service
     ↓
Pipeline
     ↓
Deploy

Payment Service
     ↓
Pipeline
     ↓
Deploy

Inventory Service
     ↓
Pipeline
     ↓
Deploy

You gain independent deployments but also need to manage multiple pipelines.

Testing Comparison

Monolith

You can run:

Unit Tests
Integration Tests
System Tests

Testing is relatively straightforward because components are inside one application.

Microservices

You need additional testing strategies:

Unit Tests
     ↓
Service Tests
     ↓
Contract Tests
     ↓
Integration Tests
     ↓
End-to-End Tests

You need to verify not only that each service works but also that services understand each other’s contracts.

Failure Handling

Failure is much more visible in distributed systems.

Suppose:

Order Service
     |
     v
Payment Service

Payment service takes 10 seconds to respond.

Should the order request wait?

Probably not indefinitely.

You may need:

timeouts
retries
circuit breakers
fallback behavior
asynchronous processing

For example:

Order Created
     |
     v
Publish Event
     |
     v
Payment Processing
     |
     v
Payment Completed

This allows parts of the system to operate asynchronously.

Monolith vs Modular Monolith vs Microservices

There is an important architecture between the two extremes:

Modular Monolith

A modular monolith is still deployed as one application, but its internal components have strict boundaries.

For example:

Rails Application
                     |
       -----------------------------
       | | |
     Orders Payments Inventory
       | | |
       -----------------------------
                     |
                 Database

The application is deployed as one unit, but modules are isolated.

This can provide many benefits of good architecture without immediately introducing distributed-system complexity.

Why Modular Monoliths Are Important

A common mistake is:

Monolith
   ↓
"We need microservices"
   ↓
20 services

A better approach may be:

Monolith
   ↓
Identify boundaries
   ↓
Create modules
   ↓
Reduce coupling
   ↓
Measure actual bottlenecks
   ↓
Extract services only when necessary

This gives the team time to understand the domain before introducing network boundaries.

When Should You Choose a Monolith?

A monolith is often a good choice when:

You’re building a new product
The team is small
The domain is still changing
Requirements are uncertain
You want fast iteration
Operational resources are limited
You don’t have strong service boundaries yet

For many startups, this is an excellent starting point.

When Should You Consider Microservices?

Microservices may make sense when:

1. Teams Need Independent Ownership

If multiple teams need to work independently on different business domains, service boundaries can help.

2. Components Scale Differently

For example:

Image Processing → Very high CPU
User Management → Low traffic

Independent scaling could be valuable.

3. Independent Deployments Are Important

If one team’s release shouldn’t require coordinating with five other teams, independently deployable services can help.

4. Strong Domain Boundaries Exist

For example:

Payments
Identity
Orders
Shipping

If these are clearly separated business domains, they may be good candidates for service boundaries.

When Microservices Are a Bad Idea

Don’t choose microservices simply because:

“Netflix uses them.”

Or:

“Our application is getting bigger.”

Or:

“Microservices are more scalable.”

Microservices may be a bad choice when:

The team is small
The domain is poorly understood
You don’t have DevOps maturity
Monitoring is weak
Deployment automation is poor
Services need constant communication
Data boundaries aren’t clear

If every service constantly calls every other service:

A → B
A → C
A → D

B → A
B → C
B → D

C → A
C → B
C → D

you haven’t created independent services.

You’ve created a distributed monolith.

What Is a Distributed Monolith?

A distributed monolith has multiple services but behaves like one tightly coupled application.

For example:

Order
  ↓
Inventory
  ↓
Payment
  ↓
User
  ↓
Notification

Every request requires several services to be available.

Deploying one service requires another service to be updated.

At this point, you’ve taken the complexity of a monolith and added network complexity on top of it.

That’s one of the worst outcomes.

The Importance of Service Boundaries

Good microservices have clear responsibilities.

For example:

Payment Service

Owns:
- Payments
- Refunds
- Payment status

Doesn't own:
- Orders
- Inventory
- User profiles

A service should ideally own its business logic and data.

This concept is often described as:

Bounded Context

from Domain-Driven Design.

Don’t Start With the Most Complex Service

When extracting your first service, choose a capability with:

Clear ownership
Clear boundaries
Limited dependencies
Independent scaling requirements
Minimal cross-service transactions

Don’t start by extracting the most interconnected component.

A Practical Decision Framework

Before choosing microservices, ask:

Question 1

Do we actually have a scaling problem?

If not, don’t introduce distributed complexity just for future scale.

Question 2

Do different parts of the application need independent deployments?

If yes, microservices may help.

Question 3

Do we have clear domain boundaries?

If no, start with a modular monolith.

Question 4

Can our team operate distributed systems?

Do we have:

monitoring
logging
tracing
CI/CD
infrastructure automation
incident response

If not, microservices may be premature.

Question 5

Can services operate independently?

If every service requires five other services for every request, reconsider the architecture.

A Simple Comparison

Feature

Monolith

Modular Monolith

Microservices

Deployment

Single

Independent

Codebase

Usually one

One

Multiple

Database

Usually shared

Usually separate

Scaling

Application-level

Service-level

Communication

In-process

Network

Transactions

Easy

Complex

Debugging

Easier

Harder

Operations

Simpler

Complex

Team independence

Lower

Medium

Higher

Infrastructure cost

Lower

Higher

Failure isolation

Lower

Medium

Higher

Initial development speed

High

Lower

Long-term complexity

Can increase

Controlled

High

A Common Misconception

“Microservices automatically scale better.”

Not necessarily.

A monolith can scale horizontally:

Load Balancer
             / | \
            / | \
         App App App

Microservices simply provide more granular scaling:

Order Service → 20 instances
User Service → 3 instances
Payment Service → 8 instances

The benefit is flexibility, not magic scalability.

What Would I Choose?

For a new application with a small or medium-sized team, I’d generally start with:

A well-structured modular monolith.

Build clear boundaries.

Measure the system.

Understand where the real problems are.

Then extract services when there is a concrete reason.

For an organization with:

many teams
clear business domains
independent deployment requirements
different scaling requirements
mature DevOps practices

microservices can be a very effective architecture.

Conclusion

Monoliths and microservices aren’t competing technologies.

They are architectural choices with different trade-offs.

A monolith provides:

simplicity
easy transactions
straightforward deployment
simpler debugging

Microservices provide:

independent deployment
independent scaling
team autonomy
stronger service boundaries
potential fault isolation

But microservices also introduce:

network failures
distributed transactions
data consistency challenges
observability requirements
operational complexity

The best architecture isn’t the one that sounds the most modern.

It’s the one that solves your actual problems without introducing unnecessary complexity.

Don’t choose microservices because your application is becoming successful. Choose them when the benefits of independence outweigh the complexity of distribution.

And if you’re starting with a monolith, that doesn’t mean you’ve made a permanent decision. A well-designed modular monolith can be an excellent foundation for gradually extracting services when the need becomes real.

What’s Next?

Choosing microservices is only the beginning.

Once an application is split into multiple services, a much bigger question appears:

How do these services communicate with each other?

Should they use:

REST APIs?
gRPC?
Message queues?
Kafka?
RabbitMQ?
Amazon SQS?
Events?

Each approach has different trade-offs around latency, reliability, scalability, consistency, and failure handling.

That’s what we’ll explore in the next article:

Microservices Communication: REST vs gRPC vs Message Queues vs Event-Driven Architecture.

What Is Vibe Coding? Benefits, Risks, and Best Practices for AI-Assisted Development

Yashika Vijayvargiya — Fri, 21 Aug 2026 12:00:59 +0000

Introduction

AI has changed how developers write software.

Instead of writing every line of code manually, many developers now describe what they want in plain English and let AI generate the implementation.

This way of working has become popularly known as vibe coding.

Some developers see it as the future of software development, while others worry it encourages developers to rely too heavily on AI.

So, what exactly is vibe coding, and when should you use it?

Let's explore.

What Is Vibe Coding?

Definition

Vibe coding is an AI-assisted development approach where developers describe what they want to build instead of manually writing every line of code.

Rather than starting with an empty file, developers provide prompts such as:

Build a REST API for managing products with authentication and pagination.

The AI generates the initial implementation, which the developer reviews, modifies, and tests.

In simple words:

Instead of writing every line yourself, you guide AI to write the first draft of your code.

Traditional Coding vs. Vibe Coding

Traditional Development

Understand the problem
↓
Design the solution
↓
Write code
↓
Debug
↓
Test
↓
Deploy

The developer writes every implementation detail manually.

Vibe Coding

Understand the problem
↓
Describe it to AI
↓
AI generates code
↓
Review
↓
Test
↓
Improve
↓
Deploy

The developer focuses more on problem-solving and less on typing boilerplate code.

An Example

Imagine you want to build authentication in a Rails application.

Traditional approach

You would:

Generate models
Configure routes
Add controllers
Write validations
Implement sessions or JWT
Create tests

This might take hours.

Vibe coding approach

You ask:

Create JWT authentication for a Rails API with login, logout, refresh tokens, request specs, and proper error handling.

Within seconds, the AI generates the initial implementation.

Your job becomes reviewing, testing, and refining the code instead of writing everything from scratch.

Why Is Vibe Coding Becoming Popular?

Modern AI coding tools can:

Understand multiple files
Navigate large codebases
Generate tests
Refactor code
Explain existing code
Detect common bugs

This allows developers to move faster, especially when working on repetitive tasks.

Popular AI Coding Tools

Some of the most widely used AI coding assistants include:

Cursor
Claude Code
GitHub Copilot
Gemini Code Assist
Windsurf

These tools help developers write, refactor, and understand code more efficiently.

Benefits of Vibe Coding

Faster Development
Instead of spending time writing repetitive code, developers can focus on solving business problems.

Less Boilerplate

AI can generate:

CRUD operations
API endpoints
Tests
Configuration
Documentation

Easier Learning

Developers exploring a new language or framework can use AI to understand patterns and best practices more quickly.

Better Productivity

Many developers use AI for:

Writing tests
Explaining unfamiliar code
Refactoring methods
Generating documentation
Creating migration files

Risks of Vibe Coding

Despite its advantages, vibe coding has important limitations.

AI Can Produce Incorrect Code

AI-generated code isn't always correct.

It may:

Misuse libraries
Ignore edge cases
Introduce bugs
Generate outdated patterns
Always review the generated code.

Security Risks

AI might generate:

SQL injection vulnerabilities
Weak authentication
Insecure API implementations

Security-critical code should always be reviewed carefully.

Overengineering

Sometimes AI solves simple problems with unnecessarily complex code.

Good developers know when a simpler solution is better.

Reduced Understanding

If developers accept AI-generated code without understanding it, debugging and maintaining the application becomes much harder.

When Should You Use Vibe Coding?

Vibe coding works well for:

CRUD applications
API scaffolding
Unit tests
Documentation
Refactoring
Code explanations
Repetitive development tasks

When Should You Avoid It?

Be cautious when working on:

Payment systems
Authentication
Authorization
Financial calculations
Security-sensitive features
Distributed systems
Performance-critical code

These areas require careful design, testing, and review.

Best Practices

Use AI as a collaborator
Don't treat AI as a replacement for engineering judgment.

Review every generated change
Understand what the AI generated before merging it.

Write tests
AI-generated code should be validated with automated tests.

Keep prompts specific
Instead of asking:

Build an API.

Ask:

Build a Rails API using service objects, request specs, pagination, JWT authentication, and proper error handling.

Clear prompts generally produce better results.

Conclusion

Vibe coding is changing the software development workflow by allowing developers to express ideas in natural language and use AI to generate an initial implementation.

Used thoughtfully, it can improve productivity and reduce repetitive work.

However, AI-generated code is still software that needs to be reviewed, tested, and maintained.

The most effective developers aren't those who let AI write everything—they're the ones who know when to rely on AI and when to rely on their own expertise.

Hashnode AI

Hashnode AI is a Pro feature
Upgrade to Pro to refine your drafts, suggest edits, and brainstorm with the Writing Assistant.

Upgrade to Pro
Search Hashnode
Search posts, tags, users, and pages

The Rails Bug That Disappeared After a Server Restart — Until I Found the Mutation

Yashika Vijayvargiya — Mon, 17 Aug 2026 07:16:44 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories.

Project Overview

Some bugs are difficult because the code is complicated.

Others are difficult because the bug seems to have no rules.

This was the second kind.

A Rails application I was working on started rendering ActiveAdmin menus incorrectly.

Sometimes nested menu items appeared under the wrong level.

Sometimes everything looked completely normal.

And sometimes restarting the application made the problem disappear.

That last part was the most suspicious.

A restart shouldn't "fix" a deterministic piece of Ruby code.

So I started digging.

What I eventually found was a much more interesting problem:

An object was being modified somewhere I didn't expect it to be modified.

And the fix turned out to be one of the simplest Ruby changes I've made:

options = options.dup

But getting there took considerably more work.

Bug Fix or Performance Improvement

The application was using ActiveAdmin for its administrative interface.

The problem appeared in the navigation menu.

We had nested menu items, and occasionally they were rendered as top-level items instead of being nested under their intended parent.

Something like:

Expected:

Reports
  ├── Sales
  └── Revenue

Actual:

Reports
Sales
Revenue

The frustrating part was that the behavior wasn't consistently reproducible.

The same application could:

render the menu correctly
render it incorrectly
restart
start working again
continue working for some time
then fail again

This was not the kind of bug where I could simply open the relevant controller and find a typo.

It looked almost random.

The First Clue: Restarting the Server "Fixed" It

The most interesting observation was that restarting the server temporarily resolved the problem.

That immediately made me suspicious of state.

If restarting the process changes the behavior without changing the database or application code, something may be surviving longer than expected inside the process.

That led me away from asking:

"What condition makes the menu render incorrectly?"

and toward:

"What state is being mutated between requests?"

That was a much better question.

Following the Menu Construction

I started tracing how ActiveAdmin constructs its menus.

Eventually I reached the menu node implementation and the add method responsible for adding menu items.

The important part looked roughly like this:

def add(options)
  # menu item construction
end

At first, there was nothing obviously wrong.

The method received an options object and used it to construct the menu node.

But the more I followed the execution path, the more suspicious the object itself became.

The same options object was being passed through multiple parts of the menu-building process.

And something was changing it.

The Problem Wasn't the Value

This was the key realization.

The problem wasn't necessarily that the options contained the wrong value.

The problem was that the options object itself was mutable.

Imagine this simplified example:

options = {
  parent: "Reports",
  label: "Revenue"
}

You pass that object into another method:

build_menu(options)

If build_menu modifies it:

options.delete(:parent)

the original object has now changed too.

There is no copy.

There is no isolation.

Both pieces of code are holding a reference to the same object.

So later:

options[:parent]

returns:

nil

even though the code that originally created the options never intentionally removed it.

That is exactly the kind of mutation that can create a bug that looks random.

Why It Looked Random

The menu wasn't necessarily broken every time.

The behavior depended on when and how the shared object was mutated.

That made the symptoms particularly confusing.

A simplified lifecycle looked like this:

Create menu options
        ↓
Pass options to ActiveAdmin
        ↓
ActiveAdmin modifies options
        ↓
Original object is now different
        ↓
Another menu operation uses it
        ↓
Parent information is missing/incorrect
        ↓
Nested item becomes top-level

And because the object lived inside the running Ruby process, restarting the server cleared that in-memory state.

That explained why a restart could appear to "fix" the bug.

It wasn't fixing anything.

It was simply giving us a fresh process with fresh objects.

Then I Found the GitHub Issue

After spending a significant amount of time debugging the behavior at the application and dependency level, I searched GitHub for similar ActiveAdmin problems.

That's when I found:

ActiveAdmin issue #8078 — "Nested menu items are rendered top-level."

The issue description was remarkably similar.

It reported that nested menus were sometimes rendered at the top level, and that restarting the server temporarily solved the problem. The issue was difficult to reproduce and had been observed in production.

That was the moment when the investigation changed direction.

I wasn't dealing with some mysterious Rails rendering bug.

There was already evidence that ActiveAdmin's menu construction could be modifying menu state.

The issue eventually led to ActiveAdmin PR #8132, titled:

"Make sure menu creation does not modify menu options."

The ActiveAdmin maintainer later reported that the patch had run in production for almost a month without the menu rendering problem recurring before merging it.

Now I had a much stronger hypothesis:

The options object was being mutated during menu construction.

The next question was:

How can I prevent that mutation from affecting the object my application is using?

Code

The Fix: Give `add` Its Own Copy

Instead of passing the original options object into the existing implementation, I created a duplicate first.

The patch was:

module MenuNode
  def add(options)
    options = options.dup
    super(options)
  end
end

ActiveAdmin::Menu.class_eval do
  include MenuNode
end

That's it.

The important line is:

options = options.dup

Before the fix:

Application
    │
    ▼
options ───────────────┐
                      │
                      ▼
                ActiveAdmin
                      │
                      ▼
                modifies object
                      │
                      ▼
            original options changed

After the fix:

Application
    │
    ▼
original options

    │
    │ dup
    ▼

copied options
    │
    ▼
ActiveAdmin
    │
    ▼
can modify its copy

The original object remains untouched.

Why `dup` Fixed It

Ruby objects are references.

Consider:

options = {
  parent: "Reports",
  label: "Revenue"
}

copy = options

copy isn't a new Hash.

Both variables point to the same object.

So:

copy.delete(:parent)

also changes:

options

because they're the same object.

But:

copy = options.dup

creates a separate Hash.

Now:

copy.delete(:parent)

doesn't remove the key from the original options.

That's exactly the isolation we needed.

Why I Used `super`

There was another important detail in the fix.

I didn't want to reimplement ActiveAdmin's add method.

That would have created another maintenance problem.

Instead, I wanted to change one thing:

Give the original method a safe copy of the options.

Then let ActiveAdmin continue doing everything else exactly as it already did.

That's why the implementation is:

def add(options)
  options = options.dup
  super(options)
end

The flow becomes:

Our wrapper
    ↓
duplicate options
    ↓
ActiveAdmin's original add
    ↓
existing behavior

This is a useful pattern when working with a third-party library:

Change the boundary, not the library's internal behavior.

My Improvements

The Debugging Lesson: Don't Trust "Random"

One of the biggest lessons from this bug was that "random" doesn't necessarily mean random.

When an application behaves differently after a restart, there is often state involved.

That state could live in:

class variables
global objects
memoized values
caches
singleton instances
mutable configuration
shared Hashes or Arrays
library objects that survive across requests

In Ruby, mutable objects make this especially important.

This:

options = original_options

and this:

options = original_options.dup

look similar.

But they create very different ownership semantics.

The Dependency Was Part of the Application

Another lesson was about debugging third-party libraries.

It is tempting to say:

"The bug is in ActiveAdmin."

But that doesn't help when you're responsible for the application.

The useful question is:

Where does the incorrect state enter my application?

That led me through:

Application behavior
       ↓
ActiveAdmin
       ↓
Menu construction
       ↓
MenuNode#add
       ↓
options object
       ↓
unexpected mutation

Once I could see the mutation boundary, the fix became straightforward.

The Fix Was Tiny. The Investigation Wasn't.

This is something I've noticed repeatedly when debugging production Rails applications.

The final patch often looks deceptively simple.

In this case:

options = options.dup

is almost trivial.

But the path to that line involved:

reproducing an intermittent problem
comparing behavior before and after a restart
tracing ActiveAdmin internals
inspecting how menu nodes were constructed
questioning object ownership
searching existing GitHub issues
finding a closely related ActiveAdmin issue
understanding why the existing implementation could mutate shared state
introducing a minimal wrapper
delegating back to the original implementation with super

The difficulty wasn't writing the fix.

The difficulty was finding the right layer to fix.

What This Taught Me About Ruby

Ruby makes it very easy to pass objects around.

That's one of its strengths.

But that convenience also means that mutable objects can cross boundaries without making ownership obvious.

Whenever I see a method receiving a Hash or Array, I now ask:

Who owns this object, and is this method allowed to modify it?

If the answer isn't clear, copying the object at the boundary can sometimes be the difference between stable behavior and an intermittent production bug.

Of course, dup isn't a universal solution.

It is a shallow copy, so nested mutable objects can still be shared:

options = {
  menu: {
    parent: "Reports"
  }
}

In that situation:

copy = options.dup

duplicates the outer Hash, but the nested :menu Hash is still shared.

So the correct solution depends on what the called code actually mutates.

In this case, duplicating the options object at the add boundary was enough.

The Bigger Lesson

When a bug looks random, don't immediately assume the framework is behaving unpredictably.

Look for state.

When restarting the server makes the bug disappear, don't celebrate.

Ask what state the restart destroyed.

When a dependency receives a mutable object, don't assume it will leave it untouched.

And when you finally identify the problem, resist the temptation to rewrite everything.

Sometimes the safest fix is simply:

options = options.dup
super(options)

A tiny boundary.

A separate object.

No accidental mutation.

And suddenly the "random" bug isn't random anymore.

Final Takeaway

The most valuable part of debugging isn't always the final code change.

Sometimes it's the moment when a confusing symptom finally becomes a predictable consequence of one small assumption.

In my case:

"Menus randomly render incorrectly"
              ↓
"Restarting fixes it"
              ↓
"There must be state"
              ↓
"ActiveAdmin is modifying menu options"
              ↓
"The same mutable object is being reused"
              ↓
"Give ActiveAdmin a copy"
              ↓
options.dup

The final fix was one line.

The investigation was the real engineering work.

And that's probably the part of this bug I'll remember.

When a String Assumption Broke Newsletter Tag Filtering in Ruby

Yashika Vijayvargiya — Fri, 14 Aug 2026 10:55:37 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

When a Single Type Assumption Broke Newsletter Tag Filtering in Ruby

A bug doesn't always need hundreds of lines of code to cause a real problem.

Sometimes, one assumption is enough.

In this case, the assumption was simple:

"Every tag is a String."

That assumption lived inside a Ruby filtering method in the open-source RubyEvents project.

It worked perfectly — until a tag wasn't a String.

That small mismatch was enough to turn a normal user interaction into an error.

This is the story of how the bug was investigated, what was actually going wrong, and how a small change made the filtering logic safer and clearer.

The Bug

The issue was reported as:

"Cannot Click tags on Newsletter"

The behavior was straightforward:

Open a newsletter.
Click one of its tags.
Instead of getting the filtered announcements, the application raises an error.

The issue was tracked as #1836.

At first glance, this sounds like it could be a routing or controller problem.

It wasn't.

The failure was deeper in the tag-filtering logic.

Finding the Assumption

The filtering logic lived in

Announcement::Collection#by_tag

The original implementation was:

def by_tag(tag)
  Collection.new(
    select { |a| a.tags.map(&:downcase).include?(tag.downcase) }
  )
end

The intent is easy to understand:

take all tags from an announcement
convert them to lowercase
compare them with the requested tag
return matching announcements

For normal String values, this works perfectly.

For example:

["Ruby", "Rails"].map(&:downcase)
=> ["ruby", "rails"]

But there is an important assumption hidden inside:

map(&:downcase)

Every element must respond to downcase.

That's not necessarily true.

Imagine the collection contains:

["Ruby", 123]

Calling:

["Ruby", 123].map(&:downcase)

eventually tries to execute:

123.downcase

And integers don't have a downcase method.

The result is a NoMethodError.

So the real problem wasn't the newsletter link itself.

The newsletter was simply the path that exposed an unsafe assumption in the tag-filtering code.

The Interesting Part: Fixing the Bug Without Changing the Behavior

There were several ways this could have been "fixed."

For example, we could have assumed that all tags should always be Strings and modified the data at the source.

But that would increase the scope of the change.

The filtering method already had a clear responsibility:

Find announcements whose tags match the requested tag, case-insensitively.

So instead of changing the data source, I wanted to make the comparison resilient to the values it actually received.

The implementation became:

def by_tag(tag)
  Collection.new(
    select { |a| a.tags.any? { |tag_value| tag_value.to_s.casecmp?(tag) } }
  )
end

There are two important changes here.

to_s Creates a Safe Comparison Boundary

Instead of assuming:

tag_value.downcase

we explicitly convert the value:

tag_value.to_s

Now a String remains a String:

"Ruby".to_s
# => "Ruby"

And a non-String value becomes safely comparable:

123.to_s
# => "123"

The filtering code no longer crashes simply because a tag value isn't already a String.

This is a small example of something I find important when working with Ruby:

Don't make an assumption about the type of an object if you don't actually need that assumption.

casecmp? Expresses the Actual Requirement

The original implementation lowercased both sides:

tag_value.downcase == tag.downcase

But the actual requirement isn't:

Convert everything to lowercase.

The requirement is:

Compare these values without considering case.

Ruby provides exactly that operation:

casecmp?

So the comparison becomes:

tag_value.to_s.casecmp?(tag)

This makes the intent clearer.

We're not transforming the data just to compare it.

We're performing a case-insensitive comparison.

Why any? Instead of map?

This was another small but meaningful improvement.

The old implementation transformed every tag:

a.tags.map(&:downcase).include?(tag.downcase)

But we don't actually need a new array.

We only need to answer one question:

Does at least one tag match?

That's exactly what any? communicates:

a.tags.any? { |tag_value| ... }

It also allows Ruby to stop checking once a match is found.

So the new implementation isn't simply more defensive.

It's also closer to the actual intent of the operation.

Before vs After

Before

def by_tag(tag)
  Collection.new(
    select { |a| a.tags.map(&:downcase).include?(tag.downcase) }
  )
end

The hidden assumption:

Every tag
   ↓
must respond to #downcase

If one doesn't:

NoMethodError
   ↓
request fails
   ↓
user cannot follow the newsletter tag

After

def by_tag(tag)
  Collection.new(
    select { |a| a.tags.any? { |tag_value| tag_value.to_s.casecmp?(tag) } }
  )
end

Now:

Tag value
   ↓
convert safely to String
   ↓
case-insensitive comparison
   ↓
match / no match

The existing filtering behavior remains intact while the unsafe type assumption is removed.

Why This Bug Was Easy to Miss

This is what I found most interesting about the issue.

The original code isn't obviously bad.

For a dataset containing only Strings, this is perfectly reasonable Ruby:

a.tags.map(&:downcase)

The problem only appears when the runtime data doesn't match the assumption made by the implementation.

That's a common class of bugs:

Code assumption
       ↓
"this value will always be a String"
       ↓
Works for normal data
       ↓
Unexpected value enters the system
       ↓
Runtime failure

The lesson isn't:

"Never use downcase."

It's:

Know where your assumptions about data types are coming from.

If a method operates on data that can contain different types, the boundary where those values are consumed should be resilient.

The Investigation

What made this issue useful as a debugging exercise was that the final code change was small.

The investigation was the interesting part.

Instead of only looking at the error message, I traced the behavior back to the collection filtering logic.

That led to a few questions:

What type can each tag actually contain?
Why does downcase fail?
Do we really need to transform every tag?
Can the comparison itself be made type-safe?
Can the existing behavior be preserved without changing the surrounding code?

Once those questions were answered, the fix became much simpler.

The problem wasn't complicated business logic.

It was an unsafe assumption about the data.

The Final Change

The actual change was intentionally small:

- Collection.new(select { |a| a.tags.map(&:downcase).include?(tag.downcase) })
+ Collection.new(select { |a| a.tags.any? { |tag_value| tag_value.to_s.casecmp?(tag) } })

One line changed.

But that one line removed the assumption that every tag value was already a String.

I also fixed a linting issue in a follow-up commit.

The pull request was reviewed by the RubyEvents maintainer, passed all checks, and was merged into the project's main branch.

Issue

1836 — Cannot Click tags on Newsletter

Pull Request

1847 — Fix tag filtering for non-string tags

What I'm Proud Of

The final diff is tiny.

That's actually what I like about this fix.

There was no need to rewrite the filtering system or introduce another abstraction.

The existing behavior was already correct for valid String values.

The problem was the assumption around those values.

So instead of changing the entire flow, the fix:

keeps the existing behavior
makes the comparison type-safe
avoids unnecessary array allocation
expresses the intent with any?
uses casecmp? for case-insensitive comparison
keeps the change isolated to the filtering method

Small change, focused responsibility.

What I Learned

Small bugs can expose bigger assumptions

The code wasn't complicated.

The assumption behind the code was the real problem.

Whenever I see code such as:

items.map(&:some_method)

I now ask myself:

Do I know for certain that every item responds to this method?

That question becomes particularly important at boundaries where data may come from different sources.

Fix the behavior, not just the exception

It would have been easy to focus only on preventing the NoMethodError.

But a good fix should do more:

preserve existing behavior
make the comparison safe
make the intent clearer
avoid unnecessary transformations

The final implementation does all four.

Express the question you're actually asking

Compare:

map(...).include?(...)

with:

any? { ... }

The second version tells the reader what we're actually asking.

We're not interested in producing another collection.

We're asking whether any tag matches.

That makes the code easier to reason about and maintain.

Open source debugging is different

One thing I enjoy about contributing to open source is that you get to work with code outside the assumptions of your own applications.

You don't necessarily know every historical decision behind a method.

You don't know every shape of data that has passed through it.

And you don't get to rewrite the whole system just because you find one imperfect assumption.

You have to understand the existing behavior, make the smallest responsible change, and verify that the fix doesn't break what was already working.

That's what made this issue interesting to me.

The final diff was tiny.

The reasoning behind it was not.

The Takeaway

A bug doesn't always announce itself with a complicated stack trace or a thousand-line fix.

Sometimes it's hidden inside a single assumption:

"Every tag is a String."
When that assumption stopped being true, clicking a newsletter tag stopped working.

The fix was to make the comparison type-safe, preserve case-insensitive matching, and express the filtering intent more directly.

One line changed. One user-facing failure removed. One more reminder that robust software is often about handling the values we didn't expect.

Related Code

Issue:
1836 — Cannot Click tags on Newsletter

Pull Request:
1847 — Fix tag filtering for non-string tags