spec README

The project's README from github.com/ulid/spec. As one markdown file: README.md.



ulid


Universally Unique Lexicographically Sortable Identifier

UUID can be suboptimal for many use-cases because:

Instead, herein is proposed ULID:

ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV

Implementations in other languages

From ourselves and the community!

Language Author Binary Implementation
C++ suyash ✓
C# mcb2001
Clojure theikkila
Objective-C ricardopereira
Crystal SuperPaintman
Dart isoos ✓
Dart GuepardoApps
Delphi matinusso
D enckse
D (dub) extrawurst
Erlang savonarola
Elixir Homepolish ✓
Elixir merongivian
Elixir omisego ✓
Elixir (Ecto) dcuddeback ✓
F# lucasschejtman
Factor Alexander Ilin ✓
Go oklog ✓
Haskell steven777400 ✓
Java huxi ✓
Java azam
Java Lewiscowles1986
JavaScript ulid
JavaScript aarondcohen ✓
Julia ararslan
Kotlin GuepardoApps
Lua Tieske
.NET RobThree ✓
.NET fvilers
Nim adelq
OCaml stripedpajamas
Perl 5 bk ✓
PHP Lewiscowles1986
PHP robinvdvleuten
PowerShell PetterBomban
Python mdipierro
Python ahawker ✓
Python mdomke ✓
R hrbrmstr
Ruby rafaelsales
Rust mmacedoeu ✓
Rust dylanhart ✓
Scala petitviolet
SQL-Microsoft rmalayter ✓
Swift simonwhitehouse
Swift yaslab ✓
Tcl dbohdan

Specification

Below is the current specification of ULID as implemented in ulid/javascript.

Note: the binary format has not been implemented in JavaScript as of yet.

 01AN4Z07BY      79KA1307SR9X4MV3

|----------|    |----------------|
 Timestamp          Randomness
   48bits             80bits

Components

Timestamp

Randomness

Sorting

The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed

Canonical String Representation

ttttttttttrrrrrrrrrrrrrrrr

where
t is Timestamp (10 characters)
r is Randomness (16 characters)

Encoding

Crockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.

0123456789ABCDEFGHJKMNPQRSTVWXYZ

Monotonicity

When generating a ULID within the same millisecond, we can provide some guarantees regarding sort order. Namely, if the same millisecond is detected, the random component is incremented by 1 bit in the least significant bit position (with carrying). For example:

import { monotonicFactory } from 'ulid'

const ulid = monotonicFactory()

// Assume that these calls occur within the same millisecond
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0

If, in the extremely unlikely event that, you manage to generate more than 280 ULIDs within the same millisecond, or cause the random component to overflow with less, the generation will fail.

import { monotonicFactory } from 'ulid'

const ulid = monotonicFactory()

// Assume that these calls occur within the same millisecond
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRY
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVRZ
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS0
ulid() // 01BX5ZZKBKACTAV9WEVGEMMVS1
...
ulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZX
ulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZY
ulid() // 01BX5ZZKBKZZZZZZZZZZZZZZZZ
ulid() // throw new Error()!

Overflow Errors when Parsing Base32 Strings

Technically, a 26-character Base32 encoded string can contain 130 bits of information, whereas a ULID must only contain 128 bits. Therefore, the largest valid ULID encoded in Base32 is 7ZZZZZZZZZZZZZZZZZZZZZZZZZ, which corresponds to an epoch time of 281474976710655 or 2 ^ 48 - 1.

Any attempt to decode or encode a ULID larger than this should be rejected by all implementations, to prevent overflow bugs.

Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Prior Art

Partly inspired by:

spec (ulid/spec)

Searching Database…

10.8K ·GitHub
Spec
What is this?This is the canonical specification for ULID (Universally Unique Lexicographically Sortable Identifier), a 128-bit identifier format designed as a sortable, URL-safe alternative to UUID.
Is this a code library or just a specification?It is just a specification document, not a runnable library itself. The repo defines the format and lists community-built implementations in dozens of languages that actually generate and parse ULIDs.
How do I actually generate ULIDs in my project?Pick an existing implementation for your language from the table in the README (Go, JavaScript, Python, Java, Rust, etc.) and install that package; this repo itself contains no code to run.
What happens if I generate too many ULIDs in the same millisecond?If more than 2^80 ULIDs are generated within the same millisecond, the random component overflows and generation must fail according to the spec.
Why would I use ULID instead of UUID?It's for developers who want sortable, time-ordered unique IDs without UUID's downsides, like needing a stable MAC address or causing index fragmentation from pure randomness.
Why is ULID better than UUID for database primary keys?ULID encodes a timestamp first, so IDs sort lexicographically in chronological order, avoiding the random-insert index fragmentation that UUID v4 causes.
How is a ULID structured?It packs a 48-bit millisecond timestamp and 80 bits of randomness into 128 bits total, canonically shown as a 26-character string.
What happens if two ULIDs are generated in the same millisecond?Implementations must guarantee monotonic order by incrementing the random component by 1 bit (with carrying) when a duplicate millisecond is detected.
Which character set does ULID use for encoding?Crockford's Base32, which excludes I, L, O and U to avoid confusion, and is case-insensitive and URL-safe.
What are similar projects?rfcs, toml, proposals, fantasy-land, agents.md, design, spec, JavaScript
Which topics is it in?sort, spec, encoding, standards, specification, algorithm, protocol, data-structures, distributed-systems, reference, documentation, database
Creator
ulid
Size
0.1 MB
Stars
10.8K
Updated
CommitMay 23
Age
8y
Commits · 90 Days