UUID v7 for New Databases: Performance, Trade-offs, and Migration

By BoltQuickTools team · May 18, 2026 · Updated November 8, 2026 · 7 min read

RFC 9562, published in May 2024, standardized UUID version 7, an ID that starts with a millisecond timestamp. PostgreSQL 18 ships a built-in uuidv7() function, MariaDB has UUID_v7() from version 11.7, and .NET 9 added Guid.CreateVersion7(). At the time of this update MySQL has no native v7 function, so you generate the value in your application or install a community component. This post covers what v7 improves, what it gives up, and when to leave existing v4 keys alone.

The performance problem v7 solves

In UUID v4, 122 of the 128 bits are random, so new values have no relationship to each other or to time.

Used as a primary key, that randomness means each insert lands at an unpredictable position in the index. MySQL InnoDB stores the rows themselves in primary key order. PostgreSQL keeps rows in a separate heap, but its B-tree index has the same placement problem. Inserts remain O(log n) in comparisons. The cost shows up in I/O: writes touch pages all over the index, far fewer of those pages stay in memory once the index outgrows the buffer pool, and random page splits leave pages less full, so the index gets bigger.

How much this matters depends on row width, hardware, and how much of the index fits in memory. A table that fits comfortably in memory may show little difference, so test with your own schema. On PostgreSQL 18 the comparison is short:

CREATE TABLE t_v4 (id uuid PRIMARY KEY DEFAULT gen_random_uuid(), payload text);
    CREATE TABLE t_v7 (id uuid PRIMARY KEY DEFAULT uuidv7(), payload text);

    \timing on
    INSERT INTO t_v4 (payload) SELECT 'x' FROM generate_series(1, 5000000);
    INSERT INTO t_v7 (payload) SELECT 'x' FROM generate_series(1, 5000000);

    SELECT pg_size_pretty(pg_relation_size('t_v4_pkey')) AS v4_index,
           pg_size_pretty(pg_relation_size('t_v7_pkey')) AS v7_index;

Use a row count large enough that the index exceeds shared_buffers, or the difference will be hidden.

v7 addresses this by putting a millisecond timestamp in the first 48 bits. New values sort after older ones, so inserts cluster at the right edge of the index and the recently written pages stay in cache.

One exception to check: SQL Server compares uniqueidentifier values with the last six bytes as most significant, so a v7 stored in that type does not sort by time. A clustered index there will not get this benefit from v7 as is.

The v7 byte layout

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           unix_ts_ms                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          unix_ts_ms           |  ver  |       rand_a          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                        rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Reading from the top: 48 bits of millisecond Unix timestamp, 4 bits of version (0111 = 7), 12 bits of random, 2 bits of variant (10), 62 bits of random. Total 128 bits = 16 bytes = the same size as v4.

The timestamp is big-endian, so byte order matches chronological order. A v7 UUID generated at noon sorts before one generated at 1 p.m. without parsing, as long as your database compares the bytes in order.

What the timestamp leaks

A v7 UUID reveals approximately when it was created. For internal keys this is usually fine. For IDs visible in URLs, it discloses information.

If you publish /users/{uuid_v7}, anyone who sees those URLs can read each account's creation time, sort accounts by age, and correlate signups with public events. The random bits still make guessing another valid ID impractical; what leaks is the time.

If that matters for your product, keep v7 for internal keys and expose a separate public_id column holding a v4 or NanoID value. Do not use any UUID as a password reset token or other secret. RFC 9562 warns against assuming UUIDs are hard to guess, so generate a dedicated random token for those.

Migrating an existing database

You usually do not migrate. Existing v4 keys stay v4 forever; they would not magically perform better if rewritten. v7 is for new tables and new records.

If you have measured that key performance is your bottleneck and need to convert a v4-keyed table, the path is:

  1. Add a new id_v7 UUID column.
  2. Populate it with v7 UUIDs derived from each row's created_at value. On PostgreSQL 18, uuidv7(created_at - clock_timestamp()) shifts the embedded time by the given interval.
  3. Add a matching column to every referencing table, backfill it with a join, and move the foreign keys over.
  4. Swap the primary key from id_v4 to id_v7.
  5. Drop the old id_v4 column once nothing references it.

This touches every referencing table and any external system that stores the old IDs, so plan it like any other primary key change. Keeping v4 on legacy tables and using v7 on new ones is usually enough.

UUIDv7 in code

Support varies by language and version:

-- PostgreSQL 18+
    INSERT INTO events (id, ...) VALUES (uuidv7(), ...);

    // JavaScript: crypto.randomUUID() is v4 only, so use the uuid package
    import { v7 } from 'uuid';
    const id = v7();

    # Python 3.14+
    import uuid
    new_id = uuid.uuid7()

    // Go: github.com/google/uuid
    id, err := uuid.NewV7()

    // Rust: uuid crate with the "v7" feature enabled
    let id = Uuid::now_v7();

    // .NET 9+
    var id = Guid.CreateVersion7();

    // Java 26+
    UUID id = UUID.ofEpochMillis(System.currentTimeMillis());

Go has an accepted proposal for a standard library UUID package, so check the release notes for your Go version before adding a dependency.

If your language has no v7 generator, a minimal one is short. The UUID generator does it in about a dozen lines of JavaScript: write Date.now() into the first 48 bits, fill the rest from crypto.getRandomValues(), then set the version and variant bits.

Common questions

Does v7 work in distributed systems?

Yes, with caveats. Two machines generating IDs in the same millisecond produce values whose relative order is decided by the random bits, so it is arbitrary. The same applies to one process unless its generator uses one of the monotonic counter methods RFC 9562 describes, and libraries differ on this. Timestamp-based IDs give approximate ordering. If you need a strict total order across machines, take it from a single sequencer such as a database sequence or a log offset.

What about clock skew?

v7 values sort by each generator's clock, not by true generation order. If two machines disagree by a few milliseconds, IDs created in that window can interleave out of order. NTP keeps well-configured servers close, but not identical. If a machine's clock jumps, its IDs can sort far from their real position, so monitor clock sync on hosts that generate keys.

What about UUIDv6?

RFC 9562 defines v6 too. It is v1 with the timestamp bits reordered so values sort by time. The RFC recommends v7 over v1 and v6 for new systems; v6 is mainly useful if you have existing v1 data and want sortable IDs without changing how they are generated.

What about ULID, KSUID, Snowflake?

All solve similar problems and predate the RFC. ULID and KSUID are sortable identifiers with their own encodings, and Snowflake-style IDs fit in 64 bits, which v7 cannot match. For new code with no existing ecosystem to match, v7 has the advantage of being a standard format with native database support in several engines.

Quick recommendation

Related