Postgres 18 UUIDv7 Primary Keys: Practical Guide (2026)

PostgreSQL 18 adds a built-in uuidv7() function, so you can use uuid PRIMARY KEY DEFAULT uuidv7() with no extension. UUIDv7 embeds a millisecond timestamp in its leading bits, so values sort by creation time and behave far more like a sequential key than random UUIDv4.¹²

TL;DR

PostgreSQL 18 (current stable 18.4)³ ships native uuidv7(), uuidv4() (an alias for gen_random_uuid()), and updated uuid_extract_timestamp() / uuid_extract_version() helpers.¹ For a new table, just write id uuid PRIMARY KEY DEFAULT uuidv7(). UUIDv7's time-ordered prefix gives smaller, less-fragmented B-tree indexes than UUIDv4 — in one published benchmark the primary-key index was about 26–27% smaller and ordered scans ran roughly three times faster.² The one real trade-off: a UUIDv7 leaks the row's approximate creation time. Every SQL block below was run against PostgreSQL 18.3 before publishing.

What you'll learn

• Whether PostgreSQL 18 has a native UUIDv7 function and what shipped with it
• How to set uuidv7() as a default primary key with copy-paste DDL
• How UUIDv7 compares to UUIDv4 on index size, fragmentation, and speed
• When to choose UUIDv7 over a plain bigint identity column
• How to migrate an existing UUIDv4 table to UUIDv7 without losing order
• How to read the creation time back out of a UUIDv7
• Why a UUIDv7 leaks creation time and how to mitigate it

Does PostgreSQL 18 have a built-in UUIDv7 function?

Yes. PostgreSQL 18 added uuidv7() as a core function — no uuid-ossp or pgcrypto extension required.¹ It generates a version 7 (time-ordered) UUID per RFC 9562, with the timestamp built from a UNIX millisecond value plus a sub-millisecond fraction plus random bits.¹

The same release rounded out the UUID toolbox. gen_random_uuid() (version 4, fully random) is still there, and uuidv4() was added as a built-in alias for it so the naming matches uuidv7().¹ Two extraction helpers were updated to understand v7: uuid_extract_version(uuid) returns the version number, and uuid_extract_timestamp(uuid) returns a timestamp with time zone for version 1 or 7 UUIDs (and null for others).¹

SELECT
  uuid_extract_version(gen_random_uuid()) AS v4,  -- 4
  uuid_extract_version(uuidv7())          AS v7;  -- 7

UUIDv7 was added natively in 18; on PostgreSQL 17 and earlier you still need an extension or application-side library to generate it.¹

How do I use uuidv7() as a default primary key?

Set the column default to uuidv7(). Because the function runs server-side on every insert, you never touch the id in application code:

CREATE TABLE invoices (
    id         uuid PRIMARY KEY DEFAULT uuidv7(),
    amount     numeric,
    created_at timestamptz NOT NULL DEFAULT now()
);

INSERT INTO invoices (amount)
SELECT g FROM generate_series(1, 5) AS g;

SELECT id, amount FROM invoices ORDER BY id;

Run against PostgreSQL 18.3, the rows come back in insertion order because the IDs are monotonic:

                  id                  | amount
--------------------------------------+--------
 019ed46f-1d7f-7000-9fd1-6978e2d1412f |      1
 019ed46f-1d7f-7001-924f-a07704cd74c2 |      2
 019ed46f-1d7f-7002-817a-caaa62db219e |      3
 019ed46f-1d7f-7003-b9c9-fc99d1d64969 |      4
 019ed46f-1d7f-7004-abf1-966ff34e4974 |      5

That ordering is not luck. PostgreSQL stores a 12-bit sub-millisecond fraction right after the 48-bit timestamp and uses the RFC 9562 "replace leftmost random bits with increased clock precision" method, which guarantees monotonically increasing values for every UUIDv7 generated within the same session (backend process). Ordering is not guaranteed across different backends.⁴

Is UUIDv7 better than UUIDv4 for primary keys?

For index health, yes — and that is the whole point. UUIDv4 is random, so each insert lands at a random spot in the primary-key B-tree, causing page splits, low page density, and fragmentation. UUIDv7 inserts land at the right-hand edge of the index, like a sequential key.

A detailed PostgreSQL 18 benchmark by credativ (1M and 50M rows) measured the difference on real on-disk structures:²

In that same test, inserting 50M rows into an empty table took about 20 minutes for UUIDv4 versus under 2 minutes for UUIDv7, and the gap widened on a second batch.² Exact numbers depend on hardware, caching, and workload, but the direction is consistent: the time-ordered prefix keeps the index compact and inserts cheap. Note that the heap table size is identical — a UUID is 16 bytes either way; only the index layout changes.²

UUIDv7 vs bigint: which primary key should you use?

Use a bigint identity column when you are on a single node and want the smallest, simplest key; use UUIDv7 when you need globally unique, client- or distributed-generatable IDs without giving up index locality.⁵

A bigint is 8 bytes against a UUID's 16, so a bigint index entry is half the size — and because that key is copied into every secondary index and foreign key, the saving compounds across a schema — while a signed bigint still counts to about 9.2 × 10¹⁸ before overflowing.² What bigint sequences cannot do is let many writers (microservices, mobile clients, sharded nodes) mint non-colliding keys independently, or hide the table's row count — a sequence value is guessable and reveals volume.⁵

UUIDv7 is the middle ground: it keeps the enormous 128-bit keyspace and distributed-generation property of UUIDs, while its index behaves close to a sequential bigint instead of the random mess UUIDv4 produces.² For a brand-new single-server CRUD app, bigint identity is still a perfectly good default. The moment you anticipate distributed writes, data merges, or exposing IDs across services, UUIDv7 is the stronger primary key.

How do I migrate an existing UUIDv4 table to UUIDv7?

Changing a live primary key is a heavy operation — you add a new column, backfill it, then move constraints and foreign keys over — so plan it like any schema migration. The mechanical part is adding a v7 column that defaults uuidv7() for new rows and backfilling old rows in a way that preserves their original order:

-- New rows get a real UUIDv7; existing rows are filled next.
ALTER TABLE legacy
  ADD COLUMN id_v7 uuid NOT NULL DEFAULT uuidv7();

-- Backfill old rows so the embedded timestamp matches each row's created_at.
UPDATE legacy
SET id_v7 = uuidv7(created_at - now());

The key detail is the uuidv7(shift interval) argument. uuidv7() with no argument embeds the current time; the optional shift offsets that time by an interval.¹ To make a backfilled UUID carry a row's original created_at, the shift must be created_at - now(). Verified against PostgreSQL 18.3, the round-trip is exact to the millisecond:

SELECT created_at,
       uuid_extract_timestamp(uuidv7(created_at - now())) AS embedded
FROM legacy ORDER BY created_at;

       created_at       |        embedded
------------------------+------------------------
 2024-03-01 12:00:00+00 | 2024-03-01 12:00:00+00
 2024-06-15 08:30:00+00 | 2024-06-15 08:30:00+00
 2025-01-20 23:15:00+00 | 2025-01-20 23:15:00+00

Watch out for a formula copied around the web: uuidv7((created_at - '2025-01-01')::interval). It looks plausible but does not embed created_at — it offsets now by the distance from a fixed anchor date, landing the timestamp years away from the real value. The same verified run shows a 2024-03-01 row coming back as 2025-08-15. Always shift relative to now(). Also remember that any backfilled ID is synthetic: it reproduces ordering, not the genuine generation instant, which never existed for those legacy rows.

Can I extract the creation time from a UUIDv7?

Yes — uuid_extract_timestamp() reads the embedded timestamp back out as a timestamp with time zone:

SELECT id, uuid_extract_timestamp(id) AS created_at_from_uuid
FROM invoices ORDER BY id LIMIT 1;

For a version 4 UUID the same function returns null, because there is no timestamp to recover.¹ The docs note the extracted value "is not necessarily exactly equal to the time the UUID was generated" — it reflects whatever the generator wrote — but for Postgres's own uuidv7() it is the insert-time clock reading.¹ This makes UUIDv7 handy for keyset pagination, log correlation, and time-series style scans where the key itself tells you roughly when a row was created.²

Does a UUIDv7 leak the row's creation time?

Yes, and it is the one caveat worth designing around. Because the leading 48 bits are a readable millisecond timestamp, anyone holding a UUIDv7 can call uuid_extract_timestamp() (or decode it client-side) to learn approximately when the row was created — and, across several IDs, infer your creation rate.² For many internal tables that is harmless or even useful; for a public-facing identifier it can expose business signals like sign-up timing or order volume.

The common mitigation is to keep UUIDv7 as the internal primary key and expose a separate, fully random UUIDv4 (gen_random_uuid()) as the public-facing identifier, so external parties never see the time-ordered value.⁵ If even an internal timestamp is sensitive, the shift argument lets you offset the embedded time by a constant to obscure the true creation date — at the cost of the timestamp no longer being meaningful.¹

Bottom line and next steps

PostgreSQL 18's native uuidv7() finally makes time-ordered UUID primary keys a one-line default with no extensions, giving you UUID's distributed-friendly keyspace with index behavior close to a bigint.¹² Reach for it when you need globally unique or client-generated IDs; stick with bigint identity when a single-node app just needs the smallest key; and isolate the timestamp leak behind a separate public ID when creation time is sensitive.

Because UUIDv7 keys are naturally ordered, they pair perfectly with keyset (cursor) pagination in Postgres, which depends on a sortable key. If you are moving to PostgreSQL 18 to get uuidv7(), see the zero-downtime Postgres 18 upgrade guide, and once you are there, pg_partman + pg_cron partition automation on Postgres 18 works hand-in-hand with time-ordered keys for large tables.