Event-Driven Architecture (EDA) is an architectural paradigm where software components communicate by publishing and consuming state changes called events.

• An Event represents an immutable record of a past occurrence within the business domain (e.g., UserRegistered, OrderPlaced, PaymentFailed).

• Producers emit events without knowing which downstream services will consume them or what actions will be taken.

Key Components of EDA

1. Event Producer: The component that detects state changes (e.g., a user signing up) and packages that change into a structured event payload.

2. Event Router / Broker: The messaging backbone (such as Apache Kafka, RabbitMQ, AWS EventBridge, or Redis Streams) responsible for ingesting, queuing, and routing events to subscribers.

3. Event Consumer: Independent worker services or microservices that listen for specific events and perform downstream processing.

4. Event Payload: The structured JSON/Avro data containing metadata (event ID, timestamp, schema version) and contextual business attributes.

Where is EDA Helpful? (Real-World Use Cases)

• E-Commerce Order Workflows: Processing an order requires multiple side effects (inventory reservation, payment gateway charging, fraud scanning, dispatching emails). EDA handles these side effects asynchronously without delaying the user's checkout response.

• Real-Time Analytics & Telemetry: Ingesting continuous streams of data (clickstream data, IoT sensor metrics, financial market ticks) with minimal latency.

• Asynchronous & Heavy Background Jobs: Offloading computationally intensive tasks (e.g., video rendering, image processing, or PDF report generation) from the main web server thread.

• Microservices Integration: Allowing multiple microservices maintained by distinct engineering teams to react to common domain events without creating tightly coupled dependencies.

Key Benefits of EDA

Drawbacks and Implementation Challenges

• Eventual Consistency: Trading strict single-database ACID transactions for eventual consistency across distributed datastores requires handling race conditions and potential data lag.

• Complex Tracing & Debugging: Troubleshooting failures across asynchronous topics requires distributed tracing frameworks like OpenTelemetry and centralized correlation IDs.

• Handling Consumer Failures: If a consumer encounters an uncaught exception, events can be lost or stuck in infinite retry loops if proper patterns are not established.

Retries & Dead Letter Queue (DLQ) Pattern

To ensure high reliability, enterprise implementations combine Exponential Backoff Retries with a Dead Letter Queue (DLQ):

Production Node.js Implementation Pattern

import { EventEmitter } from 'events';

class ResilientEventBus extends EventEmitter {}
const eventBus = new ResilientEventBus();

// Resilient Consumer with Exponential Backoff and DLQ routing
eventBus.on('userRegistered', async (eventPayload) => {
    const processWithRetry = async (attempt = 1) => {
        try {
            console.log(`[Attempt ${attempt}] Processing welcome email for: ${eventPayload.email}`);
            
            // Simulating an unreliable third-party API call
            if (Math.random() < 0.6) {
                throw new Error("SMTP Gateway Connection Timeout");
            }
            
            console.log(`[SUCCESS] Email sent to ${eventPayload.email}`);
        } catch (error) {
            console.error(`[ERROR] Attempt ${attempt} failed: ${error.message}`);
            
            if (attempt < 3) {
                const backoffDelay = Math.pow(2, attempt) * 1000;
                console.log(`Retrying in ${backoffDelay}ms...`);
                setTimeout(() => processWithRetry(attempt + 1), backoffDelay);
            } else {
                console.error(`[CRITICAL] Max retries exhausted for event ID ${eventPayload.eventId}. Forwarding to DLQ.`);
                // Route payload to Dead Letter Queue storage or database for inspection
            }
        }
    };

    await processWithRetry();
});

// Triggering Event Producer
eventBus.emit('userRegistered', {
    eventId: 'evt_994821',
    userId: 'usr_102',
    email: 'gaurav@example.com',
    timestamp: Date.now()
});

Which Systems Are Best Suited for EDA?

System Fit Comparison

Best Suited For EDA:

• Complex distributed microservices with asynchronous background workloads.

• Real-time notification systems, live dashboards, and chat platforms.

• Event-driven workflows with high throughput requirements (e.g., Kafka streaming).

Poorly Suited For EDA:

• Simple CRUD web applications with low traffic volumes.

• Workflows requiring immediate synchronous confirmation before proceeding (e.g., verifying a 2FA authentication token).

• Monolithic applications maintained by single small teams where adding message broker infra increases operational complexity unnecessarily.

That mindset works fine for a normal system — an API, a script, a CRUD endpoint. No error, no crash, ship it. But RAG isn't that. Your search can run clean, return a full result set, zero exceptions, 200 all the way — and still be quietly handing your model the wrong chunks. "It didn't crash" tells you nothing about whether it actually found the right stuff. For that you need a different set of metrics, ones built specifically to answer "is my retrieval actually relevant," not "did my code run."

So in this post we're going to break down exactly those metrics, one by one, with real examples:

• Precision@K — of what you retrieved, how much was actually useful

• Recall@K — of everything relevant out there, how much did you actually find

• MRR — how fast did you find the first relevant chunk

• MAP@K — how good is the ranking across all relevant chunks, not just the first one

• NDCG@K — how close to a perfect ranking, when some chunks are more relevant than others

And once retrieval's covered, we'll also get into how it connects to the generation side — faithfulness, answer relevance — plus how to build a golden dataset and use an LLM as a judge to actually score all this stuff automatically.

Two different failure modes, one bad answer

When a RAG system gives a wrong answer, there are two places it could have gone wrong, and conflating them is the single most common mistake in RAG debugging:

A bad answer could mean the retriever never found the right chunk (a retrieval failure) — in which case no generation model on earth could have answered correctly, it never saw the information.

Or it could mean retrieval did its job and handed over the right chunk, but the model ignored it, misread it, or made something up anyway (a generation failure). These need separate metrics because the fix is completely different: one is a search-tuning problem, the other is a prompting problem.

This article covers only retrieval side metrices in depth.

The big picture: one ranked result, five ways to score it

Every metric below is a different way of scoring the exact same thing: a ranked list of retrieved chunks, checked against a hand-labeled set of chunks that are actually relevant.

Four of the eight retrieved chunks are relevant, sitting at ranks 2, 4, 5, and 7. Every metric in this post is computed from this one picture — what changes is which ranks it looks at, and whether it cares about order at all.

Order-unaware metrics: precision@K and recall@K

Precision@K — of the K chunks you retrieved, how many are relevant?

Recall@K — of all relevant chunks that exist, how many did you actually find?

Neither metric cares where in the top-5 a relevant chunk landed — only whether it's inside the cutoff. That's their strength (simple, cheap to compute) and their weakness (a system that buries its one good chunk at rank 5 scores the same as one that puts it at rank 1, as long as both make the cutoff).

Recall@K only ever goes up as K grows. Push K to the size of your whole corpus and recall@K hits 1.0 trivially — you "found" everything because you retrieved everything. Always report recall at a realistic, fixed K (the K your reranker actually forwards to generation), and pair it with precision so a shameless K doesn't hide a bad system.

What precision@K and recall@K actually tell you

These two are less about ranking quality and more about two very different questions — one about noise, one about coverage — so it's worth reading them separately rather than as a single combined signal:

• Precision@K is a noise question: of everything you're handing to the generation model, how much of it is actually useful? Low precision means your context window is full of filler — chunks the model has to read past (or worse, get distracted by) to find the real answer. This matters most when you're feeding a fixed, small K into generation, since every irrelevant chunk in that K is wasted context budget.

• Recall@K is a coverage question: out of everything relevant that exists in your corpus, how much of it did retrieval even manage to surface? Low recall means the answer might not even be possible — no amount of good prompting or reranking can save you if the right chunk never made it into the candidate set at all. This is the metric that catches retrieval-stage blind spots, like an embedding model that consistently misses a certain phrasing of a question.

• Reading them together: high precision + low recall means retrieval is being too conservative — it's confident about the few chunks it returns, but missing others that exist. Low precision + high recall means the opposite — it's casting a wide net and catching everything relevant, but drowning it in noise. Neither number alone tells you which failure mode you're in; you need both.

Because neither metric is order-aware, they're best used as a first-pass health check — "is my candidate set roughly the right shape" — before reaching for MRR, MAP@K, or NDCG@K to judge whether that candidate set is ranked well. A system can have great precision@K and recall@K and still produce a bad user experience if the one relevant chunk out of five is sitting at rank 5 instead of rank 1 — which is exactly the gap the next section covers.

Order-aware: MRR, the "how fast did we find it" metric

MRR (Mean Reciprocal Rank) looks at one thing per query — the rank of the first relevant chunk — and scores it as 1 / rank, then averages across queries.

MRR is order-aware but first-hit-only — for the RRF query above, chunk_12 at rank 2 gives RR = 0.50, and MRR never looks past that point. Whatever happens at ranks 4, 5, and 7 (the other three relevant chunks in this example) is invisible to it. That blind spot is exactly what the next metric fixes.

What MRR actually tells you

A single MRR number is a proxy for "how much does the user have to scroll before they hit something useful." That makes it less an abstract IR score and more a direct read on system usability:

• MRR close to 1.0 — your top result is usually the right one. Users (and your generation step) rarely need to look past rank 1.

• MRR around 0.5 — the right chunk typically shows up around rank 2, on average. Retrieval is finding it, but it's not confident enough to put it first.

• MRR trending low (below ~0.3) — either the right chunk is buried deep, or it's missing from the top-K entirely for a chunk of your queries (remember, a query with zero relevant hits in the top-K contributes an RR of 0, dragging the average down hard).

Because MRR only credits the first hit, it's the metric to watch specifically when your downstream generation step only reads the first chunk or two before answering, or when you're tuning a reranker and want a fast, cheap signal for "is the single best answer floating to the top." It's a poor fit, though, for judging whether your system surfaces all the relevant context for a question — for that, keep reading.

MAP@K: the metric that doesn't stop at the first hit

MAP@K (Mean Average Precision) computes precision@k at every rank where a relevant chunk shows up, averages those numbers into a per-query score called Average Precision, then means that across all queries.

💡 Key point: on Query 1, MRR scored 0.50 (it stopped at rank 2) while AP scored 0.54 (it credited all four hits). If a reranker change moved chunk_22 from rank 7 up to rank 3, MRR wouldn't move at all — chunk_12 is still the first hit at rank 2 — but AP (and MAP@K) would go up, correctly rewarding the improvement. Use MAP@K whenever queries can have more than one relevant chunk, which is the normal case once a corpus has multi-chunk sections

What MAP@K actually tells you

MAP@K is a single number that summarizes ranking quality across your entire golden set, in a way that's sensitive to both "did we find the relevant chunks" and "did we rank them near the top." That combination makes it the metric most people report as the headline number when comparing two retrieval systems end-to-end.

• MAP@K close to 1.0 — nearly every relevant chunk for nearly every query is ranked at the very top. This is rare in practice and worth double-checking your golden set isn't too easy.

• MAP@K in the 0.5–0.7 range — a healthy, typical score for a working hybrid search + reranker setup: most queries get their relevant chunks reasonably high, but there's room to improve on the harder queries.

• MAP@K trending low — either relevant chunks are scattered deep in the ranking across many queries, or several queries are missing relevant chunks from the top-K entirely (each contributes an AP of 0, and those zeros drag the mean down fast).

Because MAP@K averages over every relevant chunk per query and every query in the set, it's the metric to reach for when you want one number to track over time as you tune chunking, embeddings, or reranking — a MAP@K that moves up after a change is a much stronger signal than a single query "looking better," since it means the improvement generalized across your whole golden set rather than fixing one query while quietly breaking another.

NDCG@K: when not all relevant chunks are equally relevant

Okay so here's the thing every metric so far has been ignoring: relevance isn't actually binary. A chunk isn't just "relevant" or "not relevant" — some chunks nail the answer, some are kinda-sorta related, and some are just noise that happens to share a keyword.

Precision@K, recall@K, MRR, MAP@K — none of them can tell the difference between "this chunk perfectly answers the question" and "this chunk mentions the topic in passing." NDCG@K (Normalized Discounted Cumulative Gain) is the metric built specifically to care about that difference.

To use it, every chunk in your golden set gets a graded relevance score instead of a yes/no — say, 0 (irrelevant), 1 (tangential), 2 (partial answer), 3 (nails it). Here's what the actual math looks like on 3 chunks with relevance scores 3, 2, and 0, shown across three different orderings:

Let's walk through what's actually happening here, because the log2 stuff looks scarier than it is:

1. First, figure out the best possible ranking. Sort your chunks by relevance, highest first — that's the "Ideal" lane at the top. Compute its DCG (more on that formula in a second), and call that number IDCG. It's your ceiling — the best score any ordering could ever get.

2. Then score whatever ordering retrieval actually gave you. Same formula, just applied to the real ranking. Each chunk's relevance score gets divided by log2(rank + 1) — so a relevance-3 chunk sitting at rank 1 contributes a full 3.0, but that exact same chunk sitting at rank 3 only contributes 1.5. Same chunk, same "goodness," way less credit — because it's buried where fewer people will actually see it.

3. Divide actual by ideal. That's NDCG. In Ordering A, retrieval nailed the ideal ranking exactly, so DCG matches IDCG and NDCG = 1.00 — perfect score. In Ordering B, retrieval buried the single best chunk (relevance 3) all the way at rank 3, so DCG drops to 2.76 and NDCG drops to 0.65.

The whole point: NDCG doesn't just ask "did you find the good stuff," it asks "did you put the best stuff first." Two systems can retrieve the exact same three chunks and still get very different NDCG scores, purely based on the order.

⚠️ Gotcha: NDCG needs graded relevance labels (e.g. 0–3) on every golden example, not just relevant/not-relevant. That's real extra annotation work on top of a binary golden set. It's the industry-standard metric for web search ranking, but it's reasonable to treat as future work until the golden dataset has graded labels — don't block a first eval pass on it.

What NDCG@K actually tells you

Basically, NDCG is the metric for when "we found the relevant chunk" isn't good enough on its own and you actually care about quality of match, not just presence.

• NDCG@K close to 1.0 — your retrieval isn't just finding relevant stuff, it's putting the best stuff right at the top, close to the ideal ordering. This is what you want feeding into generation, since the model's most likely to lean on whatever's in the first slot or two.

• NDCG@K noticeably lower than your MAP@K — this is the tell that your system is finding relevant chunks (MAP looks fine) but not distinguishing great chunks from okay chunks in how it ranks them. A reranker tuned only on binary relevance can hit this exact gap.

• NDCG@K trending low across the board — either your best chunks are consistently getting buried, or your relevance grading itself needs a second pass (inconsistent grading tanks NDCG fast since it's so sensitive to the relative ordering of scores).

Use it when you've got graded relevance to spend on, and especially when "close enough" chunks genuinely aren't as good as the perfect one — which, if you're citing sources or answering precise technical questions (exactly your case), is basically always.

Building a golden dataset that doesn't lie to you

None of the above metrics mean anything without a trustworthy golden set to check against — and the construction choices here matter more than people expect.

Why the golden dataset matters

Every single metric in this post — precision@K, recall@K, MRR, MAP@K, NDCG@K, even the faithfulness/relevance judge prompts — is computed relative to the golden set. There's no such thing as "precision" in the abstract; it's always "precision against these specific labeled examples." Which means the golden set isn't a one-off checklist item you build once and forget — it's the ruler you'll keep re-using every time you touch retrieval

Two rules worth holding firm on:

• Hand-label, don't LLM-generate. LLM-generated Q&A pairs tend to reuse the source chunk's exact phrasing, which inflates retrieval scores relative to how a real user would actually ask. It also introduces self-grading bias if the same model later judges its own generated questions.

• Reference real chunk_ids from the live table, not paraphrased summaries. This keeps the golden labels valid as ground truth even as embedding models or rerankers get swapped out underneath.

20–30 diverse examples — mixing factual lookup, comparison, "how does X work," and known edge cases (like a section that got split across chunk boundaries) — is enough for a credible first benchmark. More examples matter less than covering different query shapes.

Summary

The practical starting point: precision@K, recall@K, and MRR for a first pass, MAP@K once queries can have multiple relevant chunks, and NDCG@K once the golden set has graded relevance labels rather than binary ones.

Most tutorials treat "search" as a black box: throw text at a vector database, get chunks back. But there are five distinct families of search algorithms in production RAG systems today, each solving a different retrieval failure mode. Picking the right one — or the right combination — is the single highest-leverage decision in a RAG pipeline.

This post walks through each family: how it works, a diagram of the mechanism, the best use case, and a worked example.

1. Keyword (Lexical) Search — Matching Characters, Not Meaning

Lexical search treats text as strings. It doesn't understand that "car" and "automobile" mean the same thing — it only knows whether the same tokens appear in the query and the document.

TF-IDF — The Starting Point

TF-IDF is the original mathematical approach to lexical relevance. It scores a term in a document using two factors:

term frequency (how often the word appears in that document) and

inverse document frequency (how rare the word is across the whole corpus — common words like "the" get down-weighted, rare words get boosted).

The drawback: TF-IDF has no length normalization. A term appearing 5 times in a 50-word document and 5 times in a 5,000-word document gets scored the same way, even though the first is clearly far more "about" that term. This means very long documents can be unfairly penalized or short documents unfairly boosted, purely as an artifact of length rather than actual relevance.

Best for: simple keyword scoring where all documents are roughly the same length, or as a teaching baseline. In practice, most production systems have moved past it for the reason above.

BM25 (Best Matching 25) — Fixing TF-IDF's Length Problem

BM25 keeps the same core idea as TF-IDF — term frequency weighted by inverse document frequency — but adds length normalization, so a document doesn't score higher just because it's longer, and diminishing returns on term frequency, so a word appearing 50 times doesn't score 10x higher than one appearing 5 times. This is why BM25 replaced TF-IDF as the industry-standard lexical algorithm.

Best for: exact identifiers — part numbers, error codes, SKUs, legal citations, API method names — anything where a semantic model might "helpfully" match a conceptually similar but factually wrong result.

Example: A support agent searches "error code E4021." A vector search might return docs about "connection timeout errors" in general (semantically close but wrong). BM25 returns only the doc that literally contains "E4021," because it's matching the exact token.

2. Dense Vector (Semantic) Search — Matching Meaning, Not Characters

Instead of comparing strings, dense retrieval converts text into embeddings — high-dimensional vectors where semantically similar text ends up numerically close together. The retrieval problem then becomes "find the nearest vectors," which is where the index algorithms below come in.

Exhaustive k-NN — The Naive Baseline

The simplest possible approach: compare the query vector against every single vector in the database and return the closest matches. This is brute-force search.

The drawback: it's 100% accurate — there's no approximation, so you always get the true nearest neighbors — but the cost scales linearly with the number of vectors. Past roughly hundreds of thousands of vectors, comparing against everything on every query becomes too slow for production latency budgets.

Best for: small corpora (a few thousand chunks) or as a correctness baseline when validating that a faster, approximate index isn't silently losing relevant results.

IVF (Inverted File Indexing) — Trading Some Accuracy for Speed

IVF's fix for exhaustive search's scaling problem is to pre-cluster the vector space (e.g., via k-means) into buckets ahead of time. At query time, instead of scanning every vector, it only searches the nearest cluster(s) to the query — a much smaller subset of the total data.

The drawback: because it only checks the nearest cluster(s), a true nearest neighbor that happens to sit just across a cluster boundary can be missed. It's faster than exhaustive search, but the accuracy/speed trade-off still isn't ideal for very high-dimensional, high-recall production workloads — which is what pushed the field toward graph-based indexes.

Best for: very large datasets where memory footprint matters more than squeezing out the last few percentage points of recall — common in on-disk vector indexes.

HNSW (Hierarchical Navigable Small World)

HNSW addresses the weaknesses of both approaches above with a different data structure entirely: a multi-layer graph, similar in spirit to a skip list. The top layers are sparse and let the search jump across large distances quickly to find the right neighborhood; lower layers are dense and let it drill down to precise matches — without needing to touch every vector (like exhaustive k-NN) or accept a rigid cluster boundary (like IVF).

The search starts at node A on the sparsest top layer, where only a couple of nodes exist — enough to tell it should head toward the "D" side of the graph rather than search everywhere. It drops down a layer (more nodes now, layer 1), refines its position, and drops down again to the bottom layer where every node lives. By this point it's already standing right next to the true answer, so it only has to check a few close neighbors (C and D) instead of all seven nodes shown here — and in a real index, instead of all vectors in the entire database.

This is why HNSW has become the most widely used ANN algorithm in production vector databases — it gets close to exhaustive-search recall at a small fraction of the latency, and scales to millions of vectors without the boundary-miss problem IVF has.

Best for: production semantic search at scale — millions of chunks where you need sub-100ms latency and can tolerate "approximate" (not guaranteed 100% exact) nearest neighbors.

Example: A user asks "how do I get a refund," and the knowledge base document is phrased "requesting reimbursement for a purchase." No shared keywords, but HNSW retrieves it because the embeddings land close together in vector space — at a latency exhaustive k-NN couldn't match at that corpus size.

Distance Metrics

The three algorithms above all need a way to define "closeness":

• Cosine similarity — compares the angle between vectors, ignoring magnitude. Most common default for text embeddings.

• Dot product — factors in magnitude as well as direction; used when embedding magnitude is meaningful (e.g., some recommendation embeddings).

• Euclidean distance — straight-line distance; common in image or spatial embeddings.

3. Hybrid Search & Fusion — Getting the Best of Both Worlds

Lexical search misses paraphrases. Vector search misses exact identifiers. Production RAG systems increasingly run both in parallel and fuse the results.

The big picture: hybrid search isn't one algorithm — it's a pattern. The same query is sent to two independent search systems at once (BM25 and vector search), and the two result lists are then merged into one by a fusion method. The fusion method is the only part that varies — the two most common ones are RRF and weighted scoring, covered below.

With that overview in mind, here's how each fusion method actually works.

RRF (Reciprocal Rank Fusion)

Vector search returns a decimal similarity score (e.g., 0.82) and BM25 returns an unbounded score (e.g., 14.5) — you can't just add them together, the scales aren't comparable. RRF sidesteps this entirely: it only looks at rank position in each result list. A document ranked #1 in either list gets a high reciprocal score (1/1); one ranked #100 gets a tiny score (1/100). Scores from both lists are summed to produce one merged ranking.

Best for: general-purpose RAG where queries are unpredictable — sometimes users type exact terms, sometimes they paraphrase. RRF requires no score calibration or tuning, which makes it a safe default.

Example: A query for "PGVector connection pooling" gets exact-match boost from BM25 on "PGVector," while the vector search separately surfaces a doc titled "managing database connections at scale" that never says "PGVector." RRF merges both into one ranked list instead of picking one method and losing the other's catch.

Weighted Scoring

Assigns a tunable ratio (e.g., 70% vector, 30% keyword) and computes a blended score directly.

Easy way to think about it: instead of only caring about rank position like RRF does, weighted scoring uses the actual similarity numbers — but first it decides in advance how much to trust each search method, like a recipe with fixed proportions, and mixes them in that ratio every time.

Unlike RRF, the raw scores from each method have to be normalized onto the same 0–1 scale first (since 0.82 and 14.5 aren't comparable as-is), then each normalized score is multiplied by its fixed weight (0.7 and 0.3 here) and added together. That 70/30 split isn't automatic — someone has to decide it, usually by testing which ratio produces the best results on real queries for that specific domain.

Best for: domains where you've empirically validated that one signal should dominate — e.g., an e-commerce catalog where exact SKU matches (keyword) should almost always outrank semantic similarity.

4. Post-Retrieval Algorithms — Filtering the Noise After Retrieval

Once candidates are retrieved, a second algorithmic pass improves precision before anything reaches the LLM.

Cross-Encoder Reranking

Standard vector search (a "bi-encoder") embeds the query and each document independently, then compares vectors — fast, but blind to interactions between query and document. A cross-encoder reranker instead feeds the query and each candidate document together into a model that scores relevance directly. It's computationally heavier (can't be pre-computed or indexed), so it's only run on the top candidates from the first retrieval pass, not the whole corpus.

Best for: any pipeline where context window budget is tight and precision at the top of the list matters more than recall — which is nearly every production RAG system, since LLMs weight earlier context more heavily and irrelevant chunks dilute the answer.

Example: Initial retrieval returns 50 loosely-related chunks about "database indexing." The reranker re-scores all 50 against the actual query "why is my B-tree index not being used in this query plan" and pushes the 3 genuinely relevant chunks to the top, discarding the rest before they ever hit the LLM.

Metadata Filtering

Hard constraints applied before or after the similarity search — e.g., "only search documents where department = engineering" or "only chunks published after 2024." This isn't a ranking algorithm; it's a boundary that the ranking algorithms operate within.

Best for: multi-tenant systems, access control, or time-sensitive corpora where irrelevant-but-similar content from the wrong tenant or an outdated version must never surface, regardless of similarity score.

5. Multi-Hop and Graph-Based Search — Answering Across Documents

Vector and keyword search both operate on isolated chunks. Some questions need information stitched together across multiple documents — that's where graph-based and hypothetical-document approaches come in.

GraphRAG

GraphRAG parses unstructured text into a knowledge graph of entities and relationships, then uses graph traversal and community-detection algorithms to answer questions that span multiple disconnected source documents — something flat chunk retrieval structurally can't do well, since no single chunk contains the full answer.

Best for: questions requiring reasoning across many documents — "how are Team A's incidents connected to the vendor outage last quarter" — where the answer doesn't live in any single chunk.

Example: Asking "which customers were affected by the same root cause as the March outage" requires connecting an incident report, a customer ticket log, and a vendor postmortem — three separate documents. GraphRAG traverses the entity graph (incident → root cause → affected services → customers) to compile the answer; a single vector search over chunks would never connect all three.

6. Query Transformation — Rewriting the Question Before Searching

Every algorithm so far changes how documents are searched. This category is different: it changes what gets searched for — the query itself is rewritten before it ever reaches a retrieval algorithm. This runs at query time only; it doesn't touch or restructure the document corpus at all, which is what separates it from GraphRAG above.

HyDE (Hypothetical Document Embeddings)

An LLM first generates a hypothetical, idealized answer to the query. That hypothetical answer — not the raw question — is embedded and used to search the database. The intuition: an answer-shaped piece of text is often closer in vector space to real answer documents than a short, terse question is.

Best for: queries that are short, vague, or phrased very differently from how the source documents are written — where a literal embedding of the question undershoots the semantic target.

Choosing the Right Algorithm: Decision Guide

Trade-off Summary Table

Where This Fits in the Agentic AI Stack

Retrieval is the layer beneath everything else in an agentic RAG system — before tool selection, before reasoning chains, before final generation. Getting it wrong silently degrades every downstream step, because the agent reasons confidently over whatever context it was given, right or wrong.

Introduction

This post assumes you've already decided how to chunk your documents — if not, see the companion post, "Chunking Strategies in RAG: A Deep Dive" which measured fixed-size, recursive, and semantic chunking against real blog content and found recursive chunking the strongest default (100% clean sentence-ending rate vs. 5% for fixed-size, and structure-aware since it respects markdown headers). This post picks up from there: given chunks and a way to embed them, how do you actually get them into Postgres and query them back correctly?

Big Picture

💡 Key Point: embed_chunks() and embed_query() are the same underlying function, called at two different times. This single point of truth matters — if ingestion and query use different embedding logic (different model, different preprocessing, different normalization), the vectors won't be comparable and similarity search silently degrades without throwing any error.

Step 1: A Single Embedding Function, Used Twice

class EmbeddingService:
    def __init__(self, fitting_corpus):
        self._backend, self.dim = self._load_backend(fitting_corpus)

    def embed_chunk(self, text):
        return self._backend.embed_documents([text])[0]

    def embed_chunks(self, texts):
        return self._backend.embed_documents(texts)

    def embed_query(self, text):
        return self._backend.embed_query(text)

Wrapping the embedding backend in one class with embed_chunks() and embed_query() methods means the rest of the pipeline never touches the backend directly — it calls this interface. Swapping BAAI/bge-small-en-v1.5 for text-embedding-3-small later is a one-line change inside _load_backend(), and nothing in the schema, ingestion, or retrieval code needs to know or care.

⚠️ This only works if self.dim (the embedding dimension) is read from the actual backend after it loads, not hardcoded. Different models produce different dimensions — 384 for BGE-small, 1536 for text-embedding-3-small — and the Postgres schema in the next section is built with this exact number.

Step 2: Postgres Configuration for Vector Storage

The only mandatory step is enabling the extension:

CREATE EXTENSION IF NOT EXISTS vector;

📝 Terminology: this needs to run once per database, by a role with sufficient privilege (superuser, or a role granted CREATE on the database). It's a standard extension install — no changes to postgresql.conf, no shared_preload_libraries entry, and no server restart required, unlike some Postgres extensions.

Step 3: Schema Design

CREATE TABLE rag_chunks (
    id SERIAL PRIMARY KEY,
    document_id TEXT NOT NULL,
    document_title TEXT NOT NULL,
    chunk_index INT NOT NULL,
    content TEXT NOT NULL,
    embedding VECTOR(384) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (document_id, chunk_index)
);

Each column exists for a specific reason tied to how retrieval will use it later:

Step 4: Ingestion

# -- for each document, chunk it, embed the chunks, insert them
for document in documents: # each document has id and text
    chunks = chunk_text(document.text) # from the chunking
    vectors = embed_chunks(chunks) # single embedding fun

    for chunk_index, (chunk, vector) in enumerate(zip(chunks, vectors)):
        insert_row(
            document_id=document.document_id,
            document_title=document.title,
            chunk_index=chunk_index,
            content=chunk,
            embedding=vector,
        )

    commit()

Measured result, running this against 5 real blog posts (gauravbytes.dev):

Ingesting corpus:
  chunking-strategies-in-langchain-rag-a-deep-dive: 37 chunks
  how-i-created-an-mcp-server-for-postgresql-to-power-ai-agents-components-architecture-and-real-testing: 33 chunks
  how-to-pick-the-perfect-database-without-losing-your-mind: 51 chunks
  these-ai-memory-types-decide-whether-your-agent-is-smart-or-useless: 19 chunks
  upgrading-my-postgresql-ai-agent-3-architecture-decisions-i-made-and-why: 38 chunks
Total chunks stored: 178

Chunk count scales with document length and structure, not a fixed number per document — the database-picking post produced 51 chunks (it's the longest, most heavily ##-sectioned post in the corpus) while the AI memory post produced 19 (shorter, flatter structure).

Step 5: Retrieval

def search(conn, embedder, query, k=3):
    qvec = embedder.embed_query(query)
    with conn.cursor() as cur:
        cur.execute(
            """
            SELECT document_title, chunk_index, content, 1 - (embedding <=> %s::vector) AS similarity
            FROM rag_chunks
            ORDER BY embedding <=> %s::vector
            LIMIT %s;
            """,
            (qvec, qvec, k),
        )
        return cur.fetchall()

<=> is pgvector's cosine distance operator — smaller means more similar, which is why 1 - distance is computed separately to display an intuitive similarity score while the raw distance still drives the ORDER BY.

Measured results, three real queries against the 178 stored chunks:

Query: 'how should I structure memory for an AI agent'
-------------------------------------------------------------

1. similarity=0.819  [# These AI Memory Types Decide Whether Your A... chunk #18]
   If you truly want to build production-grade AI agents…  start with memory architecture first....
2. similarity=0.812  [# These AI Memory Types Decide Whether Your A... chunk #3]
   ## Why Memory Matters in AI Agents  Imagine hiring a human assistant who:  *   forgets your name eve...


Query: 'what commands should be blocked in a database agent for safety'
-------------------------------------------------------------

1. similarity=0.742  [# Upgrading My PostgreSQL AI Agent: 3 Archite... chunk #18]
   Two things worth noting here. First, this goes through `execute_sql()` — the single gateway from Dec...
2. similarity=0.737  [# Upgrading My PostgreSQL AI Agent: 3 Archite... chunk #11]
   The private connection API is about making the right path the only path. A future contributor should...


Query: 'why do I need to clean up log files on a server'
-------------------------------------------------------------

1. similarity=0.696  [# Upgrading My PostgreSQL AI Agent: 3 Archite... chunk #34]
   **The interface abstraction is what matters.** Because `save_session()` and `load_session()` are the...
2. similarity=0.657  [# Upgrading My PostgreSQL AI Agent: 3 Archite... chunk #12]
   ## Decision 2: Schema Caching at Startup...

Final Thoughts

Postgres, with the vector extension enabled, can store embeddings in a normal table and rank them by cosine similarity against a query using nothing more exotic than ORDER BY embedding <=> query_vector. No separate vector database, no new infrastructure to run — a schema, an insert, and a query, all standard SQL plus one operator.

Some of the results still wasn't clearly relevant, even with a real embedding model in place as we can see in the last query result. That's not a reason to distrust pgvector or the embedding — it's a sign that plain cosine similarity over chunk embeddings is a starting point, not the finished system.

Introduction

Three strategies are covered:

1. CharacterTextSplitter (fixed-size),

2. RecursiveCharacterTextSplitter (recursive), and

3. SemanticChunker (semantic).

4. They differ in exactly one thing: what signal they use to decide where a cut belongs. Fixed-size uses a raw character count. Recursive uses a priority list of structural separators. Semantic uses embedding similarity between sentences.

⏭️ If you already know what an embedding and cosine similarity are, skip to Big Picture.

Background / Prerequisites

📝 Terminology — Embedding: a numeric vector representation of text, produced by a model, positioned in vector space such that semantically similar text produces nearby vectors.

📝 Terminology — Cosine similarity / distance: similarity = cos(θ) between two vectors, ranging from -1 to 1 (in practice 0 to 1 for text embeddings). distance = 1 - similarity. Used throughout SemanticChunker to measure how related two pieces of text are.

📝 Terminology — chunk_overlap: the number of characters from the end of one chunk repeated at the start of the next, intended to preserve context that would otherwise be severed at a chunk boundary.

Big Picture: How the Three Strategies Decide Where to Cut

Each row down this diagram trades one thing for another: fixed-size gives up quality for speed and zero cost; recursive gives up a guarantee for a strong heuristic; semantic gives up a size guarantee entirely in exchange for meaning-awareness, at the cost of needing an embedding model at chunking time.

Fixed-Size Chunking: CharacterTextSplitter

from langchain_text_splitters import CharacterTextSplitter

splitter = CharacterTextSplitter(separator="", chunk_size=500, chunk_overlap=80)
chunks = splitter.split_text(document)

With separator="", the splitter performs a hard cut every chunk_size characters, sliding forward by chunk_size - chunk_overlap each time. It has no concept of a word, sentence, or heading — the cut point is purely a character index.

Measured result (real blog post, "How to Pick the Perfect Database," chunk_size=500, chunk_overlap=80): 22 chunks, mean length 791 chars, only 5% ended on a sentence-terminating character (., !, ?, :). One chunk boundary landed inside a heading marker, producing "...ETL into an analytics store. ## Graph Databases — The Relationship Specialists A gr..." split directly across two chunks.

⚠️ Gotcha: chunk_overlap in CharacterTextSplitter is a raw character count. It does not try to land on a word boundary — the repeated text at a chunk's start can itself begin mid-word.

Recursive Chunking: RecursiveCharacterTextSplitter

from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=800,
    chunk_overlap=100,
    separators=["\n## ", "\n### ", "\n\n", "\n", ". ", " ", ""],
)
chunks = splitter.split_text(document)

Decision Flow

The default separator list is ["\n\n", "\n", ". ", " ", ""], ordered from largest structural unit to smallest, with "" (raw character split) as an unconditional fallback so the algorithm can never fail to produce a chunk under chunk_size.

💡 Key Point: reordering this list to match your document's actual structure is the single highest-leverage tuning knob for this splitter. Markdown content with real ##/### headers benefits from putting \n## and \n### at the front, ahead of the generic paragraph/sentence defaults.

Measured result (same document, headers-first separator list, chunk_size=800, chunk_overlap=100): 30 chunks, mean length 511 chars, 100% ended on a sentence-terminating character — up from 5% for fixed-size on comparable settings.

⚠️ Gotcha — size ceiling persists: recursive chunking respects structure but is still size-bound. The document's "Graph Databases" section (heading through the closing sentence of its "Common pitfalls" subsection) measures 1,277 characters. At chunk_size=700, the splitter is forced to cut through this section regardless of separator ordering. At chunk_size=1300, the section survives as one chunk. This was verified directly, not assumed:

Semantic Chunking: SemanticChunker

Concept: What "Semantic" Means Here

SemanticChunker has no chunk_size parameter. It instead measures the cosine distance between the embeddings of consecutive sentence groups and cuts wherever that distance exceeds a threshold — i.e., wherever the topic changes.

Pipeline (Data Flow)

📝 Terminology — buffer_size: the number of neighboring sentences folded into each embedded unit. At buffer_size=1, combined_sentence[i] = sentence[i-1] + sentence[i] + sentence[i+1]. This means the distance between position i and i+1 compares two overlapping windows that share most of their content — only the sentence falling off one edge and the new one entering the other edge actually differ. This is a deliberate smoothing mechanism: a short, low-information sentence is never embedded in isolation.

⚠️ Gotcha: combined_sentence[i] is what gets embedded, not the raw sentence[i]. Confusing the two leads to incorrect assumptions about what the similarity score is actually measuring.

The Four breakpoint_threshold_type Options

Verified failure mode — standard_deviation vs interquartile on distance sequence [0.05, 0.06, 0.04, 0.90, 0.05, 0.06, 0.35, 0.05, 0.06, 0.04] (two real topic breaks: one dramatic at index 3, one moderate at index 6):

• standard_deviation(1): threshold = 0.426 → breakpoints at [3] only. The dramatic outlier (0.90) inflates the mean and std enough that the moderate break (0.35) falls below threshold and is missed.

• interquartile(1.5): threshold = 0.181 (Q1=0.050, Q3=0.060, computed from the tight middle cluster, unaffected by either outlier) → breakpoints at [3, 6]. Both breaks are caught, because IQR's own spread measurement isn't corrupted by the outliers it's trying to detect.

The Embedding Model Determines Correctness, Not Just Cost

SemanticChunker accepts any object implementing LangChain's Embeddings interface (embed_documents, embed_query). Two were tested:

TF-IDF (word-overlap statistics, used as a free/offline stand-in):

"The cat sat on the mat." vs "A feline was resting on the rug."
  → same meaning, zero shared content words → similarity: 0.000

"The bank raised interest rates today." vs "I sat by the river bank yesterday."
  → different meaning, one shared word ("bank") → similarity: 0.181

TF-IDF ranks the second, unrelated pair as more similar than the first, meaning-identical pair, purely on shared vocabulary. Run through SemanticChunker, this produces measurable structural noise: on the test document, chunk sizes ranged from 16 to 1,257 characters (mean 411, std 342) — a single bulleted list item was isolated as its own 16-character chunk, while an entire section was merged into one 1,257-character chunk, because TF-IDF's similarity signal doesn't track actual topic boundaries reliably.

HuggingFaceEmbeddings(model_name="BAAI/bge-small-en-v1.5") — a 384-dimension neural embedding model trained to place semantically similar text near each other regardless of shared vocabulary:

from langchain_huggingface import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-small-en-v1.5",
    model_kwargs={"device": "cpu"},
    encode_kwargs={"normalize_embeddings": True},
)

⚠️ Gotcha — environment dependency: this requires network access to huggingface.co to download model weights (~130MB, one-time). In a network-restricted environment, this call fails; a working fallback pattern is shown in the referenced script (§8) that catches the download failure and substitutes TF-IDF so the pipeline still runs end-to-end for demonstration purposes.

Comparison / Trade-offs

💡 Key Point: chunk size uniformity and chunk quality are different axes. Fixed-size had the lowest coefficient of variation (0.05) and the worst quality (5% clean endings) of the three. A tight size distribution is not evidence of good chunking.

References

• LangChain text splitters documentation (langchain_text_splitters)

• LangChain experimental SemanticChunker source (langchain_experimental)

• BAAI/bge-small-en-v1.5 model card (HuggingFace) for dimension count and intended use

• All measured percentages, chunk counts, and character counts in this post were produced by running the scripts in against my own blog post, "How to Pick the Perfect Database Without Losing Your Mind" (gauravbytes.dev) — no numbers were estimated or fabricated.

The Prototype Was Working. That Was the Problem.

After Part 1, I had a working agent. You could type a question in plain English, it would figure out the right SQL, run it, and return results. Impressive enough to demo. Not solid enough to build on.

The more I used it, the more I noticed the cracks:

• The database connection was hardcoded. Switching databases meant editing the source file.

• Every time the agent needed to understand a table, it fetched the schema live — adding latency and unnecessary DB hits.

• The conversation had no memory. Every session started from zero.

• The SQL safety check lived inside the tool itself, meaning there was nothing stopping me (or a future contributor) from adding another path that bypassed it entirely.

None of these are showstoppers at the prototype stage. All of them become real problems the moment you want to hand the tool to someone else, open-source it, or run it against a database that actually matters.

This article covers three architectural decisions I made to address these — what I changed, what I considered, and why I landed where I did.

Decision 1: A Single SQL Execution Gateway

The Problem

In v1, the execute_sql tool handled everything inline: it validated the query, opened a connection, ran it, and returned the result — all in one function that the LangChain agent called directly.

That works. But it means the safety logic and the execution logic are coupled inside a single tool. If I ever added a second tool — say, one that runs EXPLAIN plans or fetches row counts — I'd have to either duplicate the safety check or remember to call some shared validator manually. Both options are brittle.

The deeper issue: there was no structural guarantee that every SQL statement passed through a single checkpoint. The safety net existed, but it was enforced by convention, not architecture.

The Decision

I moved all database interaction behind a single execute_sql() function in db.py. This is the only place in the codebase that runs SQL against the database. Every tool, every command, every path goes through it — no exceptions.

Alongside this, I introduced two custom exceptions:

class SQLSafetyError(Exception):
    """Raised when a query violates the read-only safety policy."""
    pass

class SQLExecutionError(Exception):
    """Raised when a valid query fails during execution."""
    pass

And the connection API became private — a _get_connection() function that nothing outside db.py should call directly.

def _get_connection():
    """Private. Use execute_sql() — do not call this directly."""
    return psycopg2.connect(**_load_db_config())

Why This Matters

The separation of SQLSafetyError and SQLExecutionError is deliberate. A blocked query and a failed query are different situations — they should produce different responses to the user and, eventually, different log entries. Collapsing them into a single generic error message loses information that's useful for debugging.

The private connection API is about making the right path the only path. A future contributor shouldn't have to know to call the safety check before running a query — the architecture should make that automatic. If _get_connection() is internal and execute_sql() is the public interface, there's no accidental bypass.

This is the kind of constraint that feels like overhead when you're the only developer. It pays off the moment the codebase has more than one pair of eyes on it.

Decision 2: Schema Caching at Startup

The Problem

In v1, schema discovery was lazy. When the agent needed to understand a table's structure, it called the get_table_schema tool, which hit the database on demand.

This created a few practical problems:

• Latency. Every query that involved schema introspection added a round-trip to the database before the actual query ran.

• Inconsistency. The LLM sometimes skipped the schema fetch and guessed column names based on the table name alone. It was usually right. When it was wrong, the error wasn't obvious.

• Context fragmentation. Schema information arrived piecemeal, one table at a time, as the conversation progressed. The agent never had a complete picture of the database upfront.

The Decision

The caching implementation is deliberately simple. A module-level variable acts as the cache, populated on the first call and reused on every subsequent one:

def get_cached_tables() -> list[str]:
    """Get list of all tables in public schema (cached after first call)."""
    global _schema_cache
    if _schema_cache is not None:
        return _schema_cache
    try:
        result = execute_sql("""
            SELECT table_name FROM information_schema.tables
            WHERE table_schema = 'public'
            ORDER BY table_name
        """)
        _schema_cache = [row[0] for row in result.rows]
    except (SQLSafetyError, SQLExecutionError):
        _schema_cache = []
    return _schema_cache

Two things worth noting here. First, this goes through execute_sql() — the single gateway from Decision 1 — so the safety check applies even to internal schema queries. Second, if the fetch fails, the cache is set to an empty list rather than left as None. That means a second call won't retry a failed fetch mid-session, which keeps the behavior predictable.

The cached table list feeds into a {schema_context} block that gets injected into the system prompt at startup:

"""You are PGChat, an expert PostgreSQL database assistant. You have access to tools to inspect and query the connected database.

Current date and time: {current_time}

Guidelines:
- Use the SCHEMA SNAPSHOT below to answer questions about tables and columns — do NOT call list_tables or get_table_schema unless the user explicitly asks to refresh.
- Prefer short, precise answers. When showing data, summarize it unless the user asks for raw output.
- Never guess table or column names — verify against the schema snapshot.
- When you write SQL, explain what it does briefly.
- If a query fails, analyze the error and suggest fixes.
- Use get_table_sample to preview data when helpful.
- Use search_schema when the user asks "which table has X column?"
- Use run_query to execute SQL queries.

{schema_context}"""

The guideline do NOT call list_tables or get_table_schema unless the user explicitly asks to refresh is doing real work here. Without it, the LLM will sometimes call those tools anyway out of habit, even when the snapshot has the answer. Explicitly instructing it to trust the snapshot eliminates those redundant tool calls in practice.

A /refresh-schema command lets the user reset _schema_cache to None and trigger a fresh fetch if the schema has changed during a session.

Why This Matters

The key insight is that schema information is almost never volatile within a single session. Tables don't get columns added or dropped while you're mid-conversation. Fetching once and injecting as context is both faster and more reliable than fetching on demand.

The system prompt approach has a meaningful side effect: the LLM has the full schema available before it generates its first query. It doesn't have to reason about what tools to call to understand the database — that context is already there. In practice, this reduces the number of tool calls per user question and noticeably improves query accuracy, especially on databases with multiple tables that share similar naming patterns.

The /refresh-schema escape hatch matters for user trust. Schema caching only works if users are confident the snapshot reflects reality. Giving them a command to invalidate it manually means they're never stuck with stale information.

One tradeoff worth acknowledging: for databases with hundreds of tables, injecting the full schema as a system message could push against context window limits. For the current use case this isn't a problem, but it's something to revisit as the tool grows. A reasonable next step would be selectively injecting only the tables relevant to the current query — something worth exploring in a later iteration.

Decision 3: Session Memory with JSON (For Now)

The Problem

In v1, every conversation started from scratch. The agent had no memory of what you'd asked before, what tables you'd explored, or what the last query returned. For a quick one-off query this is fine. For anything resembling a real workflow — iterating on a report, exploring a dataset across multiple questions — it's a significant limitation.

The Decision

I added persistent session memory backed by JSON. At the end of each conversation turn, the session state is written to a .json file. When you start the agent again, it loads that file and resumes where you left off.

The interface is intentionally minimal:

def save_session(session: Session, path: str) -> None:
    """Persist session state to disk."""
    ...

def load_session(path: str) -> Session | None:
    """Load a previous session, or return None if none exists."""
    ...

Why JSON and Not SQLite or PostgreSQL?

This is the question I spent the most time on, because it seems obvious to reach for a database when you're already using one.

The case for SQLite: structured queries, better concurrency handling, easier to inspect with standard tooling. The case for PostgreSQL: the agent is already connected to one, so no additional dependency. Both are reasonable. Neither is what I chose.

JSON wins for now for a few specific reasons:

Zero additional dependencies. The agent already requires Python, psycopg2, LangChain, and Ollama. Adding a SQLite ORM or a second PostgreSQL connection for session storage would increase the setup surface area for something that isn't the core feature. For a CLI tool that someone installs with pip, simpler setup matters.

Human-readable state. A JSON session file is easy to inspect, copy, share, and debug without any tooling. If something goes wrong with session state, you can open the file in a text editor and understand it immediately.

The interface abstraction is what matters. Because save_session() and load_session() are the only way the rest of the codebase touches session state, the storage backend can be swapped later without changing anything else. If the JSON approach hits a real limitation — concurrent sessions, large history, search across sessions — migrating to SQLite or PostgreSQL is a one-file change. Building that migration path in now, by keeping the interface clean, costs nothing.

The honest answer is also that JSON is good enough for the current use case. The agent runs as a single-user CLI tool. There's no concurrency to manage, no performance requirement that JSON can't meet, and no schema to maintain. Reaching for a database here would be solving a problem I don't have yet.

What's Next

These three changes move the agent from a prototype to something I'd actually hand to another developer. The architecture is more intentional, the failure modes are clearer, and the session experience is meaningfully better.

The next step is packaging — making the agent installable as a proper CLI tool via pip install postgres-agent, with a clean entry point and configuration handled through environment variables or a config file rather than source edits.

After that, the session storage decision will get revisited. As the tool supports multiple named sessions or shared use cases, JSON will start to show its limits. That's the right time to migrate — not before.

The source code is on GitHub: github.com/icon-gaurav/pgchat. If you're building something similar or have thoughts on any of these decisions, I'd like to hear them.

Before You Even Look at a Database, Answer These 6 Questions

Every database choice I've made that turned out well started here. Every bad choice skipped at least one of these.

• What shape is your data? - Rows and columns with fixed fields? Nested JSON documents? Nodes and edges? Timestamped measurements?

• How stable is your schema? - If your fields change often between records, you'll hate rigid relational schemas. If they're locked in, schema flexibility is a non-issue.

• How complex are your relationships? - Do entities reference each other heavily? Many-to-many? Deep traversals? This is where most teams underestimate.

• What are your query patterns? - Short key lookups vs. aggregations vs. full-text vs. joins — these push you toward completely different architectures.

• What's the expected scale? - A single-region app serving 10K users is a different problem from global OLTP at 1M writes/sec.

• Who is operating this thing? - The best database for your use case is the one your team can actually run well. Don't adopt Cassandra if no one on your team has operated it.

Quick thumb rule

If most answers point to ACID + complex relationships → start with relational DB.

If you need flexibility in schema + hierarchical documents → consider document DB.

If you need extreme low-latency key lookups → key–value store.

If you need graph traversals → graph DB.

If you need high-cardinality time series → time-series DB.

Relational Databases (RDBMS) — The Reliable Workhorse

RDBMS is the foundational technology for systems where data consistency, reliability, and complex relationships are critical. Because RDBMS is designed to be highly structured and secure, it is the industry standard for any application where "getting the data right" is more important than sheer speed at the expense of accuracy

Characteristics:

• Structured rows and columns with a defined schema.

• Strong ACID guarantees for transactions.

• Powerful SQL for joins, aggregation, and complex queries.

• Mature tooling for backups, migrations, and analytics.

Pros:

• Battle-tested for correctness and consistency.

• Great for normalized data and multi-table transactions.

• Rich ecosystem (ORMs, monitoring, tooling).

Cons:

• Schema migrations can be painful at large scale.

• Joins across huge tables can be slow without careful indexing and design.

• Vertical scaling limits unless you adopt sharding or distributed SQL.

Market examples: PostgreSQL, MySQL, Microsoft SQL Server.

Who uses them: core transactional systems at Shopify, payment systems, many SaaS apps.

Common pitfalls:

• Over-normalizing for read-heavy workloads — optimize with materialized views or read replicas.

• Ignoring indexing and query plans; assume indexes are free.

Document Databases — The Flexible Multi-Tool

Document databases are chosen when your application’s data requirements are evolving rapidly or are too varied to fit neatly into a rigid, table-based schema.

Because they are highly flexible and scale easily, they are the go-to for modern, agile software development. e.g. CMS or user profiles where each user may have different fields.

Characteristics:

• Schema-flexible JSON-like documents (nested structures welcome).

• Queryable fields and secondary indexes; supports partial updates.

• Good balance between flexible modeling and querying capability.

Pros:

• Evolve your data model quickly without rigid migrations.

• Excellent for denormalized data and aggregations that map to document shapes.

• Often easier to scale horizontally than single-instance RDBMS.

Cons:

• Complex joins are either unsupported or expensive (application-level joins).

• Risk of inconsistent schemas and duplicated data if not managed.

• Transactions historically limited (but many modern engines now support distributed transactions).

Market examples: MongoDB, Couchbase, Amazon DocumentDB.

Who uses them: content systems, user profile stores, product catalogs.

Common pitfalls:

• Modeling relational semantics as documents without a strategy leads to data redundancy and maintenance headaches.

• Uncontrolled document growth (too large documents or too many nested arrays) hurts performance.

Key–Value Stores — The Blazing-Fast Lookup

Key-Value databases are your go-to choice when you need lightning-fast performance for simple tasks. Think of them like a giant, super-organized dictionary where you can grab any piece of information instantly just by knowing its unique "key."

Highly used in session management and caching

Characteristics:

• Simple API: store and retrieve by primary key.

• Extremely low-latency reads and writes.

• Minimal structure — values are opaque blobs to the store.

Pros:

• Excellent performance at scale; trivially sharded.

• Simple to reason about and operate.

Cons:

• Limited querying (no secondary indexes or complex queries).

• Application must handle consistency and indexing logic.

Market examples: Redis, Amazon DynamoDB (when used as KV), Memcached.

Common pitfalls:

• Using KV where you actually need complex queries or relationships.

• Treating cache as primary storage without durable persistence or correct eviction handling.

Column-Family (Wide-Column) Stores — The High-Throughput Workhorse

Column-family stores are the perfect choice when you need to handle massive, rapidly growing datasets that would overwhelm a traditional database.

Unlike standard systems that store data row by row, these databases organize information by columns, allowing them to read and write specific data points at incredible speeds.

They are the ideal tool for managing massive workloads like IoT telemetry, web logs, or real-time user activity feeds.

Characteristics:

• Data modeled as rows with many sparse columns grouped into families.

• Optimized for write-heavy workloads and large-scale partitioning.

• Tunable consistency and compaction strategies.

Pros:

• High write throughput, designed for horizontal scale.

• Efficient for queries that read contiguous ranges or specific columns.

Cons:

• Query flexibility is lower than relational databases.

• Requires careful data modeling to avoid hot partitions.

Market examples: Apache Cassandra, ScyllaDB, HBase.

Common pitfalls:

• Poor partition key choices causing hotspotting and degraded performance.

• Trying to support ad-hoc analytics without ETL into an analytics store.

Graph Databases — The Relationship Specialists

A Graph Database stores data as a network of nodes (entities) and edges (relationships), rather than rigid tables. By treating these connections as first-class citizens, it allows for high-performance traversal of complex data paths without the heavy cost of traditional JOIN operations.

These systems are ideal when the relationships between data points are as important as the data itself.

They are the standard for real-time, relationship-heavy tasks like powering recommendation engines, fraud detection, and social network analysis.

Characteristics:

• Native representation of nodes and edges with rich traversal capabilities.

• Efficient for deep, variable-length relationship queries.

• Query languages: Cypher, Gremlin, or GQL-like syntaxes.

Pros:

• Expressive for relationship-heavy domains; traversals are fast.

• Intuitive modeling for networks and hierarchies.

Cons:

• Not ideal for wide analytical queries or massive ad-hoc aggregations.

• Scaling can be more complex than key-value or column stores.

Market examples: Neo4j, Amazon Neptune, JanusGraph.

Common pitfalls:

• Modeling everything as a graph when simpler data models suffice.

• Ignoring graph size and traversal complexity — performance can degrade with high-degree nodes.

Time-Series Databases — Optimized for Temporal Data

A Time-Series Database is purpose-built to store and query data points indexed by time, such as sensor readings, server logs, or stock market fluctuations.

These systems are essential for applications where tracking trends, patterns, and anomalies over time is critical. They are the industry standard for real-time monitoring, forecasting, and managing complex telemetry data.

Characteristics:

• Time is a first-class citizen (efficient append, retention, downsampling).

• Built-in functions for aggregations over windows and rate calculations.

• Often compact storage and compression for high-ingest workloads.

Pros:

• Excellent for metric retention, querying recent data, and rollups.

• Features like retention policies and continuous aggregations.

Cons:

• Not a general-purpose store for arbitrary relational data.

• May need separate systems for long-term archival or complex joins.

Market examples: InfluxDB, TimescaleDB (Postgres extension), Prometheus (metrics).

Common pitfalls:

• Using a TSDB for non-temporal data or trying to join TSDB data with relational transactional data without ETL.

Search Engines / Full-Text Stores — The Queryable Text Engine

Search Engine Databases are built to index and retrieve unstructured text by mapping every word's location, allowing for nearly instant keyword and phrase searches.

Unlike traditional databases, they excel at ranking results by relevance and handling typos through fuzzy matching. They are the industry standard for powering site-wide search bars, log analysis tools, and deep-dive document discovery.

Characteristics:

• Inverted indexes optimized for text search and relevance ranking.

• Support for filters, facets, and near-real-time indexing.

• Powerful query DSLs for scoring and boosting.

Pros:

• Great for full-text search, autocomplete, and ranked results.

• Can support analytics over indexed fields.

Cons:

• Not designed as a source-of-truth transactional database.

• Indexing lag and eventual consistency between primary store and index.

Market examples: Elasticsearch, OpenSearch, Algolia.

Common pitfalls:

• Treating the search index as the primary data store (data loss risk).

• Forgetting to reindex when source data schema or semantics change.

NewSQL / Distributed SQL — SQL with Scale

NewSQL (Distributed SQL) databases offers both strict ACID consistency and massive horizontal scalability. They automate the distribution of data across cloud clusters, removing the need for manual sharding while maintaining a standard SQL interface.

They are the go-to solution for mission-critical applications that need to grow globally without sacrificing transaction integrity.

Characteristics:

• SQL and ACID semantics combined with distributed architecture.

• Built-in sharding/replication to scale reads and writes.

Pros:

• Familiar SQL model with modern horizontal scaling.

• Often simpler to operate than hand-sharded RDBMS clusters.

Cons:

• Complexity and operational costs may still be higher than single-node RDBMS.

• Some trade-offs in latency or consistency depending on config.

Market examples: CockroachDB, Google Spanner, YugabyteDB.

Common pitfalls:

• Expecting the same latency characteristics as a single-machine RDBMS.

• Underestimating the operational model (geo-partitioning, transaction latency).

Multi-Model Databases — One Engine, Multiple Models

Multi-Model Databases are versatile platforms built to handle multiple data structures—such as documents, graphs, and relational tables—within a single, unified engine.

Instead of managing separate databases for different data types, this approach allows you to store and query varied structures using one consistent API.

Characteristics:

• Support for two or more data models within one engine.

• Aims to reduce polyglot persistence complexity.

Pros:

• Flexibility; use the right model for each feature without managing multiple systems.

• Simplified operational footprint.

Cons:

• Each model may not be best-in-class; vendor lock-in risk.

• Complexity in modeling and backups across models.

Market examples: ArangoDB, Cosmos DB (multi-model flavors).

Common pitfalls:

• Believing multi-model removes need for careful modeling and performance testing.

Vector Databases — The AI-powered Semantic Engine

This database is designed to store and search data as vectors (numerical representations) instead of traditional rows and columns.

AI models convert text, images, or audio into vectors, and the database finds the most similar vectors using semantic meaning rather than exact keyword matches.

Characteristics:

• Stores high-dimensional vectors (embeddings) generated by ML models.

• Optimized for similarity search (Approximate Nearest Neighbor - ANN) rather than exact key matches.

• Supports hybrid search (combining metadata filtering with vector similarity).

Pros :

• Highly efficient at finding semantically similar items at scale.

• Enables advanced AI use cases like LLM memory and RAG.

• Flexible support for various distance metrics (cosine, L2, inner product).

Cons :

• High memory footprint; vector indexes (like HNSW) can be RAM-intensive.

• Query results are probabilistic (approximate) rather than deterministic.

• Requires complex pipeline to generate and sync embeddings from source data.

Market examples: Pinecone, Milvus, Weaviate, Qdrant, pgvector (PostgreSQL extension).

Who uses them: AI startups, platforms building generative AI features, search infrastructure teams.

Common pitfalls:

• Storing massive amounts of raw data in the vector DB, use it for embeddings and store raw data in a traditional DB.

• Ignoring the need for data maintenance (embeddings become stale when source content changes).

• Choosing the wrong distance metric or index parameters, leading to poor recall/precision.

How I choose (practical heuristics)

• Start with the shape of your data and queries:

• If queries are heavily relational and transactional → RDBMS or Distributed SQL.

• If data is document-like and schema evolves → Document DB.

• If you need extreme single-key performance → Key–Value store.

• If traversals and relationships are core → Graph DB.

• If the workload is metric/time-based → Time-Series DB.

• Prioritize correctness first for money/health/safety systems (ACID > scale). You can scale later.

• Consider operational burden and team expertise: prefer familiar tools unless scale demands otherwise.

• Prototype the hot paths: build and load-test a minimal model of your expected queries and traffic.

• Plan for backups, migrations, and observability from day one.

Quick design patterns

• Read-heavy with complex joins → RDBMS + read replicas or materialized views.

• Flexible user data + frequent reads → Document DB with controlled denormalization.

• High ingest telemetry → TSDB or column-family store with downsampling pipeline.

• Low-latency session/cache → Redis or managed in-memory KV.

• Search plus data store → Primary store (RDBMS/DocDB) + search index (Elasticsearch) with sync strategy.

But most of them have one major problem:

They forget everything.

You ask the agent something… then ask a follow-up question… and suddenly it behaves like it has amnesia.

That’s because many developers focus only on:

• prompts,

• tools,

• workflows,

• and LLM selection…

…but completely ignore memory systems.

The reality is:

Memory is what transforms an LLM into an actual AI agent.

Without memory:

• agents feel dumb,

• conversations break,

• personalization disappears,

• and long-running tasks become impossible.

Before implementing any AI agent, you must understand the different memory types, when to use them, and what should (and should not) be stored.

In this article, we’ll break down:

• Short-term memory

• Long-term memory

• Semantic memory

• Episodic memory

• Working memory

• Retrieval memory And how modern AI systems like OpenAI and Anthropic likely structure memory internally.

Why Memory Matters in AI Agents

Imagine hiring a human assistant who:

• forgets your name every minute,

• never remembers previous tasks,

• and resets after every conversation.

That assistant would be useless.

Yet that’s exactly how many AI agents behave today.

Memory enables agents to:

• maintain conversation context,

• remember user preferences,

• learn from previous interactions,

• improve future responses,

• and perform long-running autonomous tasks.

This is the difference between:

• a chatbot,

• and a real AI assistant.

1. Short-Term Memory (Conversation Memory)

What It Is

Short-term memory stores:

• recent messages,

• current task context,

• active reasoning steps,

• and temporary conversation state.

This memory usually lives inside:

• the context window,

• Redis,

• in-memory cache,

• or session storage.

Example

User says:

“Help me write a LinkedIn post about AI agents.”

Then later:

“Make it shorter.”

The AI needs short-term memory to understand: “it” = the LinkedIn post.

Without it, the agent gets confused.

Common Mistake

Many developers dump entire conversations into prompts.

This:

• increases token cost,

• slows responses,

• and eventually exceeds context limits.

Good agents summarize and compress short-term memory over time.

2. Long-Term Memory (Persistent Memory)

What It Is

Long-term memory stores information across sessions.

This includes:

• user preferences,

• goals,

• writing style,

• past projects,

• recurring workflows,

• and important facts.

Usually stored in:

• vector databases,

• PostgreSQL,

• graph databases,

• or knowledge stores.

Example

If a user always writes:

• backend engineering blogs,

• AI tutorials,

• and YouTube scripts…

…the agent can remember this and personalize future outputs automatically.

That’s how assistants start feeling “smart.”

3. Semantic Memory

What It Is

Semantic memory stores facts and knowledge.

Think of it like:

• concepts,

• relationships,

• expertise,

• and learned information.

Example

The agent remembers:

• LangChain is an AI framework,

• PostgreSQL is a database,

• Redis is used for caching.

This is knowledge-based memory.

Humans use semantic memory too.

4. Episodic Memory

What It Is

Episodic memory stores experiences and past interactions.

Instead of remembering facts, the agent remembers events.

Example

The agent remembers:

“Last week the user struggled with Docker networking.”

That historical experience helps future responses.

This is one of the most important memory types for personalization.

5. Working Memory

What It Is

Working memory is temporary reasoning memory.

It exists only while solving a task.

The agent may store:

• intermediate reasoning,

• calculations,

• plans,

• or execution steps.

Once the task finishes, this memory may disappear.

Example

While generating SQL:

1. Understand schema

2. Build query

3. Validate query

4. Execute safely

The intermediate steps live in working memory.

6. Retrieval Memory (RAG Memory)

What It Is

Instead of storing everything directly in prompts, the agent retrieves relevant information when needed.

This powers:

• RAG systems,

• document agents,

• and enterprise AI assistants.

Example

User asks:

“Summarize my uploaded PDF.”

The agent:

1. retrieves relevant chunks,

2. injects them into context,

3. then answers.

This avoids context overload.

The Real Challenge: What Should Be Stored?

This is where most AI agent systems fail.

Not everything deserves long-term memory.

Good memory systems decide:

• what to remember,

• what to forget,

• and what to summarize.

Good Things to Store

• User preferences

• Long-term goals

• Writing style

• Repeated workflows

• Important project details

Bad Things to Store

• Temporary emotions

• One-time requests

• Sensitive information

• Random conversational noise

A Practical AI Agent Memory Architecture

A production-grade AI agent often looks like this:

This layered architecture is what makes modern AI assistants scalable.

How Modern AI Systems Likely Handle Memory

Companies like OpenAI and Anthropic likely use:

• session memory,

• persistent user memory,

• retrieval systems,

• summarization pipelines,

• and memory ranking systems.

The hard part is not storing memory.

The hard part is:

• deciding importance,

• retrieval timing,

• compression,

• and relevance filtering.

Memory engineering is becoming its own field.

Final Thoughts

Most developers think AI agents are about:

• better prompts,

• bigger models,

• or more tools.

But memory is what actually creates continuity, intelligence, and personalization.

The future of AI agents won’t belong to the models with the largest context windows.

It will belong to agents that:

• remember intelligently,

• forget strategically,

• and learn continuously.

If you truly want to build production-grade AI agents…

start with memory architecture first.

That’s why cron jobs matter more than most developers realize. They are the invisible safety net keeping systems alive in production.

Below are 5 cron jobs every backend server should have.

#1. Automated Backups

Regularly backing up your data is non-negotiable. This is arguably one of the most critical uses of cron jobs in any backend system.

In production, things rarely break on purpose—they break due to small, unexpected mistakes. A deleted record, a faulty deployment, or even a storage corruption issue can wipe out critical data in seconds.

A backup cron job ensures that no matter what happens, there is always a recent version of your data that can be restored. It quietly runs in the background, taking snapshots of your database and storing them safely in external storage.

#2. Log Cleanup & Rotation

Logs are extremely useful until they aren’t. Over time, they quietly grow into massive files that start consuming disk space without any warning.

A log cleanup cron job ensures that old logs are either deleted or compressed regularly. Without this, servers can suddenly run out of storage and crash unexpectedly.

This job is less about performance optimization and more about survival. It keeps your system stable by preventing silent resource exhaustion.

#3. Server Health Checks

Your server rarely tells you when it’s about to fail—it just does. That’s why continuous health checks are essential.

This cron job periodically checks CPU usage, memory consumption, disk space, and service availability. If anything crosses safe limits, it triggers alerts before users are affected.

It acts like a silent observer, constantly watching the system so you don’t have to manually inspect it every few hours.

#4. Cache Cleanup

Every backend system generates temporary files—uploads, cached responses, processing artifacts, and more. Most of these are never cleaned automatically.

Over time, these files accumulate and slowly degrade system performance or fill up storage completely.

A cleanup cron job ensures that anything temporary truly stays temporary. It removes stale files and keeps the system lean, fast, and predictable.

#5. Retry Failed Jobs

Not everything works on the first attempt. API calls fail, webhooks timeout, and background jobs occasionally break due to external dependencies.

Instead of losing that work permanently, a retry cron job reprocesses failed tasks at regular intervals.

This is what makes modern backend systems resilient. It ensures that temporary failures don’t turn into permanent data loss or broken workflows.

Final Thoughts

Cron jobs are often overlooked because they don’t feel “core” to the product. But in reality, they are what make production systems stable, reliable, and self-healing.

Most backend failures don’t come from code—they come from missing automation.

And these 5 cron jobs quietly prevent that from happening.

What if you could query your database like this:

"Show me top 10 users by revenue"

…and get instant results—without writing SQL?

Welcome to the world of AI-powered database agents.

In this tutorial, you'll learn how to build a secure PostgreSQL AI agent using:

• 🧩 LangChain — for agent orchestration and tool chaining

• 🦙 Ollama — to run a local LLM with zero API cost

• 🐘 PostgreSQL — as the target database

• 🛡️ Custom SQL safety guard — to block destructive queries

By the end, you'll have a production-ready AI database assistant that understands natural language and safely executes SQL queries.

💻 Source Code: https://github.com/icon-gaurav/postgres-agent

🤖 What is a PostgreSQL AI Agent?

A PostgreSQL AI Agent is an LLM-powered system that:

• Converts natural language → SQL queries

• Executes queries on PostgreSQL

• Returns structured results

👉 Think of it as ChatGPT for your database, but controlled and safe.

⚙️ Tech Stack

🧱 Architecture

🔌 Step 1: PostgreSQL Connection

First, configure your database connection using psycopg2:

import psycopg2
 
DB_CONFIG = {
    "host": "localhost",
    "port": 5432,
    "database": "postgres",
    "user": "postgres",
    "password": "root",
}
 
def get_connection():
    return psycopg2.connect(**DB_CONFIG)

🔐 Security tip: In production, load credentials from environment variables or a secrets manager — never hardcode passwords.

🛠️ Step 2: Create Database Tools

LangChain agents interact with the world through tools — Python functions decorated with @tool that the LLM can invoke by name.

📋 List Tables Tool

@tool
def list_tables() -> str:
    """List all tables in the database."""
    conn = get_connection()
    try:
        cur = conn.cursor()
        cur.execute("""
            SELECT table_name FROM information_schema.tables
            WHERE table_schema = 'public'
        """)
        tables = [row[0] for row in cur.fetchall()]
        return f"Tables: {', '.join(tables)}" if tables else "No tables found."
    finally:
        conn.close()

This enables dynamic schema discovery — the agent doesn't need hardcoded table names.

📑 Get Table Schema

@tool
@tool
def get_table_schema(table_name: str) -> str:
    """Get the schema (columns and types) of a specific table."""
    conn = get_connection()
    try:
        cur = conn.cursor()
        cur.execute("""
            SELECT column_name, data_type, is_nullable
            FROM information_schema.columns
            WHERE table_schema = 'public' AND table_name = %s
            ORDER BY ordinal_position
        """, (table_name,))
        columns = cur.fetchall()
        if not columns:
            return f"Table '{table_name}' not found."
        schema = "\n".join([f"  {col[0]} ({col[1]}, nullable={col[2]})" for col in columns])
        return f"Schema for '{table_name}':\n{schema}"
    finally:
        conn.close()

Allows the agent to understand:

• Column names

• Data types

• Constraints

⚡ Execute SQL Tool

@tool
def execute_sql(query: str) -> str:
    """Execute a SQL query against the PostgreSQL database and return results. Use this for SELECT queries."""
    is_safe, reason = validate_read_only_sql(query)
    if not is_safe:
        return f"Safety Guard: Blocked query. {reason}"

    conn = get_connection()
    try:
        cur = conn.cursor()
        cur.execute(query)
        if cur.description:
            columns = [desc[0] for desc in cur.description]
            rows = cur.fetchall()
            if not rows:
                return "Query returned no results."
            result = " | ".join(columns) + "\n"
            result += "\n".join([" | ".join(str(v) for v in row) for row in rows[:50]])
            if len(rows) > 50:
                result += f"\n... ({len(rows)} total rows)"
            return result
        else:
            conn.commit()
            return f"Query executed successfully. Rows affected: {cur.rowcount}"
    except Exception as e:
        conn.rollback()
        return f"SQL Error: {e}"
    finally:
        conn.close()

This is the core execution layer.

Step 3: SQL Safety Guard — Prevent Destructive Queries

Allowing an LLM to run arbitrary SQL is a critical security risk. The SQL safety guard validates every query before execution.

Read-Only Allowlist

Only these SQL statement types are permitted:

🧼 Normalize Queries

We remove:

• Comments

• Strings

• Hidden injections

👉 This ensures safe AI execution in production environments.

🧠 Step 4: Setup Ollama (Local LLM)

Ollama lets you download and run large language models entirely on your own machine — no cloud account, no API key, no usage fees.

📚 Official Resources:

• 🌐 Website: ollama.com

• 📖 Documentation: docs.ollama.com

• 🗂️ Model Library: ollama.com/library

• 🐙 GitHub: github.com/ollama/ollama

🔽 Pulling a Model

Once Ollama is running, pull the model used in this project:

ollama pull qwen2.5:7b

You can verify it's available with:

ollama list

Browse all available models at ollama.com/library. Some good alternatives for SQL agents:

📦 Installing the LangChain Ollama Package

The LangChain integration for Ollama lives in the dedicated langchain-ollama package:

pip install langchain-ollama

📖 Package References:

• 📦 PyPI: pypi.org/project/langchain-ollama

• 🔗 LangChain Docs: docs.langchain.com — ChatOllama

• 📐 API Reference: reference.langchain.com/python/langchain-ollama

⚙️ Configuring ChatOllama

Now initialize the LLM in your Python code:

from langchain_ollama import ChatOllama
 
llm = ChatOllama(model="qwen2.5:7b", temperature=0)

Setting temperature=0 makes the model deterministic — essential for reliable SQL generation. You can tune other key parameters as needed:

Why Ollama?

• ✅ No API cost

• ✅ Runs fully locally — data never leaves your machine

• ✅ Privacy-friendly — ideal for sensitive database workloads

• ✅ Fast inference with GPU support

• ✅ Supports dozens of open-source models

🔗 Step 5: Create LangChain Agent

tools = [list_tables, get_table_schema, execute_sql]
agent = create_agent(llm, tools)

LangChain allows the AI to:

• Decide which tool to use

• Chain multiple steps

• Reason dynamically

💬 Step 6: Interactive Chat Loop

while True:
    user_input = input("\nYou: ").strip()
    if user_input.lower() in ("exit", "quit"):
        print("Goodbye!")
        break
    if not user_input:
        continue

This makes your agent:

• Conversational

• Stateful

• Easy to debug

🧾Step 7: Debugging & Observability

Visibility into what the agent is doing is essential for development. This helper function prints each tool call and its result:

def print_turn_details(messages: list[BaseMessage]) -> None:
    final_response = ""

    for message in messages:
        if isinstance(message, AIMessage):
            for tool_call in message.tool_calls:
                tool_name = tool_call.get("name", "unknown_tool")
                tool_args = format_tool_payload(tool_call.get("args", {}))
                print(f"\nTool call: {tool_name}({tool_args})")

            content = format_content(message.content).strip()
            if content:
                final_response = content

        elif isinstance(message, ToolMessage):
            tool_name = getattr(message, "name", None) or "tool"
            tool_output = format_content(message.content).strip() or "(no output)"
            print(f"\nTool response [{tool_name}]: {tool_output}")

    if final_response:
        print(f"\nAgent: {final_response}")
    else:
        print("\nAgent: I couldn't generate a response.")

Shows:

• Tool calls

• Tool outputs

• Final response

👉 This is extremely useful for debugging agent behavior.

🧪 Example Queries

Try asking:

• "List all tables"

• "Show schema of users table"

• "Get top 5 users by revenue"

• "How many orders were placed last month?"

Real-World Use Cases for a Natural Language Database Agent

This architecture can power a wide range of applications:

📊 AI-Powered Analytics Dashboards — let non-technical stakeholders query live data in plain English without learning SQL.

💬 Internal Data Chatbots — embed in Slack or Microsoft Teams so product and ops teams can self-serve data questions.

🧾 Automated Reporting — schedule the agent to answer recurring questions and generate daily or weekly reports.

🏢 SaaS Admin Panels — give your ops team a natural language interface to your product database.

🤖 AI Copilots for Data Teams — speed up analyst workflows by auto-generating SQL drafts from plain-English specs.

🎯 Conclusion

You've built more than just a demo. This is a secure, extensible AI database agent that can be used in real-world applications.

Key Takeaways:

• LangChain simplifies agent workflows

• Ollama enables local LLM execution

• SQL safety is critical

• Tool-based architecture = powerful AI agents

The core insight: wrapping your database in typed, well-described LangChain tools gives the LLM exactly the context it needs to generate correct SQL — without ever exposing raw database access.

📦 Full Source Code — complete working implementation from this tutorial

The Problem With Building Alone

Before I talk about OpenClaw, let me paint the picture.

When you're building a SaaS product by yourself, you're not just a developer. You're the researcher, the architect, the QA engineer, the SEO specialist, and — if you're lucky — the person who actually writes code. Every decision defaults to you. Every skill gap becomes a blocker.

Want to add authentication? Better research OAuth providers, understand security best practices, and implement it right. Need to figure out email deliverability? Time to go down a 3-hour rabbit hole. Building alone means you're constantly context-switching between "figuring things out" and "actually building."

I know because I've been there. Building ShiftMailer — my product for AI-powered email marketing — meant I had to wear all these hats. And honestly? It was exhausting.

Then Came OpenClaw

OpenClaw isn't just another AI chatbot. It's an AI agent framework that can actually do things — read files, run commands, search the web, analyze code, and coordinate with other tools. It's like having a team member who doesn't sleep, doesn't complain, and can spin up new skills on demand.

Here's what I learned after using it for ShiftMailer development.

What Actually Works

1. Research That Goes Beyond Google

I used to spend hours researching trends, comparing tools, and validating ideas. Now I can ask OpenClaw to:

• Find current trends in email marketing automation

• Compare pricing models of competitors

• Research technical decisions (like multi-tenancy approaches)

It doesn't just give me links — it synthesizes information and gives me actionable insights. This alone saved me days of scattered research.

2. Code That I Still Own

Here's something important: I know how to code. I'm a backend engineer. But that doesn't mean I want to write every boilerplate or debug every edge case alone.

OpenClaw helps me:

• Write faster — It handles the repetitive stuff so I focus on the interesting parts

• Review my code — Fresh eyes catch bugs I missed

• Explore new patterns — I can ask "how would you approach this with Node.js streams?" and get working examples

It's not replacing my skills. It's amplifying them.

3. Real-World Analysis

One surprise: OpenClaw analyzed my website's SEO and gave me specific suggestions. Not generic advice — actual, implementable recommendations based on my content. That's not something I expected an AI agent to do well, but it handled it.

The Honest Take: What Doesn't Work

I promised you an honest review, so here it is:

Orchestration is Hard

OpenClaw is great at analyzing requirements and using individual tools well. But when it comes to coordinating complex multi-step workflows? Sometimes it struggles. Things that would be trivial for a human — "okay, first do A, then B, but only if C worked" — can get messy.

This means I'm still the conductor. The agent executes well, but I'm the one keeping the orchestra in sync.

Security: You Gotta Be Careful

Here's the thing: OpenClaw has access to my files, my environment, my code. That's powerful, but it's also a responsibility.

For now, I'm careful about:

• Not giving agents unrestricted external access

• Reviewing code before shipping

• Keeping sensitive configs isolated

This isn't a criticism of OpenClaw — it's just smart practice. When you're delegating to an AI, trust but verify.

The Comparison: Traditional Cofounder vs. AI Agent

People often ask: "Isn't this like having a cofounder?"

Not really. Here's the difference:

With a traditional cofounder, I'd need to research every aspect myself, find different people for different skills, and coordinate schedules. With OpenClaw, I can say "I need research on X" and get it done — then switch to "help me debug this API" without friction.

What This Means for Solo Builders

If you're building alone, here's what I'd tell you:

AI agents aren't magic. They're tools. And like any tool, they have limits. But if you learn to work with them — to prompt well, to review outputs, to stay in the loop — you can do way more than you could alone.

ShiftMailer exists today because I stopped trying to do everything myself. I found a way to leverage AI that works with my skills, not instead of them.

What's Next

I'm still figuring out the orchestration piece. I'm still being careful about security. But the gap between "idea" and "working product" has shrunk dramatically.

If you're a solo builder on the fence about AI agents — try it. Start small. See what works for your workflow. You might be surprised what you can ship when you're not alone in the room.

Have questions about building with AI agents or want to share your story? Let's connect — find me on X or check out gauravbytes.hashnode.dev.

That approach works—until you need structure, reliability, or production-grade workflows.

In this post, we’ll explore sequential AI agents, how they differ from normal AI agents, and how you can build a multi-step AI workflow using the Vercel AI SDK.

What Is an AI Agent?

An AI agent is a system that:

1. Takes an input (user query, event, or data)

2. Uses an LLM to reason or generate output

3. Optionally calls tools, APIs, or functions

4. Returns a result or performs an action

In many applications, this entire process happens in one step.

Example:

User asks: “Write a product update email”
→ LLM generates the email in a single response

This works well for simple tasks—but it starts breaking down as complexity grows.

Normal AI Agent (Single-Step Agent)

A normal AI agent typically follows this flow:

Input → LLM → Output

Characteristics

• Single prompt

• Single LLM call

• Minimal or no intermediate state

• Fast and cheap

Example Use Cases

• Chatbots

• Text rewriting

• Summarization

• Simple content generation

Limitations

• Hard to enforce structure

• No explicit reasoning steps

• Poor control over multi-stage workflows

• Difficult to debug or extend

When tasks require planning, validation, transformation, or multiple roles, a single-step agent becomes fragile.

What Is a Sequential AI Agent?

A sequential AI agent breaks a task into multiple ordered steps, where:

• Each step has a clear responsibility

• Output of one step becomes input for the next

• Context accumulates across steps

Input
  ↓
Step 1 (Planner Agent)
  ↓
Step 2 (Executor Agent)
  ↓
Step 3 (Refiner / Validator Agent)
  ↓
Final Output

Instead of asking the model to do everything at once, we guide it through a pipeline.

Normal Agent vs Sequential Agent

Sequential agents trade simplicity for control and reliability.

When Are Sequential AI Agents Beneficial?

Sequential agents are ideal when:

1. Tasks Have Clear Phases

Example:

• Planning

• Writing

• Reviewing

• Formatting

2. Output Must Follow Strict Structure

• Emails

• Reports

• JSON schemas

• Code generation

3. Different “Roles” Are Needed

• Product marketer

• Engineer

• Editor

4. You Want Deterministic Pipelines

• SaaS features

• Automations

• Multi-tenant systems

This is why sequential agents work extremely well for:

• Product update emails

• CRM workflows

• Content pipelines

• Data extraction and transformation

Designing a Sequential Agent (Conceptually)

Let’s say we want to build a content generation agent.

Step 1: Planner Agent

Responsibility:

• Analyze the input

• Break it into structured sections

Output:

{
  "sections": ["Introduction", "Key Points", "Conclusion"]
}

Step 2: Writer Agent

Responsibility:

• Generate content for each section

Input:

• Original user input

• Planner output

Step 3: Refiner Agent

Responsibility:

• Improve tone

• Fix grammar

• Enforce constraints

Each step is predictable and replaceable.

Implementing a Sequential AI Agent with Vercel AI SDK

Step 1: Create the Planner Agent

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export async function plannerAgent(input: string) {
  const result = await generateText({
    model: openai("gpt-4.1"),
    prompt: `Analyze the input and create a structured plan.\n\nInput: ${input}`,
  });

  return result.text;
}

Step 2: Create the Writer Agent

export async function writerAgent(plan: string, input: string) {
  const result = await generateText({
    model: openai("gpt-4.1"),
    prompt: `Using the following plan, write detailed content.\n\nPlan:\n${plan}\n\nInput:\n${input}`,
  });

  return result.text;
}

Step 3: Create the Refiner Agent

export async function refinerAgent(content: string) {
  const result = await generateText({
    model: openai("gpt-4.1"),
    prompt: `Refine the following content for clarity and tone.\n\n${content}`,
  });

  return result.text;
}

Step 4: Orchestrate the Sequential Flow

export async function sequentialAgent(input: string) {
  const plan = await plannerAgent(input);
  const draft = await writerAgent(plan, input);
  const finalOutput = await refinerAgent(draft);

  return finalOutput;
}

This orchestration is the heart of a sequential agent.

Benefits of This Approach

• Clear separation of responsibilities

• Easier debugging (inspect each step)

• Reusable agents

• Better output consistency

• Safer production usage

This is especially useful when building AI-powered SaaS features, not demos.

Final Thoughts

Sequential AI agents represent a shift from “ask the model to do everything” to “designing AI workflows.”

With the Vercel AI SDK, building these workflows feels natural and maintainable.

If you’re building:

• AI-first products

• Content pipelines

• Internal tooling

…sequential agents will give you control, clarity, and confidence.

If you’re interested, the next step could be:

• Adding validation agents

• Parallel agents

• Streaming intermediate steps

• Persisting agent state

That’s where AI engineering starts to feel like real software engineering 🚀

• Instead of browsing 20 product pages, users simply ask:
  “Show me red shoes under ₹1500.”

• Instead of navigating a 5-step checkout, they say:
  “Add the second one to my cart and checkout.”

To explore this future, I built a fully functional AI E-Commerce Chatbot using Vercel AI SDK + Gemini, equipped with tools like:

• Fetch Catalog

• Add to Cart

• Checkout Cart

And a UI that responds with card-style product previews, add-to-cart confirmation messages, and interactive checkout prompts.

This blog is a complete to-do guide to help developers build the same chatbot from scratch.

Let’s start building it

🧩 Define Tools for Gemini

Gemini supports function calling, so we define our tools. We will create functions that accept some parameters and return a result based on them. Here, we are using an API call to achieve this, but you can implement any business logic in these functions.

Catalog tool

export async function fetchCatalog({query, maxPrice}: { query: string; maxPrice: number }) {
    const res = await fetch(
        `${process.env.NEXT_PUBLIC_BASE_URL}/api/catalog?query=${query}&maxPrice=${maxPrice}`
    );
    if (!res.ok) throw new Error("Failed to fetch catalog");
    return res.json();
}

Cart tool

export async function addToCart(productId: string, quantity: number) {
    const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/cart`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({product_id: productId, qty: quantity}),
    });
    if (!res.ok) throw new Error("Failed to add to cart");
    return res.json();
}

Checkout Tool

export async function checkoutCart() {
    const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_URL}/api/checkout`, {
        method: "POST",
    });
    if (!res.ok) throw new Error("Failed to checkout");
    return res.json();
}

🛠️ Create the Tool-Enabled Chat API

This is the heart of the chatbot.

Define the prompt for our AI agent

const SYSTEM_PROMPT = `
You are a shopping assistant AI integrated with tools.

You can help the user browse products, add them to a cart, and checkout.

### Available tools:
1. **fetchCatalog()**
   - Retrieves all products from the catalog.
   - Always call this tool to see what products are available before suggesting items.

2. **addToCart(productId: string)**
   - Adds the specified product to the user's cart.
   - Call this when the user asks to "add", "buy", or "I want this".

3. **checkoutCart()**
   - Processes the order and simulates checkout.
   - Only call this if the user explicitly says "checkout", "place order", or "buy now".

---

### Rules of behavior:
- Never invent products. Only use the results returned by 'fetchCatalog'.
- Always confirm product details (name, price, stock) when suggesting items.
- If the user is vague (e.g., "show me something cool"), fetch the catalog and then suggest a few options.
- Be conversational and friendly, but clearly indicate actions you’re taking.
- After a successful checkout, thank the user and end the flow.

---

### Examples:

**User:** "Show me headphones under $150"  
**Assistant reasoning:** Call 'fetchCatalog', filter results by category + price, then present matching products.  

**User:** "Yes, add the headphones to my cart"  
**Assistant reasoning:** Call 'addToCart(productId)' for that item then show the current cart.  

**User:** "Checkout now"  
**Assistant reasoning:** Call 'checkoutCart' and return the order confirmation.
`

API endpoint to use our chatbot

import {convertToModelMessages, streamText, UIMessage} from "ai";
import {addToCart, checkoutCart, fetchCatalog} from "@/lib/tools";
import {google} from "@ai-sdk/google";
import {NextRequest, NextResponse} from "next/server";
import {z} from 'zod';

export const runtime = "edge";
const gemini = google("models/gemini-2.5-flash-lite");


export async function POST(req: NextRequest) {
    try {
        const {messages}: { messages: UIMessage[] } = await req.json()

        const result = await streamText({
            model: gemini,
            system: SYSTEM_PROMPT,
            messages: convertToModelMessages(messages),
            tools: {
                fetchCatalog: {
                    description: "Retrieves all products from the catalog.",
                    inputSchema: z.object({
                        query: z.string().optional().default(""),
                        maxPrice: z.number().optional().default(1000)
                    }),
                    execute: async ({query, maxPrice}) => {
                        return await fetchCatalog({query, maxPrice});
                    }
                },
                addToCart: {
                    description: "Adds the specified product to the user's cart.",
                    inputSchema: z.object({
                        productId: z.string(),
                        quantity: z.number().optional().default(1)
                    }),
                    execute: async ({productId, quantity}) => {
                        return await addToCart(productId, quantity);
                    }
                },
                checkoutCart: {
                    description: "Process checkout and initiate payment",
                    inputSchema: z.object({}),
                    execute: async () => {
                        return await checkoutCart();
                    }
                }
            }
        });


        return result.toUIMessageStreamResponse({
            onError: errorHandler
        });
    } catch (err) {
        console.error("Error : ", err);
        return NextResponse.json({error: "Internal server error"}, {status: 500});
    }
}

function errorHandler(error: unknown) {
    if (error == null) {
        return 'unknown error';
    }

    if (typeof error === 'string') {
        return error;
    }

    if (error instanceof Error) {
        return error.message;
    }

    return JSON.stringify(error);
}

🎨 Build UI With Card Components

When the LLM returns tool results, your UI displays them as cards so we will implement these components in react

🟥 Product Card

// components/ProductCard.tsx
"use client";

import {useState} from "react";

export default function ProductCard({product, addToCart}: { product: any, addToCart: any }) {
    const [adding, setAdding] = useState(false);
    const [added, setAdded] = useState(false);

    const handleAddToCart = async () => {
        setAdding(true);
        addToCart(product?.id, product?.name)
        setAdded(true)
        setAdding(false);
    };

    return (
        <div className="border rounded-xl p-4 shadow-md flex flex-col items-center gap-2 bg-white">
            <img
                src={product.image}
                alt={product.name}
                className="w-32 h-32 object-cover rounded-lg"
            />
            <h3 className="text-lg font-semibold">{product.name}</h3>
            <p className="text-gray-600">₹{product?.price}</p>
            <button
                onClick={handleAddToCart}
                disabled={adding || added}
                className="bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700 disabled:bg-gray-400"
            >
                {adding ? "Adding..." : added ? "Added" : "Add to Cart"}
            </button>
        </div>
    );
}

🟦 Cart Card

"use client";
import {CartItem} from "@/lib/cartStore";
export default function Cart({items = []}: { items?: any }) {
    const total = items?.reduce((sum:number, i:CartItem) => sum + i.price * i.qty, 0);
    return (
        <div className="p-4 bg-white rounded-xl shadow-md w-[320px]">
            <h2 className="text-lg font-bold mb-3">🛒 Your Cart</h2>

            {items.length === 0 && <p className="text-gray-500">Cart is empty</p>}

            <ul className="space-y-3">
                {items.map((item:CartItem) => (
                    <li
                        key={item.productId}
                        className="flex items-center justify-between gap-2 border-b pb-2"
                    >
                        <div className="flex items-center gap-2">
                            {item.image && (
                                <img
                                    src={item.image}
                                    alt={item.name}
                                    className="w-10 h-10 rounded"
                                />
                            )}
                            <div>
                                <p className="font-medium">{item.name}</p>
                                <p className="text-sm text-gray-500">
                                    ₹{item?.price} × {item.qty} =  ${item?.price * item.qty}
                                </p>
                            </div>

                        </div>

                    </li>
                ))}
            </ul>

            {items.length > 0 && (
                <div className="pt-3 flex justify-between font-bold">
                    <span>Total -&nbsp;</span>
                    <span>₹{total ? total.toFixed(2) : "0.00"}</span>
                </div>
            )}
        </div>
    );
}

🟩 Checkout Card

"use client";
import { useState } from "react";
import {OrderItem} from "@/lib/orderStore";

export default function Checkout({order}: { order: OrderItem | null }) {
    const [step, setStep] = useState<"details" | "payment" | "success">("details");
    // mock "processing payment"
    const handlePayment = () => {
        setStep("payment");
        setTimeout(() => setStep("success"), 2000);
    };

    return (
        <div className="p-6 max-w-md mx-auto bg-white rounded-xl shadow-lg">
            <h2 className="text-xl font-bold mb-4">Checkout</h2>

            {step === "details" && (
                <div>
                    <h3 className="font-semibold mb-2">Shipping Info</h3>
                    <form className="space-y-3">
                        <input
                            type="text"
                            placeholder="Full Name"
                            className="w-full border rounded px-3 py-2"
                        />
                        <input
                            type="text"
                            placeholder="Address"
                            className="w-full border rounded px-3 py-2"
                        />
                        <input
                            type="text"
                            placeholder="City"
                            className="w-full border rounded px-3 py-2"
                        />
                        <input
                            type="text"
                            placeholder="ZIP Code"
                            className="w-full border rounded px-3 py-2"
                        />
                    </form>

                    <div className="mt-4 border-t pt-3">
                        <p className="flex justify-between">
                            <span className="font-medium">Total</span>
                            <span>₹{order?.totalAmount}</span>
                        </p>
                    </div>

                    <button
                        onClick={handlePayment}
                        className="mt-4 w-full bg-blue-500 text-white py-2 rounded"
                    >
                        Proceed to Payment
                    </button>
                </div>
            )}

            {step === "payment" && (
                <div className="text-center">
                    <p className="text-gray-600">Processing Payment...</p>
                    <div className="mt-3 animate-spin rounded-full h-10 w-10 border-4 border-blue-500 border-t-transparent mx-auto"></div>
                </div>
            )}

            {step === "success" && (
                <div className="text-center">
                    <h3 className="text-green-600 font-bold text-lg">✅ Payment Successful!</h3>
                    <p className="mt-2 text-gray-600">
                        Thank you for your purchase. Your order will be shipped soon.
                    </p>
                </div>
            )}
        </div>
    );
}

💬Integrate Tool Responses in UI

Your chat page processes three types of messages:

• normal model text

• tool calls

• tool responses

// app/page.tsx
"use client";

import {useChat} from "@ai-sdk/react";
import {DefaultChatTransport} from "ai";
import {useState} from "react";
import {Bot, User} from "lucide-react";
import ProductCard from "@/components/ProductCard";
import Cart from "@/components/CartCard";
import Checkout from "@/components/Checkout";
import {OrderItem} from "@/lib/orderStore";

export default function Home() {
    const {messages, sendMessage, status} = useChat({
        transport: new DefaultChatTransport({
            api: '/api/chat',
        }),
    });
    const [input, setInput] = useState('');

    return (
        <main className="flex flex-col items-center pt-4 min-h-screen bg-white">
            <div className="w-[70vw] bg-white rounded-lg p-6">
                <h1 className="text-2xl font-bold mb-4 text-center">
                    🛍️ Shopping Assistant
                </h1>

                {/* Chat messages */}
                <div className="space-y-4 h-[calc(100vh-200px)] w-full overflow-y-auto p-4 rounded-lg mb-4">
                    {messages.map((m) => (
                        <div
                            key={m.id}
                            className={`flex flex-start items-start gap-3 items-center`}
                        >
                            {m.role === "user" ? (
                                <div className="flex items-center gap-2">
                                    <div className="bg-blue-500 text-white p-2 rounded-full">
                                        <User className="w-5 h-5"/>
                                    </div>
                                </div>) : (
                                <div className="flex items-center gap-2">
                                    <div className="bg-gray-600 text-white p-2 rounded-full">
                                        <Bot className="w-5 h-5"/>
                                    </div>
                                </div>
                            )}
                            <div
                                className={`w-full flex py-[5px] px-[10px] rounded-[10px] ${m.role === "user" ? "bg-blue-100" : "bg-gray-200"}`}>
                                {m.parts.map((part, index) => {
                                        switch (part?.type) {
                                            case 'step-start':
                                                // show step boundaries as horizontal lines:
                                                return index > 0 ? (
                                                    <div key={index} className="text-gray-500">
                                                        <hr className="my-2 border-gray-300"/>
                                                    </div>
                                                ) : null;
                                            case 'tool-fetchCatalog':
                                                switch (part?.state) {
                                                    case 'input-streaming':
                                                        return <span className="italic text-gray-600"
                                                                     key={`tool-${index}`}> 🛍️ Fetching products… </span>;
                                                    case 'input-available':
                                                        return <span className="italic text-gray-600"
                                                                     key={`tool-${index}`}> 🛍️ Fetching products… </span>;
                                                    case 'output-available':
                                                        let products = part.output as any

                                                        return products?.length > 0 ?
                                                           <div className={"flex flex-wrap gap-4"} key={"products-list"}>
                                                                {products?.map((product: any) => {
                                                                    return <ProductCard product={product} addToCart={async (productId:string, productName:string) => {
                                                                        await sendMessage({text: `Add ${productName} to my cart`})
                                                                    }}
                                                                                        key={product.id}/>
                                                                })}
                                                                    </div>
                                                            :
                                                            <div key={`tool-${index}`} className="text-gray-600">No
                                                                products found.</div>
                                                    case 'output-error':
                                                        return <div key={`tool-${index}`}>Error: {part.errorText}</div>;
                                                }
                                                break;
                                            case 'tool-addToCart':
                                                switch (part?.state) {
                                                    case 'input-streaming':
                                                        return <span className="italic text-gray-600"
                                                                     key={`tool-${index}`}>
                                                            ➕ Adding item to cart…
                                                        </span>;
                                                    case 'input-available':
                                                        return <span className="italic text-gray-600"
                                                                     key={`tool-${index}`}>
                                                            ➕ Adding item to cart…
                                                        </span>;
                                                    case 'output-available':
                                                        return <Cart key={`tool-${index}}` } items={part.output as any[]}/>;
                                                    case 'output-error':
                                                        return <div key={`tool-${index}`}>Error: {part.errorText}</div>;
                                                }
                                                break;
                                            case 'tool-checkoutCart':
                                                const order = part?.output as OrderItem
                                                switch (part?.state) {
                                                    case 'input-streaming':
                                                        return <span className="italic text-gray-600"
                                                                     key={`tool-${index}`}>💳 Processing checkout…</span>;
                                                    case 'input-available':
                                                        return <span className="italic text-gray-600"
                                                                     key={`tool-${index}`}>💳 Processing checkout…</span>;
                                                    case 'output-available':
                                                        return <Checkout order={order} key={`tool-${index}`}/>;
                                                    case 'output-error':
                                                        return <div key={`tool-${index}`}>Error: {part.errorText}</div>;
                                                }
                                                break;

                                            case 'text':
                                                return <span key={index}>{part.text}</span>;
                                        }
                                    }
                                )}
                            </div>
                        </div>
                    ))}
                    {status === 'submitted' && <div className="text-gray-500">Thinking...</div>}
                </div>

                {/* Input box */}
                <form onSubmit={e => {
                    e.preventDefault();
                    if (input.trim()) {
                        sendMessage({text: input});
                        setInput('');
                    }
                }} className="flex gap-2">
                    <input
                        className="flex-1 border border-gray-300 shadow-lg rounded-lg px-4 py-2 focus:outline-none focus:ring-1 focus:ring-gray-400"
                        value={input}
                        disabled={status !== 'ready'}
                        placeholder="Ask about products... e.g. 'Show me shoes under 200 rupees'"
                        onChange={e => setInput(e.target.value)}
                    />
                    <button
                        type="submit"
                        className="bg-blue-500 text-white px-4 py-2 rounded-lg hover:bg-blue-600 shadow-lg disabled:opacity-50"
                        disabled={status !== 'ready' || !input.trim()}
                    >
                        Ask
                    </button>
                </form>
            </div>
        </main>
    );
}

Result

List all products

Filter products based on price

Add to cart using text

Checkout feature using text that allows user to pay using preferred method

🎯 What We Just Built

With Gemini tool calling + Vercel AI SDK + Next.js, you now have an:

• AI-powered shopping assistant

• Interactive product catalog chatbot

• Cart-enabled conversational checkout

• Real-time streaming chat UI

• Modern e-commerce experience using React card components

🚀 Next Steps

Add more advanced features:

• 🔍 Vector search (Supabase, Pinecone)

• 🔧 Tool-based filtering (by price, brand, ratings)

• 👤 Personalized recommendations

• 💳 Real checkout integration

• 📦 Track order status

🏁 Conclusion

Using Vercel AI SDK + Google Gemini, we've created a fully interactive e-commerce chatbot that transforms the shopping experience. This innovation allows users to discover products, add items to their cart, and complete the checkout process all within a conversational interface. This development is a significant advancement in the tech world, offering a seamless and engaging way to shop online.

Here is the live version: DEMO

Source code - Github

In this tutorial, we’ll walk through building a simple Ethereum dApp using Next.js, Wagmi, and MetaMask. Our application will let users:

• Connect their MetaMask wallet

• Send ETH to another address on a testnet (Sepolia)

• View their recent transactions in a paginated format

This project is designed as a starting point for anyone who wants to dive into Ethereum development and understand how wallet connections, transactions, and blockchain interactions work in practice.

We’ll use MetaMask as the crypto wallet for connecting and signing transactions, Wagmi (a React hooks library) for interacting with Ethereum, and Next.js for building the frontend of our dApp.

By the end of this guide, you’ll have a fully functional Ethereum dApp running on a testnet—ready to extend into something bigger, like token transfers or DeFi features.

Prerequisites

Before we dive into building the dApp, here’s what you’ll need to get started:

1. Basic Knowledge

• Familiarity with React and Next.js fundamentals

• A basic understanding of Ethereum and how transactions work

• Some exposure to JavaScript/TypeScript

2. Installed Tools

• Node.js & npm/yarn – To run the Next.js project

• MetaMask – Installed as a browser extension or installed on mobile (for connecting and approving transactions)

• VS Code (or any IDE) – To write and manage your project code

3. Ethereum Test Network Setup

We’ll use the Sepolia testnet for this project. That way, you don’t spend real ETH while testing.

👉 Steps:

1. Install MetaMask if you haven’t already.

2. Switch your MetaMask network to Sepolia Test Network.

3. Get some free test ETH from a Sepolia Faucet (just Google Sepolia faucet and request test ETH).

💡 Note: If you’re having trouble getting test ETH, you can also reach out to me via [email], and I can transfer some Sepolia ETH to your wallet for testing.

4. Libraries We’ll Use

• Next.js – React framework for building the frontend

• Wagmi – React hooks for Ethereum (easy wallet connection + transaction handling)

• Viem – A low-level Ethereum library used under the hood by Wagmi

• Tailwind CSS – For styling (optional, but makes UI much easier)

Once you have these prerequisites in place, you’ll be ready to start coding your dApp 🚀

🚀 Project Setup

Let’s set up our Ethereum dApp from scratch. We’ll be using Next.js for the frontend, Wagmi for wallet interactions, and MetaMask as our crypto wallet provider.

1. Create a Next.js App

First, create a new Next.js project using the official CLI:

npx create-next-app eth-dapp
cd eth-dapp

2. Install Dependencies

We’ll need Wagmi, viem, and ethers to connect with Ethereum.

npm install wagmi viem ethers

If you want pretty logging (optional), install pino-pretty:

npm install pino-pretty

3. Configure Wagmi

Inside your project, set up the Wagmi client in a Web3Provider.tsx file. This will allow us to connect to Ethereum testnets like Sepolia.

"use client"
import {createConfig, http, WagmiProvider} from 'wagmi'
import {mainnet, sepolia} from 'wagmi/chains'
import {QueryClient, QueryClientProvider} from "@tanstack/react-query";
import {metaMask} from "@wagmi/connectors";
import {injected} from "wagmi/connectors";

const queryClient = new QueryClient();
export const config = createConfig({
    chains: [mainnet, sepolia],
    connectors: [
        metaMask(),
        injected(),
    ],
    transports: {
        [mainnet.id]: http(),
        [sepolia.id]: http(),
    },
})

export function Web3Provider({children}: { children: React.ReactNode }) {
    return <WagmiProvider config={config}>
        <QueryClientProvider client={queryClient}>
            {children}
        </QueryClientProvider></WagmiProvider>;
}

Now wrap your app in this provider (app/layout.tsx in Next.js 13+):

import {Web3Provider} from "@/lib/web3/Web3Provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
            <Web3Provider>{children}</Web3Provider>
      </body>
    </html>
  );
}

4. Install MetaMask

Make sure you have the MetaMask extension installed in your browser or in your phone.

• Switch to the Sepolia Testnet in MetaMask.

• Request some test ETH from a Sepolia Faucet.

💡 If you’re unable to get test ETH, feel free to email me at [icon.gaurav806@gmail.com] and I can transfer some to your wallet for testing.

👉 That’s our base setup. Next, we’ll build the Wallet Connection component so users can connect their MetaMask wallet to the dApp.

🔗 Connecting Your Wallet

Now that our project is set up with Next.js and Wagmi, let’s add a Wallet Connect button so users can link their MetaMask wallet to the dApp.

1. Create a Wallet Connect Component

Inside components/WalletConnect.tsx, add the following:

"use client"
import { useState } from "react"
import {useAccount, useConnect, useDisconnect} from "wagmi";

export default function WalletConnect({ onAddWallet }: {
    onAddWallet: (address: string) => void
}) {
    const {connectAsync, connectors, status , reset, error} = useConnect();
    const { disconnect } = useDisconnect();
    const handleConnect = async () => {
        try {
            disconnect(); // Disconnect any existing connection
            const connector = connectors[0]; // Assuming the first connector is the one we want
            const data = await connectAsync({ connector });
            onAddWallet(data?.accounts?.[0]);
        } catch (error) {
            reset()
            console.error("Failed to connect wallet:", error);
            console.log(error)
        }
    }


    return (
        <div className="max-w-md mx-auto mt-10 p-6 bg-white rounded-2xl shadow-md">
            <h2 className="text-xl font-semibold text-gray-800 mb-4">Add Wallet</h2>

            <div className="text-center">
                <button
                    onClick={handleConnect}
                    className="w-full py-2 px-4 bg-green-600 text-white rounded-lg hover:bg-green-700 transition"
                >
                    {status === 'pending'? 'Connecting...' :'Connect Using External Wallet'}
                </button>

                {error && <p className="text-red-600 mt-2">{error.message}</p>}
            </div>
        </div>
    )
}

2. Add It to the Homepage

Open app/page.tsx and include the WalletConnect component:

import WalletConnect from "@/components/WalletConnect";

export default function Home() {
  return (
    <div className="flex flex-col items-center justify-center px-6">

            {/* ===== Hero Section with Wallet Connect ===== */}
            <section className="text-center mt-20 max-w-3xl">
                <h1 className="text-5xl font-extrabold text-gray-900 mb-6">
                    Manage Your Crypto with Ease 🚀
                </h1>
                <p className="text-lg text-gray-600 mb-8">
                    Create wallets, send & receive Ethereum, and track transactions —
                    all in one secure, easy-to-use app.
                </p>

                {/* Connect CTA */}
                <div className="mt-6">
                    <WalletConnect onAddWallet={() => redirect('/dashboard')}/>
                    <p className="text-sm text-gray-500 mt-3">
                        Don’t have a wallet yet? Install{" "}
                        <Link
                            href="https://metamask.io/download/"
                            target="_blank"
                            rel="noopener noreferrer"
                            className="text-blue-600 underline"
                        >
                            MetaMask
                        </Link>{" "}
                        to get started.
                    </p>
                </div>
            </section>
    </div>
  );
}

3. Test It

• Run your dev server:

npm run dev

• Open http://localhost:3000.

• 

• Click Connect Wallet → MetaMask should pop up asking for approval.

• 

• Once connected, you’ll see get redirected to dashboard page.

✅ At this stage, your dApp can connect and disconnect a wallet.
Next, we’ll extend this by fetching account details and showing balances.

💰 Fetching Wallet Details & Balances

Once users connect their wallet, we can show them their Ethereum address, balance, and even a quick copy button. This helps them confirm they are on the right account before sending transactions.

1. Fetch Account Details with Wagmi

Wagmi provides hooks like useAccount and useBalance to make this easy. Inside app/dashboard/page.tsx, add the following:

"use client";

import {useAccount, useBalance} from "wagmi";
import {useState} from "react";
import {Copy, Send, Wallet, ExternalLink, X} from "lucide-react";
import {redirect} from "next/navigation";
import SendTransaction from "@/components/SendTransaction";

export default function DashboardPage() {
    const {address, isConnected} = useAccount();
    const {data: balance} = useBalance({address});


    const handleCopy = () => {
        if (address) {
            navigator.clipboard.writeText(address);
            alert("Wallet address copied!");
        }
    };

    if (!isConnected) {
        return (
            <div className="flex items-center justify-center min-h-screen p-4">
                <div className="p-6 border rounded-lg shadow-md text-center w-full max-w-sm">
                    <p className="text-lg font-semibold">No wallet connected</p>
                    <p className="text-sm text-gray-500 mt-2">
                        Please connect your wallet to view your dashboard.
                    </p>
                </div>
            </div>
        );
    }

    return (
        <div className="p-4 sm:p-8 space-y-6 sm:space-y-8">
            <h1 className="text-2xl sm:text-3xl font-bold">Dashboard</h1>

            {/* Wallet Info */}
            <div className="border rounded-lg shadow-md p-4 sm:p-6 flex items-center justify-between gap-4">
                <div className="flex items-center gap-4 w-full">
                    <Wallet className="w-8 h-8 sm:w-10 sm:h-10 text-blue-600"/>
                    <div className="min-w-0 flex-1">
                        <p className="text-sm text-gray-500">Connected Wallet</p>
                        <p className="font-semibold text-sm sm:text-base break-all ">{address}</p>
                    </div>
                </div>
                <button
                    onClick={handleCopy}
                    className="p-2 border rounded-lg hover:bg-gray-100 flex-shrink-0"
                >
                    <Copy className="w-4 h-4"/>
                </button>
            </div>


            {/* Balance Info */}
            <div className="border rounded-lg shadow-md p-4 sm:p-6">
                <p className="text-sm text-gray-500">Total Balance</p>
                <p className="text-xl sm:text-2xl font-bold mt-2">
                    {balance ? `${balance.formatted} ${balance.symbol}` : "Loading..."}
                </p>
            </div>


        </div>
    );
}

2. Test It

• Connect your wallet.

• Head to /dashboard.

• You should now see your wallet address, a copy icon, and your ETH balance.

✅ With this, your dApp shows real-time account info after connection.
Next up, we’ll implement the Send ETH feature with a modal for transfers.

🚀 Sending ETH with a Transaction Modal

One of the key features of our dApp is the ability to send ETH directly from the dashboard. For this, we’ll build a modal form where users can:

• Enter a recipient’s address

• Enter the amount to send

• Confirm the transfer in MetaMask

We’ll use wagmi’s useSendTransaction hook along with viem’s parseEther utility.

1. Send Transaction Component

Inside components/SendTransaction.tsx, add the following:

"use client";

import { useState } from "react";
import { useSendTransaction, useWaitForTransactionReceipt } from "wagmi";
import { parseEther } from "viem";
import Link from "next/link";

export default function SendTransaction() {
    const [to, setTo] = useState<`0x${string}` | "">("");
    const [amount, setAmount] = useState("");

    const { data: txHash, isPending, sendTransaction, error } = useSendTransaction();
    const { isLoading: isConfirming, isSuccess: isConfirmed } =
        useWaitForTransactionReceipt({
            hash: txHash, // hash of transaction
        });

    const handleSend = async () => {
        try {
            await sendTransaction({
                to: to as `0x${string}`,
                value: parseEther(amount), // convert ETH string to wei
            });
        } catch (err) {
            console.error("Transaction failed:", err);
        }
    };

    return (
        <div className="p-4 max-w-md mx-auto space-y-4 rounded">
            <h2 className="text-lg font-semibold">Send ETH</h2>

            <input
                type="text"
                placeholder="Recipient address (0x...)"
                value={to}
                onChange={(e) => setTo(e.target.value as `0x${string}` | "")}
                className="w-full p-2 border rounded"
            />

            <input
                type="text"
                placeholder="Amount (ETH)"
                value={amount}
                onChange={(e) => setAmount(e.target.value)}
                className="w-full p-2 border rounded"
            />

            <button
                onClick={handleSend}
                disabled={isPending}
                className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:bg-gray-400"
            >
                {isPending ? "Sending..." : "Send"}
            </button>

            {/* Transaction States */}
            {isPending && <p className="text-yellow-600">⏳ Transaction is being sent...</p>}
            {isConfirming && <p className="text-blue-600">⏳ Waiting for confirmation...</p>}
            {isConfirmed && (
                <p className="text-green-600">
                    ✅ Transaction confirmed!
                </p>
            )}

            {/* Transaction Details */}
            {txHash && (
                <div className="mt-2 space-y-2">
                    <p className="text-sm break-all">
                        🔗 Tx Hash: {txHash}
                    </p>
                    <Link
                        href={`https://sepolia.etherscan.io/tx/${txHash}`}
                        target="_blank"
                        className="underline text-blue-600"
                    >
                        View on Etherscan
                    </Link>
                    <br />
                    <Link
                        href={`/dashboard`}
                        className="underline text-purple-600"
                    >
                        Go to Dashboard
                    </Link>
                </div>
            )}

            {error && (
                <p className="text-sm text-red-600">
                    ❌ Error: {error.message}
                </p>
            )}
        </div>
    );
}

2. Add Modal to Dashboard

We’ll trigger the modal using a Send Money button.

"use client";

import {useAccount, useBalance} from "wagmi";
import {useState} from "react";
import {Copy, Send, Wallet, ExternalLink, X} from "lucide-react";
import {redirect} from "next/navigation";
import SendTransaction from "@/components/SendTransaction";

export default function DashboardPage() {
    const {address, isConnected} = useAccount();
    const {data: balance} = useBalance({address});

    const [isModalOpen, setIsModalOpen] = useState(false);

    const handleCopy = () => {
        if (address) {
            navigator.clipboard.writeText(address);
            alert("Wallet address copied!");
        }
    };

    if (!isConnected) {
        return (
            <div className="flex items-center justify-center min-h-screen p-4">
                <div className="p-6 border rounded-lg shadow-md text-center w-full max-w-sm">
                    <p className="text-lg font-semibold">No wallet connected</p>
                    <p className="text-sm text-gray-500 mt-2">
                        Please connect your wallet to view your dashboard.
                    </p>
                </div>
            </div>
        );
    }

    return (
        <div className="p-4 sm:p-8 space-y-6 sm:space-y-8">
            <h1 className="text-2xl sm:text-3xl font-bold">Dashboard</h1>

            {/* Wallet Info */}
            <div className="border rounded-lg shadow-md p-4 sm:p-6 flex items-center justify-between gap-4">
                <div className="flex items-center gap-4 w-full">
                    <Wallet className="w-8 h-8 sm:w-10 sm:h-10 text-blue-600"/>
                    <div className="min-w-0 flex-1">
                        <p className="text-sm text-gray-500">Connected Wallet</p>
                        <p className="font-semibold text-sm sm:text-base break-all ">{address}</p>
                    </div>
                </div>
                <button
                    onClick={handleCopy}
                    className="p-2 border rounded-lg hover:bg-gray-100 flex-shrink-0"
                >
                    <Copy className="w-4 h-4"/>
                </button>
            </div>


            {/* Balance Info */}
            <div className="border rounded-lg shadow-md p-4 sm:p-6">
                <p className="text-sm text-gray-500">Total Balance</p>
                <p className="text-xl sm:text-2xl font-bold mt-2">
                    {balance ? `${balance.formatted} ${balance.symbol}` : "Loading..."}
                </p>
            </div>

            {/* Actions */}
            <div className="flex flex-col gap-4 sm:flex-row">
                <button
                    onClick={() => setIsModalOpen(true)}
                    className="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 w-full sm:w-auto"
                >
                    <Send className="w-4 h-4"/> Send Money
                </button>

            </div>

            {/* Send Money Modal */}
            {isModalOpen && (
                <div className="fixed inset-0 flex items-center justify-center bg-black/40 p-4">
                    <div className="bg-white rounded-lg shadow-lg w-full max-w-md p-6 relative">
                        <button
                            onClick={() => setIsModalOpen(false)}
                            className="absolute top-2 right-2 p-1 rounded hover:bg-gray-100"
                        >
                            <X className="w-5 h-5"/>
                        </button>
                        <SendTransaction/>
                    </div>
                </div>
            )}
        </div>
    );
}

3. Test the Flow

1. Connect your wallet

2. Enter a recipient address and amount

3. 

   🎉 ETH is transferred on the testnet

4. 

   Confirm the transaction in MetaMask or in Etherscan

✅ Now your dApp supports ETH transfers via a clean modal UI.

Next, we’ll build the Transactions Page to view past transfers with pagination.

📜 Viewing Past Transactions

Once users can send ETH, the next logical step is to view their past transactions. This helps them keep track of transfers, amounts, and recipients directly from our dApp.

We’ll use Etherscan APIs (or any testnet block explorer API) to fetch transaction history for the connected wallet. For simplicity, we’ll show a paginated table of transactions.

1. Transactions Page

Inside app/transactions.tsx, add the following:

"use client";

import {useAccount} from "wagmi";
import {useEffect, useState} from "react";
import {ExternalLink} from "lucide-react";

interface Transaction {
    hash: string;
    from: string;
    to: string;
    value: string;
    timeStamp: number;
}

export default function TransactionsPage() {
    const {address, isConnected} = useAccount();
    const [transactions, setTransactions] = useState<Transaction[]>([]);
    const [page, setPage] = useState(1);
    const [loading, setLoading] = useState(false);

    // replace this with your provider API
    const fetchTransactions = async (pageNumber: number) => {
        if (!address) return;
        setLoading(true);

        try {
            // Example using Etherscan API (you can use Alchemy/Moralis/Blockscout too)
            const res = await fetch(
                `https://api-sepolia.etherscan.io/api?module=account&action=txlist&address=${address}&startblock=0&endblock=99999999&page=${pageNumber}&offset=5&sort=desc&apikey=${process.env.NEXT_PUBLIC_ETHERSCAN_API_KEY}`
            );
            const data = await res.json();
            setTransactions(data.result);

        } catch (err) {
            console.error("Error fetching transactions:", err);
        } finally {
            setLoading(false);
        }
    };

    useEffect(() => {
        if (isConnected) {
            fetchTransactions(page);
        }
    }, [page, isConnected]);

    if (!isConnected) {
        return (
            <div className="flex items-center justify-center min-h-screen">
                <div className="p-6 border rounded-lg shadow-md text-center">
                    <p className="text-lg font-semibold">No wallet connected</p>
                    <p className="text-sm text-gray-500 mt-2">
                        Connect your wallet to view transactions.
                    </p>
                </div>
            </div>
        );
    }

    return (
        <div className="p-8 w-full">
            <h1 className="text-2xl font-bold mb-6">Transactions</h1>

            {loading ? (
                <p>Loading transactions...</p>
            ) : (
                <div className="overflow-x-auto border rounded-lg">
                    <table className="min-w-full text-sm">
                        <thead className="bg-gray-100">
                        <tr>
                            <th className="px-4 py-2 text-left">Sender</th>
                            <th className="px-4 py-2 text-left">Receiver</th>
                            <th className="px-4 py-2">Type</th>
                            <th className="px-4 py-2">Date</th>
                            <th className="px-4 py-2">Amount (ETH)</th>
                            <th className="px-4 py-2">Status</th>
                        </tr>
                        </thead>
                        <tbody>
                        {transactions.map((tx) => {
                            const type =
                                tx.from.toLowerCase() === address?.toLowerCase()
                                    ? "Sent"
                                    : "Received";

                            const date = new Date(
                                parseInt(tx.timeStamp.toString()) * 1000
                            ).toLocaleString();

                            const amount = (parseFloat(tx.value) / 1e18).toFixed(5);

                            return (
                                <tr key={tx.hash} className="border-t hover:bg-gray-50">
                                    <td className="px-4 py-2">{tx.from}</td>
                                    <td className="px-4 py-2">{tx.to}</td>
                                    <td className="px-4 py-2 text-center">{type}</td>
                                    <td className="px-4 py-2">{date}</td>
                                    <td className="px-4 py-2">{amount}</td>
                                    <td className="px-4 py-2 text-center">
                                        <a
                                            href={`https://sepolia.etherscan.io/tx/${tx.hash}`}
                                            target="_blank"
                                            rel="noopener noreferrer"
                                            className="inline-flex items-center gap-1 text-blue-600 hover:underline"
                                        >
                                            View <ExternalLink className="w-4 h-4"/>
                                        </a>
                                    </td>
                                </tr>
                            );
                        })}
                        </tbody>
                    </table>
                </div>
            )}

            {/* Pagination Controls */}
            <div className="flex justify-between mt-4">
                <button
                    disabled={page === 1}
                    onClick={() => setPage((p) => Math.max(p - 1, 1))}
                    className="px-4 py-2 border rounded disabled:opacity-50"
                >
                    Previous
                </button>
                <span className="px-4 py-2">Page {page}</span>
                <button
                    onClick={() => setPage((p) => p + 1)}
                    className="px-4 py-2 border rounded"
                >
                    Next
                </button>
            </div>
        </div>
    );
}

2. Key Features

• Etherscan API integration – fetches real transaction data

• Pagination support – only 5 transactions per page

• Clickable transaction hashes – link to Sepolia Etherscan explorer

• Formatted ETH values & timestamps

3. User Flow

1. User navigates to Transactions Page

2. dApp fetches their latest transactions from Sepolia testnet

3. Users can browse through pages for full history

4. Each transaction is clickable → Opens in Etherscan

In this guide, we built a simple yet powerful Ethereum dApp using Next.js, Wagmi, and MetaMask.
We walked through:

• 🔗 Connecting a crypto wallet with MetaMask

• 👛 Checking wallet balances on the Sepolia testnet

• 💸 Sending ETH transactions directly from the browser

• 📜 Viewing transaction history with pagination and Etherscan links

This project gives you a solid foundation for building decentralized applications. From here, you can expand in many exciting directions:

🚀 Possible Next Steps

• Token Transfers (ERC-20): Add support for sending tokens like USDC or DAI.

• Smart Contracts: Deploy your own contracts and interact with them.

• NFT Support (ERC-721/1155): Mint, transfer, and display NFTs in your dApp.

• Improved UI/UX: Add notifications, confirmations, and a polished dashboard.

• Security Features: Integrate rate limiting, error handling, and input validation.

👉 This dApp is just the starting point. With these building blocks, you can craft anything from a DeFi dashboard to a full-scale Web3 application.

🌐 Try it out yourself
You can explore the live version here: Deployed dApp

💻 View or fork the code
Check out the full source code on GitHub: GitHub Repo

🔮 What’s Next in Our Blog Series?

In the next post, we’ll explore integrating smart contracts into our dApp so that users can interact with decentralized logic directly from the UI.

Instead of rigid endpoints and verbose documentation, MCP offers a dynamic, model-based architecture that’s inherently more compatible with how LLMs operate. In this guide, I’ll show you how to build an MCP server backed by PostgreSQL using FastMCP and psycopg2, explain the pain points it solves and walk you through the key steps to get it running—so you can focus on building smarter systems without drowning in boilerplate. Let’s dive in.

What is an MCP Server?

Model Context Protocol (MCP) is an open-source set of rules, developed by Anthropic, that establishes a standard way for applications to provide relevant context to Large Language Models (LLMs).

Envision MCP as a universal connector, much like a USB-C port for AI. Just as USB-C allows various devices to connect to a wide range of accessories in a standardized manner, MCP enables AI models to seamlessly interface with diverse data sources and tools. This standardization simplifies the process of building AI agents and complex workflows, offering pre-built integrations and the flexibility to work with different LLM providers while prioritizing data security within your own infrastructure.

Without interfaces like MCP, LLMs are limited to their built-in capabilities and training data. With MCP, they can be empowered to:

• Read files and databases

• Execute commands

• Access APIs

• Interact with local tools

• And more!

All of this happens with user oversight and permission, making it both powerful and secure.

MCP Architecture

MCP has the following components

• MCP Hosts: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP

• MCP Clients: Protocol clients that maintain 1:1 connections with servers

• MCP Servers: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol

• Local Data Sources: Your computer’s files, databases, and services that MCP servers can securely access

• Remote Services: External systems available over the internet (e.g., through APIs) that MCP servers can connect to

Core MCP Concepts

MCP servers can provide three main types of capabilities:

1. Resources: File-like data that can be read by clients (like API responses or file contents)

2. Tools: Functions that can be called by the LLM (with user approval)

3. Prompts: Pre-written templates that help users accomplish specific tasks

MCP Resource

Resources are MCP’s way of exposing read-only data to LLMs. A resource is anything that has content that can be read, such as:

• Files on your computer

• Database records

• API responses

• Application data

• System information

Each resource has:

• A unique URI (like [file:///example.txt](file:///example.txt) or database://users/123)

• A display name

• Optional metadata (description, MIME type)

• Content (text or binary data)

MCP Tools

Tools are executable functions that LLMs can call to perform actions or retrieve dynamic information. Unlike resources, which are read-only, and prompts, which structure LLM interactions, tools allow LLMs to actively do things like calculate values, make API calls, or modify data.

Tools enable LLMs to interact with systems and perform actions.

What are MCP Prompts?

Prompts in MCP are structured templates that servers provide to standardize interactions with language models. Unlike resources which provide data, or tools which execute actions, prompts define reusable message sequences and workflows that help guide LLM behavior in consistent, predictable ways.

In this article we are going to create mcp server for postgreSQL step by step

Setting Up Your Development Environment

First, let’s install uv and set up our Python project and environment:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Make sure to restart your terminal afterwards to ensure that the uv command gets picked up.

Create Project Directory

Now, let’s create and set up our project:

# Create a new directory for our project
uv init mcp-server
cd mcp-server

# Create virtual environment and activate it
uv venv
.venv\Scripts\activate

# Install dependencies
uv add mcp[cli] httpx

# Create our server file
new-item server.py

Now let’s dive into building your server.

Building your server

Update the server.py according to the following code:

1. Import the packages

2. Database wrapper class for database connection and database queries

3. Define App Context

4. Define app lifespan and pass this lifespan to MCP instance along with MCP Server name

from contextlib import asynccontextmanager
from collections.abc import AsyncIterator
from dataclasses import dataclass

import asyncpg
from mcp.server.fastmcp import FastMCP, Context

# Async PostgreSQL wrapper using asyncpg
class Database:
    def __init__(self, pool: asyncpg.Pool):
        self.pool = pool

    @classmethod
    async def connect(cls) -> "Database":
        pool = await asyncpg.create_pool(
            user="#user",
            password="#your_password",
            database="Your_database_name",
            host="#database_host",
            port='#Port_number',
        )
        return cls(pool)

    async def disconnect(self):
        await self.pool.close()

    async def query(self, query: str) -> list:
        async with self.pool.acquire() as conn:
            try:
                return await conn.fetch(query)
            except Exception as e:
                print(f"Query error: {e}")
                return []

    async def fetch_schema(self) -> list:
        query = """
        SELECT table_name FROM information_schema.tables
        WHERE table_schema = 'public'
        """
        return await self.query(query)


@dataclass
class AppContext:
    db: Database


@asynccontextmanager
async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
    db = await Database.connect()
    try:
        yield AppContext(db=db)
    finally:
        await db.disconnect()


mcp = FastMCP("PostgresMCPServer", lifespan=app_lifespan)

The FastMCP class uses Python type hints and docstrings to automatically generate tool definitions, making it easy to create and maintain MCP tools.

Implementing MCP tools

The tool execution handler is responsible for actually executing the logic of each tool. Let’s add it:

@mcp.tool("fetch_schema")
async def fetch_schema(ctx: Context) -> str:
    db = ctx.request_context.lifespan_context.db
    schema = await db.fetch_schema()
    return str([record["table_name"] for record in schema])


@mcp.tool("fetch_all_tables")
async def fetch_all_tables(ctx: Context) -> str:
    db = ctx.request_context.lifespan_context.db
    query = "SELECT * FROM information_schema.tables WHERE table_schema='public'"
    tables = await db.query(query)
    return str(tables)


@mcp.tool("run_query")
async def run_query(ctx: Context, query: str) -> str:
    db = ctx.request_context.lifespan_context.db
    result = await db.query(query)
    return str(result)

​Running the server

Finally, let’s initialize and run the server:

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run()

Your server is complete! Run uv run server.py to confirm that everything’s working.

Let’s now test your server from an existing MCP host, Claude for Desktop.

Testing your server with Claude for Desktop

There are several ways to test your MCP server. One way is with Claude Desktop, and you can also use the MCP Inspector tool to test all capabilities during development.

Setting Up Claude Desktop

Here are the steps for setting up an MCP server in Claude Desktop:

1. Install Claude for Desktop if you haven’t already

2. Open Claude and access Settings

   You can access it in your [path of claude desktop installation]/claude_desktop_config.json

3. Edit configuration

    {
      "mcpServers": {
        "PostgresMCPServer": {
          "command": "uv",
          "args": [
            "run",
            "--with",
            "mcp[cli]",
            "mcp",
            "run",
            "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\server.py"
          ]
        }
      }
    }
   

This tells Claude for Desktop:

1. There’s an MCP server named “weather”

2. To launch it by running uv command with the following arguments

Save the file, and restart Claude for Desktop.

Test with Claude Desktop

Let’s make sure Claude for Desktop is picking up the 3 tools we’ve exposed in our PostgresMCPServer server. You can do this by looking for the setting icon

After clicking on the setting icon, you should see the MCP server listed:

After clicking the PostgresMCPServer, you should see the MCP tools listed:

If you can see the tools here, you can now test your server

We will test the server using the following commands:

1. Retrieve information on all tables within the database.

2. Use Claude Desktop to summarize the relationships between the tables.

3. Use Claude to generate a bar graph illustrating the comparison between events and registration counts.

Finally…

Building an MCP server powered by PostgreSQL offers a dynamic and efficient way to integrate large language models with structured data. By leveraging the Model Context Protocol, developers can create adaptive systems that bypass the limitations of traditional APIs, allowing AI agents to interact seamlessly with various data sources and tools. This approach not only simplifies the development process but also enhances the capabilities of AI models, enabling them to perform complex tasks with greater ease and security. By following the steps outlined in this guide, you can set up your own MCP server and unlock new possibilities for smarter, more responsive systems.

Enter GraphQL Federation—a powerful solution that lets you compose a unified GraphQL API from multiple microservices, while keeping each service independently developed and deployed.

In this article, we’ll break down what GraphQL Federation is, how it works, and why it’s a game-changer for modern backend systems.

🧩 What Is GraphQL Federation?

GraphQL Federation is a technique introduced by Apollo that allows multiple GraphQL services (called subgraphs) to be merged into a single, unified API gateway (called the federated gateway).

It solves a critical issue in microservice architectures: how to let teams work independently on their own GraphQL schemas, while still offering a seamless client experience through a single graph.

Key Components:

🔍 Core Concepts Explained

1. Entity Resolution with @key

If multiple services work on the same entity (e.g., User), the @key directive tells the gateway how to resolve it:

type User @key(fields: "id") {
  id: ID!
  name: String
}

2. Service Extension with @extends

A service can add fields to an entity defined in another service:

# In the reviews subgraph
extend type User @key(fields: "id") {
  id: ID! 
  reviews: [Review]
}

3. Gateway Composition

The gateway uses service definitions from each subgraph (via introspection or static configs) and composes them into a single schema that the client can query.

💡 Real-World Example: E-Commerce Platform

Let’s say you're building an e-commerce platform with the following services:

• User Service: Manages user data.

• Product Service: Manages products available in the store.

• Order Service: Manages customer orders and ties users to the products they purchase.

With GraphQL Federation, each service defines its part of the schema and can extend entities from other services to build a unified graph.

🔹 Schema in User Service:

type User @key(fields: "id") {
  id: ID!
  name: String
  email: String
}

This defines the User entity and its primary key (id). It can be referenced by other services.

🔹 Schema in Product Service:

type Product @key(fields: "id") {
  id: ID!
  name: String
  price: Float
}

Each product has its own ID, name, and price.

🔹 Schema in Order Service:

type Order @key(fields: "id") {
   id: ID!
   quantity: Int
   orderDate: String
   user:User @provides(fields: "id")
   product:Product @provides(fields: "id")
   total: Float
}

extend type User @key(fields: "id") {
  id: ID! 
}

extend type Product @key(fields: "id") {
  id: ID! 
}

This service defines the Order entity, and extends both User and Product entities to show which users placed orders and which products were purchased.

🧪 Unified Query at the Gateway:

Once the services are federated into a single gateway, clients can query them as one unified schema:

query {
  orders {
    id
    quantity
    orderDate
    user {
      id
      name
      email
    }
    product {
      id
      name
      price
    }
  }
}

This single query fetches user details, their orders, and associated product details—even though the data is spread across three separate services.

🚦 How Federation Makes This Work

• The User Service owns the User type.

• The Product Service owns the Product type.

• The Order Service stitches everything together by referencing User and Product entities using the @extends directive.

This setup allows each team to focus on their domain, deploy independently, and still contribute to a shared graph that feels seamless to the client.

⚙️ Setting Up Apollo Federation (Simplified Steps)

To federate your services using Apollo Federation, follow these steps:

🔧 Step 1: Set Up Each Subgraph (User, Product, Order)

Each service is an independent GraphQL server using the @apollo/subgraph package.

1.1 Install Dependencies

npm install @apollo/subgraph graphql

👤 User Service

Schema (user-schema.graphql)

type User @key(fields: "id") {
  id: ID!
  name: String
  email: String
}

Server Setup (index.js)

const { ApolloServer } = require('@apollo/server');
const { buildSubgraphSchema } = require('@apollo/subgraph');
const { startStandaloneServer } = require('@apollo/server/standalone');
const gql = require('graphql-tag');

const typeDefs = gql(require('fs').readFileSync('./user-schema.graphql', 'utf-8'));
const resolvers = {
  User: {
    __resolveReference(user) {
      return users.find(u => u.id === user.id);
    },
  },
};

const server = new ApolloServer({
  schema: buildSubgraphSchema([{ typeDefs, resolvers }]),
});

startStandaloneServer(server, { listen: { port: 4001 } });

📦 Product Service

Schema (product-schema.graphql)

type Product @key(fields: "id") {
  id: ID!
  name: String
  price: Float
}

Server Setup (index.js)

Use the same @apollo/subgraph setup, listening on port 4002.

📑 Order Service

This one extends both User and Product entities.

Schema (order-schema.graphql)

type Order @key(fields: "id") {
  id: ID!
  user: User
  products: [Product]
  total: Float
}

extend type User @key(fields: "id") {
  id: ID!
  orders: [Order]
}

extend type Product @key(fields: "id") {
  id: ID!
  purchasedBy: [User]
}

Server Setup

Use the same @apollo/subgraph setup, listening on port 4003.

🛠 Step 2: Set Up Apollo Gateway

This service composes the subgraphs and exposes one unified schema.

Install Required Packages

npm install @apollo/gateway graphql @apollo/server

Gateway Setup (gateway.js)

const { ApolloServer } = require('@apollo/server');
const { ApolloGateway } = require('@apollo/gateway');
const { startStandaloneServer } = require('@apollo/server/standalone');

const gateway = new ApolloGateway({
  serviceList: [
    { name: 'user', url: 'http://localhost:4001' },
    { name: 'product', url: 'http://localhost:4002' },
    { name: 'order', url: 'http://localhost:4003' },
  ],
});

const server = new ApolloServer({ gateway, subscriptions: false });

startStandaloneServer(server, { listen: { port: 4000 } }).then(({ url }) => {
  console.log(`🚀 Gateway ready at ${url}`);
});

🔁 Step 3: Start All Services

In separate terminal tabs or scripts:

# Terminal 1
node user/index.js

# Terminal 2
node product/index.js

# Terminal 3
node order/index.js

# Terminal 4
node gateway.js

Now your GraphQL API is live at http://localhost:4000/graphql and unified!

🧪 Step 4: Query the Federated Schema

Test it with a powerful, nested query:

query {
  orders {
    id
    quantity
    orderDate
    user {
      id
      name
      email
    }
    product {
      id
      name
      price
    }
  }
}

Even though user, order, and product are handled by separate microservices, this single query works flawlessly via federation!

⚖️ Pros and Cons of Using GraphQL Federation

Before adopting GraphQL Federation in your architecture, it’s important to weigh its advantages and potential challenges. Here’s a balanced look:

✅ Pros of GraphQL Federation

⚠️ Cons of GraphQL Federation

🧠 When to Use GraphQL Federation

Use Federation when:

• You have multiple teams working on different domains (e.g., user, orders, products).

• You want to avoid monolithic GraphQL servers.

• You’re already on a microservices architecture and need a clean API layer.

• You need to enable schema composition and controlled entity extension.

Avoid Federation when:

• You have a small team or a small monolithic app.

• Your microservices don't share much schema or are loosely coupled.

• You’re not familiar with GraphQL or don’t have time to invest in tooling/setup.

🎯 Conclusion: Future-Proof Your Backend

GraphQL Federation brings structure, scalability, and clarity to the chaos of microservice APIs. It aligns perfectly with the modular development goals of backend teams, while keeping the developer experience smooth on both server and client ends.

If you're building a microservices architecture or already using GraphQL, federation is worth exploring—especially with tools like Apollo Federation leading the way.

👉 Ready to federate your GraphQL APIs?
Start small—break one schema into subgraphs and try running a gateway locally. You’ll see the power of Federation in action.

Don’t forget to share this post with your team and bookmark it for reference!

DataLoader is a generic utility developed by Facebook for batching and caching database queries efficiently in GraphQL applications. It helps in reducing redundant queries and solving the N+1 query problem by grouping multiple queries into a single batch request.

Key Features of DataLoader:

1. Batching: Combines multiple database requests into a single query to optimize performance.

2. Caching: Stores results to prevent redundant database calls in the same request cycle.

3. Asynchronous Execution: Uses promises to handle multiple database requests efficiently.

By integrating DataLoader into GraphQL resolvers, we can significantly improve the efficiency and scalability of our APIs.

Why DataLoader is Necessary 🧐

GraphQL APIs provide flexibility in data fetching, allowing clients to request only the necessary data. However, this flexibility can lead to the N+1 query problem, a common performance issue where multiple queries to related data cause database inefficiencies.

The N+1 Query Problem 🏗️

In a GraphQL resolver, if fetching related data requires separate queries for each parent record, it results in an exponential increase in database calls. Consider an example:

const resolvers = {
  Query: {
    users: async () => await db.User.findAll(),
  },
  User: {
    posts: async (parent) => await db.Post.findAll({ where: { userId: parent.id } })
  }
};

If we fetch 10 users along with their posts, the resolver first queries for users (1 query), then for each user, it fetches their posts (10 additional queries). This results in 11 queries instead of an optimal 2 queries.

How DataLoader Solves This Problem

DataLoader batches multiple queries into a single request and caches results to avoid redundant calls. It allows GraphQL resolvers to efficiently fetch related data in bulk. 📦🔗⚡

Step-by-Step Implementation📝

1. Install DataLoader 🔧

If not already installed, add DataLoader to your project:

npm install dataloader

2. Create a DataLoader for Batching Queries 📊

In your GraphQL setup, define a DataLoader instance to batch and cache database queries.

const DataLoader = require('dataloader');
const db = require('./models');

const userPostLoader = new DataLoader(async (userIds) => {
  const posts = await db.Post.findAll({ where: { userId: userIds } });

  const postsByUserId = userIds.map(id => posts.filter(post => post.userId === id));
  return postsByUserId;
});

3. Integrate DataLoader in Resolvers 🔌

Modify the resolver to use DataLoader instead of making separate queries.

const resolvers = {
  Query: {
    users: async () => await db.User.findAll(),
  },
  User: {
    posts: (parent, args, context) => context.userPostLoader.load(parent.id)
  }
};

4. Attach DataLoader to Context 🔗

Ensure DataLoader is available in each request by adding it to the context in your GraphQL server setup.

const { ApolloServer } = require('apollo-server');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: () => ({
    userPostLoader: userPostLoader
  })
});

Verifying Performance Improvements 📊

Before implementing DataLoader, let's analyze the number of queries being made. Consider the following GraphQL query:

query {
  users {
    id
    name
    posts {
      id
      title
    }
  }
}

Without DataLoader : ❌

1. Query to fetch users (1 query)

    SELECT * FROM users;
   

2. Query for each user's posts (10 queries if there are 10 users)

    SELECT * FROM posts WHERE userId = 1;
    SELECT * FROM posts WHERE userId = 2;
    ...
    SELECT * FROM posts WHERE userId = 10;
   

Total queries: 11

With DataLoader : ✅

1. Query to fetch users (1 query)

    SELECT * FROM users;
   

2. Single batched query to fetch all posts at once (1 query)

    SELECT * FROM posts WHERE userId IN (1,2,3,4,5,6,7,8,9,10);
   

Total queries: 2

Performance Gains : 🚀

By reducing the number of queries from 11 to 2, DataLoader significantly reduces database load and improves response time. The reduction in queries is more noticeable as the dataset grows, ensuring better scalability and performance efficiency. Before DataLoader, fetching posts for 10 users resulted in 11 queries. With DataLoader, it reduces to 2 queries:

1. Fetch all users

2. Fetch all posts in a single batch query

Integrating DataLoader with Prisma/Sequelize/MongoDB 🛠️

Using DataLoader with Prisma

const userPostLoader = new DataLoader(async (userIds) => {
  const posts = await prisma.post.findMany({
    where: { userId: { in: userIds } },
  });

  const postsByUserId = userIds.map(id => posts.filter(post => post.userId === id));
  return postsByUserId;
});

Using DataLoader with Sequelize

const userPostLoader = new DataLoader(async (userIds) => {
  const posts = await Post.findAll({
    where: { userId: userIds },
  });

  return userIds.map(id => posts.filter(post => post.userId === id));
});

Using DataLoader with MongoDB (Mongoose)

const userPostLoader = new DataLoader(async (userIds) => {
  const posts = await Post.find({ userId: { $in: userIds } });

  return userIds.map(id => posts.filter(post => post.userId.toString() === id.toString()));
});

Impact of Using DataLoader

1. Improved Performance: Reduces database queries, significantly optimizing response times.

2. Better Scalability: Handles large GraphQL queries efficiently, making the API more scalable.

3. Reduced Database Load: Batching reduces the number of queries, minimizing database stress.

4. Caching Benefits: Avoids redundant database calls by caching previously fetched data.

Conclusion 💡

Using DataLoader in GraphQL APIs is essential for optimizing database queries and solving the N+1 query problem. By batching requests and caching results, it significantly enhances performance and scalability. Whether you are using Prisma, Sequelize, or MongoDB, integrating DataLoader is a best practice for efficient GraphQL APIs.

Enter GraphQL plugins—a powerful mechanism in Apollo Server that allows developers to customize and enhance their API functionality with ease.

In this blog, we’ll explore what GraphQL plugins are, set up a basic Apollo Server, and walk through creating a custom plugin to log query response times. We’ll also delve into advanced use cases and best practices for building scalable and efficient GraphQL APIs with Apollo Server plugins. Let’s dive in!

What Are GraphQL Plugins?

GraphQL plugins in Apollo Server allow developers to inject custom logic into the server’s lifecycle. Whether it’s tracking performance, managing request authentication, or adding additional logging, plugins empower developers to fine-tune their GraphQL servers for specific needs.

Lifecycle Hooks

Plugins in Apollo Server operate on a series of lifecycle hooks. These hooks allow developers to tap into various stages of a GraphQL operation, such as:

1. requestDidStart: Triggered when a new GraphQL request is received.

2. didResolveOperation: Triggered after the server successfully parses and validates the query.

3. executionDidStart: Triggered before the query execution begins.

4. willSendResponse: Triggered right before the server sends the response to the client.

By leveraging these hooks, you can implement custom behaviors like query logging, error tracking, or request throttling.

The following diagram illustrates the sequence of events that fire for each request. Each of these events is documented in Apollo Server plugin events and available on apollo website.

Setting Up Apollo Server

Before we jump into creating a custom plugin, let’s set up a basic Apollo Server with a simple schema and resolver. If you don’t already have Apollo Server installed, start by setting it up:

Step 1: Install Dependencies

Run the following command to install the necessary packages:

npm install @apollo/server graphql

Step 2: Define a Basic Schema

Create a file named schema.js with the following content:

// we store posts list in a separate file
import {posts} from "../../utils/data"

const typeDefs = `#graphql
    type Query {
        posts:[Post]
    }

    type Post {
        id: ID!
        title: String!
        content: String!
    }
`;

const resolvers = {
  Query: {
    posts: () => {
            return posts;
        },
  },
};

module.exports = { typeDefs, resolvers };

Step 3: Set Up the Apollo Server

Create a file named server.js and set up Apollo Server:

const { ApolloServer } = require('@apollo/server');
const { typeDefs, resolvers } = require('./schema');

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

Run the server using the following command:

node server.js

At this point, you have a basic Apollo Server running locally.

Creating a Custom Plugin for Response Time Logging

Now that we have a working Apollo Server, let’s create a custom plugin to log the response time of each GraphQL query.

Step 1: Understanding the Plugin Lifecycle

To measure response time, we’ll use the requestDidStart and willSendResponse hooks. Here’s the flow:

1. Record the start time when the request begins.

2. Calculate the duration when the response is about to be sent.

Step 2: Implementing the Plugin

Create a file named loggingPlugin.js with the following content:

const loggingPlugin = {
  async requestDidStart(requestContext) {
    const start = Date.now();
    console.log(`Query received: ${requestContext.request.query}`);

    return {
      async willSendResponse() {
        const duration = Date.now() - start;
        console.log(`Response sent after ${duration}ms`);
      },
    };
  },
};

module.exports = { loggingPlugin };

Step 3: Integrating the Plugin

Modify your server.js file to include the custom plugin:

const { ApolloServer } = require('@apollo/server');
const { typeDefs, resolvers } = require('./schema');
const { loggingPlugin } = require('./loggingPlugin');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [loggingPlugin],
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

Restart the server, and you’ll see query logs along with response times in the console.

Advanced Use Cases for Apollo Server Plugins

Plugins offer immense flexibility, enabling you to build advanced features for your GraphQL APIs. Here are a few examples:

1. Extending the Logging Plugin

Enhance the plugin to include user-specific details or operation names in the logs. For instance:

console.log(`Operation: ${requestContext.operationName}`);
console.log(`User ID: ${requestContext.context.userId}`);

2. Enforcing Security and Rate Limiting

Implement rate limiting or request validation to prevent abuse. For example:

• Track the number of queries.

• Reject requests exceeding a predefined threshold.

if (queryCount > MAX_QUERIES) {
  throw new Error('Rate limit exceeded.');
}

3. Monitoring and Analytics

Send query performance metrics to external tools like Prometheus, Grafana, or DataDog for detailed monitoring and analytics.

4. Dynamic Schema Modifications

Build a plugin that dynamically modifies the schema at runtime based on user roles or feature flags.

Conclusion

Apollo Server plugins are a powerful tool for enhancing the functionality and performance of your GraphQL APIs. From logging response times to enforcing security and enabling advanced monitoring, plugins offer endless possibilities to tailor your server to your application’s needs.

By following this guide, you now have the skills to create custom plugins and integrate them seamlessly into your Apollo Server. Experiment with different use cases and share your innovations with the community.

For further learning, check out the Apollo Server documentation. Happy coding! 🚀

If you found this guide helpful, share it with your network and let us know how you’re using Apollo Server plugins in your projects. Stay tuned for more tutorials on building scalable GraphQL APIs!

Essential Elements for Ensuring API Reliability

1. Performance Monitoring

   • Ensure APIs respond quickly and handle concurrent requests efficiently.

   • Optimize for low latency and high throughput.

2. Scalability

   • Design APIs to handle increasing loads without degradation.

   • Use load balancers, auto-scaling groups, and caching mechanisms.

3. Error Handling

   • Implement comprehensive error logging and monitoring.

   • Provide clear error responses for better client-side debugging.

4. Security

   • Secure APIs with authentication, authorization, and encryption.

   • Monitor for unusual activity or unauthorized access attempts.

5. Availability

   • Aim for high uptime with robust failover mechanisms.

   • Use redundancy at the network, server, and data levels.

Key Metrics to Monitor for API Success

1. Performance Metrics

   

   • Response Time (Latency): Average, 95th percentile (P95), and 99th percentile (P99) latencies.

   • Request Rate (RPS): Total requests per second handled by the API.

   • Error Rate: Percentage of requests resulting in errors (4xx or 5xx responses).

   • Cache Hit Rate: Frequency of cache hits versus total cache requests.

2. Infrastructure Metrics

   • CPU and Memory Usage: Resource consumption patterns under load.

   • Disk I/O: Storage throughput for reading and writing data.

   • Thread and Connection Pool Usage: Health of connection pools and threads.

3. Reliability Metrics

   • Uptime: Measure of API availability, often reflected as an SLA.

   • Dependency Latency: Response time for third-party APIs the service relies on.

   • Timeouts and Retries: Frequency of timed-out requests and retries.

4. Usage Metrics

   

   • Endpoint Popularity: Most accessed API endpoints.

   • User Activity Patterns: Trends in API usage over time.

   • Rate Limit Violations: Incidents where clients exceed allowed limits.

5. Security Metrics

   • Authentication Failures: Invalid login attempts or token issues.

   • Unusual IP Activity: Unexpected access patterns from specific IPs.

   • Data Integrity Issues: Monitoring anomalies in data processing or storage.

How to Monitor These Metrics

These tools provide complete solutions for monitoring performance, resource use, and reliability metrics.

• Datadog: Comprehensive monitoring and alerting with integrated APM and logging.

• New Relic: APM with powerful diagnostics and distributed tracing.

• AWS CloudWatch: Built-in monitoring for AWS-based infrastructure and APIs.

These tools stand out due to their wide adoption, robust features, and the ability to address various aspects of API monitoring, from performance metrics to log analysis.

Best Practices for API Monitoring

1. Use Distributed Tracing: Tools like Jaeger or Zipkin help trace requests across services, identifying bottlenecks.

2. Implement Logging: Use structured logging to capture detailed request/response data for troubleshooting.

3. Automate Alerts: Set up alerts for anomalies like high error rates, increased latency, or resource exhaustion.

4. Conduct Regular Load Testing: Use tools like Apache JMeter or k6 to simulate traffic and identify scaling issues.

5. Continuously Refine Metrics: Regularly review and update monitored metrics to align with evolving business needs.

Conclusion

In conclusion, ensuring API reliability is a multifaceted endeavor that requires careful attention to performance, scalability, error handling, security, and availability. By monitoring key metrics such as response time, error rate, and resource usage, developers can gain valuable insights into the health and performance of their APIs. Utilizing powerful monitoring tools like Prometheus, Datadog, and AWS CloudWatch can aid in effectively tracking these metrics and identifying potential issues before they impact users. Adopting best practices such as distributed tracing, structured logging, and regular load testing further enhances the robustness of APIs. By implementing these strategies, developers can significantly improve application performance, leading to a more reliable and satisfying user experience.

Postman is a robust API development environment that enables you to create, send, test, and document APIs efficiently. GitHub Actions is a CI/CD platform designed to automate the testing and deployment of your code. By integrating Postman with GitHub Actions, you can seamlessly automate your API testing as part of your development workflow.

Prerequisites:

• A GitHub account and repository.

• A Postman collection containing your API tests.

• A Postman environment containing the necessary variables for your tests (e.g., API keys, base URLs).

Steps:

1. Create a Postman Collection:

   • In Postman, create a new collection and add your API test cases.

   • Configure the necessary environment variables in your Postman environment.

2. Generate Postman API Key:

   • Go to the settings page and then API keys to generate a new API key

   • Save this API key to GitHub repository secrets

3. Create a GitHub Actions Workflow:

   • In your GitHub repository, create a new file named .github/workflows/postman-tests.yml.

   • Paste the following code into the file, replacing the placeholders with your specific values:

       name: Automated Testing using Postman CLI
     
       on:
         push:
           branches: [main]
     
       jobs:
         automated-api-tests:
           runs-on: ubuntu-latest
           steps:
             - uses: actions/checkout@v4
             - name: Install Postman CLI
               run: |
                 curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh
             - name: Login to Postman CLI
               run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
             - name: Run API tests
               run: |
                 postman collection run "[collection_id]" -e "[environment_id]"
     

4. Commit and Push:

   • Commit and push the .github/workflows/postman-tests.yml file to your GitHub repository.

Explanation:

• The workflow is triggered by pushing events to the main branch.

• It installs the Postman CLI for Linux

• It uses the postman login command to authenticate with the Postman CLI

• It runs the Postman collection specified by the [collection_id] placeholder (replace it with your actual collection ID). It also uses the environment defined by the [environment_id] placeholder (replace it with your actual environment ID) for variables.

Additional Considerations:

• You can customize the workflow to run tests on different branches, trigger on pull requests, or use different runners.

• Consider using environment variables to store sensitive information (e.g., API keys) securely.

• Explore other features of GitHub Actions, such as caching, artifacts, and secrets, to enhance your workflow.

By following these steps, you can effectively automate the testing of your APIs using Postman and GitHub Actions, ensuring that your code changes are thoroughly tested before deployment.