Singleton

The problem

Some things should exist once per program: a configuration loaded from the environment, a database connection pool, a shared logger. If every caller created its own, you’d get inconsistent config, exhausted connections, or interleaved log files.

You need two guarantees: only one instance is ever created, and everyone can reach that same instance through one access point. And in Go specifically: initialization must be safe when many goroutines ask for the instance at once.

Structure

classDiagram
class Singleton {
  -instance Singleton
  +GetInstance() Singleton
  +SomeMethod()
}
note for Singleton "GetInstance() always returns the same instance. The constructor is unexported."

Callers never construct the type directly — they go through a single accessor that hands back the one shared value.

How it works

sequenceDiagram
participant G1 as Goroutine 1
participant G2 as Goroutine 2
participant S as GetInstance / sync.Once
G1->>S: GetInstance()
S->>S: once.Do creates instance (runs ONCE)
S-->>G1: *instance
G2->>S: GetInstance()
S-->>G2: *instance (same pointer, no re-init)

Idiomatic Go

Go’s standard library hands you the perfect tool: sync.Once. Its Do method runs a function exactly once, no matter how many goroutines call it concurrently — and it’s faster than locking on every access.

package config

import "sync"

type Config struct {
	DSN   string
	Debug bool
}

var (
	instance *Config
	once     sync.Once
)

// Get returns the one shared Config, initializing it on first use.
// Safe to call from many goroutines at once.
func Get() *Config {
	once.Do(func() {
		instance = &Config{DSN: "postgres://localhost/app"}
	})
	return instance
}

Try it — this version spins up five goroutines that all race to initialize, then proves they got the same instance. Edit it and hit Run:

package main

import (
"fmt"
"sync"
)

type Config struct {
DSN   string
Debug bool
}

var (
instance *Config
once     sync.Once
)

func Get() *Config {
once.Do(func() {
	fmt.Println("initializing config (this prints once)")
	instance = &Config{DSN: "postgres://localhost/app"}
})
return instance
}

func main() {
var wg sync.WaitGroup
for i := 0; i < 5; i++ {
	wg.Add(1)
	go func() { defer wg.Done(); _ = Get() }()
}
wg.Wait()

a, b := Get(), Get()
fmt.Printf("same instance: %v\n", a == b)
fmt.Println("DSN:", a.DSN)
}

var instance = &Config{DSN: "postgres://localhost/app"} // created once, at startup
func Get() *Config { return instance }

A parameterized variation

One variation passes the *sync.Once in as a parameter and even recovers from panics during construction — a nice way to see the mechanics laid bare. In production you’d usually keep the sync.Once as an unexported package-level variable instead.

Under the hood: why sync.Once beats double-checked locking

In Java, the classic lazy singleton drove people to double-checked locking — check, lock, check again, with a volatile field — a notoriously easy thing to get subtly wrong. Go sidesteps the whole saga: sync.Once does the careful work for you. Internally it keeps a done flag read with an atomic load on the fast path, so after the first call Do is a single cheap atomic check with no mutex — and the slow path takes a lock only until initialization finishes. You get correct, race-free lazy init without ever writing the locking dance yourself (and go test -race will confirm it).

The deeper lesson from the foundations: the pattern’s value is the single access point and the one-instance guarantee, not the locking. Go gives you the locking for free, which is exactly why a bare nil check is both unnecessary and unsafe.

In the standard library

• sync.Once itself is the canonical building block.
• http.DefaultClient, http.DefaultServeMux are package-level singletons you use every day.
• Go’s package initialization (init() + package-level vars) is a language-level singleton guarantee.

Pitfalls

When to use it — and when not

Related patterns