Add n-plus-one-guard module: detecting N+1 with Hibernate Statistics vs datasource-proxy, five fixes with statement counts, and a JUnit 6 @MaxSelects guard (Hibernate 7.4.16.Final, datasource-proxy 1.11.1)

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b6R1spapM7nBteaqeo
This commit is contained in:
asmhatre
2026-11-17 00:48:25 +05:30
co-authored by Claude Sonnet 5.5
parent eab5461d86
commit 0db721805b
20 changed files with 851 additions and 0 deletions
+38
View File
@@ -0,0 +1,38 @@
# n-plus-one-guard
Companion module for the ankurm.com article **Catch N+1 Queries Automatically: Hibernate Statistics, datasource-proxy and a JUnit Guard**.
Every statement count and SQL line in the article comes from a test here; each test writes what it observed to `output/` and asserts the same facts.
Plain Hibernate on an in-memory H2: no Spring, no Docker.
## Versions
| Component | Version | Notes |
|---|---|---|
| Hibernate ORM | `7.4.16.Final` | newest 7.x GA in `maven-metadata.xml` on 2026-11-17 (`8.0.0.CR1` is listed after it but is not GA) |
| datasource-proxy | `1.11.1` | `net.ttddyy:datasource-proxy` |
| JUnit | `6.1.3` | Jupiter, plus `junit-platform-testkit` to run the deliberately failing fixture |
| H2 / AssertJ | `2.4.240` / `3.27.7` | |
| Java | `25` (Temurin 25.0.5+8) | |
## Run
```bash
./scripts/run-all.sh # or: mvn clean test
```
## What is where
| File | Role |
|---|---|
| `Author`, `Book` | The entities: lazy `@OneToMany` and lazy `@ManyToOne`; `Author.withBooks` is the entity graph |
| `QueryGuard` | Wraps a `DataSource` with datasource-proxy, counts SELECT/INSERT/UPDATE/DELETE per thread and remembers the SQL |
| `@MaxSelects` + `QueryGuardExtension` | The JUnit extension: a per-test (or per-class) SELECT budget; copy these two files and `QueryGuard` into your own project |
| `Db` | Plain Hibernate bootstrap with the guarded DataSource and `hibernate.generate_statistics=true` |
| Test | Output | Question it answers |
|---|---|---|
| `T01_ReproduceTest` | `output/01-n-plus-one.txt`, `output/02-n-plus-one-to-one.txt` | How many statements does N+1 send, and what do Hibernate Statistics and datasource-proxy each report for it? |
| `T02_FixesTest` | `output/03-fixes.txt`, `output/04-join-fetch-pagination.txt` | What does each fix send, and what does `join fetch` + `setMaxResults` do in Hibernate 7.4? |
| `T03_GuardTest` | `output/05-guard-failure.txt` | What does the guard print when a test regresses? (runs `BrokenFixture` through the JUnit Platform) |
`BrokenFixture` is deliberately failing and is not run by Surefire (its name does not match Surefire's patterns); only `T03_GuardTest` runs it.
+23
View File
@@ -0,0 +1,23 @@
# N+1 on a lazy collection: 10 authors, 3 books each
# Hibernate ORM 7.4.16.Final, datasource-proxy 1.11.1, H2, JDK 25
== Code: one HQL query, then a.getBooks().size() for every author
books counted by the loop : 30
datasource-proxy SELECT count : 11
Hibernate prepareStatementCount : 11
Hibernate queryExecutionCount : 1
Hibernate collectionFetchCount : 10
Hibernate collectionLoadCount : 10
== The statements, in order
sql> select a1_0.id,a1_0.name from Author a1_0
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
@@ -0,0 +1,19 @@
# N+1 on a lazy @ManyToOne: 30 books, 10 distinct authors
# Hibernate ORM 7.4.16.Final, datasource-proxy 1.11.1, H2, JDK 25
== Code: one HQL query for 30 books, then book.getAuthor().getName() for every book
datasource-proxy SELECT count : 11
Hibernate entityFetchCount : 10
== The statements, in order
sql> select b1_0.id,b1_0.author_id,b1_0.title from Book b1_0
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
sql> select a1_0.id,a1_0.name from Author a1_0 where a1_0.id=?
+36
View File
@@ -0,0 +1,36 @@
# Five ways to load 10 authors with their books
# Hibernate ORM 7.4.16.Final, datasource-proxy 1.11.1, H2, JDK 25
== naive loop (lazy collection per author)
sql> select a1_0.id,a1_0.name from Author a1_0
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
== join fetch
sql> select a1_0.id,b1_0.author_id,b1_0.id,b1_0.title,a1_0.name from Author a1_0 join Book b1_0 on a1_0.id=b1_0.author_id
== entity graph (Author.withBooks)
sql> select a1_0.id,b1_0.author_id,b1_0.id,b1_0.title,a1_0.name from Author a1_0 left join Book b1_0 on a1_0.id=b1_0.author_id
== batch fetching, size 5 (session.setFetchBatchSize)
sql> select a1_0.id,a1_0.name from Author a1_0
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id in (?,?,?,?,?)
sql> select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id in (?,?,?,?,?)
== DTO projection (no entities)
sql> select count(b1_0.id) from Book b1_0 group by b1_0.author_id
== SELECT statements for 10 authors x 3 books, same result every time (30 books)
naive loop (lazy collection per author) 11
join fetch 1
entity graph (Author.withBooks) 1
batch fetching, size 5 (session.setFetchBatchSize) 3
DTO projection (no entities) 1
@@ -0,0 +1,5 @@
# join fetch on a collection + setMaxResults(3), 10 authors x 3 books
# Hibernate ORM 7.4.16.Final, datasource-proxy 1.11.1, H2, JDK 25
authors returned: 3, books loaded: 9
SELECT statements: 1
sql> select a1_0.id,b1_0.author_id,b1_0.id,b1_0.title,a1_0.name from (select a1_0.id,a1_0.name from Author a1_0 where exists(select 1 from Book b1_0 where a1_0.id=b1_0.author_id) order by a1_0.id offset ? rows fetch first ? rows only) a1_0(id,name) join Book b1_0 on a1_0.id=b1_0.author_id order by a1_0.id
@@ -0,0 +1,16 @@
# What the guard prints when a test regresses (BrokenFixture, @MaxSelects(2))
# Hibernate ORM 7.4.16.Final, datasource-proxy 1.11.1, H2, JDK 25
== Failure message
listAuthorsWithBookCount(): expected at most 2 SELECT statement(s) but 11 were sent.
1) select a1_0.id,a1_0.name from Author a1_0
2) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
3) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
4) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
5) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
6) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
7) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
8) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
9) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
10) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
11) select b1_0.author_id,b1_0.id,b1_0.title from Book b1_0 where b1_0.author_id=?
+85
View File
@@ -0,0 +1,85 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.ankurm</groupId>
<artifactId>n-plus-one-guard</artifactId>
<version>1.0.0</version>
<name>n-plus-one-guard</name>
<description>Detecting N+1 queries automatically: Hibernate Statistics, datasource-proxy and a JUnit 6 query-count guard (plain Hibernate on H2)</description>
<properties>
<maven.compiler.release>25</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!-- Newest 7.x GA in maven-metadata.xml on 2026-11-17 (8.0.0.CR1 is listed after it, but CR1 is not GA). -->
<hibernate.version>7.4.16.Final</hibernate.version>
<persistence.version>3.2.0</persistence.version>
<junit.version>6.1.3</junit.version>
<datasource-proxy.version>1.11.1</datasource-proxy.version>
</properties>
<dependencies>
<dependency>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-core</artifactId>
<version>${hibernate.version}</version>
</dependency>
<dependency>
<groupId>jakarta.persistence</groupId>
<artifactId>jakarta.persistence-api</artifactId>
<version>${persistence.version}</version>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.4.240</version>
</dependency>
<dependency>
<groupId>net.ttddyy</groupId>
<artifactId>datasource-proxy</artifactId>
<version>${datasource-proxy.version}</version>
</dependency>
<!-- The guard extension lives in src/main so it can be copied into any project as-is. -->
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>${junit.version}</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.platform</groupId>
<artifactId>junit-platform-testkit</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.27.7</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<argLine>-Xmx512m</argLine>
<systemPropertyVariables>
<h.version>${hibernate.version}</h.version>
<dsp.version>${datasource-proxy.version}</dsp.version>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
</project>
+7
View File
@@ -0,0 +1,7 @@
#!/usr/bin/env bash
# Regenerates every file under output/. Needs JDK 25, Maven 3.9 and network access to Maven Central (no Docker: H2 only).
# ./scripts/run-all.sh
set -euo pipefail
cd "$(dirname "$0")/.."
mvn -B clean test
ls -1 output
@@ -0,0 +1,50 @@
package com.ankurm.nplusone;
import jakarta.persistence.CascadeType;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.NamedEntityGraph;
import jakarta.persistence.NamedAttributeNode;
import jakarta.persistence.OneToMany;
import java.util.LinkedHashSet;
import java.util.Set;
/** One author, many books. The collection is LAZY (the JPA default for @OneToMany), which is what makes N+1 possible. */
@Entity
@NamedEntityGraph(name = "Author.withBooks", attributeNodes = @NamedAttributeNode("books"))
public class Author {
@Id
@GeneratedValue
private Long id;
private String name;
@OneToMany(mappedBy = "author", cascade = CascadeType.PERSIST)
private Set<Book> books = new LinkedHashSet<>();
protected Author() {
}
public Author(String name) {
this.name = name;
}
public Long getId() {
return id;
}
public String getName() {
return name;
}
public Set<Book> getBooks() {
return books;
}
public void addBook(Book b) {
books.add(b);
b.setAuthor(this);
}
}
@@ -0,0 +1,44 @@
package com.ankurm.nplusone;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToOne;
/** The many side. {@code @ManyToOne(fetch = LAZY)} is set explicitly because the JPA default for @ManyToOne is EAGER. */
@Entity
public class Book {
@Id
@GeneratedValue
private Long id;
private String title;
@ManyToOne(fetch = FetchType.LAZY)
private Author author;
protected Book() {
}
public Book(String title) {
this.title = title;
}
public Long getId() {
return id;
}
public String getTitle() {
return title;
}
public Author getAuthor() {
return author;
}
void setAuthor(Author author) {
this.author = author;
}
}
@@ -0,0 +1,89 @@
package com.ankurm.nplusone;
import java.util.UUID;
import java.util.function.Consumer;
import java.util.function.Function;
import org.h2.jdbcx.JdbcDataSource;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.boot.MetadataSources;
import org.hibernate.boot.registry.StandardServiceRegistry;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
/**
* Plain Hibernate bootstrap on an in-memory H2, with the DataSource wrapped by {@link QueryGuard}
* and Hibernate's own statistics switched on, so both counters can be compared on the same code.
*/
public final class Db implements AutoCloseable {
private final SessionFactory sf;
private Db(SessionFactory sf) {
this.sf = sf;
}
public static Db open() {
JdbcDataSource h2 = new JdbcDataSource();
h2.setURL("jdbc:h2:mem:" + UUID.randomUUID() + ";DB_CLOSE_DELAY=-1");
h2.setUser("sa");
StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
.applySetting("jakarta.persistence.nonJtaDataSource", QueryGuard.wrap(h2))
.applySetting("hibernate.hbm2ddl.auto", "create-drop")
.applySetting("hibernate.generate_statistics", "true")
.build();
MetadataSources sources = new MetadataSources(registry)
.addAnnotatedClass(Author.class)
.addAnnotatedClass(Book.class);
return new Db(sources.buildMetadata().buildSessionFactory());
}
public SessionFactory sf() {
return sf;
}
/** Inserts {@code authors} authors with {@code booksEach} books each, then clears every counter. */
public void seed(int authors, int booksEach) {
txv(s -> {
for (int a = 0; a < authors; a++) {
Author author = new Author("author-" + a);
for (int b = 0; b < booksEach; b++) {
author.addBook(new Book("book-" + a + "-" + b));
}
s.persist(author);
}
});
sf.getStatistics().clear();
QueryGuard.reset();
}
public <T> T tx(Function<Session, T> work) {
try (Session s = sf.openSession()) {
var t = s.beginTransaction();
try {
T r = work.apply(s);
t.commit();
return r;
}
catch (RuntimeException e) {
if (t.isActive()) {
t.rollback();
}
throw e;
}
}
}
public void txv(Consumer<Session> work) {
tx(s -> {
work.accept(s);
return null;
});
}
@Override
public void close() {
if (sf.isOpen()) {
sf.close();
}
}
}
@@ -0,0 +1,19 @@
package com.ankurm.nplusone;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.junit.jupiter.api.extension.ExtendWith;
/**
* Query budget for one test: the test fails if it sends more than {@link #value()} SELECT statements.
* Put it on a method, or on the class to apply the same budget to every test in it.
*/
@Target({ ElementType.METHOD, ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(QueryGuardExtension.class)
public @interface MaxSelects {
int value();
}
@@ -0,0 +1,95 @@
package com.ankurm.nplusone;
import java.util.ArrayList;
import java.util.List;
import javax.sql.DataSource;
import net.ttddyy.dsproxy.QueryCount;
import net.ttddyy.dsproxy.QueryCountHolder;
import net.ttddyy.dsproxy.QueryInfo;
import net.ttddyy.dsproxy.listener.QueryExecutionListener;
import net.ttddyy.dsproxy.support.ProxyDataSourceBuilder;
import org.opentest4j.AssertionFailedError;
/**
* Counts every statement that reaches the JDBC driver, whoever sent it.
*
* <p>{@link #wrap(DataSource)} puts datasource-proxy between Hibernate and the real DataSource.
* datasource-proxy keeps per-type counters (select / insert / update / delete) in
* {@link QueryCountHolder}; a small listener additionally remembers the SQL text so a failed
* assertion can print the statements that broke the budget. Counters are per thread: the code
* under test and the assertion must run on the same thread.
*/
public final class QueryGuard {
static final String DATASOURCE_NAME = "guarded";
private static final ThreadLocal<List<String>> SQL = ThreadLocal.withInitial(ArrayList::new);
private QueryGuard() {
}
/** Wraps a DataSource so every statement is counted and recorded. */
public static DataSource wrap(DataSource real) {
return ProxyDataSourceBuilder.create(real)
.name(DATASOURCE_NAME)
.countQuery()
.listener(new QueryExecutionListener() {
@Override
public void beforeQuery(net.ttddyy.dsproxy.ExecutionInfo execInfo, List<QueryInfo> queryInfoList) {
}
@Override
public void afterQuery(net.ttddyy.dsproxy.ExecutionInfo execInfo, List<QueryInfo> queryInfoList) {
for (QueryInfo q : queryInfoList) {
SQL.get().add(q.getQuery().replaceAll("\\s+", " ").trim());
}
}
})
.build();
}
/** Zeroes the counters and the SQL log for the current thread. */
public static void reset() {
QueryCountHolder.clear();
SQL.get().clear();
}
public static QueryCount counts() {
QueryCount c = QueryCountHolder.get(DATASOURCE_NAME);
return c != null ? c : new QueryCount();
}
public static long selects() {
return counts().getSelect();
}
public static List<String> sql() {
return List.copyOf(SQL.get());
}
/** Runs the action from a clean slate and returns the SELECT count it caused. */
public static long countSelects(Runnable action) {
reset();
action.run();
return selects();
}
/** Fails with the full statement list when the current thread has sent more than {@code max} SELECTs. */
public static void assertMaxSelects(long max, String what) {
long actual = selects();
if (actual > max) {
throw new AssertionFailedError(message(max, actual, what));
}
}
static String message(long max, long actual, String what) {
StringBuilder sb = new StringBuilder();
sb.append(what).append(": expected at most ").append(max).append(" SELECT statement(s) but ")
.append(actual).append(" were sent.");
int i = 1;
for (String s : SQL.get()) {
sb.append(System.lineSeparator()).append(" ").append(i++).append(") ").append(s);
}
return sb.toString();
}
}
@@ -0,0 +1,31 @@
package com.ankurm.nplusone;
import org.junit.jupiter.api.extension.AfterTestExecutionCallback;
import org.junit.jupiter.api.extension.BeforeTestExecutionCallback;
import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.platform.commons.support.AnnotationSupport;
/**
* Enforces {@link MaxSelects}.
*
* <p>The counters are reset in {@code BeforeTestExecutionCallback}, which runs <em>after</em>
* {@code @BeforeEach} methods, so seeding done there is not counted against the test. The check
* runs in {@code AfterTestExecutionCallback}, before {@code @AfterEach}.
*/
public class QueryGuardExtension implements BeforeTestExecutionCallback, AfterTestExecutionCallback {
@Override
public void beforeTestExecution(ExtensionContext ctx) {
QueryGuard.reset();
}
@Override
public void afterTestExecution(ExtensionContext ctx) {
MaxSelects budget = AnnotationSupport.findAnnotation(ctx.getTestMethod(), MaxSelects.class)
.or(() -> AnnotationSupport.findAnnotation(ctx.getTestClass(), MaxSelects.class))
.orElse(null);
if (budget != null) {
QueryGuard.assertMaxSelects(budget.value(), ctx.getDisplayName());
}
}
}
@@ -0,0 +1,35 @@
package com.ankurm.nplusone;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
/**
* A deliberately regressed test: it is NOT picked up by surefire (name does not end in Test).
* {@link T03_GuardTest} runs it through the JUnit Platform and records the failure message.
*/
class BrokenFixture {
static Db db;
@BeforeAll
static void open() {
db = Db.open();
db.seed(10, 3);
}
@AfterAll
static void close() {
db.close();
}
@Test
@MaxSelects(2)
void listAuthorsWithBookCount() {
db.txv(s -> {
for (Author a : s.createQuery("from Author", Author.class).getResultList()) {
a.getBooks().size();
}
});
}
}
@@ -0,0 +1,73 @@
package com.ankurm.nplusone;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.List;
import org.hibernate.stat.Statistics;
import org.junit.jupiter.api.Test;
/** Reproduces both flavours of N+1 and shows what each counter reports. */
class T01_ReproduceTest {
@Test
void collectionNPlusOne() {
Transcript t = new Transcript("01-n-plus-one", "N+1 on a lazy collection: 10 authors, 3 books each");
try (Db db = Db.open()) {
db.seed(10, 3);
Statistics stats = db.sf().getStatistics();
int[] books = {0};
db.txv(s -> {
List<Author> authors = s.createQuery("from Author", Author.class).getResultList();
for (Author a : authors) {
books[0] += a.getBooks().size();
}
});
t.heading("Code: one HQL query, then a.getBooks().size() for every author");
t.line("books counted by the loop : " + books[0]);
t.line("datasource-proxy SELECT count : " + QueryGuard.selects());
t.line("Hibernate prepareStatementCount : " + stats.getPrepareStatementCount());
t.line("Hibernate queryExecutionCount : " + stats.getQueryExecutionCount());
t.line("Hibernate collectionFetchCount : " + stats.getCollectionFetchCount());
t.line("Hibernate collectionLoadCount : " + stats.getCollectionLoadCount());
t.heading("The statements, in order");
t.sql(QueryGuard.sql());
assertThat(books[0]).isEqualTo(30);
assertThat(QueryGuard.selects()).isEqualTo(11);
assertThat(stats.getPrepareStatementCount()).isEqualTo(11);
// The trap: HQL executions are 1 because lazy loads are not "queries" to Hibernate.
assertThat(stats.getQueryExecutionCount()).isEqualTo(1);
assertThat(stats.getCollectionFetchCount()).isEqualTo(10);
}
t.write();
}
@Test
void toOneNPlusOne() {
Transcript t = new Transcript("02-n-plus-one-to-one", "N+1 on a lazy @ManyToOne: 30 books, 10 distinct authors");
try (Db db = Db.open()) {
db.seed(10, 3);
Statistics stats = db.sf().getStatistics();
db.txv(s -> {
List<Book> all = s.createQuery("from Book", Book.class).getResultList();
for (Book b : all) {
b.getAuthor().getName();
}
});
t.heading("Code: one HQL query for 30 books, then book.getAuthor().getName() for every book");
t.line("datasource-proxy SELECT count : " + QueryGuard.selects());
t.line("Hibernate entityFetchCount : " + stats.getEntityFetchCount());
t.heading("The statements, in order");
t.sql(QueryGuard.sql());
// 30 rows, but only 10 distinct authors: the persistence context loads each author once.
assertThat(QueryGuard.selects()).isEqualTo(11);
assertThat(stats.getEntityFetchCount()).isEqualTo(10);
}
t.write();
}
}
@@ -0,0 +1,86 @@
package com.ankurm.nplusone;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.function.Consumer;
import org.hibernate.Session;
import org.junit.jupiter.api.Test;
/** The same "list every author with a book count" job, written five ways, with the SELECT count of each. */
class T02_FixesTest {
private static final String HEADING = "SELECT statements for 10 authors x 3 books, same result every time (30 books)";
@Test
void fixesCompared() {
Transcript t = new Transcript("03-fixes", "Five ways to load 10 authors with their books");
Map<String, Long> counts = new LinkedHashMap<>();
try (Db db = Db.open()) {
db.seed(10, 3);
run(db, t, counts, "naive loop (lazy collection per author)", s -> total(s.createQuery("from Author", Author.class).getResultList()));
run(db, t, counts, "join fetch", s -> total(s.createQuery("select a from Author a join fetch a.books", Author.class).getResultList()));
run(db, t, counts, "entity graph (Author.withBooks)", s -> total(s.createQuery("from Author", Author.class)
.setHint("jakarta.persistence.fetchgraph", s.getEntityGraph("Author.withBooks")).getResultList()));
run(db, t, counts, "batch fetching, size 5 (session.setFetchBatchSize)", s -> {
s.setFetchBatchSize(5);
return total(s.createQuery("from Author", Author.class).getResultList());
});
run(db, t, counts, "DTO projection (no entities)", s -> s.createQuery(
"select count(b) from Book b group by b.author.id", Long.class).getResultList().stream().mapToInt(Long::intValue).sum());
}
t.heading(HEADING);
counts.forEach((k, v) -> t.line(String.format("%-52s %d", k, v)));
t.write();
assertThat(counts.values()).containsExactly(11L, 1L, 1L, 3L, 1L);
}
private static int total(List<Author> authors) {
int n = 0;
for (Author a : authors) {
n += a.getBooks().size();
}
return n;
}
private static void run(Db db, Transcript t, Map<String, Long> counts, String label, java.util.function.Function<Session, Integer> job) {
QueryGuard.reset();
int books = db.tx(job);
assertThat(books).as(label).isEqualTo(30);
counts.put(label, QueryGuard.selects());
t.heading(label);
t.sql(QueryGuard.sql());
}
/**
* join fetch on a collection + setMaxResults. Older Hibernate versions paged this in memory (warning HHH90003004);
* this test pins what 7.4 does: the limit is applied in SQL, to the owning side, inside a subquery.
*/
@Test
void joinFetchPagination() {
Transcript t = new Transcript("04-join-fetch-pagination", "join fetch on a collection + setMaxResults(3), 10 authors x 3 books");
try (Db db = Db.open()) {
db.seed(10, 3);
QueryGuard.reset();
List<Author> page = db.tx(s -> {
List<Author> r = s.createQuery("select a from Author a join fetch a.books order by a.id", Author.class)
.setMaxResults(3).getResultList();
r.forEach(a -> a.getBooks().size());
return r;
});
int books = page.stream().mapToInt(a -> a.getBooks().size()).sum();
t.line("authors returned: " + page.size() + ", books loaded: " + books);
t.line("SELECT statements: " + QueryGuard.selects());
t.sql(QueryGuard.sql());
assertThat(page).hasSize(3);
assertThat(books).isEqualTo(9);
assertThat(QueryGuard.selects()).isEqualTo(1);
assertThat(QueryGuard.sql().get(0)).contains("fetch first");
}
t.write();
}
}
@@ -0,0 +1,51 @@
package com.ankurm.nplusone;
import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.platform.testkit.engine.EngineTestKit;
/** The guard itself: a passing budget, and the failure message a regressed test produces. */
class T03_GuardTest {
private Db db;
@BeforeEach
void seed() {
// Db.seed() clears every counter when it finishes, so the INSERTs never count against a budget.
db = Db.open();
db.seed(10, 3);
}
@org.junit.jupiter.api.AfterEach
void close() {
db.close();
}
@Test
@MaxSelects(1)
void joinFetchStaysWithinBudget() {
db.txv(s -> s.createQuery("select a from Author a join fetch a.books", Author.class).getResultList()
.forEach(a -> a.getBooks().size()));
}
@Test
void regressedTestFailsWithTheStatementList() {
var results = EngineTestKit.engine("junit-jupiter").selectors(selectClass(BrokenFixture.class)).execute();
var failures = results.testEvents().failed().stream().toList();
assertThat(failures).hasSize(1);
String message = failures.get(0).getRequiredPayload(org.junit.platform.engine.TestExecutionResult.class)
.getThrowable().orElseThrow().getMessage();
Transcript t = new Transcript("05-guard-failure", "What the guard prints when a test regresses (BrokenFixture, @MaxSelects(2))");
t.heading("Failure message");
message.lines().forEach(t::line);
t.write();
assertThat(message).contains("expected at most 2 SELECT statement(s) but 11 were sent.");
assertThat(message).contains("1) select a1_0.id,a1_0.name from Author a1_0");
assertThat(message).contains("11) select b1_0.author_id");
}
}
@@ -0,0 +1,48 @@
package com.ankurm.nplusone;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
/** Collects what a test observed and writes output/NN-name.txt; the tests assert the same facts. */
final class Transcript {
private final List<String> lines = new ArrayList<>();
private final Path file;
Transcript(String name, String title) {
this.file = Path.of("output", name + ".txt");
line("# " + title);
line("# Hibernate ORM " + System.getProperty("h.version", "?") + ", datasource-proxy "
+ System.getProperty("dsp.version", "?") + ", H2, JDK " + Runtime.version().feature());
}
Transcript line(String s) {
lines.add(s);
return this;
}
Transcript heading(String s) {
line("");
return line("== " + s);
}
Transcript sql(List<String> sql) {
for (String s : sql) {
line(" sql> " + s);
}
return this;
}
void write() {
try {
Files.createDirectories(file.getParent());
Files.write(file, lines);
}
catch (IOException ex) {
throw new IllegalStateException(ex);
}
}
}