uuid
Dependency-free RFC 9562 UUID generation and parsing for Go, with built-in SQL and encoding support.
Repository Health
Technical Analysis
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.
Used by 102 apps in this directory
temporal
Automation · Devops
Open-source durable execution platform that keeps mission-critical workflows running through any failure, automatically.
TiDB
AI Development · Databases
AI-Native Distributed SQL Database for Agentic Workloads
Trieve
AI Development · Developer Tools · Search
All-in-one self-hostable platform for hybrid search, RAG, recommendations, and analytics built on Rust and Qdrant.
Tusk
AI Code Assistants · Developer Tools · Devops
Record live API traffic and replay it as deterministic, sandboxed tests, plus AI code review and unit test generation, all from one Go CLI built by YC W2024's Use-Tusk.
Tyk API Gateway
Developer Tools · Devops
Cloud-native, high-performance open-source API gateway for REST, GraphQL, gRPC, and TCP — built in Go since 2014 with no feature lockout.
Uncloud
Devops
Deploy and scale containerised apps across any servers without Kubernetes or Swarm overhead
Uptrace
Devops · Monitoring
Unified open-source APM that collects OpenTelemetry traces, metrics, and logs into a single self-hosted platform backed by ClickHouse.
Vikunja
Project Management
Self-hosted task management with natural-language quick-add, multiple views, and a fully documented REST API — your tasks, your infrastructure, zero lock-in.
Warrant
Authentication · Security
A Google Zanzibar-inspired authorization service for defining, checking, and auditing fine-grained access control across your applications.