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:
- The first goroutine calls
g.Do("product:42", fetchFromDB). The group sees no active work for the string key"product:42", registers an internalcallstruct, grabs a local lock, and runsfn(). - At that exact instant, 50 more goroutines call
g.Dowith"product:42". The group sees an in-flight call, skips runningfnagain, and parks those goroutines on async.WaitGroup. - Once the first call finishes, all 51 goroutines unblock together and receive the same
v,err, andshared = true(indicating the result was shared across callers). - 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 ©Item, nil
}
}
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:
- 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. - Group lifetime:
A
singleflight.Groupinstance must live on a long-lived service or repository struct. Declaringvar g singleflight.Groupinside 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.

