ulid

oklog/ulid is a Go implementation of the ULID specification, providing Universally Unique Lexicographically Sortable Identifiers as a drop-in alternative to UUIDs. Each ULID packs a 48-bit millisecond timestamp and 80 bits of entropy into a fixed 16-byte array, encoded as a 26-character Crockford Base32 string that sorts the same lexicographically as it does chronologically.

The package exposes low-allocation constructors (ulid.New, ulid.Make), parsing (Parse, ParseStrict), and monotonic entropy sources that guarantee strictly increasing IDs generated within the same millisecond. It implements the standard encoding.TextMarshaler, encoding.BinaryMarshaler, and database/sql/driver.Valuer/Scanner interfaces, so ULIDs slot directly into JSON APIs, binary protocols, and SQL columns without custom glue code. A companion CLI (cmd/ulid) generates and parses ULIDs from the command line.

What You Get

• A ULID type backed by a [16]byte array with zero-allocation binary encoding
• Millisecond-precision, monotonically increasing ID generation via ulid.Make and ulid.Monotonic
• Strict and lenient parsers (Parse, ParseStrict) for round-tripping the 26-character Base32 string form
• Native support for database/sql, encoding/json, and binary marshaling interfaces
• A standalone ulid command-line tool for generating and inspecting IDs outside of Go code

Common Use Cases

• Primary keys for database rows that need to sort by creation time without a separate timestamp column
• Distributed request/trace IDs where lexicographic sort order doubles as chronological order
• Replacing UUID v4 primary keys in high-write systems to reduce B-tree index fragmentation
• Generating collision-resistant, URL-safe identifiers for object storage keys and event logs

Under The Hood

Architecture A single flat package (ulid.go, ~720 lines) is built around a [16]byte-backed ULID type with no internal layering — timestamp (bytes 0-5) and entropy (bytes 6-15) are packed directly into the array and manipulated with bit-shifting rather than through an internal struct, and the separate cmd/ulid binary is the only consumer split out from the core package, wiring the library’s New/Parse/Monotonic API to a pborman/getopt CLI. Monotonicity is handled by a MonotonicEntropy/LockedMonotonicReader pair that wraps an io.Reader in a bufio.Reader and tracks a package-level uint80 counter, so the only meaningful layer boundary in the codebase is between the pure data type (encoding/parsing/comparison methods on ULID) and the stateful entropy sources that feed it; changing the core byte layout would ripple through every marshal/unmarshal method since offsets are hardcoded by index rather than derived from named constants.

Tech Stack The core package uses only the standard library — encoding/binary, math/bits, crypto/rand and math/rand, database/sql/driver, and sync cover parsing, monotonic increments, and SQL integration — with zero third-party runtime dependencies declared in go.mod (module github.com/oklog/ulid/v2, go 1.15). The sole external dependency, github.com/pborman/getopt/v2, is scoped to the optional cmd/ulid CLI binary, not the importable package. Build and test tooling is plain go build/go test, with CI running gofmt, go vet, staticcheck, and go test -race across Linux, macOS, and Windows on the current Go toolchain.

Code Quality A single, extensive test file uses property-based checks (testing/quick) for randomized round-trip verification alongside explicit doctest-style examples and error-path assertions, giving dense coverage of the small public surface. Error handling is idiomatic Go with typed sentinel errors rather than panics in the non-Must* API, comments are precise and credit upstream sources for optimized routines, and CI enforces formatting, vet, and static-analysis checks on every push in addition to running the race detector across three operating systems — a level of quality-gate rigor above most Go libraries of comparable scope.

API Design The public API is deliberately layered from convenience to control: ulid.Make() takes zero arguments for the common case, ulid.New(ms, entropy) exposes the two dimensions that matter, and Monotonic/LockedMonotonicReader let advanced users opt into strict ordering guarantees without changing call sites elsewhere. The type implements every standard Go serialization interface a caller could want (TextMarshaler, BinaryMarshaler, sql.Scanner/driver.Valuer) so a ULID field works directly in JSON, raw byte protocols, and any database/sql driver without adapter code, and the doc comments even demonstrate how to wrap the type for edge cases the maintainers deliberately didn’t special-case — a level of documented extensibility that’s more thoughtful than most ID-generation libraries offer.