Define Unique Key in JPA/Hibernate Entity

In this tutorial, we will demonstrate how to define a unique key in a JPA/Hibernate entity. A unique key ensures that the specified columns contain unique values, preventing duplicate entries.

We will create a simple Hibernate Maven project to demonstrate how to define a unique key in a JPA entity. Note that Hibernate is a popular JPA provider.


  1. Java Development Kit (JDK) 21 or higher: Ensure JDK is installed and configured in your system.
  2. Integrated Development Environment (IDE): IntelliJ IDEA, Eclipse, or any other IDE.
  3. Maven: Ensure Maven is installed and configured in your system.

Step 1: Create a Maven Project

  1. Open your IDE and create a new Maven project.
  2. Update the pom.xml file to include Hibernate and other required dependencies.
<project xmlns=""



  • Hibernate Core Dependency: This includes the main Hibernate framework, which implements JPA.
  • SLF4J Dependencies: Used for logging.
  • H2 Database Dependency: An in-memory database for testing purposes.

Step 2: Create Hibernate Configuration File

Create a file named hibernate.cfg.xml in the src/main/resources directory.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "">
        <property name="hibernate.dialect">org.hibernate.dialect.H2Dialect</property>
        <property name="hibernate.connection.driver_class">org.h2.Driver</property>
        <property name="hibernate.connection.url">jdbc:h2:mem:testdb</property>
        <property name="hibernate.connection.username">sa</property>
        <property name="hibernate.connection.password"></property>
        <property name="">update</property>
        <property name="hibernate.show_sql">true</property>
        <property name="hibernate.format_sql">true</property>


  • Dialect: Specifies the SQL dialect (H2 in this case).
  • Connection Properties: Configure the JDBC connection to the H2 database.
  • Automatically manages the database schema (update existing schema).
  • show_sql: Prints SQL statements to the console.
  • format_sql: Formats SQL statements.

Step 3: Create the Employee Entity Class with a Unique Key

Create a package named com.example.entity and a class named Employee.

package com.example.entity;

import jakarta.persistence.*;

@Table(name = "Employee", uniqueConstraints = {@UniqueConstraint(columnNames = "email")})
public class Employee {
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @Column(nullable = false, unique = true)
    private String email;

    public Employee() {}

    public Employee(String name, String email) { = name; = email;

    public Long getId() {
        return id;

    public void setId(Long id) { = id;

    public String getName() {
        return name;

    public void setName(String name) { = name;

    public String getEmail() {
        return email;

    public void setEmail(String email) { = email;

    public String toString() {
        return "Employee{id=" + id + ", name='" + name + '\'' + ", email='" + email + '\'' + '}';


  • @Table: Specifies the table details and unique constraints.
  • @UniqueConstraint: Defines unique constraints on the table level.
  • @Column: Marks the email column as unique.

Step 4: Create Hibernate Utility Class

Create a package named com.example.util and a class named HibernateUtil.

package com.example.util;

import org.hibernate.SessionFactory;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
import org.hibernate.cfg.Configuration;
import org.hibernate.service.ServiceRegistry;

public class HibernateUtil {
    private static SessionFactory sessionFactory;

    static {
        try {
            Configuration configuration = new Configuration().configure();
            ServiceRegistry serviceRegistry = new StandardServiceRegistryBuilder()
            sessionFactory = configuration.buildSessionFactory(serviceRegistry);
        } catch (Throwable ex) {
            throw new ExceptionInInitializerError(ex);

    public static SessionFactory getSessionFactory() {
        return sessionFactory;


  • Configuration: Loads Hibernate configuration from hibernate.cfg.xml.
  • ServiceRegistry: Builds the service registry from the configuration settings.
  • SessionFactory: Provides sessions to interact with the database.

Step 5: Create Main Class

Create a package named com.example and a class named Main.

package com.example;

import com.example.entity.Employee;
import com.example.util.HibernateUtil;
import org.hibernate.Session;
import org.hibernate.Transaction;

public class Main {
    public static void main(String[] args) {
        // Save a new employee
        Session session = HibernateUtil.getSessionFactory().openSession();
        Transaction transaction = session.beginTransaction();
        Employee employee1 = new Employee("John Doe", "[email protected]");;

        // Try to save another employee with the same email
        session = HibernateUtil.getSessionFactory().openSession();
        transaction = session.beginTransaction();
        try {
            Employee employee2 = new Employee("Jane Doe", "[email protected]");
        } catch (Exception e) {
            System.out.println("Error: " + e.getMessage());
        } finally {

        // Retrieve and display the employee
        session = HibernateUtil.getSessionFactory().openSession();
        Employee retrievedEmployee = session.get(Employee.class, employee1.getId());
        System.out.println("Retrieved Employee: " + retrievedEmployee);

        // Close the SessionFactory


  • Session: Opens a session to interact with the database.
  • Transaction: Begins and commits a transaction for database operations.
  • Save: Persists the entity to the database.
  • Try-Catch Block: Demonstrates handling of unique constraint violation.

Step 6: Run the Application

  1. Run the Main class.
  2. The output in the console should be:
Hibernate: create table Employee (id bigint generated by default as identity, email varchar(255) not null, name varchar(255), primary key (id), unique (email))
Hibernate: insert into Employee (email, name) values (?, ?)
Hibernate: select as id1_0_0_, as email2_0_0_, as name3_0_0_ from Employee employee0_ where
Retrieved Employee: Employee{id=1, name='John Doe', email='[email protected]'}


You have successfully created an example using Hibernate to define a unique key in a JPA/Hibernate entity. This tutorial covered setting up a Maven project, configuring Hibernate, creating an entity class with unique constraints, and handling unique constraint violations during CRUD operations.