Go singleflight: Protecting Your Database from a Flood of Identical RequestsArticle · digest for October 25
Metaphorical scene of a Go singleflight synchronization gate shielding a database from an avalanche of simultaneous requests.
Article4 sections≈ 6 min

Go singleflight: Protecting Your Database from a Flood of Identical Requests

Every backend engineer hits this drama at least once: a high-load service is happily serving tens of thousands of requests per second from a fast Redis cache, latency graphs are flat, and monitoring is green. Then a popular key expires—say, a hot flash-sale product page or a celebrity profile.

Within a single millisecond, hundreds of concurrent goroutines hit a cache miss and stampede the primary database with the exact same heavy SQL query. The connection pool maxes out, latency skyrockets, cascading timeouts fire, and production goes down. In the industry, this nightmare goes by two fitting names: Cache Stampede and Thundering Herd.

A developer's first instinct is often to bolt on distributed locks via Redis Redlock or slap a global mutex around the call. But distributed locks add network latency and can stall if a node dies, while a naive sync.Mutex freezes every unrelated operation in the process.

Inside Go's extended standard library lives a remarkably clean, battle-tested fix: the singleflight package from golang.org/x/sync.

Anatomy of a Panic: How One Expired Key Takes Down a Database

Picture a supermarket on New Year's Eve. The champagne shelf goes empty. If all hundred shoppers sprint into the back room screaming "Grab me a bottle!" at the lone stock clerk, the storeroom jams up and nobody gets served.

The sensible move: the first shopper asks an associate, "We need champagne." The associate tells the other ninety-nine people to wait by the shelf for a moment, walks into the back once, brings out a crate, and hands bottles to everyone waiting. One trip to the storeroom, a hundred satisfied shoppers.

That is precisely what singleflight.Group does. It deduplicates concurrent calls to the same function inside a single application process's memory, collapsing them into one actual execution.

How Group.Do Works—and Why It's a Sync Barrier, Not a Cache

The core API of singleflight.Group is minimal:

func (g *Group) Do(key string, fn func() (any, error)) (v any, err error, shared bool)

Here is the step-by-step mechanics:

  1. The first goroutine calls g.Do("product:42", fetchFromDB). The group sees no active work for the string key "product:42", registers an internal call struct, grabs a local lock, and runs fn().
  2. At that exact instant, 50 more goroutines call g.Do with "product:42". The group sees an in-flight call, skips running fn again, and parks those goroutines on a sync.WaitGroup.
  3. Once the first call finishes, all 51 goroutines unblock together and receive the same v, err, and shared = true (indicating the result was shared across callers).
  4. The key is immediately deleted from the group's internal map.

Notice one crucial detail: singleflight is not a cache. It retains nothing once the call finishes. If another request arrives a microsecond later, fn() runs fresh. singleflight only shields your system from simultaneous duplicate work during a miss.

Preventing Hangs: Pairing DoChan with context.Context

Group.Do blocks every waiting goroutine until fn() returns. What if the database hangs or an upstream API stalls? All waiting goroutines are held hostage, HTTP connections pile up, and memory runs dry.

To prevent that, the package provides the non-blocking DoChan method, which returns a receive-only <-chan Result. Paired with context.Context, it gives you complete protection against hangs:

package repository

import (
    "context"
    "database/sql"
    "fmt"
    "golang.org/x/sync/singleflight"
)

type Product struct {
    ID    int64
    Title string
    Price int64
}

type ProductStore struct {
    db    *sql.DB
    group singleflight.Group
}

func (s *ProductStore) GetProduct(ctx context.Context, tenantID int, productID int64) (*Product, error) {
    // Deduplication key must include tenant and permission boundaries
    key := fmt.Sprintf("tenant:%d:product:%d", tenantID, productID)

    ch := s.group.DoChan(key, func() (any, error) {
        var p Product
        query := `SELECT id, title, price FROM products WHERE tenant_id = $1 AND id = $2`
        // Pass an independent context to the shared query so one client
        // canceling doesn't abort the call for everyone else
        err := s.db.QueryRowContext(context.Background(), query, tenantID, productID).
            Scan(&p.ID, &p.Title, &p.Price)
        if err != nil {
            return nil, err
        }
        return &p, nil
    })

    select {
    case <-ctx.Done():
        // Client canceled the request or hit an HTTP timeout
        return nil, ctx.Err()
    case res := <-ch:
        if res.Err != nil {
            return nil, res.Err
        }
        // Guard against data races: return a copy of the struct
        orig := res.Val.(*Product)
        copyItem := *orig
        return &copyItem, nil
    }
}
Context Inside the Closure

Pay close attention to one subtle detail: the fn closure receives context.Background(). If you passed the first caller's ctx instead and that client closed their tab, canceling the context would kill the query for all the other goroutines still waiting on the result!

Common Pitfalls: Pointer Races and Group Lifetime

Engineers new to singleflight usually step on two classic rakes:

  1. Mutable pointer data races: If your function returns a pointer (*Product) or a slice, all 50 goroutines get a reference to the exact same heap memory. If one caller mutates a field later (e.g., product.Price = 0), you trigger a textbook data race. The fix: return values by value or make a shallow copy (copyItem := *orig) before handing it back, as shown above.
  2. Group lifetime: A singleflight.Group instance must live on a long-lived service or repository struct. Declaring var g singleflight.Group inside an HTTP handler completely defeats the pattern—every request creates its own empty group and zero deduplication happens.

Wrapping cache-miss database lookups in singleflight takes roughly twenty lines of code, yet it saves production from the ugliest 3 a.m. traffic spikes.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 2