Go Standard Library Adds UUID Support with a Streamlined V4/V7 API

Background: UUID is a universal identifier defined in RFC 9562 and used widely in distributed systems. Go historically lacked built‑in support, forcing developers to rely on third‑party packages such as github.com/google/uuid.

Community proposal: In August 2023, @mzattahri opened Issue #62026 requesting a std‑lib uuid package. The proposal highlighted the widespread use of the google/uuid package, the maturity of the RFC, and the stability of the existing API.

Design discussion: Over two years of discussion examined the appropriate API surface. The Go team argued that the google/uuid package is too large to import wholesale. An ecosystem survey by Roland Shoemaker showed that more than 70 % of calls are for generation (New) and string conversion (String).

Core design decisions

Type definition: type UUID [16]byte – a plain 16‑byte array, matching the layout of google/uuid and allowing direct conversion.

No introspection methods: Methods such as Version() or Time() were rejected because the RFC treats UUIDs as opaque identifiers.

Supported versions: Only V4 (random) and V7 (time‑ordered) are implemented. V4 covers the majority of current use cases; V7 provides monotonic timestamps useful for database keys.

Generation functions return no error: The functions New(), NewV4() and NewV7() return a UUID directly. Under Go 1.24+ the underlying crypto/rand.Read never returns an error; a failure now triggers a fatal crash.

Serialization support: The type implements encoding.TextMarshaler, encoding.TextUnmarshaler and encoding.TextAppender, enabling seamless use with encoding/json and encoding/xml.

V7 implementation details

The V7 layout splits the 128‑bit value into timestamp (48 bits), version (4 bits), a 12‑bit sub‑millisecond field ( rand_a), variant (2 bits) and random data (62 bits). The Go implementation stores a 12‑bit sub‑millisecond fraction in rand_a, achieving a resolution of 1/4096 ms (≈244 ns). A sync.Mutex guarantees monotonic increase when timestamps collide, and clock‑backward detection falls back to resetting the last timestamp.

func NewV7() UUID {
    v7mu.Lock()
    now := time.Now()
    // build 60‑bit timestamp: 48 ms + 12‑bit fraction
    timestamp := (1000*secs + msecs) << 12
    timestamp += (frac * 4096) / 1_000_000
    if timestamp <= v7lastTimestamp {
        timestamp = v7lastTimestamp + 1
    }
    v7lastTimestamp = timestamp
    v7mu.Unlock()
    // set version and variant bits, fill random part
    binary.BigEndian.PutUint64(u[0:8], hibits)
    rand.Read(u[8:])
    u.setVersion(7)
    u.setVariant(0b10)
    return u
}

Database/sql integration

The new uuid package adds native support to database/sql. Conversions are added in convert.go so that a string or []byte can be scanned directly into a *uuid.UUID. The driver now treats uuid.UUID as a driver.Valuer, returning the string representation for SQL parameters.

var id uuid.UUID
row.QueryRow("SELECT id FROM users WHERE name = $1", "alice").Scan(&id)

Comparison with github.com/google/uuid

Supported versions: std lib – V4, V7; google/uuid – V1‑V7.

Generation functions: std lib never returns an error; google/uuid returns an error.

Custom io.Reader: not supported in std lib; supported in google/uuid.

Introspection methods: absent in std lib; present in google/uuid (Version, NodeID, etc.).

SQL integration: built‑in in std lib; manual implementation required for google/uuid.

Type definition: both use [16]byte, allowing direct conversion.

Conclusion: By trimming the API to the most common operations—three generation functions, two parsing functions, full serialization support, comparison, and native database integration—the Go standard library now provides a lightweight, production‑ready UUID solution that satisfies the needs of most Go developers while still allowing the use of the more feature‑rich third‑party library when required.