UUID Best Practices: v4, v7, and When to Use Them

Version quick reference

UUID v4: Random

UUID v4 is mostly random (122 bits). No timestamp, no hardware info. It is simple and good for most cases: primary keys, file IDs, correlation IDs. Our UUID Generator produces v4. Collision risk is negligible for normal workloads.

// Node.js
crypto.randomUUID()
// "f47ac10b-58cc-4372-a567-0e02b2c3d479"

UUID v1: Timestamp + MAC

v1 includes a timestamp and MAC address. Sortable by time, but exposes hardware and can leak creation time. Prefer v4 unless you specifically need time ordering and accept the privacy trade-off.

UUID v7: Time-Ordered

v7 embeds a timestamp in the high bits, so UUIDs are roughly time-ordered. Better for database indexing than v4: inserts cluster and B-tree indexes perform well. Use v7 when you need sortable, unique IDs and can use a library that supports it.

UUID or auto-increment?

Auto-increment IDs are smaller and can be faster in a single-database setup. UUIDs shine when you need distributed ID generation or you plan to expose IDs publicly.

• Choose UUIDs when: multi-region writes, offline generation, merging data from multiple sources, public IDs in APIs.
• Choose auto-increment when: single DB, strictly internal IDs, you want compact indexes, and you do not need distributed ID generation.

Database Indexing

Random UUIDs (v4) cause scattered inserts, which can fragment B-tree indexes. If insert order matters for performance, use v7 or ULID. For read-heavy or smaller tables, v4 is usually fine.

PostgreSQL example

For PostgreSQL, pgcrypto provides gen_random_uuid() which is suitable for v4 IDs.

-- PostgreSQL (pgcrypto extension)
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- Default UUID primary key
CREATE TABLE items (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  name text NOT NULL
);

ULID vs UUID v7

Both ULID and UUID v7 are time-sortable. ULID uses Crockford Base32 and is often shorter in URLs. UUID v7 stays in the standard UUID format and integrates cleanly with systems expecting UUIDs. If you want time ordering for DB locality, either can work; pick what your ecosystem supports best.

UUIDs Are Not Secrets

UUIDs are unique, not unguessable. Do not use them as sole secrets for tokens or API keys. Use cryptographically secure random bytes (e.g. 256 bits) and encode as hex or Base64 for secrets. UUID v4 is fine for public IDs (e.g. in URLs) where you only need uniqueness.

UUIDs in URLs: do's and don'ts

• Do: use UUIDs as public resource identifiers (e.g. /users/{uuid}) when you want uniqueness without exposing internal counts.
• Do: validate format server-side before using as a lookup key.
• Don't: treat a UUID as authorization. You still need access control.
• Don't: use UUIDs as secrets (tokens, API keys). Use longer random secrets.

Formats

Standard format is 8-4-4-4-12 hex with hyphens. Some systems use no hyphens or uppercase. Our generator supports lowercase, UPPERCASE, and no-hyphens. Pick one format and stick to it in your system.

Format normalization checklist

• Store a canonical format (commonly lowercase with hyphens)
• Normalize at boundaries (API input/output), not deep in business logic
• Do not compare UUIDs as case-sensitive strings if your system allows mixed casing