Skip to content
Tutorials Center
My learning

Topics

Lesson 120 of 147 ยท Databases

Caching and NoSQL from Go

Cache and store data from Go - go-redis and MongoDB basics, plus runnable in-process caches - sync.Map, TTL expiry, a hand-built LRU, cache-aside and singleflight.

Relational databases are not the only place data lives. Many Go services also talk to a cache (a fast, temporary copy of data that is slow to compute or fetch) and sometimes to a NoSQL store such as Redis or MongoDB. Caches take load off your database, shorten response times and absorb traffic spikes. They also introduce one of the hardest problems in programming: deciding when a cached value is no longer true.

This lesson has two halves. First, a read-only tour of the two most common external stores and how Go code talks to them. Then the part you can run here: in-process caches built from the standard library. They are the same ideas Redis uses, and building them yourself shows you what a cache library does for you. If you have not met the building blocks yet, skim maps, the sync package and context first.

Redis from Go

Redis is an in-memory server that stores keys and values (strings, lists, sets, hashes, sorted sets and more) and answers commands over TCP. It is the usual choice for shared caches, rate limiters, session stores, job queues and leaderboards. Our sandbox has no Redis server and no third-party modules, so the code below is read-only. It uses the popular client github.com/redis/go-redis/v9:

Go
package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/redis/go-redis/v9"
)

func main() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr: "localhost:6379",
	})
	defer rdb.Close()

	// SET with a time to live: the key disappears after 10 minutes.
	if err := rdb.Set(ctx, "user:42:name", "Ada", 10*time.Minute).Err(); err != nil {
		panic(err)
	}

	// GET returns redis.Nil when the key does not exist. That is not a failure.
	name, err := rdb.Get(ctx, "user:42:name").Result()
	switch {
	case errors.Is(err, redis.Nil):
		fmt.Println("cache miss")
	case err != nil:
		panic(err)
	default:
		fmt.Println("hit:", name)
	}

	// Atomic counter, handy for rate limiting.
	views, _ := rdb.Incr(ctx, "page:home:views").Result()
	fmt.Println("views:", views)
}

Three habits matter here. Every call takes a context.Context, so a slow Redis cannot hang a request forever: pass the request context or one with a timeout. A missing key is reported as the sentinel error redis.Nil, which you compare with errors.Is, and it is a normal outcome rather than a failure. And the client is safe for concurrent use and manages its own connection pool, so you create one client at startup and share it, just as you share a *sql.DB.

Typical key design uses colons as separators (user:42:name) and always sets a TTL (time to live) on cache entries, so that forgotten keys cannot fill memory.

Redis commands are executed one at a time on the server, which makes single commands like INCR atomic. A sequence of commands (read a value, compute, write it back) is not atomic unless you use a transaction (MULTI/EXEC, or WATCH for optimistic locking) or a Lua script.

MongoDB from Go

MongoDB stores documents: JSON-like records grouped into collections, with no fixed schema. The official driver is go.mongodb.org/mongo-driver/v2. Documents map to Go structs through struct tags, in the same spirit as json tags:

Go
package main

import (
	"context"
	"fmt"
	"time"

	"go.mongodb.org/mongo-driver/v2/bson"
	"go.mongodb.org/mongo-driver/v2/mongo"
	"go.mongodb.org/mongo-driver/v2/mongo/options"
)

type Product struct {
	ID    bson.ObjectID `bson:"_id,omitempty"`
	Name  string        `bson:"name"`
	Price float64       `bson:"price"`
	Tags  []string      `bson:"tags,omitempty"`
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	client, err := mongo.Connect(options.Client().ApplyURI("mongodb://localhost:27017"))
	if err != nil {
		panic(err)
	}
	defer client.Disconnect(ctx)

	products := client.Database("shop").Collection("products")

	_, err = products.InsertOne(ctx, Product{Name: "Notebook", Price: 4.5, Tags: []string{"paper"}})
	if err != nil {
		panic(err)
	}

	var found Product
	err = products.FindOne(ctx, bson.D{{Key: "name", Value: "Notebook"}}).Decode(&found)
	if err == mongo.ErrNoDocuments {
		fmt.Println("not found")
	} else if err != nil {
		panic(err)
	}
	fmt.Println(found.Name, found.Price)
}

Filters are built from bson.D (an ordered document) or bson.M (an unordered map). As with Redis, "no result" is a specific error (mongo.ErrNoDocuments) that you check for, and every operation takes a context.

Choosing a store

Need Good fit
Shared cache, counters, rate limits, sessions Redis
Flexible documents that vary in shape MongoDB
Transactions, joins, constraints A relational database (database/sql)
One process, small data, no sharing An in-process cache (the rest of this lesson)

An in-process cache has no network hop, no serialization and no extra server to run. Its limits: each instance of your program has its own copy, and everything vanishes on restart. For many services that is exactly right.

A map is not a cache

The first idea is to use a map and a mutex. That works as a store, but a cache needs two more properties: entries must expire, and memory must stay bounded. Start with expiry. The cache below stores each value with a deadline, and takes the clock as a function so that this demonstration is deterministic (a test, or this page, can move time forward without sleeping):

Go A cache with time-to-live expiry

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The output shows 7 true twice and then 0 false, with no entries left. This is lazy expiry: an expired entry is only removed when someone asks for it. That is simple and fast, but keys nobody asks for again would stay forever. Production caches add a background goroutine that sweeps the map on a ticker, or a size limit as described next. The generic type parameters ([K comparable, V any]) come from generic types.

sync.Map for read-mostly caches

The standard library also ships sync.Map, a concurrent map that needs no extra lock. It is optimized for two situations: a key is written once and read many times, or goroutines work on disjoint sets of keys. Its API uses any for keys and values, so you lose type safety:

Go sync.Map and LoadOrStore

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

All four keys end up with the right square, but the number of times expensive ran is not fixed: two goroutines can both miss on the same key at the same moment and both compute the value, which is why the program prints only the safe claim computed at least 4 times: true. LoadOrStore guarantees consistency (everyone sees one winner) but not that the work is done once. The singleflight section below fixes that. Use a plain map plus sync.RWMutex when you want type safety or need operations like counting entries.

A bounded cache: LRU

Memory is finite, so a cache needs an eviction policy: a rule for which entry to throw away when it is full. The classic one is LRU (least recently used): evict the entry that has gone unused for the longest time. An LRU needs fast lookup by key and fast "move to front" on every access. A map plus a doubly linked list does both in constant time. The standard library has the list in container/list:

Go A hand-built LRU cache

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The first line prints order: [c b a] (newest first). Reading a moves it to the front, so when d arrives the one that falls off is b, not a. This version is not safe for concurrent use; to share it, wrap Get and Put with a mutex. Note that Get mutates the list, so even reads need an exclusive sync.Mutex, not an RWMutex.

In real services you rarely hand-roll this. Libraries such as hashicorp/golang-lru, ristretto and otter add sharding (to cut lock contention), TTLs, statistics and smarter policies. Writing one once makes their documentation easy to understand.

Cache-aside and the stampede problem

The most common caching pattern is cache-aside (also called lazy loading):

  1. Look in the cache. On a hit, return the value.
  2. On a miss, load from the source of truth (database, API, disk).
  3. Store the result in the cache, then return it.

It is easy to write, and it has a well-known flaw. When a popular key expires, many requests arrive before the first one has refilled the cache, and all of them go to the database at once. This is a cache stampede (or thundering herd). The fix is to let one caller do the work while the others wait for its answer. The Go team's golang.org/x/sync/singleflight package does exactly that; here is a minimal version built from a mutex and a sync.WaitGroup, so you can see how it works:

Go singleflight built by hand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Ten goroutines ask for the same key; both lines print true: all ten got the same answer and the database saw fewer than ten queries. The exact count depends on scheduling (usually it is 1, but a goroutine that arrives after the first finished starts a new load), so the program only prints a claim that always holds. The real singleflight.Group also returns an error, reports whether the result was shared, and offers DoChan and Forget.

Invalidation

There are two classic hard problems in computer science: naming things, cache invalidation, and off-by-one errors. Practical strategies:

  • TTL only. Accept that data can be stale for up to the TTL. Simple, and good enough for most read-heavy data. Add a little random jitter to TTLs so many keys do not expire in the same second.
  • Explicit invalidation. When you write to the database, delete the cache key (Delete, not "update the cached copy"). The next read repopulates it. Deleting is safer than updating because concurrent writers cannot leave an old value behind.
  • Versioned keys. Put a version or timestamp in the key (product:42:v7) so a change simply stops using the old key and the old entry ages out.
  • Cache negative results. If a lookup says "does not exist", cache that too, briefly, so repeated misses do not hammer the database.

Never cache values that depend on who is asking (a user's private data) under a key that does not include that identity. A shared key leaks one user's data to another.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does redis.Nil returned from a Get call mean?

    redis.Nil is a sentinel error meaning the key was not found. It is a normal cache miss, and you check for it with errors.Is.
  2. 2. Why does the TTL cache in this lesson take a now func() time.Time instead of calling time.Now()?

    Injecting the clock is a common technique: production passes time.Now, tests pass a fake clock they can advance instantly.
  3. 3. An LRU cache with capacity 3 holds keys a, b, c (c most recent). You call Get("a") and then Put("d", 4). Which key is evicted?

    Get("a") moves a to the front, so the order is a, c, b. The least recently used key is b, and it is evicted when d is added.
  4. 4. What problem does singleflight solve?

    Concurrent requests for the same key share one execution of the loader and its result, which prevents a cache stampede.
  5. 5. Why is it usually safer to delete a cache key after a database write than to update the cached value?

    With delete-on-write, the next read reloads the current truth from the database. Racing updates could overwrite a newer cached value with an older one.

Summary

  • Redis (go-redis) and MongoDB (the official driver) are used through a long-lived, concurrency-safe client; every call takes a context.Context, and "not found" is a specific, expected error (redis.Nil, mongo.ErrNoDocuments).
  • A cache needs expiry and a size bound. A map plus a mutex is only the storage part.
  • A TTL cache with lazy expiry is a few lines; inject the clock so it is testable.
  • sync.Map suits read-mostly or disjoint-key workloads; LoadOrStore keeps one winner but does not stop duplicate work.
  • An LRU is a map plus a doubly linked list (container/list): constant-time lookup and eviction of the least recently used entry.
  • Cache-aside plus singleflight avoids stampedes; prefer deleting keys on writes over updating them, add TTL jitter, and never share user-specific data under a shared key.

Next: Reflection shows how a program can inspect and build values whose types it only learns at run time.