uuid

google/uuid is a small, dependency-free Go library for generating and working with UUIDs (Universally Unique Identifiers) as defined in RFC 9562 (which obsoletes RFC 4122) and DCE 1.1. It represents a UUID as a fixed 16-byte array rather than a byte slice, and supports Version 1, 4, 6, and 7 generation alongside parsing, string formatting, and variant/version inspection.

Because it implements the standard database/sql and encoding interfaces (Scanner, Valuer, TextMarshaler, BinaryMarshaler), it drops directly into ORMs, JSON encoders, and SQL drivers without adapter code, making it the de facto default UUID package for Go projects.

What You Get

• One-call random UUID generation via uuid.New() / uuid.NewString(), plus error-returning variants for callers that want to handle crypto/rand failure explicitly
• Version 1 (MAC/node-based), Version 4 (random), Version 6 (reordered time), and Version 7 (Unix Millisecond time-ordered, monotonic within a millisecond) generation functions
• Parse, ParseBytes, Validate, and MustParse for the four accepted textual UUID forms (plain, urn:uuid:, braced, and unhyphenated hex)
• Built-in encoding.TextMarshaler/TextUnmarshaler, encoding.BinaryMarshaler/BinaryUnmarshaler, and database/sql driver.Valuer/Scanner implementations for zero-adapter JSON and database interop
• An optional internal randomness pool (EnableRandPool/DisableRandPool) that batches crypto/rand reads to raise UUID generation throughput

Common Use Cases

• Generating primary keys or row identifiers for database records without depending on the database’s own UUID generation
• Assigning distributed-system-safe identifiers to requests, jobs, sessions, or trace IDs without a central coordinator
• Round-tripping UUIDs through JSON APIs and SQL columns using standard library interfaces instead of hand-rolled (un)marshaling code
• Producing time-ordered (V7) identifiers for records where index locality and rough chronological sortability matter, as an alternative to random V4 IDs

Under The Hood

Architecture: The core type UUID is a [16]byte array (uuid.go). Parsing (Parse, ParseBytes, Validate) handles four textual formats via a shared xtob hex-decode routine (util.go) and index tables mapping string positions to byte offsets. Generation is split across version-specific files: version4.go for random V4 UUIDs (via crypto/rand, with an optional pool guarded by uuid.go’s poolMu/pool/poolPos globals for throughput), version1.go/node.go for MAC-address-based V1 (hardware interface lookup dispatched via build-tagged node_net.go/node_js.go), version6.go for time-ordered V6, and version7.go for RFC 9562 V7 monotonic timestamp-based UUIDs (getV7Time uses a timeMu-guarded lastV7time counter to guarantee strictly increasing sequence numbers within a millisecond). Encoding/decoding interfaces are centralized in marshal.go (encoding.Text/BinaryMarshaler) and sql.go (database/sql driver.Valuer/Scanner), so any consumer type embedding UUID gets JSON, text, binary, and SQL support for free.

Tech Stack: Pure Go, zero third-party dependencies — go.mod declares only module github.com/google/uuid with no requires. Standard library only: crypto/rand for randomness, encoding/hex for hex encode/decode, database/sql/driver for SQL interop, sync for pool/node mutexes. Build-tag-gated files (node_net.go vs node_js.go) swap in a no-op hardware-address lookup under GOOS=js/wasm. No build tooling beyond go build/go test; releases and CHANGELOG.md entries are generated via release-please through GitHub Actions.

Code Quality: Extensive table-driven tests (uuid_test.go, ~930 lines) cover Parse/Validate across all four input shapes plus error paths (invalid length, invalid hex, bad urn prefix) and version/variant round-tripping; dedicated test files isolate sql.go (sql_test.go), marshal.go (json_test.go, null_test.go for a nullable wrapper type), and version-specific behavior (seq_test.go, time_test.go, version6_test.go). Errors use typed sentinel values (invalidLengthError, URNPrefixError) implementing the errors.Is interface for structured matching instead of string comparison. Concurrency-sensitive state (nodeID, the random pool, the V7 monotonic clock) is guarded by separate sync.Mutex instances rather than one global lock, limiting contention between unrelated generation paths.

API Design: Zero-config entry points (uuid.New(), uuid.NewString()) cover the common case in one call and panic only on the near-impossible crypto/rand-failure path, while error-returning variants (NewRandom, NewV7, Parse) exist for callers who need to handle failure explicitly — a deliberate two-tier API. Naming is consistent and predictable across versions (NewRandom/NewV6/NewV7 map directly to spec version numbers), and the UUID type’s small value-type footprint means it can be compared with ==, used as a map key, and passed by value without extra heap allocation. Documentation is entirely inline godoc with no separate docs site, which is sufficient given the package’s narrow, well-understood surface — onboarding is a single go get plus the pkg.go.dev reference.