Spring Boot JPA and Hibernate

  application.yml (url, username, password)
            |
            v
  DataSource            connection pool (HikariCP)
            |
            v
  EntityManagerFactory  Hibernate, configured with your entities
            |
            v
  JpaTransactionManager makes @Transactional work
            |
            v
  Repositories and EntityManager injected into your beans

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/shop
    username: shop_user
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate          # see section 15
    open-in-view: false
    properties:
      hibernate:
        format_sql: true
        jdbc:
          batch_size: 50          # see section 17

package com.example.shop.product;

import java.math.BigDecimal;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Entity
@Table(name = "products")
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 120)
    private String name;

    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal price;

    private int stock;

    protected Product() {
        // required by JPA
    }

    public Product(String name, BigDecimal price, int stock) {
        this.name = name;
        this.price = price;
        this.stock = stock;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public BigDecimal getPrice() { return price; }
    public int getStock() { return stock; }

    public void changePrice(BigDecimal newPrice) { this.price = newPrice; }
    public void reduceStock(int quantity) { this.stock -= quantity; }
}

CREATE TABLE products (
    id     BIGSERIAL PRIMARY KEY,
    name   VARCHAR(120)   NOT NULL,
    price  NUMERIC(10, 2) NOT NULL,
    stock  INTEGER        NOT NULL
);

// Sequence: Hibernate reserves 50 IDs per database call
@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "order_seq")
@SequenceGenerator(name = "order_seq", sequenceName = "order_seq", allocationSize = 50)
private Long id;

// UUID: generated in Java, no database round trip
@Id
@GeneratedValue(strategy = GenerationType.UUID)
private UUID id;

@Entity
@Table(name = "customers")
public class Customer {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String fullName;

    @Enumerated(EnumType.STRING)          // store "GOLD", not 0, 1, 2
    @Column(length = 20)
    private CustomerTier tier;

    private LocalDate birthDate;          // DATE column

    private Instant registeredAt;         // TIMESTAMP column

    @Embedded
    private Address address;              // columns stored in the same table

    @Transient
    private int loginCountThisSession;    // not stored at all

    protected Customer() {
    }
}

@Embeddable
public class Address {

    private String street;
    private String city;
    private String postalCode;

    protected Address() {
    }

    public Address(String street, String city, String postalCode) {
        this.street = street;
        this.city = city;
        this.postalCode = postalCode;
    }
}

  categories                products
  ----------                --------------------------
  id  (PK)    <-------      category_id (FK)
  name                      id (PK), name, price, stock

@Entity
@Table(name = "categories")
public class Category {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @OneToMany(mappedBy = "category")          // the other side owns the foreign key
    private List<Product> products = new ArrayList<>();

    protected Category() {
    }

    public void addProduct(Product product) {   // keep both sides in sync
        products.add(product);
        product.setCategory(this);
    }
}

@ManyToOne(fetch = FetchType.LAZY, optional = false)
@JoinColumn(name = "category_id")              // foreign key column in products
private Category category;

void setCategory(Category category) {
    this.category = category;
}

@Entity
@Table(name = "purchase_orders")
public class PurchaseOrder {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();

    public void addItem(Product product, int quantity) {
        items.add(new OrderItem(this, product, quantity));
    }

    public void removeItem(OrderItem item) {
        items.remove(item);              // orphanRemoval deletes the row
    }
}

@Entity
@Table(name = "order_items")
public class OrderItem {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id")
    private PurchaseOrder order;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "product_id")
    private Product product;

    private int quantity;

    protected OrderItem() {
    }

    OrderItem(PurchaseOrder order, Product product, int quantity) {
        this.order = order;
        this.product = product;
        this.quantity = quantity;
    }
}

   new Product(...)                     persist() / save()
   TRANSIENT  --------------------------------------------->  MANAGED
   (not known to Hibernate)                                  (tracked; changes saved at commit)
                                                               |        |
                                       transaction ends /      |        |  remove() / delete()
                                       clear() / detach()      v        v
                                                         DETACHED      REMOVED
                                         (has an ID but no longer tracked)  (deleted at commit)

@Service
public class PricingService {

    private final ProductRepository productRepository;

    public PricingService(ProductRepository productRepository) {
        this.productRepository = productRepository;
    }

    @Transactional
    public void applyDiscount(Long productId, BigDecimal percent) {
        Product product = productRepository.findById(productId).orElseThrow();   // MANAGED

        BigDecimal factor = BigDecimal.ONE.subtract(percent.movePointLeft(2));
        product.changePrice(product.getPrice().multiply(factor));

        // No save() call: Hibernate notices the change and runs UPDATE at commit
    }
}

@Repository
public class ProductReportDao {

    @PersistenceContext
    private EntityManager entityManager;

    @Transactional(readOnly = true)
    public List<Product> findLowStock(int threshold) {
        return entityManager
                .createQuery("SELECT p FROM Product p WHERE p.stock < :threshold ORDER BY p.stock", Product.class)
                .setParameter("threshold", threshold)
                .setMaxResults(20)
                .getResultList();
    }

    @Transactional
    public void archive(Long productId) {
        Product product = entityManager.find(Product.class, productId);
        if (product != null) {
            entityManager.remove(product);
        }
    }
}

// Filter and sort
"SELECT p FROM Product p WHERE p.price BETWEEN :min AND :max ORDER BY p.price"

// Navigate a relationship (an implicit join)
"SELECT p FROM Product p WHERE p.category.name = :categoryName"

// Aggregate into a DTO record
"SELECT new com.example.shop.product.CategoryStats(c.name, COUNT(p), AVG(p.price)) "
        + "FROM Product p JOIN p.category c GROUP BY c.name"

// Load an order with its items in one query
"SELECT o FROM PurchaseOrder o JOIN FETCH o.items WHERE o.id = :id"

package com.example.shop.product;

public record CategoryStats(String category, Long productCount, Double averagePrice) {
}

List<PurchaseOrder> orders = orderRepository.findAll();      // 1 query

for (PurchaseOrder order : orders) {
    System.out.println(order.getItems().size());             // 1 query per order
}
// 100 orders = 101 queries

public interface OrderRepository extends JpaRepository<PurchaseOrder, Long> {

    @EntityGraph(attributePaths = "items")
    List<PurchaseOrder> findByCustomerId(Long customerId);   // orders and items in one query
}

@Entity
public class Product {

    // ... other fields

    @Version
    private Long version;
}

@ExceptionHandler(ObjectOptimisticLockingFailureException.class)
@ResponseStatus(HttpStatus.CONFLICT)
public String onConflict() {
    return "The product was changed by someone else. Please reload and try again.";
}

spring:
  jpa:
    properties:
      hibernate:
        format_sql: true                       # readable, multi-line SQL
        generate_statistics: true              # query counts and timings per session

logging:
  level:
    org.hibernate.SQL: debug                   # every SQL statement
    org.hibernate.orm.jdbc.bind: trace         # the parameter values (Hibernate 6)

DEBUG org.hibernate.SQL :
    select p1_0.id, p1_0.name, p1_0.price, p1_0.stock
    from products p1_0
    where p1_0.id=?
TRACE org.hibernate.orm.jdbc.bind : binding parameter (1:BIGINT) <- [42]

@Transactional
public void importProducts(List<Product> products) {
    for (int i = 0; i < products.size(); i++) {
        entityManager.persist(products.get(i));

        if (i > 0 && i % 50 == 0) {          // same as hibernate.jdbc.batch_size
            entityManager.flush();           // send the batch
            entityManager.clear();           // free memory used by managed entities
        }
    }
}