Skip to content

advanced.md

Latest commit

 

History

History
71 lines (48 loc) · 2.37 KB

advanced.md

File metadata and controls

71 lines (48 loc) · 2.37 KB

Advanced Usage

This document covers features beyond basic UUID generation and parsing. For getting started, see the README.

V7 Monotonicity

Multiple V7 UUIDs generated within the same millisecond are guaranteed to sort in creation order within a single Generator:

gen := uuid.NewGenerator()
id1 := gen.NewV7()
id2 := gen.NewV7() // guaranteed id1 < id2 even within the same millisecond

The package-level uuid.NewV7() uses a default shared generator, so it also provides monotonicity out of the box. Create a dedicated Generator when you need isolated monotonicity guarantees (e.g., per-request or per-goroutine ordering).

See Internals: V7 Monotonic Counter Fallback for how this works under the hood.

High-Throughput Generation

For hot paths, Pool amortizes the cost of crypto/rand by pre-generating random bytes in bulk:

pool := uuid.NewPool()
id := pool.NewV4() // ~14x faster than NewV4()
id  = pool.NewV7() // ~2x faster than NewV7() (time.Now dominates)

For bulk workloads (database seeding, ETL, load testing), batch APIs generate many UUIDs with a single crypto/rand call:

ids := uuid.NewV4Batch(1000) // ~25x faster than calling NewV4() in a loop

gen := uuid.NewGenerator()
ids  = gen.NewV7Batch(1000)  // ~15x faster, all monotonically increasing

Both Pool and Batch use crypto/rand exclusively - no security trade-offs. Pool is safe for concurrent use.

See Internals: Pool for how pooling works.

Properties

id := uuid.NewV7()

id.Version()  // uuid.Version7
id.Variant()  // uuid.VariantRFC9562
id.IsNil()    // false
id.Time()     // time.Time (millisecond precision, V7 only)
id.Bytes()    // [16]byte

Compare(a, b UUID) int returns -1, 0, or +1 for use with slices.SortFunc:

slices.SortFunc(ids, uuid.Compare)

Namespace Constants

Predefined namespace UUIDs for use with NewV5 (RFC 9562 Appendix C):

uuid.NamespaceDNS   // 6ba7b810-9dad-11d1-80b4-00c04fd430c8
uuid.NamespaceURL   // 6ba7b811-9dad-11d1-80b4-00c04fd430c8
uuid.NamespaceOID   // 6ba7b812-9dad-11d1-80b4-00c04fd430c8
uuid.NamespaceX500  // 6ba7b814-9dad-11d1-80b4-00c04fd430c8

See pkg.go.dev for the full API reference.