KSUID Generator

KSUID (K-Sortable Unique IDentifier) is a 20-byte identifier consisting of a 4-byte Unix timestamp prefix followed by 16 bytes of random data, encoded as a 27-character Base62 string. Unlike UUID v4 (which is entirely random and not sortable), KSUIDs sort lexicographically in creation order, making them useful for database primary keys where time-based ordering is desired without a separate timestamp column. UUID v7 is a newer standard that also provides time-ordered UUIDs.

Auto-increment integers expose record counts, are not portable across distributed systems, and require centralised sequence generation. KSUIDs are globally unique without coordination, embed creation time, sort chronologically, and are safe to expose in URLs without revealing business metrics. The trade-off is larger storage (20 bytes vs 4–8 bytes for integers) and slightly slower index operations due to random high bytes preventing perfect sequential insertion.

Base62 uses digits 0–9 and letters A–Z and a–z (62 characters total). Unlike Base64, it has no special characters (+, /, =) making it safe for URLs, file names, and string comparison without encoding. KSUID uses Base62 because the resulting 27-character string sorts lexicographically in the same order as the underlying 20-byte binary, which is critical for the time-ordering property to work correctly in string comparisons.

KSUID timestamps have 1-second precision, using a 4-byte unsigned integer representing seconds since a custom epoch of May 13, 2014 00:00:00 UTC. This epoch was chosen so the timestamp doesn’t overflow until the year 2150. The 16-byte random component ensures uniqueness even when multiple KSUIDs are generated within the same second on multiple machines, making collisions astronomically unlikely.