Spring Boot with JPA and Hibernate is the most common Java stack for production applications. Hibernate 6.2 (shipped with Spring Boot 3.2) added native UUID v7 support via @UuidGenerator(style = TIME) — a single annotation replaces the multi-class IdentifierGenerator boilerplate that UUID v7 required before. See UUID in Java and Spring Boot for the full ecosystem context.
Entity with @UuidGenerator TIME
// Order.java
import jakarta.persistence.*;
import org.hibernate.annotations.UuidGenerator;
import java.util.UUID;
@Entity
@Table(name = "orders")
public class Order {
@Id
@UuidGenerator(style = UuidGenerator.Style.TIME) // UUID v7 — Hibernate 6.2+
@Column(name = "id", updatable = false, nullable = false)
private UUID id;
@Column(nullable = false)
private String status;
@Column(name = "customer_id", nullable = false)
private UUID customerId;
// getters and setters...
}
UuidGenerator.Style.TIME maps to UUID v7 (time-ordered epoch) in Hibernate 6.2+. Earlier versions mapped TIME to UUID v1 — verify your Hibernate version before deploying. See UUID Versions for the v1 vs v7 distinction.
Spring Data JPA repository
// OrderRepository.java
import org.springframework.data.jpa.repository.JpaRepository;
import java.util.UUID;
public interface OrderRepository extends JpaRepository<Order, UUID> {
// Spring Data derives queries from method names — UUID works transparently
List<Order> findByCustomerId(UUID customerId);
}
// OrderService.java
@Service
@RequiredArgsConstructor
public class OrderService {
private final OrderRepository repo;
public Order createOrder(UUID customerId, String status) {
Order order = new Order();
order.setCustomerId(customerId);
order.setStatus(status);
return repo.save(order); // Hibernate assigns UUID v7 before INSERT
}
}
PostgreSQL migration — schema
CREATE TABLE orders (
id uuid PRIMARY KEY, -- stored as 16-byte binary in PG
customer_id uuid NOT NULL,
status varchar(32) NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
);
No special column type is needed — PostgreSQL’s uuid type stores UUID v4 and v7 identically as 16 bytes. ORDER BY id returns rows in UUID v7’s chronological order. See UUID in Databases.
PostgreSQL 18 — server-side generation
Alternatively, delegate generation to PostgreSQL 18:
@Entity
@Table(name = "orders")
public class Order {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY) // use DB default
@Column(name = "id", columnDefinition = "uuid DEFAULT uuidv7()")
private UUID id;
// ...
}
ALTER TABLE orders ALTER COLUMN id SET DEFAULT uuidv7();
The database generates UUID v7 on every INSERT — including raw SQL and migration scripts. See PostgreSQL 18 Ships Native UUID v7.
Older Hibernate — uuid-creator library
For Spring Boot 2.x / Hibernate 5.x:
<!-- pom.xml -->
<dependency>
<groupId>com.github.f4b6a3</groupId>
<artifactId>uuid-creator</artifactId>
<version>5.3.7</version>
</dependency>
import com.github.f4b6a3.uuid.UuidCreator;
import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.id.IdentifierGenerator;
public class UuidV7Generator implements IdentifierGenerator {
@Override
public Object generate(SharedSessionContractImplementor session, Object obj) {
return UuidCreator.getTimeOrderedEpoch(); // UUID v7
}
}
@Entity
public class Order {
@Id
@GenericGenerator(name = "uuid7", type = UuidV7Generator.class)
@GeneratedValue(generator = "uuid7")
private UUID id;
}
Migrating from UUID v4 to v7
No schema migration required — uuid columns store both versions identically. Change only the generator:
// Before (Hibernate 6.2+)
@UuidGenerator(style = UuidGenerator.Style.RANDOM) // UUID v4
// After
@UuidGenerator(style = UuidGenerator.Style.TIME) // UUID v7
Existing rows keep their UUID v4 values. New inserts use v7. See Zero-Downtime UUID Migration for a full backfill strategy.
Further reading
- UUID in Java and Spring Boot
- UUID in Java — full guide
- UUID in Databases — storage and indexing
- PostgreSQL 18 Ships Native UUID v7
- Zero-Downtime UUID Migration
- UUID v4 vs v7 — performance comparison
External references
- Hibernate 6.2 — @UuidGenerator documentation
- uuid-creator — Java UUID v7 library
- RFC 9562 — UUID standard
Frequently asked questions
How do I use UUID v7 as a primary key in Spring Boot with Hibernate?
Add @UuidGenerator(style = UuidGenerator.Style.TIME) on the @Id field in your JPA entity. This requires Hibernate 6.2+ (Spring Boot 3.2+). The TIME style generates UUID v7 (time-ordered epoch) values. For older Hibernate versions, implement IdentifierGenerator manually using the uuid-creator library's UuidCreator.getTimeOrderedEpoch(). See UUID in Java and Spring Boot.
Does Spring Data JPA work with UUID v7 primary keys?
Yes. Declare the entity id field as UUID (java.util.UUID) with @UuidGenerator(style = TIME). Spring Data repositories (JpaRepository<Order, UUID>) work identically for UUID v4 and v7 — the version is transparent to Spring Data's query derivation, pagination, and save/find methods.