UXID

User eXperience focused IDentifiers (UXIDs) are identifiers which:

• Describe the resource (aid in debugging and investigation)
• Work well with copy and paste (double clicking selects the entire ID)
• Can be shortened for low cardinality resources
• Are secure against enumeration attacks
• Can be generated by application code (not tied to the datastore)
• Are K-sortable (lexicographically sortable by time - works well with datastore indexing)
• Do not require any coordination (human or automated) at startup, or generation
• Are very unlikely to collide (more likely with less randomness)
• Are easily and accurately transmitted to another human using a telephone

Many of the concepts of Stripe IDs have been used in this library.

Usage

Generating UXIDs

# No options generates a basic ULID
UXID.generate! # "01emdgjf0dqxqj8fm78xe97y3h"

# A prefix can be provided
UXID.generate! prefix: "cus" # "cus_01emdgjf0dqxqj8fm78xe97y3h"

# The amount of randomness can be decreased for smaller cardinality resources
# T-Shirt sizes can be used (xs, s, m, l, xl) or (xsmall, small, medium, large, xlarge)
UXID.generate! prefix: "cus", size: :small # "cus_01eqrh884aqyy1"

# Compact time mode trades timestamp precision for more randomness (good for collision resistance)
UXID.generate! prefix: "sess", size: :small, compact_time: true # "sess_kf3ng7s1mf41b"

# Uppercase can be used to match previous UXID versions
UXID.generate! case: :upper # "01EMDGJF0DQXQJ8FM78XE97Y3H"

Ecto

UXIDs can be used as Ecto fields including primary keys.

defmodule YourApp.User do
  use Ecto.Schema

  @primary_key {:id, UXID, autogenerate: true, prefix: "usr", size: :medium}
  schema "users" do
    field :api_key, UXID, autogenerate: true, prefix: "apikey", size: :small, compact_time: true
    field :api_secret, UXID, autogenerate: true, prefix: "apisecret", size: :xlarge
  end
end

Configuration

Case

The :case config option controls the default case for generated UXIDs. By default, UXIDs are lowercase (:lower), but you can configure uppercase (:upper) globally or per-call.

# config/config.exs
config :uxid, case: :upper

# All generated UXIDs will be uppercase by default
UXID.generate!()
# => "01EMDGJF0DQXQJ8FM78XE97Y3H"

# Override per-call if needed
UXID.generate!(case: :lower)
# => "01emdgjf0dqxqj8fm78xe97y3h"

Minimum Size

The :min_size config option enforces a minimum UXID size regardless of what size is requested. This is useful in test environments where many IDs are generated rapidly, as smaller sizes have limited randomness that can cause duplicate key violations.

# config/test.exs
config :uxid, min_size: :medium

# In application code - requests :small but gets :medium in test env
UXID.generate!(prefix: "usr", size: :small)
# => Returns 18 character UXID instead of 14

When configured, any requested size smaller than :min_size will be automatically upgraded. Larger sizes are not affected.

Compact Time

The :compact_small_times config option and per-call compact_time option provide improved collision resistance for small UXIDs by using shorter timestamps and more randomness.

Global Policy:

# config/test.exs
config :uxid, compact_small_times: true

# Automatically compacts :xs/:xsmall and :s/:small sizes
UXID.generate!(size: :small)
# => 13 chars (8 time + 5 rand = 24 bits random vs 16 bits standard)

Per-Call Override:

# Override for any size - works even when global policy is off
UXID.generate!(size: :large, compact_time: true)
# => 21 chars with extra randomness

# Opt out of global policy for specific calls
UXID.generate!(size: :small, compact_time: false)
# => 14 chars with standard randomness

In Ecto Schemas:

defmodule YourApp.Session do
  use Ecto.Schema

  @primary_key {:id, UXID, autogenerate: true, prefix: "sess", size: :small, compact_time: true}
  schema "sessions" do
    # This session ID will always use compact mode for better collision resistance
  end
end

How it works:

• Reduces timestamp from 48 bits (10 chars) to 40 bits (8 chars)
• Frees 8 bits for additional randomness (e.g., :small gets 24 bits vs 16 bits)
• Perfect 5-bit Crockford Base32 alignment
• K-sortability maintained until ~September 2039
• Decoder automatically detects compact format and reconstructs full timestamp using epoch inference

When to use:

• Test environments with rapid ID generation
• Resources with small cardinality that need better collision resistance
• Any scenario where you want to maximize randomness within a given length constraint

Installation

The package can be installed by adding uxid to your list of dependencies in mix.exs:

def deps do
  [
    {:uxid, "~> 2.3"}
  ]
end

Online documenttion can be found at https://hexdocs.pm/uxid.