ulid Ruby Library

A ULID is a 128-bit identifier encoded as a 26-character string using Crockford's base32. It consists of two main components:

1. Timestamp (48 bits): A UNIX-time integer in milliseconds. This component ensures the identifier is lexicographically sortable. It is represented by the first 10 characters of the string.
2. Randomness (80 bits): A cryptographically secure random component. This is represented by the remaining 16 characters of the string.

String Representation

ttttttttttrrrrrrrrrrrrrrrr where t is the Timestamp and r is the Randomness.

If you are starting a new project with an empty database or attempting to resolve database slowness caused by non-time-ordered UUIDs (like UUIDv4), the author recommends considering UUID v7 instead of ULID.

For more information, visit:

• https://uuid7.com
• https://buildkite.com/resources/blog/goodbye-integers-hello-uuids/

To use ULID in your Ruby project, install the gem via the command line:

gem install ulid

The ULID module provides methods to generate Universally Unique Lexicographically Sortable Identifiers. By default, ULID.generate creates a ULID with the current timestamp and a random 80-bit suffix.

Custom Timestamp

You can pass a Time instance to ULID.generate to set a specific timestamp component (the prefix of the ULID).

require 'ulid'

# Default generation
ULID.generate # => "01ARZ3NDEKTSV4RRFFQ69G5FAV"

# Generation with an arbitrary timestamp
time_t1 = Time.now
ulid = ULID.generate(time_t1)

To generate a fully deterministic ULID, you can provide an 80-bit hex-encodable String as the suffix argument. This replaces the random component with your provided string, ensuring that the same timestamp and suffix always produce the same ULID.

require 'securerandom'
require 'ulid'

time = Time.now
an_event_identifier = SecureRandom.uuid

ulid1 = ULID.generate(time, suffix: an_event_identifier)
ulid2 = ULID.generate(time, suffix: an_event_identifier)

puts ulid1 == ulid2 # => true

Use ULID::Generator.generate to create a 26-character ULID string. By default, it uses the current time (Time.now) for the first 48 bits and generates 80 random bits for the suffix. You can provide a specific time object or a custom suffix string.

# Default generation (current time + random suffix)
ULID::Generator.generate

# Generation with a specific timestamp
ULID::Generator.generate(Time.new(2023, 1, 1))

# Generation with a custom suffix (must be a hex-encodable string representing 80 bits)
ULID::Generator.generate(suffix: 'your_80_bit_suffix_string')

The ULID module serves as the primary entrypoint for the library. By extending the Generator module, it provides direct access to ULID generation methods. You can use it to generate new Universally Unique Lexicographically Sortable Identifiers.

require 'ulid'

# Generate a new ULID
new_ulid = ULID.generate
puts new_ulid

Use ULID::Generator.generate_bytes to obtain the raw 16-byte (128-bit) representation of a ULID. This is useful when you need the binary data rather than the Crockford's Base32 string representation.

# Returns a 16-byte string
binary_ulid = ULID::Generator.generate_bytes