guid

Fast cryptographically secure Guid generator for Go.
By Stan Drapkin.

Guid is defined as type Guid [16]byte and filled with 128 cryptographically strong bits.

package main

import (
	"fmt"

	"github.com/sdrapkin/guid"
)

func main() {
	for range 4 {
		fmt.Printf("%x\n", guid.New())
	}
	fmt.Println()
	for range 4 {
		g := guid.New()
		fmt.Println(&g) // calls g.String()
	}
}

79c9779af20dcd21fbe60f3b336ed08c
da2026d38edca4371a476efd41333d23
88c3033b002b0e73321509ef26de607f
a84e961ff7f09f5210ea04585f152e73

WF8MvK5CUOrI-enEuvS0jw
AOp8Voi5knpu1mg3RjzmSg
gxOQRIVR4B_uGHD6OP76XA
Zo_hpnDxkOsAWLk1tIS6DA

Why `guid`? 🔥

guid is a high-performance, cryptographically secure UUID/GUID (Globally Unique Identifier) generator for Go. It's built for speed without compromising on security, offering a significant performance advantage—up to 10x faster than github.com/google/uuid.

Beyond raw speed, guid offers:

Cryptographically Strong: Generates 128 cryptographically secure bits for robust, unique identifiers.
Optimized for Databases: Includes special GuidPG and GuidSS types that generate sequential Guids, dramatically improving INSERT performance and preventing index fragmentation in PostgreSQL and SQL Server databases.
Seamless Interoperability: Easily integrate with existing google/uuid codebases, and even boost uuid's performance by up to 4x using guid.Reader.
FIPS 140 Compliant: Ensures adherence to stringent security standards.
Zero Allocations for Core Operations: guid.New() generates new Guids with no memory allocations, making it incredibly efficient.

Guid is ~10x faster than `github.com/google/uuid` 🔥

guid.New() is 6~10 ns
guid.NewString() is 40~60 ns
String() on existing guid is ~40 ns
multi-goroutine calls do not increase per-call latency
if your library is faster - please let me know!

API Overview

All APIs are safe for concurrent use by multiple goroutines.

Functions	Description
`guid.New()` `Guid`	Generate a new Guid
`guid.NewString()` `string`	Generate a new Guid as a Base64Url string
`guid.NewPG()` `GuidPG`	Generate a new PostgreSQL sequential Guid
`guid.NewSS()` `GuidSS`	Generate a new SQL Server sequential Guid
`guid.Parse(s string)` `(Guid, error)`	Parse a Base64Url string into a Guid
`guid.ParseBytes(src []byte)` `(Guid, error)`	Parse Base64Url bytes to a Guid
`guid.FromBytes(src []byte)` `(Guid, error)`	Parse 16-byte slice to a Guid
`guid.DecodeBase64URL(dst []byte, src []byte)` `(ok bool)`	Decode a Base64Url slice into a Guid slice
`guid.Reader` 🔥 implements `io.Reader`	Faster alternative to `crypto/rand`
guid.Nil	The zero-value Guid

`Guid` methods	Description
`.String()` `string`	Encodes the Guid into Base64Url 22-char string `fmt.Stringer`
`.EncodeBase64URL(dst []byte)` `error`	Like `.String()` but encodes into len(22) byte slice
.MarshalBinary()	Implements `encoding.BinaryMarshaler`
.UnmarshalBinary()	Implements `encoding.BinaryUnmarshaler`
.MarshalText()	Implements `encoding.TextMarshaler`
.UnmarshalText()	Implements `encoding.TextUnmarshaler`

`GuidPG`, `GuidSS` methods	Description
`.Timestamp()` `time.Time`	Extracts the UTC timestamp

Sequential Guids 🔥

guid includes two special types GuidPG and GuidSS optimized for use as database primary keys (PostgreSQL and SQL Server). Their time-ordered composition helps prevent index fragmentation and improves INSERT performance compared to fully random Guids. Note that sequential sorting is only across time.Now() timestamp precision.

guid.NewPG(): Generates a GuidPG, which is sortable in PostgreSQL.
- It is structured as [8-byte timestamp][8 random bytes].
guid.NewSS(): Generates a GuidSS, which is sortable in SQL Server.
- It is structured as [8 random bytes][8-byte SQL Server-ordered timestamp].
.Timestamp() on GuidPG/GuidSS returns Guid creation time as UTC time.Time.

Both GuidPG and GuidSS are nearly as fast as guid.New(). They can be used as a standard Guid and support the same interfaces.

Sequential Guid Example:

fmt.Printf("%s\t       %s\t\t\t\t%s\t       %s\n",
	"gpg.String()", "hex(gpg)", "gss.String()", "hex(gss)")
for range 10 {
	gpg := guid.NewPG()
	gss := guid.NewSS()
	fmt.Println(&gpg, hex.EncodeToString(gpg.Guid[:]), &gss, hex.EncodeToString(gss.Guid[:]))
}

gpg := guid.NewPG()
gss := guid.NewSS()
fmt.Println(gpg.Timestamp()) // time.Time
fmt.Println(gss.Timestamp()) // time.Time

gpg.String()           hex(gpg)                         gss.String()           hex(gss)
GFEU88wgQvDlahOowSGTKA 185114f3cc2042f0e56a13a8c1219328 9SurLKL6ti2l0BhRFPPMKA f52bab2ca2fab62da5d0185114f3cc28
GFEU88wopdChlFba89-4yg 185114f3cc28a5d0a19456daf3dfb8ca yTRE6Rr1gISl0BhRFPPMKA c93444e91af58084a5d0185114f3cc28
GFEU88ww9fA01GntVDQ_4w 185114f3cc30f5f034d469ed54343fe3 8SaILyee6q718BhRFPPMMA f126882f279eeaaef5f0185114f3cc30
GFEU88ww9fASNFzZQJpv7Q 185114f3cc30f5f012345cd9409a6fed xZ3KYLzqJ0f18BhRFPPMMA c59dca60bcea2747f5f0185114f3cc30
GFEU88ww9fAHgWvjAmkQJw 185114f3cc30f5f007816be302691027 yEif2kTQBcD18BhRFPPMMA c8489fda44d005c0f5f0185114f3cc30
GFEU88ww9fD4_Vm3PG5Vuw 185114f3cc30f5f0f8fd59b73c6e55bb SRKgSiCc-gL18BhRFPPMMA 4912a04a209cfa02f5f0185114f3cc30
GFEU88ww9fDzO_One7T6BA 185114f3cc30f5f0f33bf3a77bb4fa04 rGr2czgQcmr18BhRFPPMMA ac6af6733810726af5f0185114f3cc30
GFEU88w5PqQAifEi5tqoWQ 185114f3cc393ea40089f122e6daa859 5YYbiI3p7P4-pBhRFPPMOQ e5861b888de9ecfe3ea4185114f3cc39
GFEU88w5PqSFkX4bmxSvMQ 185114f3cc393ea485917e1b9b14af31 PqUPeiyessU-pBhRFPPMOQ 3ea50f7a2c9eb2c53ea4185114f3cc39
GFEU88w5PqTsYX0kcZzL6Q 185114f3cc393ea4ec617d24719ccbe9 yFIlRwKZJNo-pBhRFPPMOQ c8522547029924da3ea4185114f3cc39
2025-07-11 03:32:47.3597457 +0000 UTC
2025-07-11 03:32:47.3597457 +0000 UTC

Interoperability with `google/uuid` 🔥

If you must keep using google/uuid, use guid to increase performance by 2~4x:

// do this before using google/uuid
uuid.SetRand(guid.Reader)

Quick conversions between guid and google/uuid if you need uuid behavior:

g := guid.New()
gpg := guid.NewPG()
gss := guid.NewSS()

var u uuid.UUID

u = uuid.UUID(g) // copy by value
fmt.Println(u)

u = uuid.UUID(gpg.Guid) // copy by value
fmt.Println(u)

u = uuid.UUID(gss.Guid) // copy by value
fmt.Println(u)

uptr := (*uuid.UUID)(unsafe.Pointer(&g)) // zero-copy cast
g[0], g[1] = 0xAB, 0xCD
fmt.Println(uptr)

05166521-a124-9d0c-cb11-7f0cbf3a030c
1852e32a-5aac-bb9c-bffc-b330606813af
7e8badae-57f8-c88d-bb9c-1852e32a5aac
abcd6521-a124-9d0c-cb11-7f0cbf3a030c

FIPS Ready

FIPS-140 ready (https://go.dev/doc/security/fips140)
- set GODEBUG=fips140=on environment variable
- https://go.dev/blog/fips140

uuid Benchmarks with and without `guid.Reader`

Benchmark Name	Time per Op	Bytes per Op	Allocs per Op
Benchmark_uuid_New_x10-8	3031 ns/op	160 B/op	10 allocs/op
Benchmark_uuid_New_guidRand_x10-8 🔥	862.0 ns/op	160 B/op	10 allocs/op
Benchmark_uuid_New_RandPool_x10-8	747.6 ns/op	0 B/op	0 allocs/op
Benchmark_uuid_New_RandPool_guidRand_x10-8 🔥	516.8 ns/op	0 B/op	0 allocs/op
Benchmark_uuid_New_Parallel_x10-8	1230 ns/op	160 B/op	10 allocs/op
Benchmark_uuid_New_Parallel_guidRand_x10-8 🔥	510.0 ns/op	160 B/op	10 allocs/op
Benchmark_uuid_New_Parallel_RandPool_x10-8	1430 ns/op	0 B/op	0 allocs/op
Benchmark_uuid_New_Parallel_RandPool_guidRand_x10-8 🔥	1185 ns/op	0 B/op	0 allocs/op

Guid Benchmarks [raw]

go test -bench=.* -benchtime=4s
goos: windows
goarch: amd64
pkg: github.com/sdrapkin/guid
cpu: Intel(R) Core(TM) i7-10510U CPU @ 1.80GHz

Benchmarks guid [10 calls]	Time/op	Bytes/op	Allocs/op
guid_New_x10-8	203.4 ns/op	0 B/op	0 allocs/op
guid_NewString_x10-8	582.4 ns/op	240 B/op	10 allocs/op
guid_String_x10-8	388.9 ns/op	240 B/op	10 allocs/op
guid_New_Parallel_x10-8 🔥	62.45 ns/op	0 B/op	0 allocs/op
guid_NewString_Parallel_x10-8	374.2 ns/op	240 B/op	10 allocs/op

Sequential Guid Benchmarks

`guid.NewPG()` vs `uuid.NewV7()` [10 calls]	Time/op
guid.NewPG()_x10_Sequential	386.4 ns/op
uuid.NewV7()_x10_Sequential	887.9 ns/op	2.3x slower ⏳
guid.NewPG()_x10_Parallel	144.3 ns/op
uuid.NewV7()_x10_Parallel	2575 ns/op	18x slower ⏳

Alternative library benchmarks:

Benchmarks nanoid v1.35 [10 calls]	Time/op	Bytes/op	Allocs/op
`guid.NewString()` x10 Sequential	609.9 ns/op	240 B/op	10 allocs/op
`guid.NewString()` x10 Parallel (8 CPU)	384.0 ns/op	240 B/op	10 allocs/op
`nanoid.New()` x10 Sequential	2257 ns/op	240 B/op	10 allocs/op
`nanoid.New()` x10 Parallel (8 CPU)	1337 ns/op	240 B/op	10 allocs/op

Benchmarks uuid [10 calls]	Time/op	Bytes/op	Allocs/op
uuid_New_x10-8	2216 ns/op	160 B/op	10 allocs/op
uuid_New_RandPool_x10-8	528.2 ns/op	0 B/op	0 allocs/op
uuid_New_Parallel_x10-8	1064 ns/op	160 B/op	10 allocs/op
uuid_New_RandPool_Parallel_x10-8	1301 ns/op	0 B/op	0 allocs/op

Benchmarks [20 guid encodings]	Time/op	Bytes/op	Allocs/op
g.String-8	1025 ns/op	480 B/op	20 allocs/op
base64.RawURLEncoding.EncodeToString-8	1867 ns/op	960 B/op	40 allocs/op
g.EncodeBase64URL-8	392.0 ns/op	0 B/op	0 allocs/op
base64.RawURLEncoding.Encode-8	463.4 ns/op	0 B/op	0 allocs/op

Documentation

Full go doc style documentation: https://pkg.go.dev/github.com/sdrapkin/guid

Requirements

Go 1.24+

Installation

Using `go get`

To install the guid package, run the following command:

go get -u github.com/sdrapkin/guid

To use the guid package in your Go project, import it as follows:

import "github.com/sdrapkin/guid"

JSON Support

Guid supports JSON marshalling and unmarshalling for both value and pointer types:

Value fields serialize as 22-character Base64Url strings.
Pointer fields serialize as strings or null (for nil pointers).
Zero-value Guids (guid.Nil) are handled correctly.

Example: JSON Marshalling

type User struct {
	ID        guid.Guid  `json:"id"`
	ManagerID *guid.Guid `json:"mid"`
}

u, u2 := User{ID: guid.New()}, User{}
data, _ := json.Marshal(u)
fmt.Println(string(data)) // {"id":"tI0EMdDXpOcvvGLktob4Ug","mid":null}

_ = json.Unmarshal(data, &u2)
fmt.Println(u2.ID == u.ID) // true

📚 guid - Awesome Go Library for UUID

Detailed Description of guid

guid

Fast cryptographically secure Guid generator for Go.
By Stan Drapkin.

Why `guid`? 🔥

Guid is ~10x faster than `github.com/google/uuid` 🔥

API Overview

Sequential Guids 🔥

Sequential Guid Example:

Interoperability with `google/uuid` 🔥

FIPS Ready

uuid Benchmarks with and without `guid.Reader`

Guid Benchmarks [raw]

Sequential Guid Benchmarks

Alternative library benchmarks:

Documentation

Requirements

Installation

Using `go get`

JSON Support

Example: JSON Marshalling

📚 guid - Awesome Go Library for UUID

Detailed Description of guid

guid

Fast cryptographically secure Guid generator for Go.By Stan Drapkin.

Why guid? 🔥

Guid is ~10x faster than github.com/google/uuid 🔥

API Overview

Sequential Guids 🔥

Sequential Guid Example:

Interoperability with google/uuid 🔥

FIPS Ready

uuid Benchmarks with and without guid.Reader

Guid Benchmarks [raw]

Sequential Guid Benchmarks

Alternative library benchmarks:

Documentation

Requirements

Installation

Using go get

JSON Support

Example: JSON Marshalling

Fast cryptographically secure Guid generator for Go.
By Stan Drapkin.

Why `guid`? 🔥

Guid is ~10x faster than `github.com/google/uuid` 🔥

Interoperability with `google/uuid` 🔥

uuid Benchmarks with and without `guid.Reader`

Using `go get`