UXID

View Source

MIT License Hex Version Hex Downloads

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

Validation

By default cast/2 accepts any binary unchanged, which is ideal while a schema still holds a mix of legacy identifiers. A field can opt in to strict validation with validate: true, in which case a value must be either a structurally valid UXID carrying the field's configured :prefix, or a legacy bare UUID string (canonical 36-character form). Anything else — an empty string, the wrong prefix, non–Base32 characters — casts to :error.

@primary_key {:id, UXID, autogenerate: true, prefix: "org", size: :medium, validate: true}
schema "organizations" do
  field :owner_org_id, UXID, prefix: "org", validate: true
end

UUID coexistence is on by default so a table can migrate its column type from uuid to text without rewriting existing rows. Turn it off with allow_uuid: false once a table holds only UXIDs.

You can also validate a string directly, without Ecto:

UXID.valid?("org_01emdgjf0dqxqj8fm78xe97y3h")                 # => true
UXID.valid?("org_01emdgjf0dqxqj8fm78xe97y3h", prefix: "usr")  # => false
UXID.valid?("not-a-uxid")                                     # => false

valid?/2 checks structure (prefix + Crockford Base32 body), not authenticity, and deliberately does not accept bare UUIDs — that coexistence lives in cast/2.

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

Monotonic IDs

Standard UXIDs draw fresh randomness for every ID, so collision risk within a single millisecond is a birthday problem — for small sizes (:xsmall has 0 random bits, :small has 16) a burst of same-millisecond IDs can collide. Monotonic mode fixes this the way the ULID monotonic spec does: within a millisecond it seeds the random field once from the CSPRNG, then advances it by a random positive step for each subsequent ID. That turns "birthday collision among N draws" into "guaranteed distinct until the field overflows," and because the field is encoded big-endian, a strictly increasing counter also sorts strictly after — K-sortability is preserved at every size.

The step is uniform over [1, 2^(bits/2)] (the square root of the field space, auto-derived from the size — no configuration). Stepping by a random amount instead of exactly +1 means an attacker who sees …0004 can no longer guess …0005: single-shot guess cost rises from certainty to ~1/2^(bits/2) (1/256 at :small, ~1/10⁶ at :medium), while still leaving ample same-ms burst headroom before overflow (~512 IDs/ms at :small, ~2M at :medium).

# Per-call: on for all sizes
UXID.generate!(size: :small, monotonic: true)

# Per-size list (alias-aware: :small also matches :s, :medium matches :m, ...)
UXID.generate!(size: :small, monotonic: [:small, :medium])

Global policy (overridable per-call/per-field, mirrors compact_small_times):

# config/config.exs
config :uxid, monotonic: true
# or only for specific sizes:
config :uxid, monotonic: [:small, :medium]

In Ecto schemas:

field :id, UXID, autogenerate: true, prefix: "evt", size: :small, monotonic: true

Scope of the guarantee: monotonic and collision-free within a single BEAM process. State lives in the process dictionary (keyed by prefix and field size) — no GenServer, no ETS, no shared state, so it is async: true safe. Each process gets an independent random starting point per millisecond, so cross-process collisions fall back to a birthday probability on the field size.

Tradeoff (why it is opt-in): the random step is a mitigation, not cryptographic unpredictability. It removes trivial +1 enumeration, but an attacker who observes two consecutive same-ms IDs learns the actual gap, and values still lie in a bounded window ahead. Low-entropy sizes stay low-entropy, so monotonic must be a conscious per-resource choice and is never a silent default — don't use :small/:medium monotonic IDs as externally-enumerable, security-sensitive identifiers; prefer :large/:xl (and non-monotonic) there.

:xs/:xsmall note: a standard :xs has 0 random bits — nothing to increment — so when monotonic is active compact_time is enabled automatically for :xs/:xsmall, yielding a 1-byte (8-bit) counter field. Passing an explicit compact_time: false on :xs/:xsmall with monotonic on raises an ArgumentError (there would be no field to count). This inherits the compact :xsmall time-decode ambiguity described under Compact Time — uniqueness and sorting are unaffected, but decoding the timestamp back out of a monotonic :xs is unreliable.

Prefix Registry

A prefix only pays off — "the ID names its resource on sight" — when it is globally unique and well-formed across your whole app. UXID.Registry is an opt-in, compile-time DSL that makes those guarantees the compiler's job instead of a hand-rolled CI test, and turns the same declarations into a runtime routing table (prefix → schema) for the ID-driven patterns Adam Kirk describes in his ElixirConf US 2025 talk, UXIDs in Elixir/Ecto (authorization/IDOR checks, admin auto-linking, Relay global IDs).

Declare one registry module as your single source of truth:

defmodule MyApp.IDs do
  use UXID.Registry,
    default_size: :medium,
    default_validate: true

  defid :org,     prefix: "org",     schema: MyApp.Org,         category: :account
  defid :contact, prefix: "contact", size: :large, schema: MyApp.CRM.Contact
  defid :lead,    prefix: "lead"
  retired "usr" # reserve a prefix so it stays unique-checked, never reused
end

Compile-time guarantees. Every prefix is checked against :prefix_format (overridable; the default permits an internal underscore for compound prefixes like in_ref), and all prefixes — active and retired — are checked for uniqueness. A malformed or duplicate prefix is a compile error, so the governance every prefixed-ID scheme needs ships in the library.

By key — minting and schema configuration:

MyApp.IDs.generate!(:org)   # => "org_01h…"
MyApp.IDs.prefix(:org)      # => "org"
MyApp.IDs.size(:org)        # => :medium
MyApp.IDs.schema(:org)      # => MyApp.Org
MyApp.IDs.all()             # => [%{key: :org, prefix: "org", schema: MyApp.Org, ...}, ...]

field_opts/1 is the single-source-of-truth hook — a schema spreads it instead of restating prefix/size/validate anywhere:

@primary_key {:id, UXID, [autogenerate: true] ++ MyApp.IDs.field_opts(:org)}

By ID string — the runtime routing table (the "which resource is this?" map):

MyApp.IDs.known?("org_01h…")      # => true   (cheap prefix-only membership check)
MyApp.IDs.key_for("org_01h…")     # => :org
MyApp.IDs.schema_for("org_01h…")  # => MyApp.Org
MyApp.IDs.resolve("org_01h…")     # => %{key: :org, schema: MyApp.Org, category: :account, ...}

Lookups split an ID on the last delimiter, which is unambiguous without any registry lookup because a UXID body is Crockford Base32 and never contains the delimiter — so in_ref_01h… recovers the in_ref prefix cleanly. For that reason the :delimiter must be a character that cannot appear in a Base32 body ("_" — the default — or "-"); an underscore is preferred for compound prefixes since it does not break double-click-to-select-the-whole-id.

Sharing the registry across sources (JSON manifest)

UXIDs are source-agnostic — you can mint them in Postgres with INSERT ... SELECT or on a mobile/JS client that generates an ID offline before upload. To keep the Elixir registry the single source of truth in those places too, export a JSON manifest and let the other runtime read it:

MyApp.IDs.manifest()
# => [%{"key" => "org", "prefix" => "org", "size" => "medium", "category" => "account"}, ...]

MyApp.IDs.manifest_json()
# => ~s([{"key":"org","prefix":"org","size":"medium","category":"account"}, ...])

manifest/0 returns plain JSON-safe data (string keys, scalar values, nil for unset fields) that you can hand to any JSON library; manifest_json/0 returns a ready-to-write string with no extra dependency. A common pattern is a tiny Mix task or release step that writes it to a file your database migrations or client build consume, so every generator agrees on prefixes and sizes:

# lib/mix/tasks/uxid.manifest.ex
defmodule Mix.Tasks.Uxid.Manifest do
  use Mix.Task
  @shortdoc "Writes the UXID prefix manifest to priv/uxid_manifest.json"
  def run(_args) do
    File.write!("priv/uxid_manifest.json", MyApp.IDs.manifest_json())
  end
end

The manifest carries prefix, size (which fixes the random length), category, and key; combine each prefix with the registry's delimiter and a Base32 body to assemble an ID anywhere.

Installation

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

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

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