🧭 Introduction
With PostgreSQL 18 introducing native uuidv7(), time-ordered UUIDs are finally going mainstream.
But if you’re running YugabyteDB (or older PostgreSQL versions)… you don’t have to wait.
In this tip, we’ll walk through how to install the pg_uuidv7 extension in YugabyteDB… the fastest way to start using time-ordered UUIDs today.
pg_uuidv7 extension is a third-party project and is not officially supported by YugabyteDB at this time.Use it at your own risk, and be sure to validate it thoroughly in your environment before using it in production.
If official support for UUIDv7 is added in YugabyteDB (or upstream PostgreSQL compatibility improves), this post will be updated accordingly.
🛠️ Step-by-Step: Install pg_uuidv7 on YugabyteDB
1️⃣ Use YugabyteDB’s PostgreSQL Toolchain
export PATH=$PATH:/root/yugabyte-2025.2.2.0/postgres/bin
✔ Ensures pg_config and build tools point to YugabyteDB
2️⃣ Clone the Extension
git clone https://github.com/fboulnois/pg_uuidv7.git
cd pg_uuidv7
3️⃣ Build the Extension (Default Behavior)
make
sudo make install
⚠️ This compiles against system PostgreSQL (expected)
4️⃣ Copy Files into YugabyteDB
This is the key step.
# Copy shared library
cp /usr/lib64/pgsql/pg_uuidv7.so \
/root/yugabyte-2025.2.2.0/postgres/lib/
# Copy control file
cp pg_uuidv7.control \
/root/yugabyte-2025.2.2.0/postgres/share/extension/
# Copy SQL definition
cp sql/pg_uuidv7--1.7.sql \
/root/yugabyte-2025.2.2.0/postgres/share/extension/
Each node runs its own YSQL process, and extensions are loaded locally from disk… not shared across the cluster.
5️⃣ Fix Permissions
chmod 755 /root/yugabyte-2025.2.2.0/postgres/lib/pg_uuidv7.so
chmod 644 /root/yugabyte-2025.2.2.0/postgres/share/extension/pg_uuidv7*
6️⃣ Enable the Extension
CREATE EXTENSION pg_uuidv7;
7️⃣ Test It
SELECT uuid_generate_v7();
Example output:
019d3eb8-8355-79df-854a-43563ef02b0a
✔ You now have UUIDv7 running in YugabyteDB today
🔎 What Functions are Created by this Extension?
The List Functions Created by an Extension YugabyteDB Tip demonstrates how to view the functions added by an extension after installation:
SELECT e.extname, ne.nspname AS extschema, p.proname, np.nspname AS proschema
FROM pg_catalog.pg_extension AS e
INNER JOIN pg_catalog.pg_depend AS d ON (d.refobjid = e.oid)
INNER JOIN pg_catalog.pg_proc AS p ON (p.oid = d.objid)
INNER JOIN pg_catalog.pg_namespace AS ne ON (ne.oid = e.extnamespace)
INNER JOIN pg_catalog.pg_namespace AS np ON (np.oid = p.pronamespace)
WHERE d.deptype = 'e'
AND e.extname = 'pg_uuidv7'
ORDER BY 1, 3;
Example output:
. extname | extschema | proname | proschema
-----------+-----------+------------------------+-----------
pg_uuidv7 | public | uuid_generate_v7 | public
pg_uuidv7 | public | uuid_timestamp_to_v7 | public
pg_uuidv7 | public | uuid_timestamptz_to_v7 | public
pg_uuidv7 | public | uuid_v7_to_timestamp | public
pg_uuidv7 | public | uuid_v7_to_timestamptz | public
(5 rows)
🧪 Demo: UUIDv7 via Extension Default
In the original version of this tip, Generate UUIDv7 in YSQL with Better Write Efficiency, we used a custom YSQL function to generate UUIDv7 values.
Now that pg_uuidv7 is installed, we can simplify the demo and use the extension’s function directly in the table definition.
That gives us cleaner DDL while preserving the same batching-friendly write behavior.
DROP TABLE IF EXISTS test_uuid7;
CREATE TABLE test_uuid7 (
id uuid NOT NULL DEFAULT uuid_generate_v7(),
payload text,
PRIMARY KEY (id HASH)
);
Now let’s insert a small batch of rows.
This time, instead of Santa’s reindeer, we’ll use the Seven Dwarfs:
EXPLAIN (ANALYZE, DIST)
INSERT INTO test_uuid7(payload) VALUES
('Doc'),
('Grumpy'),
('Happy'),
('Sleepy'),
('Bashful'),
('Sneezy'),
('Dopey');
And here is the result:
Insert on test_uuid7 (cost=0.00..0.11 rows=0 width=0) (actual time=2.239..2.240 rows=0 loops=1)
-> Values Scan on "*VALUES*" (cost=0.00..0.11 rows=7 width=48) (actual time=0.042..0.068 rows=7 loops=1)
Storage Table Write Requests: 7
Planning Time: 0.066 ms
Execution Time: 4.139 ms
Storage Read Requests: 0
Storage Read Ops: 0
Storage Rows Scanned: 0
Catalog Read Requests: 6
Catalog Read Execution Time: 3.130 ms
Catalog Read Ops: 6
Catalog Write Requests: 0
Storage Write Requests: 7
Storage Flush Requests: 1
Storage Flush Execution Time: 1.785 ms
Storage Execution Time: 4.915 ms
Peak Memory Usage: 64 kB
What to Notice
The key line is:
Storage Flush Requests: 1
That tells us YugabyteDB is still able to batch the multi-row insert efficiently, even when the UUIDv7 values are generated by the extension function in the column default.
So the extension-based approach gives us the same important result as the improved custom-function version:
- ● one write per row
- ● but only one flush for the batch
That is exactly what we wanted to preserve.
🧪 Other Options (Quick Mention)
There are a few alternatives:
- ● Generate UUIDv7 in your application (most portable)
- ● Use custom SQL functions
- ● Wait for PostgreSQL 18 native support
⚡ Why UUIDv7 Matters in YugabyteDB (Final Takeaway)
UUIDv7 isn’t just a new identifier format… it’s a performance optimization for distributed databases like YugabyteDB.
Because it is time-ordered, UUIDv7 improves:
- ● Insert locality
- ● Index efficiency
- ● LSM compaction behavior
- ● Write throughput
In contrast, UUIDv4 introduces randomness that can:
- ● Scatter writes across tablets
- ● Increase compaction pressure
- ● Reduce cache and index efficiency
And with the
pg_uuidv7 extension, you can start using it today… no need to wait for PostgreSQL 18.Have Fun!
