DEV Community: Yashika Vijayvargiya

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

What Is Ponytail? A Beginner’s Guide to the AI Coding Companion Everyone Is Talking About

Yashika Vijayvargiya — Wed, 05 Aug 2026 09:29:26 +0000

⚠️ Note: AI developer tools evolve incredibly fast. Installation steps, supported editors, AI models, and configuration options may change over time. This article is not intended to be official documentation . Instead, its goal is to help you understand what Ponytail is, why it exists, and when you might want to use it . Before installing or configuring Ponytail, always refer to its official documentation for the latest instructions.

Introduction

If you’ve recently spent time on X (Twitter), Reddit, or developer communities, you’ve probably seen people talking about Ponytail.

Some developers call it an AI coding assistant.

Others think it’s an alternative to Cursor.

Some believe it’s a replacement for Claude Code.

And many assume it’s another Large Language Model (LLM) like ChatGPT or Claude.

None of these descriptions are entirely accurate.

This confusion exists because Ponytail is different from most AI tools developers are familiar with.

In this article, we’ll break down exactly what Ponytail is, what it is not, how it fits into the AI coding ecosystem, and when it makes sense to use it.

The Biggest Misconception About Ponytail

The first thing to understand is this:

Ponytail is not an AI model.

It cannot answer questions by itself.

It cannot generate code by itself.

It cannot replace ChatGPT, Claude, Gemini, or any other language model.

Instead, Ponytail works alongside an AI coding agent.

Think of it as a layer that influences how the AI approaches programming tasks.

Understanding the AI Coding Ecosystem

Many developers mix together editors, AI models, and coding agents.

These are different pieces of the puzzle.

Imagine you’re building a Rails application.

You have:

VS Code
    ↓
AI Coding Agent
    ↓
LLM (Claude / GPT / Gemini)

Each layer has a different responsibility.

VS Code

VS Code is simply your editor.

It doesn’t understand your code or generate anything on its own.

AI Model

Claude

GPT

Gemini

These are language models.

They understand natural language and generate code.

However, by themselves they don’t know how to edit files inside your project or interact with your development environment.

AI Coding Agent

An AI coding agent connects your editor to an AI model.

It can:

Read project files
Edit code
Create new files
Run commands
Analyze your repository
Suggest refactoring
Generate tests

Examples include various AI-powered coding assistants and editor integrations.

Ponytail

Ponytail sits on top of this workflow.

Instead of replacing your AI, it attempts to improve how the AI behaves while writing code.

An Analogy

Imagine you’re hiring a software engineer.

Without guidance, they might:

create unnecessary abstractions
introduce extra classes
over-engineer a simple solution
use complex design patterns for small problems

Now imagine giving that engineer a document that says:

Keep things simple.
Don’t create classes unless necessary.
Prefer existing libraries.
Avoid unnecessary complexity.
Write code another developer can understand quickly.

The engineer hasn’t changed.

Their instructions have.

Ponytail plays a similar role for AI coding assistants.

What Problem Does Ponytail Solve?

As AI became better at writing code, developers noticed recurring issues.

The AI often:

creates more files than necessary
writes excessive boilerplate
introduces unnecessary abstractions
overuses design patterns
invents helper classes
makes small tasks more complicated than they need to be

Sometimes this is useful.

Often it isn’t.

Ponytail aims to steer the AI toward simpler, more maintainable solutions.

What Ponytail Is NOT

Ponytail is not :

another version of ChatGPT
another LLM
a replacement for Claude
a replacement for Cursor
an IDE
a code editor
a compiler

Understanding this distinction removes most of the confusion.

Can Ponytail Work Without an AI?

No.

If you only install Ponytail, nothing happens.

You still need an AI coding agent backed by an AI model.

Think of it like this:

VS Code
❌

VS Code + Ponytail
❌

VS Code + AI Agent
✅

VS Code + AI Agent + Ponytail
✅

Does Ponytail Replace Cursor?

No.

Cursor is a complete AI-powered editor.

Ponytail is not.

Cursor provides:

editor integration
AI chat
autocomplete
repository understanding

Ponytail focuses on influencing how an AI coding assistant approaches problems rather than replacing the editor itself.

Does Ponytail Replace Claude?

No.

Claude is the intelligence.

Ponytail provides guidance.

Without Claude (or another supported model), Ponytail has nothing to reason with.

Does Ponytail Reduce Token Usage?

This is one of the most common questions.

The answer is:

Not directly.

Ponytail does not magically reduce the number of tokens consumed.

However, by encouraging the AI to produce smaller, simpler solutions with fewer unnecessary edits, some workflows may naturally involve fewer generated tokens.

This depends on:

the AI model
the coding task
the prompts
the agent’s behavior

So any reduction is a side effect of simpler outputs, not a guaranteed feature.

Is Ponytail Free?

Ponytail itself has generally been made available as an open-source project.

However, remember:

Using Ponytail does not eliminate the need for an AI model.

If your coding assistant relies on a paid AI service or API, those costs still apply.

Think of Ponytail as improving the workflow rather than replacing the underlying AI.

When Should You Use Ponytail?

Ponytail can be valuable when:

working on large production codebases
contributing to open-source projects
maintaining mature Rails applications
reviewing AI-generated code
encouraging simpler implementations
reducing unnecessary abstractions

These are situations where readability and maintainability often matter more than generating the maximum amount of code.

When Should You Avoid It?

Ponytail may not add much value if you’re:

learning programming from scratch
writing small throwaway scripts
experimenting with new ideas
using AI only for quick code snippets

In these cases, a standard AI assistant may already be sufficient.

A Rails Example

Suppose you ask your AI:

“Optimize this ActiveRecord query.”

Without guidance, the AI might introduce several service objects, helper modules, and layers of abstraction.

With a “keep it simple” philosophy, the AI is more likely to suggest:

adding the correct index
using includes
avoiding N+1 queries
simplifying the ActiveRecord chain
making a small, focused improvement

This often aligns well with how experienced Rails developers prefer to evolve applications.

Frequently Asked Questions

Is Ponytail another AI?

No.

Can Ponytail write code?

Not by itself.

Does Ponytail work without Claude or another AI model?

No.

Does Ponytail replace Cursor?

No.

Does Ponytail replace VS Code?

No.

Is Ponytail a code editor?

No.

Does Ponytail guarantee better code?

No. It provides guidance, but you should always review AI-generated code before merging it into production.

Final Thoughts

AI-assisted development is evolving at an incredible pace. New models, editors, and coding agents appear regularly, and the surrounding ecosystem changes just as quickly.

Ponytail is best thought of as a way to influence how an AI coding assistant approaches software development , encouraging simpler, more maintainable solutions rather than acting as a new AI model or editor.

Whether Ponytail becomes part of your daily workflow depends on your projects, your preferred tools, and how much you value AI-generated code that favors clarity over complexity.

As with any AI tool, the most important skill isn’t learning a specific product — it’s understanding where that product fits into the broader development workflow.

If this article introduced you to Ponytail for the first time, take a few minutes to explore its latest documentation, experiment with it in a small project, and decide whether its philosophy aligns with the way you like to build software.

Part 3: Optimistic Locking in Rails – Preventing Lost Updates Without Blocking Users

Yashika Vijayvargiya — Fri, 31 Jul 2026 10:49:53 +0000

Introduction

In the previous article, we learned how Pessimistic Locking prevents concurrent modifications by locking database rows.

While this guarantees data consistency, it also means other users may have to wait until the lock is released.

But what if conflicts are rare?

Should we still lock every row?

Probably not.

This is where Optimistic Locking comes in.

Instead of preventing concurrent updates, Optimistic Locking allows multiple users to edit the same record and detects conflicts only when they try to save their changes.

It assumes that conflicts are unlikely, making it a great choice for many web applications.

What is Optimistic Locking?

Definition

Optimistic Locking is a concurrency control strategy that allows multiple transactions to read and modify the same record without acquiring database locks.

Before saving changes, Rails checks whether the record has been modified by another transaction.

If it has, Rails raises an exception instead of silently overwriting the newer data.

In simple words:

"I believe no one else will modify this record. But before saving, I'll verify that assumption."

Why Do We Need Optimistic Locking?

Imagine an admin panel.

Two administrators open the same product.

Current Product:

Title: iPhone 16
Price: ₹80,000

Admin A changes:

Price → ₹75,000

Admin B changes:

Title → iPhone 16 Pro

Without optimistic locking:

Admin A saves.

Database:

Title: iPhone 16
Price: ₹75,000

A few seconds later...

Admin B saves.

Database becomes:

Title: iPhone 16 Pro
Price: ₹80,000

Admin A's update is lost.

This is called a Lost Update.

How Rails Solves This

Rails provides built-in support for Optimistic Locking using a column named:

lock_version

Whenever a record is updated:

Rails increments lock_version
Rails verifies the previous version before updating
If the version has changed, Rails raises an exception

Enabling Optimistic Locking

Simply add a column:

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

That's it.

Rails automatically enables optimistic locking.

No additional configuration is required.

Example

Current row:

Admin A loads:

lock_version = 0

Admin B also loads:

lock_version = 0

Admin A updates:

product.price = 75000
product.save!

Database:

Notice:

lock_version

became

Now Admin B tries:

product.title = "iPhone Pro"

product.save!

Rails generates SQL similar to:

UPDATE products SET title = 'iPhone Pro', lock_version = 2 WHERE id = 1 AND lock_version = 0;

But the database contains:

lock_version = 1

Therefore:

0 rows updated

Rails raises:

ActiveRecord::StaleObjectError

Timeline

Admin A

Read Product

Version = 0

↓

Edit

↓

Save

Version becomes 1

----------------------------

Admin B

Read Product

Version = 0

↓

Edit

↓

Try Save

↓

StaleObjectError

What Happens Internally?

Suppose current version:

lock_version = 3

Rails updates using:

UPDATE products
SET
price = 100,
lock_version = 4
WHERE
id = 1
AND lock_version = 3;

If another transaction already updated it:

lock_version = 4

The WHERE condition fails.

No row is updated.

Rails knows someone modified the record.

Handling the Exception

Typical implementation:

begin
  product.update!(product_params)

rescue ActiveRecord::StaleObjectError

  flash[:alert] =
    "This product was updated by another user. Please reload and try again."

  redirect_to edit_product_path(product)
end

Instead of silently overwriting data, the user is informed.

Real Production Example 1

CMS Article Editing

Two editors modify the same article.

Without optimistic locking:

One editor overwrites another's work.

With optimistic locking:

Second editor sees:

"This article has changed since you opened it."

Real Production Example 2

Admin Dashboard

Inventory manager changes:

Stock = 15

Manager B changes:

Price = ₹500

Instead of losing one update,

Rails detects the conflict.

Real Production Example 3

User Profile

Editing profile:

Name
Bio
Address

Conflicts are rare.

Blocking users would hurt UX.

Optimistic locking is a better fit.

Advantages

✅ No waiting

✅ Better scalability

✅ Better user experience

✅ No database locks

✅ Great for read-heavy applications

Disadvantages

❌ Save may fail

❌ Users must retry

❌ Not suitable for financial systems

❌ Doesn't prevent concurrent reads

Optimistic vs Pessimistic Locking

Understanding Database Locking in Ruby on Rails: Types, Examples, and Best Practices

Yashika Vijayvargiya — Wed, 15 Jul 2026 08:39:39 +0000

Goal of this article: Build a strong foundation before learning pessimistic locking, optimistic locking, deadlocks, and isolation levels.

When I started working with production Rails applications, I realized that most database problems were not caused by missing indexes but by concurrent requests modifying the same data. Understanding locking completely changed the way I design payment, inventory, and booking systems.

What is a lock?

A lock is a mechanism used by PostgreSQL to protect data from being modified incorrectly by multiple transactions at the same time.

In simple words:

A lock tells other transactions: “Someone is currently working with this data. Wait your turn.”

Imagine two people editing the same Google Doc at the same moment. Without coordination, one person’s changes could overwrite the other’s. Databases use locks to prevent similar problems.

Why do databases need locking?

Suppose an e-commerce application has only 1 item left in inventory.

Without locking, both requests may read:

Both transactions believe the product is available and both place an order.

Result:

This is called a race condition.

What is a race condition?

A race condition occurs when the final result depends on the timing of concurrent operations.

Example

If two requests execute this code simultaneously, both may read the same inventory value before either update occurs.

This is the fundamental problem locking is designed to solve.

Transactions: The Foundation of Locking

Locks exist inside database transactions.

A transaction guarantees that all operations inside the block either:

Succeed together (COMMIT)
Fail together (ROLLBACK)

Locks are typically acquired when the transaction begins modifying or explicitly locking rows.

How PostgreSQL Handles Concurrent Transactions

Consider two transactions.

PostgreSQL automatically prevents both transactions from modifying the same row simultaneously.

MVCC: Why SELECT Usually Doesn’t Block

One of PostgreSQL’s most important features is MVCC (Multi-Version Concurrency Control).

Instead of blocking readers, PostgreSQL creates multiple versions of rows.

Example

Transaction A updates a product but has not committed yet.

At the same time, Transaction B runs:

Transaction B usually does not wait. It reads the previous committed version of the row.

This is why PostgreSQL can handle many readers efficiently.

Common Concurrency Problems

1. Lost Update

Very common

Problem: Two users overwrite each other’s changes.

Correct result should be: $30

Actual result: $50

2. Dirty Read

Usually prevented in PostgreSQL

Reading data that another transaction has modified but not committed.

PostgreSQL’s default isolation level (Read Committed) prevents this.

3. Non-repeatable Read

Possible in Read Committed

You read the same row twice and get different values because another transaction committed between the reads.

4. Phantom Read

Isolation-level issue

A query returns a different set of rows the second time it runs because another transaction inserted matching records.

Rails Example: Preventing Double Booking

Unsafe code:

Safe code using locking:

What changed?

generates:

This acquires a row-level lock so only one transaction can modify that event record at a time.

Visual Timeline

Important Insight: PostgreSQL Uses Multiple Lock Types

Many beginners think there is only one lock.

In reality PostgreSQL has:

We’ll explore these deeply in later parts of the series.

How to See Locks in Production

PostgreSQL exposes lock information through pg_locks.

A more useful query:

This helps identify which transaction is holding a lock and which transaction is waiting.

Key Takeaways

Locks prevent race conditions and data corruption.

Locks exist inside transactions.

PostgreSQL uses MVCC so readers usually do not block writers.

Row locks protect individual records.

Table locks protect entire tables.

FOR UPDATE is the foundation of pessimistic locking in Rails.

Most production concurrency bugs are caused by missing transactions or missing locks.

Interview Question

Why does PostgreSQL allow many SELECT queries to run without blocking each other?

Answer: PostgreSQL uses MVCC (Multi-Version Concurrency Control). Instead of blocking readers, it keeps multiple versions of rows so a SELECT query can read the last committed version while another transaction is updating the row. This greatly improves concurrency and is one of PostgreSQL’s biggest advantages.

Next Article in the Series

Pessimistic Locking in Rails

We will dive into lock, with_lock, FOR UPDATE, NOWAIT, SKIP LOCKED, and real production examples such as inventory reservation and payment processing.

Originally published at https://railswithyashika.hashnode.dev on July 13, 2026.

PostgreSQL Index Types Explained with Real Rails Examples

Yashika Vijayvargiya — Thu, 02 Jul 2026 08:00:26 +0000

Part-1 Understanding Indexes before learning Index Types

Now that we understand what indexes are and why they matter, let’s explore the different types of indexes available in PostgreSQL and when to use them in Rails applications.

1. Single Column Index

The simplest and most commonly used index.

Query

User.find_by(email: "john@example.com")

Migration

add_index :users, :email

SQL Generated

CREATE INDEX index_users_on_email ON users(email);

When to Use

Email lookups
SKU lookups
UUID searches
Foreign keys

Real Example

Product.find_by(sku: params[:sku])

Without an index, PostgreSQL scans the entire table.

With an index, PostgreSQL can jump directly to the matching row.

2. Unique Index

A unique index improves lookup performance while also preventing duplicate values.

Migration

add_index :users, :email, unique: true

What It Solves

Prevents:

john@example.com
john@example.com

Common Use Cases

Email addresses
Usernames
External IDs
API tokens

Rails Validation vs Database Constraint

Many developers write:

validates :email, uniqueness: true

This is not enough.

Always add a database unique index because validations can be bypassed during race conditions.

3. Composite (Multi-column) Index

Used when queries filter using multiple columns.

Query

Order.where(user_id: 1, status: "paid")

Migration

add_index :orders, [:user_id, :status]

Important Rule

Index order matters.

[:user_id, :status]

Works efficiently for:

WHERE user_id = 1

WHERE user_id = 1
AND status = 'paid'

But not for:

WHERE status = 'paid'

Real Example

In e-commerce:

Order.where(user_id: current_user.id, status: "completed")

4. Partial Index

Indexes only a subset of rows.

Migration

add_index :users, :email, where: "active = true"

Example Query

User.where(active: true)

Why Use It?

Suppose:

10 million users
9 million inactive 
1 million active

Creating an index only for active users makes the index:

Smaller
Faster
Less memory intensive

Common Uses

Soft deletes
Active records
Published content
Pending jobs

5. Index with Order

Optimizes sorting operations.

Query

Product.order(created_at: :desc)

Migration

add_index :products, :created_at, order: { created_at: :desc }

Benefits

Useful for:

Product.order(created_at: :desc).limit(20)

Common in:

News feeds
Activity logs
Product listings

6. GIN Index

GIN stands for Generalized Inverted Index.

Used for:

JSONB
Arrays
Full-text search

JSONB Example

add_index :users, :preferences, using: :gin

Query

WHERE preferences @> '{"theme":"dark"}'

Real Rails Example

User.where("preferences @> ?", { theme: "dark" }.to_json)

Without GIN indexes, JSONB searches become slow as data grows.

7. Full Text Search Index

PostgreSQL can act as a search engine.

Migration

add_index :articles, "to_tsvector('english', content)", using: :gin, name: "index_articles_on_content_search"

Query

SELECT * FROM articles WHERE to_tsvector('english', content) @@ plainto_tsquery('rails indexing');

Useful For

Blogs
Documentation sites
Product search
Knowledge bases

8. Concurrent Index

One of the most important production techniques.

Problem

Running:

add_index :users, :email

on a huge table can lock writes.

Solution

class AddIndexToUsersEmail < ActiveRecord::Migration[8.0] 
  disable_ddl_transaction!
  def change 
    add_index :users, :email, algorithm: :concurrently 
  end 
end

Benefits

No downtime
No table lock
Safe for production

Real World

Never add indexes to large production tables without considering concurrent creation.

9. Expression Index

Indexes a calculated value instead of a column.

Query

User.where("LOWER(email) = ?", email.downcase)

Migration

add_index :users, "LOWER(email)", name: "index_users_on_lower_email"

Benefits

Supports fast:

Case-insensitive searches
Date transformations
String manipulations

10. Covering Index (INCLUDE)

Introduced to reduce table lookups.

Migration

add_index :orders, :user_id, include: [:status, :total]

Why Useful?

Query:

Order.select(:status, :total) .where(user_id: current_user.id)

PostgreSQL can answer directly from the index.

This is called an Index Only Scan.

Benefits

Fewer disk reads
Faster queries

11. BRIN Index

BRIN stands for Block Range Index.

Designed for huge tables.

Migration

add_index :events, :created_at, using: :brin

Best For

Logs
Analytics data
Audit records
Time-series events

Why?

Instead of storing every value, BRIN stores summaries for ranges of pages.

Result:

Extremely small indexes
Very low maintenance overhead

Example

100 million events

A BRIN index may be only a few MBs compared to hundreds of MBs for a B-tree index.

12. Hash Index

Optimized for equality lookups.

Migration

add_index :users, :email, using: :hash

Query

WHERE email = 'john@example.com'

Limitation

Does not support:

<
>
BETWEEN
ORDER BY

Because B-tree indexes support more operations, Hash indexes are rarely used.

Which Index Should You Choose?

Final Thoughts

Indexes are not about adding them everywhere.

A good database engineer first identifies:

Slow queries
Query patterns
Filter columns
Sort columns
Join columns

Then chooses the index that matches the workload.

Always verify improvements using:

EXPLAIN ANALYZE

and remember that every index speeds up reads but adds overhead to writes. The best indexing strategy is the one that balances both.

Concurrent Indexes: https://railswithyashika.hashnode.dev/postgresql-concurrent-indexes-in-rails-avoiding-downtime-in-production

Originally published at https://railswithyashika.hashnode.dev on July 1, 2026.

Understanding Indexes Before Learning Index Types

Yashika Vijayvargiya — Wed, 01 Jul 2026 07:59:39 +0000

Before diving into different types of indexes, let’s understand why indexes are needed.

Imagine a library with 100,000 books.

If someone asks for a book named “Clean Code”, there are two ways to find it:

Without an Index

You start from the first shelf and check every book one by one until you find the required book.

This approach is similar to a Sequential Scan in PostgreSQL.

SELECT * FROM books
WHERE title = 'Clean Code';

PostgreSQL may need to scan every row in the table to find matching records.

As the table grows from thousands to millions of rows, query performance degrades significantly.

With an Index

Now imagine the library has a catalog that stores:

Clean Code → Shelf A12
The Pragmatic Programmer → Shelf B03
Refactoring → Shelf C08

Instead of checking every book, you first look at the catalog and immediately jump to the correct shelf.

This catalog is similar to a database index.

An index stores selected column values in a structure that allows PostgreSQL to locate rows much faster than scanning the entire table.

Why Not Index Every Column?

A common beginner question is:

If indexes make queries faster, why not create indexes everywhere?

Indexes improve read performance, but they come with a cost.

Whenever data changes, PostgreSQL must update both:

The table data
Every related index

For example:

User.create!(email: "john@example.com")

If the users table has 10 indexes, PostgreSQL must update all 10 indexes during the insert operation.

This means:

More storage usage
Slower INSERT operations
Slower UPDATE operations
Slower DELETE operations

Because of this trade-off, indexes should be added only for queries that are frequently executed and benefit from faster lookups.

How PostgreSQL Uses an Index

Suppose we have:

add_index :users, :email

And run:

SELECT *
FROM users
WHERE email = 'john@example.com';

Without an index:

Seq Scan on users

With an index:

Index Scan using index_users_on_email

The database can jump directly to matching records instead of examining every row.

A Simple Rule

Create an index when a column is frequently used in:

WHERE clauses
JOIN conditions
ORDER BY clauses
GROUP BY clauses

Examples:

User.find_by(email: email)

Order.where(user_id: current_user.id)

Product.order(created_at: :desc)

Lead.where(status: "active")

These are strong candidates for indexing.

How to Verify an Index Is Being Used

Never assume PostgreSQL is using your index.

Use:

EXPLAIN ANALYZE
SELECT *
FROM users
WHERE email = 'john@example.com';

Look for:

Index Scan

instead of:

Seq Scan

This confirms PostgreSQL is benefiting from the index.

Understanding these fundamentals makes it much easier to choose the right indexing strategy, whether it is a simple B-Tree index, a composite index, a GIN index for JSONB data, or a BRIN index for massive datasets.