UUID v7 Generator

What is UUID v7?

UUID v7 is a next-generation UUID format standardised in RFC 9562 (May 2024). It encodes a 48-bit Unix millisecond timestamp in the most-significant bits, followed by version and variant markers, and fills the remaining bits with cryptographically secure random data.

Because the timestamp occupies the high bits, UUID v7 values sort chronologically — both lexicographically and numerically. This makes them an excellent fit for database primary keys, where random UUIDs (v4) cause B-tree index fragmentation.

Why Random UUIDs Fragment Database Indexes

B-tree indexes — used by PostgreSQL, MySQL, SQLite, and most other databases — keep rows sorted by key value. When you insert a new row, the database must place it in the correct sorted position within the index.

With UUID v4 (fully random), each new insert lands at an essentially random position in the index tree. This forces the database to read and rewrite internal index pages constantly, splitting full pages and leaving others half-empty. The result is a fragmented, bloated index that slows both writes and reads as the table grows.

UUID v7 Bit Layout

UUID v7 is 128 bits wide, divided into six fields:

The timestamp precision is 1 millisecond. Within the same millisecond, UUID v7 values are ordered by their random suffix — they are not guaranteed to be monotonically increasing sub-millisecond, but they are k-sortable: IDs generated close together in time will sort close together in the index.

UUID v7 vs UUID v1

Both UUID v1 and UUID v7 embed a timestamp, but they differ significantly in design:

For any new project that needs time-ordered UUIDs, prefer UUID v7 over UUID v1. UUID v1 is legacy and leaks host information.

UUID v7 vs ULID

ULID (Universally Unique Lexicographically Sortable Identifier) solves a similar problem to UUID v7. Here is how they compare:

If you are already in a UUID ecosystem (PostgreSQL uuid column, REST APIs returning UUIDs), use UUID v7. If you are starting fresh and prefer a more human-friendly encoding, ULID is a reasonable alternative.

Using UUID v7 in Databases

UUID v7 is not yet natively generated by most databases, but it can be stored in standard UUID columns and generated in application code or via extensions:

Code Examples

UUID v7 is not yet available via crypto.randomUUID(). Use a library such as uuidv7 (npm) until native support arrives:

function generateUuidV7() {
  const buf = new Uint8Array(16)
  crypto.getRandomValues(buf)

  const ms = BigInt(Date.now())

  // Embed 48-bit Unix ms timestamp
  buf[0] = Number((ms >> 40n) & 0xFFn)
  buf[1] = Number((ms >> 32n) & 0xFFn)
  buf[2] = Number((ms >> 24n) & 0xFFn)
  buf[3] = Number((ms >> 16n) & 0xFFn)
  buf[4] = Number((ms >> 8n)  & 0xFFn)
  buf[5] = Number(ms & 0xFFn)

  // Set version 7 (0111xxxx)
  buf[6] = (buf[6] & 0x0F) | 0x70

  // Set variant (10xxxxxx)
  buf[8] = (buf[8] & 0x3F) | 0x80

  const hex = [...buf].map(b => b.toString(16).padStart(2, '0')).join('')
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}`
}

// Node.js 20+ built-in
// import { randomUUID } from 'node:crypto'  // v4 only — no v7 yet in stdlib

# pip install uuid7
import uuid_extensions

uid = uuid_extensions.uuid7()
print(uid)                       # e.g. 018e2b3d-1a2b-7000-8000-abc123456789
print(uid.time)                  # Unix ms timestamp embedded in the UUID

# Or as a plain string
from uuid_extensions import uuid7str
print(uuid7str())

-- PostgreSQL 13+ extension-free implementation
CREATE OR REPLACE FUNCTION uuid_generate_v7()
RETURNS uuid
LANGUAGE sql
AS $$
  SELECT encode(
    set_bit(
      set_bit(
        overlay(
          uuid_send(gen_random_uuid())
          PLACING substring(int8send(floor(extract(epoch FROM clock_timestamp()) * 1000)::bigint) FROM 3)
          FROM 1 FOR 6
        ),
        52, 1
      ),
      53, 1
    ),
    'hex'
  )::uuid;
$$;

-- Usage as a default primary key
CREATE TABLE events (
  id uuid PRIMARY KEY DEFAULT uuid_generate_v7(),
  payload jsonb,
  created_at timestamptz DEFAULT now()
);

function extractTimestamp(uuid: string): Date {
  const hex = uuid.replace(/-/g, '')
  const ms = parseInt(hex.slice(0, 12), 16)  // first 48 bits = ms timestamp
  return new Date(ms)
}

const uid = '018e2b3d-1a2b-7000-8000-abc123456789'
console.log(extractTimestamp(uid).toISOString())
// → "2024-03-15T10:22:05.259Z"

Frequently Asked Questions