uuid

README

go-uuid

A simple, stdlib only, go module for generating UUIDs (Universally Unique IDentifiers).

Installation

CLI

# Using go install
go install github.com/cmackenzie1/go-uuid/cmd/uuid@latest

Or download the binary from Releases

Package

go get github.com/cmackenzie1/go-uuid

Supported versions

Version	Variant	Details
Version 4	10	Pure random as defined in RFC9562.
Version 7	10	Time-sortable as defined in RFC9562.

Usage

// example/example.go
package main

import (
	"fmt"

	"github.com/cmackenzie1/go-uuid"
)

func main() {
	v4, err := uuid.NewV4()
	if err != nil {
		panic(err)
	}
	fmt.Printf("UUIDv4: %s\n", v4) // c07526de-40e5-418f-93d1-73ba20d2ac2c

	v7, _ := uuid.NewV7()
	if err != nil {
		panic(err)
	}
	fmt.Printf("UUIDv7: %s\n", v7) // 0185e1af-a3c1-704f-80f5-6fd2f8387f09
}

FAQ

What are the benefits of this library over X?

• A single library with no external dependencies for multiple types of UUIDs.
• UUID type is defined as a fixed-size, [16]byte, array which can be used as a map (instead of the 36 byte string representation). Over 2x space savings for memory!
• Limited API. As per RFC9562, UUIDs (while containing embedded information), should be treated as opaque values. There is no temptation to build dependencies on the embedded information if you can't easily access it. 😉

When should I use UUIDv7 over UUIDv4?

Non-time-ordered UUID versions such as UUIDv4 have poor database index locality. This means that new values created in succession are not close to each other in the index and thus require inserts to be performed at random locations. The negative performance effects of which on common structures used for this (B-tree and its variants) can be dramatic. 1

tl;dr: if you intend to use the UUID as a database key, use UUIDv7. If you require purely random IDs, use UUIDv4.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Documentation

Index

• type UUID
  • func NewV4() (UUID, error)
  • func NewV7() (UUID, error)
  • func Parse(s string) (UUID, error)
  • func (uuid UUID) MarshalText() ([]byte, error)
  • func (uuid UUID) String() string
  • func (uuid UUID) URN() string
  • func (uuid *UUID) UnmarshalText(text []byte) error

Types

type UUID

type UUID [16]byte

UUID is a 128 bit (16 byte) value defined by RFC9562.

var Nil UUID

Nil represents the zero-value UUID

func NewV4

func NewV4() (UUID, error)

NewV4 returns a Version 4 UUID as defined in RFC9562. Random bits are generated using crypto/rand.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           random_a                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          random_a             |  ver  |       random_b        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                       random_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           random_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func NewV7

func NewV7() (UUID, error)

NewV7 returns a Version 7 UUID as defined in RFC9562. Random bits are generated using crypto/rand.

This function employs method 3 (Replace Leftmost Random Bits with Increased Clock Precision) to increase the clock precision of the UUID. This helps support scenarios where several UUIDs are generated within the same millisecond.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           unix_ts_ms                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          unix_ts_ms           |  ver  |       rand_a          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                        rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func Parse

func Parse(s string) (UUID, error)

Parse a UUID string with or without the dashes.

u, err := Parse("56c450b3255d4a2aa761cd1b1bf028e2") // no dashes
u, err := Parse("56c450b3-255d-4a2a-a761-cd1b1bf028e2") // with dashes
u, err := Parse("urn:uuid:56c450b3-255d-4a2a-a761-cd1b1bf028e2") // urn uuid prefix

func (UUID) MarshalText

func (uuid UUID) MarshalText() ([]byte, error)

func (UUID) String

func (uuid UUID) String() string

String returns the UUID in "hex-and-dash" string format.

56c450b3-255d-4a2a-a761-cd1b1bf028e2

func (UUID) URN

func (uuid UUID) URN() string

URN returns the UUID in "urn:uuid" string format.

urn:uuid:56c450b3-255d-4a2a-a761-cd1b1bf028e2

func (*UUID) UnmarshalText

func (uuid *UUID) UnmarshalText(text []byte) error