From 0db721805b5d866b3442da8ff972cf2a835c7ace Mon Sep 17 00:00:00 2001 From: asmhatre Date: Tue, 17 Nov 2026 00:48:25 +0530 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_017ic4b6R1spapM7nBteaqeo --- README.md | 1 + n-plus-one-guard/README.md | 38 ++++++++ n-plus-one-guard/output/01-n-plus-one.txt | 23 +++++ .../output/02-n-plus-one-to-one.txt | 19 ++++ n-plus-one-guard/output/03-fixes.txt | 36 +++++++ .../output/04-join-fetch-pagination.txt | 5 + n-plus-one-guard/output/05-guard-failure.txt | 16 ++++ n-plus-one-guard/pom.xml | 85 +++++++++++++++++ n-plus-one-guard/scripts/run-all.sh | 7 ++ .../main/java/com/ankurm/nplusone/Author.java | 50 ++++++++++ .../main/java/com/ankurm/nplusone/Book.java | 44 +++++++++ .../src/main/java/com/ankurm/nplusone/Db.java | 89 +++++++++++++++++ .../java/com/ankurm/nplusone/MaxSelects.java | 19 ++++ .../java/com/ankurm/nplusone/QueryGuard.java | 95 +++++++++++++++++++ .../ankurm/nplusone/QueryGuardExtension.java | 31 ++++++ .../com/ankurm/nplusone/BrokenFixture.java | 35 +++++++ .../ankurm/nplusone/T01_ReproduceTest.java | 73 ++++++++++++++ .../com/ankurm/nplusone/T02_FixesTest.java | 86 +++++++++++++++++ .../com/ankurm/nplusone/T03_GuardTest.java | 51 ++++++++++ .../java/com/ankurm/nplusone/Transcript.java | 48 ++++++++++ 20 files changed, 851 insertions(+) create mode 100644 n-plus-one-guard/README.md create mode 100644 n-plus-one-guard/output/01-n-plus-one.txt create mode 100644 n-plus-one-guard/output/02-n-plus-one-to-one.txt create mode 100644 n-plus-one-guard/output/03-fixes.txt create mode 100644 n-plus-one-guard/output/04-join-fetch-pagination.txt create mode 100644 n-plus-one-guard/output/05-guard-failure.txt create mode 100644 n-plus-one-guard/pom.xml create mode 100755 n-plus-one-guard/scripts/run-all.sh create mode 100644 n-plus-one-guard/src/main/java/com/ankurm/nplusone/Author.java create mode 100644 n-plus-one-guard/src/main/java/com/ankurm/nplusone/Book.java create mode 100644 n-plus-one-guard/src/main/java/com/ankurm/nplusone/Db.java create mode 100644 n-plus-one-guard/src/main/java/com/ankurm/nplusone/MaxSelects.java create mode 100644 n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuard.java create mode 100644 n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuardExtension.java create mode 100644 n-plus-one-guard/src/test/java/com/ankurm/nplusone/BrokenFixture.java create mode 100644 n-plus-one-guard/src/test/java/com/ankurm/nplusone/T01_ReproduceTest.java create mode 100644 n-plus-one-guard/src/test/java/com/ankurm/nplusone/T02_FixesTest.java create mode 100644 n-plus-one-guard/src/test/java/com/ankurm/nplusone/T03_GuardTest.java create mode 100644 n-plus-one-guard/src/test/java/com/ankurm/nplusone/Transcript.java diff --git a/README.md b/README.md index adcda17..48c32db 100755 --- a/README.md +++ b/README.md @@ -352,3 +352,4 @@ Modules with their own `pom.xml` that run plain Hibernate without the Spring Boo | [`json-columns`](json-columns/) | JSON columns in Hibernate 7.4: `@JdbcTypeCode(SqlTypes.JSON)` for Map / List / record / POJO / `@Embeddable`, `json` vs `jsonb` DDL, HQL JSON functions, native JSONB operators, GIN and expression indexes with `EXPLAIN`, dirty checking, Jackson 3 vs Jackson 2 `FormatMapper`, MySQL 8.0, on PostgreSQL 18 (Hibernate `7.4.14.Final`, Spring Boot `4.1.2`) | | [`cascade-types`](cascade-types/) | JPA cascade types and `orphanRemoval` in Hibernate 7: composition vs aggregation, `orphanRemoval` vs `CascadeType.REMOVE`, the `cascade = ALL` on `@ManyToOne` incident reproduced in three schemas, `@ManyToMany` / `@OneToOne` / `@ManyToOne` cases, the cost of cascading a 1,000-row delete, `@OnDelete`, and the same tests on Hibernate `8.0.0.CR1`; plain Hibernate on H2 (Hibernate `7.4.15.Final`) | | [`one-to-many`](one-to-many/) | `@OneToMany` in Hibernate 7: unidirectional join table vs `@JoinColumn` vs bidirectional `mappedBy`, the SQL each sends, why removing one child from a join-table `List` deletes and re-inserts the rest (and why a `mappedBy` List does not), the bidirectional sync helper, fetch defaults, N+1 fixes, `MultipleBagFetchException` and its three fixes, and the id-based `hashCode` trap; plain Hibernate on H2 (Hibernate `7.4.16.Final`) | +| [`n-plus-one-guard`](n-plus-one-guard/) | Detecting N+1 queries automatically: Hibernate Statistics vs datasource-proxy (what each counts and what each misses), five fixes with statement counts, and a JUnit 6 `@MaxSelects` guard that fails a test with the full SQL list; plain Hibernate on H2 (Hibernate `7.4.16.Final`, datasource-proxy `1.11.1`) | diff --git a/n-plus-one-guard/README.md b/n-plus-one-guard/README.md new file mode 100644 index 0000000..2fab02f --- /dev/null +++ b/n-plus-one-guard/README.md @@ -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. diff --git a/n-plus-one-guard/output/01-n-plus-one.txt b/n-plus-one-guard/output/01-n-plus-one.txt new file mode 100644 index 0000000..da5745f --- /dev/null +++ b/n-plus-one-guard/output/01-n-plus-one.txt @@ -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=? diff --git a/n-plus-one-guard/output/02-n-plus-one-to-one.txt b/n-plus-one-guard/output/02-n-plus-one-to-one.txt new file mode 100644 index 0000000..f0e0873 --- /dev/null +++ b/n-plus-one-guard/output/02-n-plus-one-to-one.txt @@ -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=? diff --git a/n-plus-one-guard/output/03-fixes.txt b/n-plus-one-guard/output/03-fixes.txt new file mode 100644 index 0000000..aa98384 --- /dev/null +++ b/n-plus-one-guard/output/03-fixes.txt @@ -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 diff --git a/n-plus-one-guard/output/04-join-fetch-pagination.txt b/n-plus-one-guard/output/04-join-fetch-pagination.txt new file mode 100644 index 0000000..5cebd48 --- /dev/null +++ b/n-plus-one-guard/output/04-join-fetch-pagination.txt @@ -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 diff --git a/n-plus-one-guard/output/05-guard-failure.txt b/n-plus-one-guard/output/05-guard-failure.txt new file mode 100644 index 0000000..91fd575 --- /dev/null +++ b/n-plus-one-guard/output/05-guard-failure.txt @@ -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=? diff --git a/n-plus-one-guard/pom.xml b/n-plus-one-guard/pom.xml new file mode 100644 index 0000000..712fb50 --- /dev/null +++ b/n-plus-one-guard/pom.xml @@ -0,0 +1,85 @@ + + + 4.0.0 + + com.ankurm + n-plus-one-guard + 1.0.0 + n-plus-one-guard + Detecting N+1 queries automatically: Hibernate Statistics, datasource-proxy and a JUnit 6 query-count guard (plain Hibernate on H2) + + + 25 + UTF-8 + + 7.4.16.Final + 3.2.0 + 6.1.3 + 1.11.1 + + + + + org.hibernate.orm + hibernate-core + ${hibernate.version} + + + jakarta.persistence + jakarta.persistence-api + ${persistence.version} + + + com.h2database + h2 + 2.4.240 + + + net.ttddyy + datasource-proxy + ${datasource-proxy.version} + + + + org.junit.jupiter + junit-jupiter-api + ${junit.version} + + + org.junit.jupiter + junit-jupiter + ${junit.version} + test + + + org.junit.platform + junit-platform-testkit + ${junit.version} + test + + + org.assertj + assertj-core + 3.27.7 + test + + + + + + + maven-surefire-plugin + 3.6.0 + + -Xmx512m + + ${hibernate.version} + ${datasource-proxy.version} + + + + + + diff --git a/n-plus-one-guard/scripts/run-all.sh b/n-plus-one-guard/scripts/run-all.sh new file mode 100755 index 0000000..c17c31a --- /dev/null +++ b/n-plus-one-guard/scripts/run-all.sh @@ -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 diff --git a/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Author.java b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Author.java new file mode 100644 index 0000000..19a7dc0 --- /dev/null +++ b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Author.java @@ -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 books = new LinkedHashSet<>(); + + protected Author() { + } + + public Author(String name) { + this.name = name; + } + + public Long getId() { + return id; + } + + public String getName() { + return name; + } + + public Set getBooks() { + return books; + } + + public void addBook(Book b) { + books.add(b); + b.setAuthor(this); + } +} diff --git a/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Book.java b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Book.java new file mode 100644 index 0000000..b78dae2 --- /dev/null +++ b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Book.java @@ -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; + } +} diff --git a/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Db.java b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Db.java new file mode 100644 index 0000000..fa7fba3 --- /dev/null +++ b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/Db.java @@ -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 tx(Function 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 work) { + tx(s -> { + work.accept(s); + return null; + }); + } + + @Override + public void close() { + if (sf.isOpen()) { + sf.close(); + } + } +} diff --git a/n-plus-one-guard/src/main/java/com/ankurm/nplusone/MaxSelects.java b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/MaxSelects.java new file mode 100644 index 0000000..456f70b --- /dev/null +++ b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/MaxSelects.java @@ -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(); +} diff --git a/n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuard.java b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuard.java new file mode 100644 index 0000000..e084a00 --- /dev/null +++ b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuard.java @@ -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. + * + *

{@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> 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 queryInfoList) { + } + + @Override + public void afterQuery(net.ttddyy.dsproxy.ExecutionInfo execInfo, List 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 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(); + } +} diff --git a/n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuardExtension.java b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuardExtension.java new file mode 100644 index 0000000..64b7b53 --- /dev/null +++ b/n-plus-one-guard/src/main/java/com/ankurm/nplusone/QueryGuardExtension.java @@ -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}. + * + *

The counters are reset in {@code BeforeTestExecutionCallback}, which runs after + * {@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()); + } + } +} diff --git a/n-plus-one-guard/src/test/java/com/ankurm/nplusone/BrokenFixture.java b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/BrokenFixture.java new file mode 100644 index 0000000..4881001 --- /dev/null +++ b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/BrokenFixture.java @@ -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(); + } + }); + } +} diff --git a/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T01_ReproduceTest.java b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T01_ReproduceTest.java new file mode 100644 index 0000000..613427a --- /dev/null +++ b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T01_ReproduceTest.java @@ -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 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 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(); + } +} diff --git a/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T02_FixesTest.java b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T02_FixesTest.java new file mode 100644 index 0000000..b151b74 --- /dev/null +++ b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T02_FixesTest.java @@ -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 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 authors) { + int n = 0; + for (Author a : authors) { + n += a.getBooks().size(); + } + return n; + } + + private static void run(Db db, Transcript t, Map counts, String label, java.util.function.Function 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 page = db.tx(s -> { + List 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(); + } +} diff --git a/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T03_GuardTest.java b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T03_GuardTest.java new file mode 100644 index 0000000..4839af8 --- /dev/null +++ b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/T03_GuardTest.java @@ -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"); + } +} diff --git a/n-plus-one-guard/src/test/java/com/ankurm/nplusone/Transcript.java b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/Transcript.java new file mode 100644 index 0000000..7bd5502 --- /dev/null +++ b/n-plus-one-guard/src/test/java/com/ankurm/nplusone/Transcript.java @@ -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 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 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); + } + } +}