dj-prefixed-ulids

Prefixed ULID Primary Keys

This project uses Stripe-style prefixed ULIDs as the primary key for every Django model:

prd_01jq3v8f6a7b2c8d9e0f1g2h3j4k
ord_01jq3v8fgh7x2y5z9a1b2c3d4e5f

A 3-4 character prefix identifies the entity type, followed by an underscore and a lowercase ULID. ULIDs are 128-bit, lexicographically sortable by creation time, URL-safe, and collision-resistant.

Why

• Debuggable. ord_01jq... in a log line tells you immediately it's an order — no need to cross-reference the column.
• Safe to expose. Unlike auto-increment integers, prefixed ULIDs leak no ordering or volume information, and unlike opaque UUIDs they remain human-readable.
• Time-sortable. ULIDs sort chronologically, so ORDER BY id doubles as ORDER BY created_at without a second index.
• Type-safe across layers. Every ID is a str end-to-end — no UUID / str coercion at the service/API boundary.
• No integer collisions. Exporting, importing, and sharding are all easier without monotonic counters.

The Generator

Put this in src/project/ids.py:

from ulid import ULID


def prefixed_ulid(prefix: str) -> str:
    return f"{prefix}_{str(ULID()).lower()}"


def _make_generator(prefix: str):
    def generate() -> str:
        return prefixed_ulid(prefix)

    generate.__name__ = f"generate_{prefix}_id"
    generate.__qualname__ = f"generate_{prefix}_id"
    return generate

Then register a generator per aggregate root:

generate_prd_id = _make_generator("prd")
generate_ord_id = _make_generator("ord")
generate_itm_id = _make_generator("itm")

The __name__ / __qualname__ rewrite matters: Django migrations serialize the default callable's fully qualified name, so each generator needs a distinct identity or the autodetector will get confused.

Choosing a Prefix

• 3 to 4 lowercase letters — short enough to stay readable in logs
• Must be unique across the whole project
• Prefer mnemonic, not cryptic: ord for order, inv for invoice, prd for product, usr for user
• Avoid collisions with existing prefixes — grep src/project/ids.py before inventing a new one
• Never rename a prefix once it's in production; the prefix is part of the ID