Introduction to PostgreSQL uuid Data Type

The PostgreSQL uuid data type stores 128-bit UUID values, also known as GUIDs. UUIDs are useful when identifiers are created in separate services or databases before records are combined. Properly generated UUIDs have a very low probability of collision, but the uuid type does not enforce uniqueness by itself. Add a PRIMARY KEY or UNIQUE constraint when duplicate values must be rejected in a table.

Syntax

In PostgreSQL, the uuid data type is used when creating columns or variables of type uuid. The following is an example SQL statement for creating a uuid column:

CREATE TABLE users (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL
);

Use Cases

The uuid data type is particularly useful in the following scenarios:

• When identifiers need to be generated independently in multiple systems and later combined.
• When unique identifiers are needed in a distributed system.
• When synchronizing data across multiple databases to avoid primary key conflicts.

Examples

Example 1

Suppose we want a UUID primary key for each row in a users table. The uuid type stores the identifier, and the PRIMARY KEY constraint rejects duplicates in this table:

CREATE TABLE users (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL
);

We can insert some data into the users table:

INSERT INTO users (id, name, email) VALUES
('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11', 'Alice', '[email protected]'),
('3c8d4435-1612-4125-8443-6031c534c069', 'Bob', '[email protected]'),
('7f9c7985-4e38-4b4e-b16f-02bce67a7f6f', 'Charlie', '[email protected]');

Query the data in the users table:

SELECT * FROM users;

The result is as follows:

 id                 |  name   |        email
--------------------------------------+---------+---------------------
 a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 | Alice   | [email protected]
 3c8d4435-1612-4125-8443-6031c534c069 | Bob     | [email protected]
 7f9c7985-4e38-4b4e-b16f-02bce67a7f6f | Charlie | [email protected]
(3 rows)

Example 2

Suppose each product has an assigned UUID. Create a uuid column and use a PRIMARY KEY constraint to enforce uniqueness within the products table:

CREATE TABLE products (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL,
    price NUMERIC(10,2) NOT NULL
);

We can insert some data into the products table:

INSERT INTO products (id, name, price)
VALUES
    ('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11', 'Product 1', 19.99),
    ('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'Product 2', 29.99),
    ('6ba7b811-9dad-11d1-80b4-00c04fd430c8', 'Product 3', 39.99);

Query the data in the products table:

SELECT * FROM products;

The result is as follows:

 id                |   name    | price
--------------------------------------+-----------+-------
 a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 | Product 1 | 19.99
 6ba7b810-9dad-11d1-80b4-00c04fd430c8 | Product 2 | 29.99
 6ba7b811-9dad-11d1-80b4-00c04fd430c8 | Product 3 | 39.99
(3 rows)

In the above example, the uuid data type stores each product identifier. The primary key constraint prevents duplicate values in this table.

Conclusion

The uuid data type stores UUID values; a primary key or unique constraint enforces uniqueness in a table. PostgreSQL 18 adds native UUIDv7 generation, which embeds time information in the identifier. For generation options and version trade-offs, see our PostgreSQL UUID and UUIDv7 guide. When mapping table schemas with UUID columns to application code, use the SQL to Types Converter to generate TypeScript interfaces, Python Pydantic models (with uuid.UUID), and Go structs.