Documentation
¶
Overview ¶
Package uuid provides an implementation of Version 7 (Time-ordered) Universally Unique Identifiers (UUID) as defined in RFC 4122 and RFC 9562.
MIGRATION NOTE (v4 -> v7): We migrated from UUIDv4 (fully random) to UUIDv7 (time-ordered) to improve database performance. UUIDv4 causes significant index fragmentation and random I/O in B-Tree structures (standard database primary keys) due to its lack of locality.
UUIDv7 solves this by being strictly monotonic (like a sequence ID) while retaining global uniqueness. This results in "append-only" index behavior, significantly higher write throughput, and better cache locality. It also aligns with native support arriving in PostgreSQL 18+.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type UUIDv7 ¶
type UUIDv7 [16]byte
UUIDv7 is a 128-bit time-ordered identifier (16 bytes).
Layout: - 48 bits: Unix Timestamp (milliseconds) - 4 bits: Version (0111) - 12 bits: Random Data A - 2 bits: Variant (10) - 62 bits: Random Data B
func New ¶
func New() UUIDv7
New generates a strictly monotonic UUIDv7 with sub-millisecond precision.
It fills the timestamp and sequence fields using a global monotonic counter derived from the system clock, ensuring that IDs generated within the same millisecond are ordered. The remaining bits are filled with cryptographically secure random data.
func Parse ¶
Parse parses a standard 36-character hyphenated string representation of a UUID into a UUIDv7 type.
It strictly validates that the UUID is Version 7 and Variant 1 (RFC 4122).
func ParseBytes ¶ added in v1.1.5
ParseBytes parses a 16-byte raw slice into a UUIDv7 type.
It strictly validates that the byte slice is exactly 16 bytes and conforms to Version 7 and Variant 1.
Note: This function does not modify the input slice; it creates a complete copy of the data.
Source Files