TSID Generator (Time-Sorted ID)

TSID and TLID: the 64-bit time-sorted ID

TSID stands for Time-Sorted Identifier and TLID for Time-Locked Identifier — a 64-bit identifier designed by Brazilian developer Caio Gondim, originally released as the Java library tsid-creator in 2020. It is a deliberately smaller alternative to Twitter Snowflake and a much smaller alternative to UUID, while still being globally unique, sortable by time and friendly to relational databases.

Bit layout

The 64 bits are split into 42 bits of timestamp (milliseconds since a custom epoch) and 22 bits of randomness or node + counter. The whole value fits in a SQL BIGINT, so PostgreSQL, MySQL, SQL Server and SQLite store it natively — no extra uuid column needed.

| 42 bits time (ms)             | 22 bits random / node-counter |
+-------------------------------+-------------------------------+

The canonical text form is 13 characters of Crockford Base32 — URL-safe, case-insensitive, no ambiguous characters (no I, L, O, U). The TLID variant applies extra shuffling/encoding so values are not visibly monotonic, useful when you want time-sorted indexing without exposing creation order to end users.

Why TSID instead of UUID or Snowflake

• Smaller than UUID — 64 bits versus 128 bits halves index size and doubles cache density.
• Sortable by time — sequential B-tree inserts, ~2-3x faster than UUID v4 at scale.
• No coordinator — unlike Snowflake, which needs a worker-id registry, TSID can be generated with pure randomness in the low 22 bits.
• URL-safe — 13-char Crockford Base32 is shorter than a UUID and friendlier to humans.
• No database sequence — every node generates independently, perfect for microservices.

Comparison with other ID schemes

• UUID v4 — 128 bits, fully random, terrible for B-tree locality.
• UUID v7 — 128 bits, timestamp + random, sortable but still double the size.
• ULID — 128 bits, similar idea to v7 but earlier and uses Crockford Base32.
• Snowflake — 64 bits, centralised counter, needs worker-id coordination.
• TSID — 64 bits, decentralised, random tail, no coordinator required.

Ecosystem and libraries

The reference implementation is tsid-creator for Java, hugely popular in the Spring Boot community — TSID is one of the most successful Brazilian open-source exports in backend tooling. Ports exist for many ecosystems: tsid-rs (Rust), pgtsid (PostgreSQL extension), JavaScript and Go implementations, and CLR/Kotlin wrappers. Store them as BIGINT in Postgres and BIGINT UNSIGNED in MySQL.

Trade-offs to be aware of

With only 22 random bits per millisecond, entropy is far lower than UUID v4's 122 random bits. For most application workloads (millions of IDs per second across a fleet) this is fine, but for security-sensitive identifiers — password reset tokens, session IDs, anything an attacker might try to brute-force — you should still prefer UUID v4 or a dedicated CSPRNG token. TSID is for primary keys, not secrets.

FAQ

Does TSID replace UUID? Yes, at large scale TSID is a strong replacement for UUID v4 as a primary key when you need compact, time-sortable IDs and you can fit them in a BIGINT column.

Is TSID smaller than UUID v7? Yes — 64 bits versus 128 bits. Half the index size, half the network payload, half the memory.

When should I NOT use TSID? When you need maximum entropy for security (use UUID v4 or a CSPRNG), when you must follow the standard UUID column type for compatibility, or when 64 bits won't be enough across the lifetime of the system.

What's the difference between TSID and TLID? TSID is the raw time-sorted value. TLID adds an encoding step that hides the monotonic ordering from the textual representation, so consecutive IDs don't look consecutive.