Choosing an ID
Choose for the system boundary, not the trend.
Different identifiers optimize for different constraints. Start with the boundary the value crosses: database index, URL, public API, MongoDB collection, or a native integer column.
| Situation | Choose | Why |
|---|---|---|
| Database primary keys | UUID v7 or ULID | Time-ordered values improve index locality. |
| Public API resources | TypeID | UUID v7 with a readable, domain-specific prefix. |
| Short URLs and invite codes | Nanoid | Compact and URL-safe. |
| Values that should resist enumeration | CUID v2 | Non-sequential, secure identifier. |
MongoDB _id compatibility | ObjectID | Matches MongoDB's 12-byte ObjectID format. |
| Go rs/xid compatibility | XID | Matches rs/xid's compact 12-byte text and binary format. |
Native BIGINT storage | TSID | A sortable 64-bit integer, not a UUID-shaped string. |
| Broad standards compatibility | UUID v4 | The conventional random UUID format. Random values fragment primary key indexes. |
| An ID derived from something you already have | UUID v5 | The same name and namespace always give the same UUID, with no state to keep. |
A good default
If you create records in more than one service or need an ID before inserting a row, start with UUID v7. It is a UUID-native value, sort-friendly, and uses a familiar database column type.
import { uuidv7 } from 'uniku/uuid/v7'
const orderId = uuidv7()Storing IDs in a database
A time-ordered ID keeps inserts at the end of an index only if the database compares the stored value in generation order. The stored width decides how large every index on the table gets.
PostgreSQL has a native uuid type for UUID v7 and UUID v4 values. It stores the 128-bit value and compares it byte by byte, so UUID v7 rows sort by creation time. For ULID and other binary formats, the Drizzle example stores toBytes() output in a bytea column.
MySQL has no UUID column type. Store UUID v7 and ULID values in a BINARY(16) column. Convert with toBytes() before you write and with fromBytes() after you read:
import { uuidv7 } from 'uniku/uuid/v7'
const id = uuidv7()
const bytes = uuidv7.toBytes(id) // 16 bytes for a BINARY(16) column
uuidv7.fromBytes(bytes) === id // trueAvoid CHAR(36) primary keys in MySQL. InnoDB stores each table's rows in a clustered index ordered by the primary key, and every secondary index record repeats the primary key columns. A key of 36 bytes or more makes each of those indexes larger than a 16-byte key does.
Skip the swap flag for UUID v7
MySQL's UUID_TO_BIN(id, 1) swaps the first and third groups of hex digits before it stores the value. The swap exists for UUID v1, whose fastest-changing timestamp bits come first. UUID v7 already starts with its millisecond timestamp. The swap puts the third group, 7xxx, in front. That group holds the version digit and 12 bits of a counter that uniku seeds with random bytes every millisecond, so the stored values stop following creation time.
Use UUID_TO_BIN(id) without the flag, or bind uuidv7.toBytes(id) directly. Both store the same 16 bytes. A table that already uses the flag must also read with BIN_TO_UUID(col, 1), because the flags have to match in both directions.
Random UUID v4 primary keys
UUID v4 is a poor fit for an InnoDB primary key. Each insert lands at a random position in the clustered index, so InnoDB splits pages across the whole index instead of appending to the last one. The MySQL manual says pages filled in sequential order end up about 15/16 full, and pages filled in random order end up between 1/2 and 15/16 full. Use UUID v7 when the key must be a UUID. Use TSID when a BIGINT column works, since it takes 8 bytes.
An ID derived from something you already have
Every other generator creates a new value on each call. Sometimes you need the opposite: an ID that is a pure function of an identifier you already hold, such as a session ID issued by a third-party tool. The same input must give the same output in another process, on another machine, or after a reinstall, with no lookup table to keep.
UUID v5 does this. It hashes a namespace and a name, so the function is the table:
import { uuidv5 } from 'uniku/uuid/v5'
// Generated once with uuidv4(), then hard-coded and never changed.
const SESSION_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'
const sessionId = uuidv5.namespace(SESSION_NAMESPACE)
sessionId('tool-a:3f2c') // the same UUID in every processA UUID v5 has no timestamp and no useful order, and it is an identifier, not a secret: anyone who knows the name and namespace can compute it. See UUID v5 for namespaces, composing inputs, and string encoding.
Time ordering is local
UUID v7, ULID, ObjectID, XID, and TSID carry time information. uniku keeps the state required for monotonic sequencing inside one JavaScript isolate; it does not coordinate clocks or sequences between processes or machines.
Time order leaks creation time
UUID v7, ULID, KSUID, ObjectID, XID, and TSID embed a creation timestamp in the identifier itself. Anyone who can read the ID can decode when the record was created, not just its order relative to other records. That is a feature for index locality and a leak if the ID is public and the creation time is sensitive, for example a document, invoice, or account that should not reveal how old it is. If the identifier is exposed outside your system and creation time must stay private, use UUID v4, CUID v2, or Nanoid instead: none of them encode a timestamp.