Tideland Go UUID

Description

Tideland Go UUID provides functions for the creation and working with UUIDs in versions 1, 2, 3, 4, 5, 6, and 7 as per RFC 9562. The package supports:

• Version 1: Gregorian time-based with MAC address
• Version 2: DCE Security with embedded POSIX UID/GID
• Version 3: MD5 name-based
• Version 4: Random/pseudorandom
• Version 5: SHA-1 name-based
• Version 6: Reordered Gregorian time-based (sortable)
• Version 7: Unix Epoch time-based (sortable, recommended)

Features

• Full RFC 9562 compliance
• Time-ordered sortable UUIDs (v6, v7)
• Improved database index locality with v7
• Concurrent-safe UUID generation
• Multiple string formats (standard, short, URN, braced)
• Comprehensive test coverage

Installation

go get tideland.dev/go/uuid

Usage

Creating UUIDs

import "tideland.dev/go/uuid"

// Version 4 (random) - default
id := uuid.New()

// Version 7 (time-based, sortable) - recommended for databases
id, err := uuid.NewV7()

// Version 6 (time-based, sortable)
id, err := uuid.NewV6()

// Version 1 (time-based with MAC)
id, err := uuid.NewV1()

// Version 2 (DCE Security with UID/GID)
id, err = uuid.NewV2Person()  // Uses current process UID
id, err = uuid.NewV2Group()   // Uses current process GID
id, err = uuid.NewV2(uuid.Org, 12345)  // Custom domain and ID

// Version 5 (name-based with SHA-1)
ns := uuid.NamespaceDNS()
id, err := uuid.NewV5(ns, []byte("www.example.com"))

// Version 4 (random)
id, err := uuid.NewV4()

// Version 3 (name-based with MD5)
id, err := uuid.NewV3(ns, []byte("www.example.com"))

Parsing and Formatting

// Parse from string
id, err := uuid.Parse("123e4567-e89b-12d3-a456-426614174000")

// Format as string
str := id.String()  // "123e4567-e89b-12d3-a456-426614174000"
short := id.ShortString()  // "123e4567e89b12d3a456426614174000"

// Get version and variant
version := id.Version()
variant := id.Variant()

Namespaces

// Predefined namespaces for name-based UUIDs
ns := uuid.NamespaceDNS()   // DNS namespace
ns := uuid.NamespaceURL()   // URL namespace
ns := uuid.NamespaceOID()   // OID namespace
ns := uuid.NamespaceX500()  // X.500 namespace

Choosing a UUID Version

• Use v7 for database primary keys, sortable IDs, or when creation time matters
• Use v4 for general-purpose unique identifiers when randomness is preferred
• Use v5/v3 when you need deterministic UUIDs from names
• Use v2 for security contexts requiring embedded POSIX UID/GID
• Use v6 when you need v1 compatibility with sorting
• Use v1 only for legacy compatibility (consider v6 or v7 instead)

DCE Security (Version 2)

Version 2 UUIDs embed POSIX user or group identifiers:

// Using current user's UID
id, err := uuid.NewV2Person()
fmt.Printf("Domain: %s, UID: %d\n", id.Domain(), id.ID())

// Using current user's GID
id, err = uuid.NewV2Group()
fmt.Printf("Domain: %s, GID: %d\n", id.Domain(), id.ID())

// Custom domain and identifier
id, err = uuid.NewV2(uuid.Org, 12345)

Domains:

• uuid.Person - POSIX UID (user identifier)
• uuid.Group - POSIX GID (group identifier)
• uuid.Org - Organization-specific identifier

I hope you like it. ;)

Contributors

• Frank Mueller (https://github.com/themue / https://github.com/tideland / https://tideland.dev)