<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Spring-Boot on Vitalii Sukach</title><link>https://vitaliisukach.dev/tags/spring-boot/</link><description>Recent content in Spring-Boot on Vitalii Sukach</description><generator>Hugo</generator><language>en-us</language><lastBuildDate>Sun, 15 Nov 2026 10:00:00 +0000</lastBuildDate><atom:link href="https://vitaliisukach.dev/tags/spring-boot/index.xml" rel="self" type="application/rss+xml"/><item><title>Your AI Assistant Is Just Another Team That Ignores Your Bounded Context</title><link>https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/</link><pubDate>Sun, 15 Nov 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/</guid><description>AI assistants cross DDD boundaries like a new team that never read the design docs. Make the domain explicit for the AI, then enforce it with tests.</description><content:encoded><![CDATA[<p><img alt="A cheerful robot with a &ldquo;New team – Day 1&rdquo; badge breaks through the wall of a garden labelled &ldquo;Loyalty&rdquo;, carrying a glowing jar of points and dropping coins behind it. It ignores the open gate nearby with the sign &ldquo;LoyaltyService – please use this entrance&rdquo;, and an unread AGENTS.md scroll lies on the ground. Two surprised developers with coffee mugs watch." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/image-01.jpg"></p>
<blockquote>
<p><strong>TL;DR</strong></p>
<ul>
<li>An AI assistant takes the shortest path through your code, and that path usually crosses a boundary.</li>
<li>It sees code, not intent. If the rules live in people&rsquo;s heads, the AI can&rsquo;t follow them.</li>
<li>Write the bounded context down in an <code>AGENTS.md</code> next to the code: language, invariants, public API, forbidden dependencies.</li>
<li>Prompts are suggestions, tests are guarantees. Enforce the boundary with ArchUnit.</li>
</ul></blockquote>
<h2 id="the-ai-wrote-a-feature-that-works-and-breaks-four-rules">The AI wrote a feature that works and breaks four rules</h2>
<p>The ticket was simple: &ldquo;Customers get 2x loyalty points on their birthday.&rdquo; An AI assistant opened the checkout module, found the loyalty repository, and produced this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">CheckoutService</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">OrderRepository</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyAccountRepository</span><span class="w"> </span><span class="n">loyaltyAccountRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// constructor omitted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">completeCheckout</span><span class="p">(</span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">,</span><span class="w"> </span><span class="n">Customer</span><span class="w"> </span><span class="n">customer</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">order</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">loyaltyAccountRepository</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">.</span><span class="na">findByCustomerId</span><span class="p">(</span><span class="n">customer</span><span class="p">.</span><span class="na">getId</span><span class="p">()).</span><span class="na">orElseThrow</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="kt">long</span><span class="w"> </span><span class="n">points</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getTotal</span><span class="p">().</span><span class="na">longValue</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">customer</span><span class="p">.</span><span class="na">getBirthday</span><span class="p">()).</span><span class="na">equals</span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">now</span><span class="p">()))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">points</span><span class="w"> </span><span class="o">*=</span><span class="w"> </span><span class="n">2</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">points</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">loyaltyAccountRepository</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>It compiles. The tests pass. The feature works in the demo. Here is what it breaks:</p>
<ul>
<li><strong>Checkout reaches into Loyalty&rsquo;s persistence.</strong> <code>LoyaltyAccountRepository</code> is an internal detail of another context.</li>
<li><strong>Points before payment.</strong> The order is saved, not paid. A failed card still earns points.</li>
<li><strong>Checkout changes the balance itself.</strong> Calling <code>setBalance()</code> from checkout skips every rule <code>LoyaltyService</code> is supposed to enforce.</li>
<li><strong>No event.</strong> <code>PointsEarned</code> is never published, so the email service and analytics never hear about it.</li>
</ul>
<p><img alt="Diagram: CheckoutService in the Checkout context has two paths into the Loyalty context. The intended path goes to LoyaltyService, the public API that returns DTOs. The AI&rsquo;s shortcut, marked with a red cross, goes straight to the hidden LoyaltyAccountRepository and LoyaltyAccount. The rules it breaks: uses another context&rsquo;s repository, points before payment, sets the balance directly, publishes no event." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-shortcut.jpg"></p>
<p>None of this is new. A team that joined last month and never read the design docs would write the same code, for the same reason: nobody told them where the boundary was.</p>
<h2 id="why-the-ai-crosses-the-line">Why the AI crosses the line</h2>
<p><strong>The shortest path wins.</strong> The assistant is asked to make a feature work. A repository that&rsquo;s already on the classpath is the shortest path to a working feature. Nothing in the code says &ldquo;don&rsquo;t.&rdquo;</p>
<p><strong>It sees code, not intent.</strong> Your bounded contexts exist in a whiteboard photo, a Confluence page and the heads of three senior engineers. The AI reads <code>src/main/java</code>. If a public setter exists, the AI reads that as permission to call it.</p>
<p><strong>There is no ubiquitous language in the prompt.</strong> &ldquo;Add birthday points at checkout&rdquo; puts the rule in checkout. A domain expert would say &ldquo;Loyalty awards double points for orders paid on the customer&rsquo;s birthday.&rdquo; Same feature, different owner.</p>
<p>This is exactly how a new team behaves when it joins without onboarding. We already know the fix for that team. It works for the AI too.</p>
<h2 id="step-1-ask-the-ai-to-discover-the-domain-first">Step 1: Ask the AI to discover the domain first</h2>
<p>Before writing rules, find out what the code already says. Use the AI as a reader, not a writer.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Read the packages under com.shop.domain.loyalty.
</span></span><span class="line"><span class="cl">Build a glossary of the domain terms you find: class names, method
</span></span><span class="line"><span class="cl">names, enum values, event names. For each term give a one-line
</span></span><span class="line"><span class="cl">definition based only on the code. Mark terms that mean different
</span></span><span class="line"><span class="cl">things in different places, and terms that look like technical
</span></span><span class="line"><span class="cl">names rather than business language (e.g. &#34;updateRecord&#34;).
</span></span><span class="line"><span class="cl">Do not suggest changes yet.
</span></span></code></pre></div><p>Then look for the leaks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">List every class outside com.shop.domain.loyalty that imports a
</span></span><span class="line"><span class="cl">Loyalty entity or repository, or reads/writes the loyalty_account
</span></span><span class="line"><span class="cl">table through a repository, JdbcTemplate or native query.
</span></span><span class="line"><span class="cl">Calls to LoyaltyService that only get DTOs back are fine. Skip them.
</span></span><span class="line"><span class="cl">For each one, show the file, the line, and whether it reads or
</span></span><span class="line"><span class="cl">writes. Group the results by calling module.
</span></span></code></pre></div><p>The second list is your boundary violations. Controllers and app-layer services that call <code>LoyaltyService</code> and get DTOs back are not on it, because that&rsquo;s the intended way in. The list is often longer than expected. Each entry is either a missing public API or a missing event.</p>
<h2 id="step-2-write-the-context-down-where-the-ai-will-read-it">Step 2: Write the context down where the AI will read it</h2>
<p>Put an <code>AGENTS.md</code> in the Loyalty domain package, <code>com/shop/domain/loyalty/</code>. It&rsquo;s a shared convention: Codex, Cursor, GitHub Copilot, Gemini CLI and other assistants read it when they work in that directory. Keep it short and specific.</p>
<p>Recent versions of Claude Code read <code>AGENTS.md</code> too, but only when the project has no <code>CLAUDE.md</code>. If your repo already has one, Claude skips <code>AGENTS.md</code> by default. Don&rsquo;t copy the rules into a second file, because two copies drift apart. Add a <code>CLAUDE.md</code> next to <code>AGENTS.md</code> that imports it:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="ni">@AGENTS</span>.md
</span></span></code></pre></div><p>Now every assistant on the team reads the same rules, and you maintain them in one place.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gh"># Loyalty context
</span></span></span><span class="line"><span class="cl"><span class="gh"></span>Purpose: award and redeem points. Loyalty owns the balance. Nobody else writes it.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Language
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> Points: whole, non-negative amount. Never &#34;credits&#34; or &#34;bonus&#34;.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Earn: add points for a paid order. Redeem: spend points at checkout.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Earning rule: how many points an order is worth (base rate, birthday 2x).
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Invariants
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">1.</span> balance &gt;= 0, always.
</span></span><span class="line"><span class="cl"><span class="k">2.</span> Points are earned only for paid orders. Only com.shop.listener calls earnForPaidOrder().
</span></span><span class="line"><span class="cl"><span class="k">3.</span> Only LoyaltyService changes a LoyaltyAccount. The entity holds data, no logic.
</span></span><span class="line"><span class="cl"><span class="k">4.</span> Every state change publishes an event in the same transaction.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Public API
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> LoyaltyService: balanceOf(CustomerId), redeem(CustomerId, Points),
</span></span><span class="line"><span class="cl">  earnForPaidOrder(...) (listeners only). Returns DTOs, never entities.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Events out: PointsEarned, PointsRedeemed.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Loyalty doesn&#39;t listen to other domains. App-layer listeners call its service.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Forbidden
</span></span></span><span class="line"><span class="cl"><span class="gu"></span><span class="k">-</span> Code outside domain/loyalty using its entity or repository packages.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Loyalty using other domains&#39; entities or repositories. Use their service or events.
</span></span><span class="line"><span class="cl"><span class="k">-</span> Writing loyalty tables from SQL, scripts or admin tools.
</span></span></code></pre></div><p>Two things matter here. The language section gives the AI the words to use in names and commits. The forbidden section names the shortcuts you&rsquo;ve already seen it take.</p>
<p>A real system has more than one context. Don&rsquo;t put them all in one file. Give each domain package its own <code>AGENTS.md</code>, and keep a short context map at the root:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">src/main/java/com/shop/
</span></span><span class="line"><span class="cl">├── AGENTS.md          ← context map: one line per domain + global rules
</span></span><span class="line"><span class="cl">├── controller/        ← REST controllers
</span></span><span class="line"><span class="cl">├── service/           ← use cases that combine several domains
</span></span><span class="line"><span class="cl">├── dto/               ← request/response DTOs for the frontend
</span></span><span class="line"><span class="cl">├── listener/          ← event listeners that connect domains
</span></span><span class="line"><span class="cl">├── common/            ← shared kernel: Money, CustomerId, OrderId
</span></span><span class="line"><span class="cl">└── domain/
</span></span><span class="line"><span class="cl">    ├── loyalty/
</span></span><span class="line"><span class="cl">    │   ├── AGENTS.md  ← Loyalty only
</span></span><span class="line"><span class="cl">    │   ├── service/   ← LoyaltyService: the only entry point
</span></span><span class="line"><span class="cl">    │   ├── dto/       ← what the service returns, plus events
</span></span><span class="line"><span class="cl">    │   ├── entity/    ← LoyaltyAccount (hidden)
</span></span><span class="line"><span class="cl">    │   └── repository/ ← hidden
</span></span><span class="line"><span class="cl">    ├── ordering/      ← same shape, own AGENTS.md
</span></span><span class="line"><span class="cl">    └── customer/      ← same shape, own AGENTS.md
</span></span></code></pre></div><p>The top-level packages are a thin application layer. When the frontend needs a balance plus order details on one page, a top-level service calls <code>LoyaltyService</code> and <code>OrderService</code> and builds the response DTO. When one domain&rsquo;s event should trigger work in another, a listener in <code>listener/</code> connects them. Neither layer ever injects a domain&rsquo;s repository.</p>
<p><img alt="Diagram: the application layer in com.shop contains controller/, service/, dto/ and listener/. Arrows point down into the domains in com.shop.domain: loyalty/, ordering/ and customer/. Each domain has public service/ and dto/ packages and hidden entity/ and repository/ packages. ArchUnit enforces that nothing outside a domain touches its entity/ or repository/, and that no domain depends on the application layer." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-layers.jpg"></p>
<p>The root file says what each domain owns and how others use it: its service or its events. Global rules go here too: domains never depend on the top-level packages, and a domain&rsquo;s service returns DTOs, never entities. Each domain file covers only its own language, invariants and dependencies.</p>
<p>Domains still need some shared language. <code>earnForPaidOrder()</code> takes <code>Money</code>, <code>CustomerId</code> and <code>OrderId</code>, and Ordering uses the same types. These live in <code>common/</code>, which DDD calls a shared kernel: a small set of types every domain may use.</p>
<p>Keep it to immutable value records like these, with validation and no business logic. No entities, services or frontend DTOs belong there. Every team depends on it, so a change to <code>common/</code> needs every team&rsquo;s agreement.</p>
<p>Say this in the root <code>AGENTS.md</code>; without that rule, an assistant will start moving anything that two domains need into <code>common/</code>.</p>
<p>This split matters for three reasons. Assistants load a nested file only when they work in that folder, so a change to Checkout doesn&rsquo;t pull in fifteen other contexts. Each context keeps its own vocabulary, so &ldquo;Account&rdquo; in Loyalty never gets mixed up with &ldquo;Account&rdquo; in Billing. And each team owns its file.</p>
<p>If you use Claude Code and your repo already has a <code>CLAUDE.md</code>, repeat the trick from above in every domain: put a one-line <code>CLAUDE.md</code> with <code>@AGENTS.md</code> next to each domain&rsquo;s <code>AGENTS.md</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">domain/
</span></span><span class="line"><span class="cl">├── loyalty/
</span></span><span class="line"><span class="cl">│   ├── AGENTS.md
</span></span><span class="line"><span class="cl">│   └── CLAUDE.md      ← contains only: @AGENTS.md
</span></span><span class="line"><span class="cl">└── ordering/
</span></span><span class="line"><span class="cl">    ├── AGENTS.md
</span></span><span class="line"><span class="cl">    └── CLAUDE.md      ← contains only: @AGENTS.md
</span></span></code></pre></div><p>It&rsquo;s tempting to import every domain&rsquo;s <code>AGENTS.md</code> from the root <code>CLAUDE.md</code> instead. Don&rsquo;t. Claude Code loads the root file and everything it imports at the start of every session, so every context&rsquo;s rules would be loaded all the time. A <code>CLAUDE.md</code> inside a domain folder is loaded only when Claude works on files in that folder.</p>
<h2 id="step-3-make-the-ai-work-inside-the-context">Step 3: Make the AI work inside the context</h2>
<p>Now rewrite the feature request. Point it at the context and ask it to reason about invariants before it writes code.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Read com/shop/domain/loyalty/AGENTS.md first.
</span></span><span class="line"><span class="cl">Feature: Loyalty awards double points for orders paid on the
</span></span><span class="line"><span class="cl">customer&#39;s birthday.
</span></span><span class="line"><span class="cl">Before writing code:
</span></span><span class="line"><span class="cl">1. Say which bounded context owns this rule and why.
</span></span><span class="line"><span class="cl">2. List every invariant from AGENTS.md this change touches.
</span></span><span class="line"><span class="cl">3. List the classes you plan to change. Flag any outside
</span></span><span class="line"><span class="cl">   domain/loyalty.
</span></span><span class="line"><span class="cl">Wait for my confirmation. Then implement it inside the
</span></span><span class="line"><span class="cl">LoyaltyService with unit tests for each invariant.
</span></span></code></pre></div><p>The &ldquo;wait for confirmation&rdquo; step is where you catch a wrong plan. It costs one message instead of a code review.</p>
<p>The entity only holds data:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">LoyaltyAccount</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.domain.loyalty.entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">MonthDay</span><span class="w"> </span><span class="n">birthday</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Points</span><span class="w"> </span><span class="n">balance</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// getters and setters, no logic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>Points</code> is a record that rejects negative values in its constructor, so <code>balance &gt;= 0</code> holds no matter who sets the balance.</p>
<p>The rules live in <code>LoyaltyService</code>. It&rsquo;s the only class that changes a <code>LoyaltyAccount</code>, and every change publishes an event in the same transaction:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">LoyaltyService</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.domain.loyalty.service</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyAccountRepository</span><span class="w"> </span><span class="n">accounts</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ApplicationEventPublisher</span><span class="w"> </span><span class="n">events</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// constructor and balanceOf() omitted</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">earnForPaidOrder</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">OrderId</span><span class="w"> </span><span class="n">orderId</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                                 </span><span class="n">Money</span><span class="w"> </span><span class="n">paidAmount</span><span class="p">,</span><span class="w"> </span><span class="n">LocalDate</span><span class="w"> </span><span class="n">paidOn</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">customerId</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Points</span><span class="w"> </span><span class="n">earned</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Points</span><span class="p">.</span><span class="na">forAmount</span><span class="p">(</span><span class="n">paidAmount</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">MonthDay</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">paidOn</span><span class="p">).</span><span class="na">equals</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBirthday</span><span class="p">()))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">earned</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">earned</span><span class="p">.</span><span class="na">times</span><span class="p">(</span><span class="n">2</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">plus</span><span class="p">(</span><span class="n">earned</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">accounts</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">events</span><span class="p">.</span><span class="na">publishEvent</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PointsEarned</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">orderId</span><span class="p">,</span><span class="w"> </span><span class="n">earned</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">public</span><span class="w"> </span><span class="n">PointsDto</span><span class="w"> </span><span class="nf">redeem</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">Points</span><span class="w"> </span><span class="n">points</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="n">account</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">load</span><span class="p">(</span><span class="n">customerId</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">isLessThan</span><span class="p">(</span><span class="n">points</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">throw</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">InsufficientPointsException</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">points</span><span class="p">,</span><span class="w"> </span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">account</span><span class="p">.</span><span class="na">setBalance</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">().</span><span class="na">minus</span><span class="p">(</span><span class="n">points</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">accounts</span><span class="p">.</span><span class="na">save</span><span class="p">(</span><span class="n">account</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">events</span><span class="p">.</span><span class="na">publishEvent</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PointsRedeemed</span><span class="p">(</span><span class="n">customerId</span><span class="p">,</span><span class="w"> </span><span class="n">points</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">PointsDto</span><span class="p">(</span><span class="n">account</span><span class="p">.</span><span class="na">getBalance</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">LoyaltyAccount</span><span class="w"> </span><span class="nf">load</span><span class="p">(</span><span class="n">CustomerId</span><span class="w"> </span><span class="n">customerId</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">accounts</span><span class="p">.</span><span class="na">findByCustomerId</span><span class="p">(</span><span class="n">customerId</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="p">.</span><span class="na">orElseThrow</span><span class="p">(()</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">LoyaltyAccountNotFoundException</span><span class="p">(</span><span class="n">customerId</span><span class="p">));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The setters are public, so in principle anyone could call them. Two things stop that: the entity package is closed to code outside Loyalty, and inside Loyalty only <code>LoyaltyService</code> may call the setters. Step 5 turns both into tests.</p>
<p>The balance change and the event are in one transaction. Listeners annotated with <code>@TransactionalEventListener</code> run only after that transaction commits, so a rolled-back change never sends an event.</p>
<p>Neither domain knows about the other. Ordering publishes <code>OrderPaid</code> without knowing who listens. Loyalty exposes <code>earnForPaidOrder()</code> without knowing where paid orders come from. The rule that links them, &ldquo;a paid order earns points&rdquo;, lives in the application layer, in a listener that combines the two domains. It translates the event into a call and does nothing else:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Component</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">OrderPaidListener</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="c1">// com.shop.listener</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">LoyaltyService</span><span class="w"> </span><span class="n">loyalty</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderPaidListener</span><span class="p">(</span><span class="n">LoyaltyService</span><span class="w"> </span><span class="n">loyalty</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">loyalty</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">loyalty</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@TransactionalEventListener</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Transactional</span><span class="p">(</span><span class="n">propagation</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Propagation</span><span class="p">.</span><span class="na">REQUIRES_NEW</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">void</span><span class="w"> </span><span class="nf">on</span><span class="p">(</span><span class="n">OrderPaid</span><span class="w"> </span><span class="n">event</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">loyalty</span><span class="p">.</span><span class="na">earnForPaidOrder</span><span class="p">(</span><span class="n">event</span><span class="p">.</span><span class="na">customerId</span><span class="p">(),</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="na">orderId</span><span class="p">(),</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">event</span><span class="p">.</span><span class="na">amount</span><span class="p">(),</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="na">paidOn</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Checkout doesn&rsquo;t know Loyalty exists. A failed payment never produces <code>OrderPaid</code>, so it never produces points.</p>
<p><img alt="Diagram: OrderService in Ordering commits a successful payment and publishes OrderPaid after commit. OrderPaidListener in com.shop.listener receives it and calls LoyaltyService, which loads the account, doubles the points on the customer&rsquo;s birthday, updates the balance, saves, and publishes PointsEarned to email and analytics. A failed payment rolls back, so there is no OrderPaid and no points." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-event-flow.jpg"></p>
<p><code>earnForPaidOrder()</code> has to be public so the listener can call it. That also means a controller could call it and award points without a paid order. Step 5 closes that gap with a test.</p>
<h2 id="step-4-review-in-a-fresh-session">Step 4: Review in a fresh session</h2>
<p>Don&rsquo;t ask the session that wrote the code to review it. It has the same blind spots it had five minutes ago. Open a new session, give it the rules and the diff, and nothing else.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">You are reviewing a change to the Loyalty bounded context.
</span></span><span class="line"><span class="cl">Read com/shop/domain/loyalty/AGENTS.md, then run: git diff main...HEAD
</span></span><span class="line"><span class="cl">For each invariant and each &#34;Forbidden&#34; rule in AGENTS.md,
</span></span><span class="line"><span class="cl">answer: kept, broken, or not affected. For &#34;broken&#34;, quote the
</span></span><span class="line"><span class="cl">line. Then list any new terms in names or comments that are not
</span></span><span class="line"><span class="cl">in the Language section. Do not comment on style.
</span></span></code></pre></div><p>A reviewer with a checklist finds more than a reviewer with a vibe. That&rsquo;s true for people and for models.</p>
<h2 id="step-5-enforce-the-boundary-with-tests">Step 5: Enforce the boundary with tests</h2>
<p>Everything so far makes a good outcome more likely. None of it makes a bad outcome impossible. The next prompt, the next model or the next tired developer can still call <code>loyaltyAccountRepository</code> from checkout.</p>
<p><img alt="Diagram: five steps rising like stairs. Steps 1 to 4 are prompts, which are suggestions: Discover (glossary and leak list), Write it down (AGENTS.md per domain), Plan first (invariants before code), Fresh review (checklist from AGENTS.md). Step 5, Enforce (ArchUnit tests in the build), is the only guarantee. An arrow runs from &ldquo;a good outcome is more likely&rdquo; to &ldquo;a bad outcome fails the build&rdquo;." loading="lazy" src="https://vitaliisukach.dev/posts/your-ai-assistant-is-just-another-team-that-ignores-your-bounded-context/img/diagram-guardrails.jpg"></p>
<p>Prompts are suggestions, tests are guarantees. Turn the forbidden section of <code>AGENTS.md</code> into ArchUnit rules:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@AnalyzeClasses</span><span class="p">(</span><span class="n">packages</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;com.shop&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">importOptions</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ImportOption</span><span class="p">.</span><span class="na">DoNotIncludeTests</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">LoyaltyBoundaryTest</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">internalsStayInside</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">classes</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">resideInAnyPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty.entity..&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.domain.loyalty.repository..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeAccessed</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: use LoyaltyService&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">onlyServiceChangesAccount</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">methods</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">areDeclaredIn</span><span class="p">(</span><span class="n">LoyaltyAccount</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">and</span><span class="p">().</span><span class="na">haveNameMatching</span><span class="p">(</span><span class="s">&#34;set[A-Z].*&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeCalled</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain.loyalty.service..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: invariant 3&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">onlyListenersEarnPoints</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">methods</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">areDeclaredIn</span><span class="p">(</span><span class="n">LoyaltyService</span><span class="p">.</span><span class="na">class</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">and</span><span class="p">().</span><span class="na">haveName</span><span class="p">(</span><span class="s">&#34;earnForPaidOrder&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">onlyBeCalled</span><span class="p">().</span><span class="na">byClassesThat</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.listener..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;domain/loyalty/AGENTS.md: invariant 2&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ArchTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ArchRule</span><span class="w"> </span><span class="n">domainsDoNotDependOnAppLayer</span><span class="w"> </span><span class="o">=</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">noClasses</span><span class="p">().</span><span class="na">that</span><span class="p">().</span><span class="na">resideInAPackage</span><span class="p">(</span><span class="s">&#34;com.shop.domain..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">should</span><span class="p">().</span><span class="na">dependOnClassesThat</span><span class="p">().</span><span class="na">resideInAnyPackage</span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.controller..&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;com.shop.service..&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                            </span><span class="s">&#34;com.shop.dto..&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;com.shop.listener..&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                    </span><span class="p">.</span><span class="na">because</span><span class="p">(</span><span class="s">&#34;dependencies point one way: app layer -&gt; domain&#34;</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>(<code>classes</code>, <code>noClasses</code> and <code>methods</code> are static imports from <code>ArchRuleDefinition</code>.)</p>
<p>The <code>because()</code> text points back to <code>AGENTS.md</code>. When the AI breaks a rule, the failing build tells it which rule and where it&rsquo;s written. Most assistants will read that and fix the code on their own.</p>
<h2 id="takeaways">Takeaways</h2>
<ul>
<li>Treat the AI as a new team. It needs onboarding, not more detailed tickets.</li>
<li>Use the AI to discover the domain before you ask it to change it. The glossary and the leak list are useful even without AI.</li>
<li>Keep <code>AGENTS.md</code> next to the code it describes: language, invariants, public API, forbidden dependencies.</li>
<li>Ask for affected invariants before code, and review in a fresh session against the written rules.</li>
<li>Every rule you care about should end up as a test. Prompts are suggestions, tests are guarantees.</li>
</ul>
]]></content:encoded></item><item><title>5 JPA/Hibernate Mistakes That Quietly Kill Your Spring Boot Performance</title><link>https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/</link><pubDate>Sat, 07 Nov 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/</guid><description>Open Session in View, EAGER to-ones, in-memory pagination, deleteBy and read-only entities: 5 JPA defaults that only hurt with real data.</description><content:encoded><![CDATA[<p><em>Everything works in dev. Then production gets real data.</em></p>
<p><img alt="A cartoon bear waiter rushes tiny plates tagged &ldquo;3 ms&rdquo; out of a kitchen where a blue elephant relaxes, while a long line of customers waits at the door marked API" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-01.jpg"></p>
<p>Here&rsquo;s how it usually goes. Spring Boot app, Spring Data JPA, Postgres behind it. Every query in the log takes 3 ms. The database is bored. And yet the API is slow, the connection pool runs dry at lunchtime, and the nightly export job is still running at breakfast.</p>
<p>Nobody wrote a slow query. Hibernate just did a lot of things nobody asked it to do, very quickly, many times.</p>
<p>In <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">5 PostgreSQL Mistakes I See in Every Spring Boot App</a> I covered the database side, including the cartesian product you get from <code>JOIN FETCH</code> on several collections and <code>IDENTITY</code> quietly turning off batch inserts. This one is about the JPA side: five defaults and habits I find in almost every Spring Boot codebase I review, and what each of them actually makes Hibernate do.</p>
<p>The examples use Spring Boot 4, Hibernate ORM 7 and Java 21, with SQL logging on:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">logging.level.org.hibernate.SQL</span><span class="o">=</span><span class="s">DEBUG</span>
</span></span><span class="line"><span class="cl"><span class="na">logging.level.org.hibernate.orm.jdbc.bind</span><span class="o">=</span><span class="s">TRACE</span>
</span></span></code></pre></div><h3 id="mistake-1-leaving-open-session-in-view-on">Mistake 1: Leaving Open Session in View on</h3>
<p><img alt="Ten bears hold all ten DB connection keys while waiting on hold for the pricing service, as a bored elephant sits at reception and a queue of people waits" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-02.jpg"></p>
<p>Here&rsquo;s an endpoint that looks completely harmless:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@RestController</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@RequestMapping</span><span class="p">(</span><span class="s">&#34;/orders&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">OrderController</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">OrderService</span><span class="w"> </span><span class="n">orderService</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">PricingClient</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderController</span><span class="p">(</span><span class="n">OrderService</span><span class="w"> </span><span class="n">orderService</span><span class="p">,</span><span class="w"> </span><span class="n">PricingClient</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">orderService</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderService</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">this</span><span class="p">.</span><span class="na">pricingClient</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@GetMapping</span><span class="p">(</span><span class="s">&#34;/{id}&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">OrderView</span><span class="w"> </span><span class="nf">get</span><span class="p">(</span><span class="nd">@PathVariable</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderService</span><span class="p">.</span><span class="na">findOrder</span><span class="p">(</span><span class="n">id</span><span class="p">);</span><span class="w">                                   </span><span class="c1">// @Transactional, ~5 ms</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">delivery</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">pricingClient</span><span class="p">.</span><span class="na">estimateDelivery</span><span class="p">(</span><span class="n">order</span><span class="p">.</span><span class="na">getShippingCountry</span><span class="p">());</span><span class="w"> </span><span class="c1">// HTTP call, ~300 ms</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">return</span><span class="w"> </span><span class="n">OrderView</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">order</span><span class="p">,</span><span class="w"> </span><span class="n">delivery</span><span class="p">);</span><span class="w">                                     </span><span class="c1">// walks order.getItems()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The service method is <code>@Transactional(readOnly = true)</code> and does one <code>findById</code>. The transaction is over the moment it returns. So the connection goes back to the pool, right?</p>
<p>No. <code>spring.jpa.open-in-view</code> is <code>true</code> by default, so Spring registers an <code>OpenEntityManagerInViewInterceptor</code> for every web request. It opens the <code>EntityManager</code> when the request starts and closes it after the response is written. Spring also configures Hibernate to hold on to the JDBC connection once it has one, until the session closes. Here&rsquo;s the log:</p>
<pre tabindex="0"><code>select o1_0.id,o1_0.created_at,c1_0.id,c1_0.email,c1_0.name,o1_0.shipping_country,o1_0.status from orders o1_0 left join customers c1_0 on c1_0.id=o1_0.customer_id where o1_0.id=?
                                  -- transaction committed, connection still held
                                  -- ~300 ms waiting for the pricing service
select i1_0.order_id,i1_0.id,i1_0.price,i1_0.product_id,i1_0.quantity from order_items i1_0 where i1_0.order_id=?
</code></pre><p>The second query runs from <code>OrderView.from()</code> in the controller, outside any transaction, because the session is still open and the lazy <code>items</code> collection can still load. If you return the entity directly, Jackson does the same thing during serialization.</p>
<p>Now the arithmetic. The request does about 15 ms of SQL but holds a connection for about 320 ms. HikariCP&rsquo;s default pool has 10 connections, so the whole service tops out at 10 / 0.32 s ≈ <strong>31 requests per second</strong>. With the connection held only for the SQL it would be around 660. At 50 requests per second, threads start queueing for a connection, and 30 seconds later:</p>
<pre tabindex="0"><code>HikariPool-1 - Connection is not available, request timed out after 30000ms (total=10, active=10, idle=0, waiting=42)
</code></pre><p>Meanwhile, <code>pg_stat_activity</code> shows your ten connections as <code>idle</code>. The database isn&rsquo;t slow. It&rsquo;s waiting for you.</p>
<p><img alt="Request timeline: with Open Session in View the connection is held from the first query until the response is written, without it only during the service call" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/diagram-osiv.jpg"></p>
<p><strong>The fix:</strong> turn it off, and load everything the response needs inside the service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.open-in-view</span><span class="o">=</span><span class="s">false</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@EntityGraph</span><span class="p">(</span><span class="n">attributePaths</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="s">&#34;customer&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;items&#34;</span><span class="p">})</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Optional</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findWithCustomerAndItemsById</span><span class="p">(</span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="p">(</span><span class="n">readOnly</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="n">OrderDetails</span><span class="w"> </span><span class="nf">findOrder</span><span class="p">(</span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findWithCustomerAndItemsById</span><span class="p">(</span><span class="n">id</span><span class="p">).</span><span class="na">orElseThrow</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">OrderDetails</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">order</span><span class="p">);</span><span class="w">   </span><span class="c1">// map to a DTO while the session is still open</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>The first thing you&rsquo;ll see after switching it off is <code>LazyInitializationException</code> in places you didn&rsquo;t know were lazy-loading. That&rsquo;s the point. Each one is a hidden query that used to run from a controller or a JSON serializer. Fetch it explicitly in the service, and it stops being hidden.</p>
<p><strong>How to check your app:</strong></p>
<ul>
<li>If you never set the property, Spring Boot tells you at startup: <code>spring.jpa.open-in-view is enabled by default. Therefore, database queries may be performed during view rendering.</code></li>
<li>Compare HikariCP&rsquo;s <code>hikaricp.connections.usage</code> metric (how long a connection is held) with your SQL time. If usage is 10× the query time, something is holding connections.</li>
</ul>
<p><strong>Read more:</strong> <a href="https://docs.spring.io/spring-boot/reference/data/sql.html#data.sql.jpa-and-spring-data.open-entity-manager-in-view">Spring Boot reference: Open EntityManager in View</a></p>
<h3 id="mistake-2-trusting-the-default-fetch-type-on-manytoone">Mistake 2: Trusting the default fetch type on @ManyToOne</h3>
<p><img alt="A bear waits for a single envelope while a blue elephant delivers a chain of boxes: Payment, Order, Customer, Country" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-03.jpg"></p>
<p>Collections are lazy by default. To-one associations aren&rsquo;t. The JPA spec says <code>@ManyToOne</code> and <code>@OneToOne</code> are <code>EAGER</code> unless you say otherwise, and most entities I see never say otherwise:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Payment.java</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Table</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;payments&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Payment</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@GeneratedValue</span><span class="p">(</span><span class="n">strategy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GenerationType</span><span class="p">.</span><span class="na">SEQUENCE</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ManyToOne</span><span class="w">                          </span><span class="c1">// EAGER by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Enumerated</span><span class="p">(</span><span class="n">EnumType</span><span class="p">.</span><span class="na">STRING</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">PaymentStatus</span><span class="w"> </span><span class="n">status</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">BigDecimal</span><span class="w"> </span><span class="n">amount</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="c1">// Order.java</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Table</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;orders&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Order</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@GeneratedValue</span><span class="p">(</span><span class="n">strategy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GenerationType</span><span class="p">.</span><span class="na">SEQUENCE</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ManyToOne</span><span class="w">                          </span><span class="c1">// EAGER by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;customer_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Customer</span><span class="w"> </span><span class="n">customer</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@OneToMany</span><span class="p">(</span><span class="n">mappedBy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order&#34;</span><span class="p">)</span><span class="w">      </span><span class="c1">// LAZY by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">List</span><span class="o">&lt;</span><span class="n">OrderItem</span><span class="o">&gt;</span><span class="w"> </span><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ArrayList</span><span class="o">&lt;&gt;</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Enumerated</span><span class="p">(</span><span class="n">EnumType</span><span class="p">.</span><span class="na">STRING</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">String</span><span class="w"> </span><span class="n">shippingCountry</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">createdAt</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>paymentRepository.findById(42L)</code> gives you a chain of joins:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">select</span><span class="w"> </span><span class="n">p1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">p1_0</span><span class="p">.</span><span class="n">amount</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">created_at</span><span class="p">,</span><span class="n">c1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">c1_0</span><span class="p">.</span><span class="n">email</span><span class="p">,</span><span class="n">c1_0</span><span class="p">.</span><span class="n">name</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">shipping_country</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">status</span><span class="p">,</span><span class="n">p1_0</span><span class="p">.</span><span class="n">status</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">from</span><span class="w"> </span><span class="n">payments</span><span class="w"> </span><span class="n">p1_0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">left</span><span class="w"> </span><span class="k">join</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="n">o1_0</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=</span><span class="n">p1_0</span><span class="p">.</span><span class="n">order_id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">left</span><span class="w"> </span><span class="k">join</span><span class="w"> </span><span class="n">customers</span><span class="w"> </span><span class="n">c1_0</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="n">c1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=</span><span class="n">o1_0</span><span class="p">.</span><span class="n">customer_id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">where</span><span class="w"> </span><span class="n">p1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=?</span><span class="w">
</span></span></span></code></pre></div><p>For one row that&rsquo;s tolerable, and that&rsquo;s why nobody notices. But the chain grows every time someone adds a to-one anywhere above it. Add <code>Customer.country</code> and every <code>findById</code> on <code>Payment</code> now joins four tables.</p>
<p>The real damage shows up with a query. Here&rsquo;s a retry job that needs pending payments, just their IDs and amounts:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">List</span><span class="o">&lt;</span><span class="n">Payment</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findAllByStatus</span><span class="p">(</span><span class="n">PaymentStatus</span><span class="w"> </span><span class="n">status</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>JPQL doesn&rsquo;t turn <code>EAGER</code> mappings into joins. Hibernate runs the query you wrote, and then, because it promised to load <code>order</code> eagerly, it loads every order with a separate select:</p>
<pre tabindex="0"><code>select p1_0.id,p1_0.amount,p1_0.order_id,p1_0.status from payments p1_0 where p1_0.status=?
select o1_0.id,o1_0.created_at,c1_0.id,c1_0.email,c1_0.name,o1_0.shipping_country,o1_0.status from orders o1_0 left join customers c1_0 on c1_0.id=o1_0.customer_id where o1_0.id=?
select o1_0.id,o1_0.created_at,c1_0.id,c1_0.email,c1_0.name,o1_0.shipping_country,o1_0.status from orders o1_0 left join customers c1_0 on c1_0.id=o1_0.customer_id where o1_0.id=?
... 498 more
</code></pre><p>500 pending payments, <strong>501 queries</strong>, and the code never calls <code>getOrder()</code> once. It&rsquo;s N+1 without a single lazy load, which is why people don&rsquo;t recognize it.</p>
<p><strong>The fix:</strong> <code>LAZY</code> on every to-one, no exceptions, then fetch explicitly where you actually need the parent:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@ManyToOne</span><span class="p">(</span><span class="n">fetch</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">FetchType</span><span class="p">.</span><span class="na">LAZY</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">    select p from Payment p
</span></span></span><span class="line"><span class="cl"><span class="s">    join fetch p.order o
</span></span></span><span class="line"><span class="cl"><span class="s">    join fetch o.customer
</span></span></span><span class="line"><span class="cl"><span class="s">    where p.status = :status
</span></span></span><span class="line"><span class="cl"><span class="s">    &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">List</span><span class="o">&lt;</span><span class="n">Payment</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findAllWithOrderAndCustomerByStatus</span><span class="p">(</span><span class="n">PaymentStatus</span><span class="w"> </span><span class="n">status</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>Fetch-joining to-ones is cheap: still one row per payment, no multiplication. (Collections are a different story. That&rsquo;s the cartesian product from the PostgreSQL article.) And if hydration cost is new to you, <a href="/posts/when-one-fast-query-becomes-a-production-nightmare-the-dehydration-problem-in-hibernate/">The Dehydration Problem in Hibernate</a> explains why loading entities you don&rsquo;t use is expensive even when the SQL is fast.</p>
<p>One trap: on the inverse side of a <code>@OneToOne</code> (the one with <code>mappedBy</code>), Hibernate can&rsquo;t know whether the related row exists without querying, so it may load it eagerly even with <code>LAZY</code>. Map the association from the owning side only, or share the primary key with <code>@MapsId</code>.</p>
<p><strong>How to check your app:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">grep -rn -E <span class="s2">&#34;@(ManyToOne|OneToOne)&#34;</span> src/main/java <span class="p">|</span> grep -v <span class="s2">&#34;LAZY&#34;</span>
</span></span></code></pre></div><p>Then make the query count part of a test. Turn on statistics in the test profile:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.generate_statistics</span><span class="o">=</span><span class="s">true</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import static</span><span class="w"> </span><span class="nn">org.assertj.core.api.Assertions.assertThat</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">jakarta.persistence.EntityManagerFactory</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hibernate.SessionFactory</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hibernate.stat.Statistics</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.junit.jupiter.api.Test</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.springframework.beans.factory.annotation.Autowired</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.springframework.boot.test.context.SpringBootTest</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@SpringBootTest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">class</span> <span class="nc">PaymentQueryCountTest</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Autowired</span><span class="w"> </span><span class="n">PaymentRepository</span><span class="w"> </span><span class="n">paymentRepository</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Autowired</span><span class="w"> </span><span class="n">EntityManagerFactory</span><span class="w"> </span><span class="n">entityManagerFactory</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Test</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">void</span><span class="w"> </span><span class="nf">loadingPendingPaymentsIsOneQuery</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">Statistics</span><span class="w"> </span><span class="n">stats</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">entityManagerFactory</span><span class="p">.</span><span class="na">unwrap</span><span class="p">(</span><span class="n">SessionFactory</span><span class="p">.</span><span class="na">class</span><span class="p">).</span><span class="na">getStatistics</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">stats</span><span class="p">.</span><span class="na">clear</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">paymentRepository</span><span class="p">.</span><span class="na">findAllByStatus</span><span class="p">(</span><span class="n">PaymentStatus</span><span class="p">.</span><span class="na">PENDING</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">assertThat</span><span class="p">(</span><span class="n">stats</span><span class="p">.</span><span class="na">getPrepareStatementCount</span><span class="p">()).</span><span class="na">isEqualTo</span><span class="p">(</span><span class="n">1</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>I&rsquo;ll reuse this test for the next mistakes. It&rsquo;s the cheapest performance test you&rsquo;ll ever write.</p>
<p><strong>Read more:</strong> <a href="https://docs.hibernate.org/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#fetching">Hibernate ORM 7 User Guide: Fetching</a></p>
<h3 id="mistake-3-paginating-a-join-fetch-of-a-collection">Mistake 3: Paginating a JOIN FETCH of a collection</h3>
<p><img alt="A truck dumps a mountain of 500,000 boxes, and a bear picks 20 of them into a basket labeled Page 1 while the rest go into a dumpster" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-04.jpg"></p>
<p>An order list screen, 20 per page, with items, because the screen shows them:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">        select o from Order o
</span></span></span><span class="line"><span class="cl"><span class="s">        join fetch o.items
</span></span></span><span class="line"><span class="cl"><span class="s">        where o.status = :status
</span></span></span><span class="line"><span class="cl"><span class="s">        &#34;&#34;&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="n">countQuery</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;select count(o) from Order o where o.status = :status&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findWithItemsByStatus</span><span class="p">(</span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Pageable</span><span class="w"> </span><span class="n">pageable</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>Called with <code>PageRequest.of(0, 20, Sort.by(&quot;createdAt&quot;).descending())</code>. Here&rsquo;s the SQL:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">select</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">created_at</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">customer_id</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">shipping_country</span><span class="p">,</span><span class="n">o1_0</span><span class="p">.</span><span class="n">status</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="n">i1_0</span><span class="p">.</span><span class="n">order_id</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">id</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">price</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">product_id</span><span class="p">,</span><span class="n">i1_0</span><span class="p">.</span><span class="n">quantity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">from</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="n">o1_0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">join</span><span class="w"> </span><span class="n">order_items</span><span class="w"> </span><span class="n">i1_0</span><span class="w"> </span><span class="k">on</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">id</span><span class="o">=</span><span class="n">i1_0</span><span class="p">.</span><span class="n">order_id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">where</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">status</span><span class="o">=?</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">order</span><span class="w"> </span><span class="k">by</span><span class="w"> </span><span class="n">o1_0</span><span class="p">.</span><span class="n">created_at</span><span class="w"> </span><span class="k">desc</span><span class="w">
</span></span></span></code></pre></div><p>No <code>LIMIT</code>. No <code>OFFSET</code>. And that&rsquo;s deliberate: a <code>LIMIT 20</code> in SQL would cut rows, not orders. Twenty rows might be two orders with ten items each, or one order cut in half. So Hibernate fetches everything, builds every entity, and does the pagination in memory. The only trace is a warning:</p>
<pre tabindex="0"><code>WARN  HHH90003004: firstResult/maxResults specified with collection fetch; applying in memory
</code></pre><p>This is the behavior up to Hibernate 7.3. Starting with 7.4, the docs say the limit is applied in memory only when the database doesn&rsquo;t support <code>LIMIT</code> inside a subquery, so on newer versions check your SQL log before assuming you&rsquo;re affected.</p>
<p>With 50,000 open orders and 10 items each, page 1 of 20 orders loads <strong>500,000 rows</strong>. They go over the network, Hibernate hydrates 550,000 entities into the persistence context, keeps 20 orders, and throws the rest away. Page 2 costs exactly the same. In dev, with 30 orders, it&rsquo;s instant.</p>
<p><img alt="The database returns 500,000 rows, Hibernate builds every entity and keeps 20 for the page" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/diagram-pagination.jpg"></p>
<p><strong>The fix:</strong> page the IDs, then fetch the entities by ID.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;select o.id from Order o where o.status = :status&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findIdsByStatus</span><span class="p">(</span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Pageable</span><span class="w"> </span><span class="n">pageable</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;select o from Order o join fetch o.items where o.id in :ids&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">List</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findWithItemsByIdIn</span><span class="p">(</span><span class="n">Collection</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ids</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="p">(</span><span class="n">readOnly</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findOrders</span><span class="p">(</span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Pageable</span><span class="w"> </span><span class="n">pageable</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Page</span><span class="o">&lt;</span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="n">ids</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findIdsByStatus</span><span class="p">(</span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">pageable</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Map</span><span class="o">&lt;</span><span class="n">Long</span><span class="p">,</span><span class="w"> </span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">byId</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findWithItemsByIdIn</span><span class="p">(</span><span class="n">ids</span><span class="p">.</span><span class="na">getContent</span><span class="p">()).</span><span class="na">stream</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">.</span><span class="na">collect</span><span class="p">(</span><span class="n">Collectors</span><span class="p">.</span><span class="na">toMap</span><span class="p">(</span><span class="n">Order</span><span class="p">::</span><span class="n">getId</span><span class="p">,</span><span class="w"> </span><span class="n">Function</span><span class="p">.</span><span class="na">identity</span><span class="p">()));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">ids</span><span class="p">.</span><span class="na">map</span><span class="p">(</span><span class="n">byId</span><span class="p">::</span><span class="n">get</span><span class="p">);</span><span class="w">   </span><span class="c1">// keeps the sort order of the ID page</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Now the database does the paging:</p>
<pre tabindex="0"><code>select o1_0.id from orders o1_0 where o1_0.status=? order by o1_0.created_at desc offset ? rows fetch first ? rows only
select count(o1_0.id) from orders o1_0 where o1_0.status=?
select o1_0.id,...,i1_0.quantity from orders o1_0 join order_items i1_0 on o1_0.id=i1_0.order_id where o1_0.id in (?,?,?,...)
</code></pre><p>Three queries and about 200 rows instead of 500,000. Since Hibernate 6, duplicate roots from a fetch join are removed automatically, so you don&rsquo;t need <code>distinct</code> in the second query.</p>
<p>The other option is to not fetch-join the collection at all. Page the orders normally and let batch fetching load the items for the whole page in one <code>IN</code> query:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@BatchSize</span><span class="p">(</span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">50</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@OneToMany</span><span class="p">(</span><span class="n">mappedBy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">List</span><span class="o">&lt;</span><span class="n">OrderItem</span><span class="o">&gt;</span><span class="w"> </span><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ArrayList</span><span class="o">&lt;&gt;</span><span class="p">();</span><span class="w">
</span></span></span></code></pre></div><p>Or globally with <code>hibernate.default_batch_fetch_size</code>, which I covered in the <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">PostgreSQL article</a>.</p>
<p><strong>How to check your app:</strong> make Hibernate fail instead of warn, at least in tests:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.query.fail_on_pagination_over_collection_fetch</span><span class="o">=</span><span class="s">true</span>
</span></span></code></pre></div><p>And search your production logs for <code>HHH90003004</code> today. If it&rsquo;s there, it&rsquo;s been there for a while.</p>
<p><strong>Read more:</strong> <a href="https://docs.hibernate.org/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#hql-limit-offset">Hibernate ORM 7 User Guide: Limits and offsets</a></p>
<h3 id="mistake-4-deleting-with-derived-deleteby-methods">Mistake 4: Deleting with derived deleteBy&hellip;() methods</h3>
<p><img alt="At 4 AM a bear removes warehouse items one by one with tweezers under a counter reading 87,412 of 120,001, next to an untouched DELETE WHERE button" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-05.jpg"></p>
<p>I mentioned this one in the <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">PostgreSQL article</a>, from the database&rsquo;s point of view. Here&rsquo;s what happens before the <code>DELETE</code> even reaches the database.</p>
<p>The orders aggregate, mapped the way most aggregates are:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@OneToMany</span><span class="p">(</span><span class="n">mappedBy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">cascade</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">CascadeType</span><span class="p">.</span><span class="na">ALL</span><span class="p">,</span><span class="w"> </span><span class="n">orphanRemoval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">List</span><span class="o">&lt;</span><span class="n">OrderItem</span><span class="o">&gt;</span><span class="w"> </span><span class="n">items</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ArrayList</span><span class="o">&lt;&gt;</span><span class="p">();</span><span class="w">
</span></span></span></code></pre></div><p>And a nightly purge that reads like plain English:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">long</span><span class="w"> </span><span class="nf">deleteByCreatedAtBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">purgeOrdersOlderThan</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">deleteByCreatedAtBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Spring Data doesn&rsquo;t turn that into <code>DELETE ... WHERE</code>. It selects the orders, then calls <code>EntityManager.remove()</code> on each one. <code>remove()</code> cascades to <code>items</code>, and to cascade, Hibernate first has to load each collection. Then, at flush, every row gets its own <code>DELETE</code>:</p>
<pre tabindex="0"><code>select o1_0.id,o1_0.created_at,o1_0.customer_id,o1_0.shipping_country,o1_0.status from orders o1_0 where o1_0.created_at&lt;?
select i1_0.order_id,i1_0.id,i1_0.price,i1_0.product_id,i1_0.quantity from order_items i1_0 where i1_0.order_id=?
... 9,999 more
delete from order_items where id=?
... 99,999 more
delete from orders where id=?
... 9,999 more
</code></pre><p>For 10,000 orders with 10 items each, that adds up fast:</p>
<p><img alt="deleteByCreatedAtBefore runs 120,001 statements: 1 select of orders, 10,000 selects of items, 100,000 item deletes and 10,000 order deletes, while two bulk deletes run 2" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/diagram-delete.jpg"></p>
<p>Plus 110,000 managed entities in memory, plus every <code>@PreRemove</code> callback, plus an Envers audit row per deleted entity if you use Envers. Setting <code>hibernate.jdbc.batch_size</code> groups the deletes into fewer round trips, but the selects, the memory and the statement count stay the same. And on the Postgres side you now have 110,000 dead tuples to vacuum. <a href="/posts/your-delete-insert-is-burning-postgresqls-cpu-here-s-what-s-actually-happening-on-the-page/">Your DELETE + INSERT Is Burning PostgreSQL&rsquo;s CPU</a> shows what that does on the page.</p>
<p><strong>The fix:</strong> bulk deletes, children first:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Modifying</span><span class="p">(</span><span class="n">flushAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="n">clearAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">        delete from OrderItem i
</span></span></span><span class="line"><span class="cl"><span class="s">        where i.order.id in (select o.id from Order o where o.createdAt &lt; :cutoff)
</span></span></span><span class="line"><span class="cl"><span class="s">        &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="nf">deleteItemsOfOrdersCreatedBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Modifying</span><span class="p">(</span><span class="n">flushAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w"> </span><span class="n">clearAutomatically</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;delete from Order o where o.createdAt &lt; :cutoff&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="nf">deleteOrdersCreatedBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">purgeOrdersOlderThan</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">deleteItemsOfOrdersCreatedBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">deleteOrdersCreatedBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Two statements. But a bulk delete is fast precisely because it skips everything JPA normally does, so know what you&rsquo;re giving up:</p>
<ul>
<li><strong>No cascades.</strong> Nothing else gets deleted for you. If <code>payments</code> references <code>orders</code>, you get a foreign key violation, or orphans if there&rsquo;s no FK. Delete in the right order yourself, or let the database cascade: <code>ON DELETE CASCADE</code> on the FK plus <code>@OnDelete(action = OnDeleteAction.CASCADE)</code> on <code>OrderItem.order</code>, and then you only delete orders.</li>
<li><strong>No lifecycle callbacks.</strong> <code>@PreRemove</code>, entity listeners and Envers don&rsquo;t run. In regulated domains, where the audit trail is a compliance requirement, check with whoever owns that requirement before you switch.</li>
<li><strong>No persistence context.</strong> Entities already loaded in this session don&rsquo;t know they were deleted. <code>clearAutomatically = true</code> clears the context after the delete, and <code>flushAutomatically = true</code> writes pending changes first, so the clear doesn&rsquo;t throw them away.</li>
</ul>
<p>For millions of rows, delete in chunks instead of one giant statement. The PostgreSQL article has the pattern.</p>
<p><strong>How to check your app:</strong> <code>grep -rn -E &quot;(delete|remove)(All)?By|deleteAll\(&quot; src/main/java</code>, then run the statistics test from Mistake 2 around your purge with 3 orders of 2 items each. If <code>getPrepareStatementCount()</code> says 13 instead of 2, you&rsquo;ve found it.</p>
<p><strong>Read more:</strong> <a href="https://docs.spring.io/spring-data/jpa/reference/jpa/query-methods.html#jpa.modifying-queries.derived-delete">Spring Data JPA: Derived delete queries</a></p>
<h3 id="mistake-5-loading-managed-entities-just-to-read-them">Mistake 5: Loading managed entities just to read them</h3>
<p><img alt="A bear takes a polaroid of every box on a conveyor belt to CSV export, until the warehouse is buried in photos and the heap gauge hits 98%" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-06.jpg"></p>
<p>A nightly export: one day of orders to CSV. Streaming, so it must be memory-safe, right?</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">interface</span> <span class="nc">OrderRepository</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">JpaRepository</span><span class="o">&lt;</span><span class="n">Order</span><span class="p">,</span><span class="w"> </span><span class="n">Long</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">streamByCreatedAtBetween</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">to</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">streamByCreatedAtBefore</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">exportDay</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">to</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">streamByCreatedAtBetween</span><span class="p">(</span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">to</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">orders</span><span class="p">.</span><span class="na">forEach</span><span class="p">(</span><span class="n">order</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">csv</span><span class="p">.</span><span class="na">write</span><span class="p">(</span><span class="n">order</span><span class="p">.</span><span class="na">getId</span><span class="p">(),</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getStatus</span><span class="p">(),</span><span class="w"> </span><span class="n">order</span><span class="p">.</span><span class="na">getCreatedAt</span><span class="p">()));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Every <code>Order</code> you load is a managed entity. For each one, Hibernate keeps the entity itself, an entry in the persistence context, and a snapshot: a copy of every field&rsquo;s value at load time, used for dirty checking. The stream doesn&rsquo;t change that. Entities stay in the persistence context until the transaction ends, whether you still hold a reference or not.</p>
<p>So for 1,000,000 orders you hold <strong>2,000,000 objects</strong> (entities plus snapshots) until commit. Then the flush at commit compares every field of every entity against its snapshot, to update nothing. And if the loop runs any JPQL query, Hibernate auto-flushes before it, which means dirty-checking everything loaded so far. Every time. That&rsquo;s how a linear job becomes quadratic.</p>
<p><strong>The fix:</strong> read DTOs when you only read.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kd">record</span> <span class="nc">OrderExportRow</span><span class="p">(</span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">,</span><span class="w"> </span><span class="n">OrderStatus</span><span class="w"> </span><span class="n">status</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">createdAt</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span></span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">    select new com.example.orders.OrderExportRow(o.id, o.status, o.createdAt)
</span></span></span><span class="line"><span class="cl"><span class="s">    from Order o
</span></span></span><span class="line"><span class="cl"><span class="s">    where o.createdAt &gt;= :from and o.createdAt &lt; :to
</span></span></span><span class="line"><span class="cl"><span class="s">    &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@QueryHints</span><span class="p">(</span><span class="nd">@QueryHint</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">HibernateHints</span><span class="p">.</span><span class="na">HINT_FETCH_SIZE</span><span class="p">,</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;1000&#34;</span><span class="p">))</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">OrderExportRow</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">streamExportRows</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">Instant</span><span class="w"> </span><span class="n">to</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>No managed entities, no snapshots, no dirty checking. Memory stays flat. The fetch size matters too: without it, the Postgres JDBC driver reads the entire result set into memory before your stream sees the first row. (It only streams inside a transaction, with auto-commit off.)</p>
<p>The other tools, for the cases where you need entities:</p>
<ul>
<li><strong><code>@Transactional(readOnly = true)</code>.</strong> Spring marks the Hibernate session read-only and sets flush mode to manual, so entities load without snapshots and nothing is flushed at commit. They still sit in the persistence context, though. Good for normal read endpoints, not enough on its own for a million rows.</li>
<li><strong><code>flush()</code> + <code>clear()</code> every few hundred entities</strong> when the job modifies what it loads:</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Transactional</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">recalculateTotals</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="n">processed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">0</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Stream</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">streamByCreatedAtBefore</span><span class="p">(</span><span class="n">cutoff</span><span class="p">))</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">Order</span><span class="w"> </span><span class="n">order</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">Iterable</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="p">)</span><span class="w"> </span><span class="n">orders</span><span class="p">::</span><span class="n">iterator</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="n">order</span><span class="p">.</span><span class="na">recalculateTotal</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">++</span><span class="n">processed</span><span class="w"> </span><span class="o">%</span><span class="w"> </span><span class="n">500</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">entityManager</span><span class="p">.</span><span class="na">flush</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="n">entityManager</span><span class="p">.</span><span class="na">clear</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><ul>
<li><strong><code>StatelessSession</code></strong> for pure batch work: no persistence context, no snapshots, no cascades, no lazy loading. You call <code>update()</code> yourself, and it runs outside Spring&rsquo;s transaction management.</li>
</ul>
<p><strong>How to check your app:</strong> run the job in staging with statistics on and look at the session metrics Hibernate logs at the end:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.generate_statistics</span><span class="o">=</span><span class="s">true</span>
</span></span><span class="line"><span class="cl"><span class="na">logging.level.org.hibernate.engine.internal.StatisticalLoggingSessionEventListener</span><span class="o">=</span><span class="s">INFO</span>
</span></span></code></pre></div><p>For the export above, you&rsquo;ll see something like this:</p>
<pre tabindex="0"><code>Session Metrics {
    ...
    1843000000 nanoseconds spent executing 1 flushes (flushing a total of 1000000 entities and 1000000 collections);
}
</code></pre><p>If a read-only job flushes a million entities, it&rsquo;s loading entities it should be reading as DTOs.</p>
<p><strong>Read more:</strong> <a href="https://docs.spring.io/spring-data/jpa/reference/repositories/projections.html">Spring Data JPA: Projections</a></p>
<h3 id="bonus-lomboks-data-on-entities">Bonus: Lombok&rsquo;s @Data on entities</h3>
<p><img alt="A bear types log.debug(order) and an avalanche of boxes bursts out of the laptop, burying the elephant, with a counter showing 51 queries" loading="lazy" src="https://vitaliisukach.dev/posts/5-jpa-hibernate-mistakes-that-quietly-kill-your-spring-boot-performance/image-07.jpg"></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Table</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;orders&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Order</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* customer, items, ... */</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>Then, somewhere in a service:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">log</span><span class="p">.</span><span class="na">debug</span><span class="p">(</span><span class="s">&#34;Saving order {}&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">order</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p><code>@Data</code> generates a <code>toString()</code> that prints every field. Printing <code>items</code> initializes the lazy collection, and printing each item&rsquo;s lazy <code>product</code> initializes that too. An order with 50 items: <strong>51 queries from one log line</strong>. If <code>OrderItem</code> also has <code>@Data</code>, its <code>toString()</code> prints <code>order</code>, which prints <code>items</code>, which prints <code>order</code>, and you get a <code>StackOverflowError</code>. And all of this only happens when DEBUG is on, which is exactly when you&rsquo;re investigating a production problem.</p>
<p>The generated <code>equals()</code> and <code>hashCode()</code> are just as bad: they use every field, so they touch lazy associations, and the hash code changes when the ID is assigned on persist, which loses the entity inside a <code>HashSet</code>.</p>
<p>Use <code>@Getter</code> and <code>@Setter</code>, and write these three yourself:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">equals</span><span class="p">(</span><span class="n">Object</span><span class="w"> </span><span class="n">o</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="k">this</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">o</span><span class="p">)</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">true</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="p">(</span><span class="n">o</span><span class="w"> </span><span class="k">instanceof</span><span class="w"> </span><span class="n">Order</span><span class="w"> </span><span class="n">other</span><span class="p">))</span><span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">false</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span><span class="n">id</span><span class="p">.</span><span class="na">equals</span><span class="p">(</span><span class="n">other</span><span class="p">.</span><span class="na">getId</span><span class="p">());</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">hashCode</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">getClass</span><span class="p">().</span><span class="na">hashCode</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@Override</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="n">String</span><span class="w"> </span><span class="nf">toString</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="s">&#34;Order{id=&#34;</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="s">&#34;, status=&#34;</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">status</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="s">&#34;}&#34;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><strong>Read more:</strong> <a href="https://docs.hibernate.org/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#mapping-model-pojo-equalshashcode">Hibernate ORM 7 User Guide: Implementing equals() and hashCode()</a></p>
<h3 id="a-quick-checklist">A quick checklist</h3>
<ul>
<li>Is <code>spring.jpa.open-in-view=false</code> set explicitly?</li>
<li>Does every <code>@ManyToOne</code> and <code>@OneToOne</code> say <code>fetch = FetchType.LAZY</code>?</li>
<li>Is <code>HHH90003004</code> anywhere in your production logs?</li>
<li>Any derived <code>deleteBy...()</code> or <code>deleteAll()</code> on tables with more than a few thousand rows?</li>
<li>Do your export and batch jobs read DTOs, or a million managed entities?</li>
<li>Is there a query-count test for your three busiest endpoints?</li>
</ul>
<p>None of these are Hibernate bugs. Every one is a default, or a convenience method, doing exactly what it was designed to do, on data it was never tested with. If you fixed these and want the next layer down, <a href="/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/">5 PostgreSQL Mistakes I See in Every Spring Boot App</a> covers what the database does with the queries Hibernate sends, <a href="/posts/when-one-fast-query-becomes-a-production-nightmare-the-dehydration-problem-in-hibernate/">The Dehydration Problem in Hibernate</a> goes deep on hydration cost, and <a href="/posts/5-spring-boot-mistakes-i-see-in-every-codebase/">5 Spring Boot Mistakes I See in Every Codebase</a> covers the transaction boundaries all of this depends on.</p>
]]></content:encoded></item><item><title>5 PostgreSQL Mistakes I See in Every Spring Boot App</title><link>https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/</link><pubDate>Tue, 27 Oct 2026 10:00:00 +0000</pubDate><guid>https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/</guid><description>&lt;p>&lt;em>Your ORM is lying to you a little. Here&amp;rsquo;s where.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-01.jpg">&lt;/p>
&lt;p>Here&amp;rsquo;s how it usually goes. Spring Boot app, Spring Data JPA, Postgres behind it. Everything is fast in dev, because dev has 200 rows. Staging is fine too. Then production hits a few million rows and suddenly the database CPU is at 90%, a deploy hangs for ten minutes, and someone in Slack asks &amp;ldquo;did anyone change anything?&amp;rdquo;&lt;/p>
&lt;p>Usually nobody changed anything. The problem was there from day one, it just needed data to show up.&lt;/p></description><content:encoded><![CDATA[<p><em>Your ORM is lying to you a little. Here&rsquo;s where.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-01.jpg"></p>
<p>Here&rsquo;s how it usually goes. Spring Boot app, Spring Data JPA, Postgres behind it. Everything is fast in dev, because dev has 200 rows. Staging is fine too. Then production hits a few million rows and suddenly the database CPU is at 90%, a deploy hangs for ten minutes, and someone in Slack asks &ldquo;did anyone change anything?&rdquo;</p>
<p>Usually nobody changed anything. The problem was there from day one, it just needed data to show up.</p>
<p>I keep running into the same five issues in pretty much every Spring Boot + Postgres codebase I look at. None of them are exotic. They&rsquo;re all &ldquo;the defaults did something you didn&rsquo;t expect&rdquo; kind of problems. Let&rsquo;s go through them.</p>
<h3 id="mistake-1-assuming-postgres-indexes-your-foreign-keys">Mistake 1: Assuming Postgres indexes your foreign keys</h3>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-02.jpg"></p>
<p>Quick quiz. You have this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Entity</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Order</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@ManyToOne</span><span class="p">(</span><span class="n">fetch</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">FetchType</span><span class="p">.</span><span class="na">LAZY</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nd">@JoinColumn</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;customer_id&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kd">private</span><span class="w"> </span><span class="n">Customer</span><span class="w"> </span><span class="n">customer</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p>and the migration has <code>customer_id BIGINT REFERENCES customer(id)</code>. Is there an index on <code>order.customer_id</code>?</p>
<p>Nope.</p>
<p>Postgres automatically creates indexes for <code>PRIMARY KEY</code> and <code>UNIQUE</code> constraints, and that&rsquo;s it. A foreign key is just a constraint. It makes sure the referenced row exists, but it does nothing to make lookups by that column fast. If you came from MySQL this one hurts, because InnoDB <em>does</em> create an index for every foreign key, so lots of people just assume every database does.</p>
<p>Hibernate won&rsquo;t save you either. Even with <code>ddl-auto=update</code> (please don&rsquo;t do that in prod) it creates the FK constraint and no index.</p>
<p><strong>Where it bites you, part one: reads.</strong> Every <code>findByCustomerId</code>, every lazy load of <code>customer.getOrders()</code>, every join from customer to orders is a sequential scan on <code>order</code>. At 10k rows you won&rsquo;t notice. At 50 million you will.</p>
<p><strong>Where it bites you, part two: deletes.</strong> This is the sneaky one. When you delete a customer, Postgres has to check that no order still points to it. Internally it runs something like this for <strong>every deleted row</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="k">WHERE</span><span class="w"> </span><span class="n">customer_id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="err">$</span><span class="mi">1</span><span class="w"> </span><span class="k">FOR</span><span class="w"> </span><span class="k">KEY</span><span class="w"> </span><span class="k">SHARE</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>No index means a full scan of <code>order</code> per deleted customer. Delete 1,000 customers and you get 1,000 sequential scans of your biggest table. With <code>ON DELETE CASCADE</code> it&rsquo;s the same story, Postgres still has to find the child rows somehow. The worst part is that <code>EXPLAIN</code> on your <code>DELETE</code> won&rsquo;t show it, because the check runs inside a trigger. You just see a delete that &ldquo;randomly&rdquo; takes 40 seconds. (<code>EXPLAIN ANALYZE</code> does show trigger time at the bottom, look for <code>RI_ConstraintTrigger</code>.)</p>
<p><strong>The fix:</strong> Index your FK columns. Not necessarily all of them, a tiny lookup table that never gets deleted from is fine without one, but that should be a decision you actually made, not something you forgot.</p>
<p>Here&rsquo;s a query that finds foreign keys whose column isn&rsquo;t the leading column of any index (it covers single-column FKs, which is 95% of what JPA produces):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="k">c</span><span class="p">.</span><span class="n">conrelid</span><span class="p">::</span><span class="n">regclass</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="k">table_name</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="n">a</span><span class="p">.</span><span class="n">attname</span><span class="w">            </span><span class="k">AS</span><span class="w"> </span><span class="n">fk_column</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">c</span><span class="p">.</span><span class="n">conname</span><span class="w">            </span><span class="k">AS</span><span class="w"> </span><span class="k">constraint_name</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">FROM</span><span class="w"> </span><span class="n">pg_constraint</span><span class="w"> </span><span class="k">c</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">JOIN</span><span class="w"> </span><span class="n">pg_attribute</span><span class="w"> </span><span class="n">a</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">ON</span><span class="w"> </span><span class="n">a</span><span class="p">.</span><span class="n">attrelid</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">c</span><span class="p">.</span><span class="n">conrelid</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="n">a</span><span class="p">.</span><span class="n">attnum</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">c</span><span class="p">.</span><span class="n">conkey</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">WHERE</span><span class="w"> </span><span class="k">c</span><span class="p">.</span><span class="n">contype</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;f&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">AND</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">EXISTS</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="k">SELECT</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">pg_index</span><span class="w"> </span><span class="n">i</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="k">WHERE</span><span class="w"> </span><span class="n">i</span><span class="p">.</span><span class="n">indrelid</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">c</span><span class="p">.</span><span class="n">conrelid</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">AND</span><span class="w"> </span><span class="n">i</span><span class="p">.</span><span class="n">indkey</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">c</span><span class="p">.</span><span class="n">conkey</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="k">AND</span><span class="w"> </span><span class="n">i</span><span class="p">.</span><span class="n">indisvalid</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">ORDER</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>Run it on your prod database. I&rsquo;d honestly be surprised if it comes back empty.</p>
<p>Then add the indexes in a migration, and do it with <code>CONCURRENTLY</code> (more on why in mistake 5):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">CREATE</span><span class="w"> </span><span class="k">INDEX</span><span class="w"> </span><span class="n">CONCURRENTLY</span><span class="w"> </span><span class="n">idx_order_customer_id</span><span class="w"> </span><span class="k">ON</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="p">(</span><span class="n">customer_id</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><h3 id="mistake-2-fetching-the-whole-object-graph-in-one-query">Mistake 2: Fetching the whole object graph in one query</h3>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-03.jpg"></p>
<p>This one starts with good intentions. Someone reads about the N+1 problem, gets scared (fair), and decides everything should be loaded in one query.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Query</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">    SELECT o FROM Order o
</span></span></span><span class="line"><span class="cl"><span class="s">    JOIN FETCH o.items
</span></span></span><span class="line"><span class="cl"><span class="s">    JOIN FETCH o.payments
</span></span></span><span class="line"><span class="cl"><span class="s">    WHERE o.createdAt &gt; :since
</span></span></span><span class="line"><span class="cl"><span class="s">    &#34;&#34;&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">List</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="nf">findRecentWithEverything</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">since</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>First thing that happens: Hibernate throws <code>MultipleBagFetchException: cannot simultaneously fetch multiple bags</code>. Somebody googles it, the top answer says &ldquo;change <code>List</code> to <code>Set</code>&rdquo;, they do it, the exception goes away, and everyone moves on.</p>
<p>The exception was actually trying to help. Here&rsquo;s what the database sends back now. An order with 50 items and 20 payments isn&rsquo;t 1 row, or 71 rows. It&rsquo;s <strong>50 × 20 = 1,000 rows</strong>, because SQL joins multiply. Every item row gets repeated for every payment. Load 200 orders like that and Postgres is shipping 200,000 wide rows over the network, all carrying the same order columns again and again.</p>
<p>Then Hibernate has to deal with them. For every single row it reads the result set, builds the entity key, checks the persistence context, finds &ldquo;oh, I already have this one&rdquo;, and throws the duplicate away. That&rsquo;s what hydration costs: you pay CPU and memory for thousands of rows just to end up with a few hundred objects. I wrote a whole deep dive on this, <a href="/posts/when-one-fast-query-becomes-a-production-nightmare-the-dehydration-problem-in-hibernate/">The Dehydration Problem in Hibernate</a>, but the short version is this: <strong>the query looks fast in <code>pg_stat_statements</code> and your app is slow anyway</strong>, because the time goes into moving and deduplicating rows, not into executing the SQL.</p>
<p>And it grows with every join you add. Add <code>JOIN FETCH o.shipments</code> with 5 shipments and you&rsquo;re at 5,000 rows per order.</p>
<p><strong>The fix:</strong> Fetch at most one collection per query. Load the rest separately:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">List</span><span class="o">&lt;</span><span class="n">Order</span><span class="o">&gt;</span><span class="w"> </span><span class="n">orders</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findRecentWithItems</span><span class="p">(</span><span class="n">since</span><span class="p">);</span><span class="w">   </span><span class="c1">// JOIN FETCH items</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">orderRepository</span><span class="p">.</span><span class="na">findWithPayments</span><span class="p">(</span><span class="n">orders</span><span class="p">);</span><span class="w">                           </span><span class="c1">// JOIN FETCH payments WHERE o IN :orders</span><span class="w">
</span></span></span></code></pre></div><p>Since both queries run in the same persistence context, Hibernate fills <code>payments</code> into the <code>Order</code> instances it already has. You get two queries and 50 + 20 rows per order, instead of one query and 1,000 rows.</p>
<p>Even easier, turn on batch fetching globally and let lazy collections load in chunks:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.default_batch_fetch_size</span><span class="o">=</span><span class="s">50</span>
</span></span></code></pre></div><p>Now touching <code>order.getPayments()</code> loads payments for up to 50 orders in one <code>IN (...)</code> query. You get roughly N/50 queries instead of N+1, and no cartesian product.</p>
<p>And if this is a read-only screen or an API response, skip entities entirely and use a DTO projection. No persistence context, no dirty checking, no hydration of stuff you don&rsquo;t need.</p>
<p><strong>How to spot it:</strong> turn on <code>hibernate.generate_statistics</code> in staging and look for queries where rows fetched is way higher than entities loaded. Or look in <code>pg_stat_statements</code> for queries with a huge <code>rows / calls</code> ratio.</p>
<h3 id="mistake-3-treating-delete-as-free">Mistake 3: Treating DELETE as free</h3>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-04.jpg"></p>
<p>In your head, <code>DELETE</code> makes data go away. In Postgres it doesn&rsquo;t, at least not right away.</p>
<p>Because of <a href="/posts/mvcc-invisible-superpower-inside-every-query/">MVCC</a>, a deleted row stays on the page. Postgres just marks it as dead for transactions that start after yours. The space comes back only after vacuum cleans it up. Until then every index still points to it, sequential scans still read it, and the table is exactly as big as before.</p>
<p>So a few Spring patterns that look totally innocent are actually expensive.</p>
<p><strong><code>deleteAll()</code> and derived <code>deleteBy...</code> methods.</strong> Spring Data JPA&rsquo;s <code>deleteAll()</code> doesn&rsquo;t run <code>DELETE FROM table</code>. It loads every entity into memory and then removes them one by one. Same for <code>deleteByStatus(...)</code>: it selects first, then deletes each row separately, firing cascades and lifecycle callbacks on the way. For 100k rows that&rsquo;s 100k <code>DELETE</code> statements plus a heap full of entities.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">repository</span><span class="p">.</span><span class="na">deleteAll</span><span class="p">();</span><span class="w">          </span><span class="c1">// SELECT * + N deletes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">repository</span><span class="p">.</span><span class="na">deleteAllInBatch</span><span class="p">();</span><span class="w">   </span><span class="c1">// one DELETE statement</span><span class="w">
</span></span></span></code></pre></div><p>If you don&rsquo;t need the JPA lifecycle, use <code>deleteAllInBatch()</code> or a <code>@Modifying @Query(&quot;delete from ...&quot;)</code>.</p>
<p><strong>The &ldquo;replace the collection&rdquo; pattern.</strong> This one is everywhere:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="n">order</span><span class="p">.</span><span class="na">getItems</span><span class="p">().</span><span class="na">clear</span><span class="p">();</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="n">order</span><span class="p">.</span><span class="na">getItems</span><span class="p">().</span><span class="na">addAll</span><span class="p">(</span><span class="n">newItems</span><span class="p">);</span><span class="w">   </span><span class="c1">// with orphanRemoval = true</span><span class="w">
</span></span></span></code></pre></div><p>Every time the order is saved, Hibernate deletes all the old item rows and inserts new ones, even if 49 of the 50 items didn&rsquo;t change. That&rsquo;s 49 dead tuples and 49 new tuples for nothing, plus index entries for all of them. Do it on a hot path and you get a table that bloats constantly and autovacuum that never gets to rest. I measured exactly this, down to the page level, in <a href="/posts/your-delete-insert-is-burning-postgresqls-cpu-here-s-what-s-actually-happening-on-the-page/">Your DELETE + INSERT Is Burning PostgreSQL&rsquo;s CPU</a>. Spoiler: diffing the collection and only touching changed rows makes a huge difference.</p>
<p><strong>The nightly cleanup job.</strong> Everyone has one:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">DELETE</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">event_log</span><span class="w"> </span><span class="k">WHERE</span><span class="w"> </span><span class="n">created_at</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">now</span><span class="p">()</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="nb">interval</span><span class="w"> </span><span class="s1">&#39;90 days&#39;</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>As a single statement on a big table, this:</p>
<ul>
<li>creates millions of dead tuples in one go</li>
<li>writes a huge burst of WAL, so your replicas fall behind</li>
<li>holds one long transaction, and as long as it&rsquo;s open, vacuum can&rsquo;t clean dead rows anywhere in the database that are newer than its snapshot</li>
<li>then autovacuum kicks in on a giant table and chews CPU and I/O for an hour, right when morning traffic starts</li>
</ul>
<p><strong>The fix:</strong> Delete in batches, with each batch committed in its own transaction:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">purgeOldEvents</span><span class="p">(</span><span class="n">Instant</span><span class="w"> </span><span class="n">cutoff</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="kt">int</span><span class="w"> </span><span class="n">deleted</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">do</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="n">deleted</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">tx</span><span class="p">.</span><span class="na">execute</span><span class="p">(</span><span class="n">status</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">jdbc</span><span class="p">.</span><span class="na">update</span><span class="p">(</span><span class="s">&#34;&#34;&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">            DELETE FROM event_log
</span></span></span><span class="line"><span class="cl"><span class="s">            WHERE id IN (
</span></span></span><span class="line"><span class="cl"><span class="s">                SELECT id FROM event_log
</span></span></span><span class="line"><span class="cl"><span class="s">                WHERE created_at &lt; ?
</span></span></span><span class="line"><span class="cl"><span class="s">                LIMIT 5000
</span></span></span><span class="line"><span class="cl"><span class="s">            )
</span></span></span><span class="line"><span class="cl"><span class="s">            &#34;&#34;&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">Timestamp</span><span class="p">.</span><span class="na">from</span><span class="p">(</span><span class="n">cutoff</span><span class="p">)));</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w"> </span><span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">deleted</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="n">0</span><span class="p">);</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><p><code>tx</code> is a <code>TransactionTemplate</code>. Don&rsquo;t put <code>@Transactional</code> on the method, or the whole loop becomes one big transaction again and you&rsquo;re back where you started. And yes, <code>created_at</code> needs an index, otherwise every batch does a full scan.</p>
<p>For time-based data, the real fix is <strong>partitioning</strong>. Partition <code>event_log</code> by month, and cleanup becomes <code>DROP TABLE event_log_2026_07</code>. That&rsquo;s a metadata operation: no dead tuples, no vacuum, basically instant. If you&rsquo;re throwing away the whole table, <code>TRUNCATE</code> does the same thing for you.</p>
<p>And for tables that churn a lot, tune autovacuum per table instead of living with the defaults (which wait until 20% of the table is dead):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="n">order_item</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="p">(</span><span class="n">autovacuum_vacuum_scale_factor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">.</span><span class="mi">02</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>Keep an eye on <code>n_dead_tup</code> and <code>last_autovacuum</code> in <code>pg_stat_user_tables</code>. If dead tuples keep climbing and vacuum never catches up, you&rsquo;ve found your CPU problem.</p>
<h3 id="mistake-4-using-identity-and-wondering-why-batch-inserts-are-slow">Mistake 4: Using IDENTITY and wondering why batch inserts are slow</h3>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-05.jpg"></p>
<p>Every tutorial shows this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@GeneratedValue</span><span class="p">(</span><span class="n">strategy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GenerationType</span><span class="p">.</span><span class="na">IDENTITY</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>Works fine. Looks clean. And it silently <strong>turns off JDBC insert batching</strong>.</p>
<p>Here&rsquo;s why. With <code>IDENTITY</code> the database generates the id during the <code>INSERT</code>. But Hibernate needs the id as soon as you call <code>persist()</code>, because that&rsquo;s how it tracks the entity in the persistence context. So it can&rsquo;t queue inserts and send them in a batch. It has to run each insert right away and read back the generated key.</p>
<p>So you set <code>hibernate.jdbc.batch_size=50</code>, call <code>saveAll()</code> with 10,000 entities, and get&hellip; 10,000 separate round trips. The batch setting is just ignored. No warning, nothing in the logs unless you go looking.</p>
<p><strong>The fix:</strong> Switch to a sequence with a proper allocation size:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="nd">@Id</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@GeneratedValue</span><span class="p">(</span><span class="n">strategy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">GenerationType</span><span class="p">.</span><span class="na">SEQUENCE</span><span class="p">,</span><span class="w"> </span><span class="n">generator</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_seq&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="nd">@SequenceGenerator</span><span class="p">(</span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_seq&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">sequenceName</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&#34;order_id_seq&#34;</span><span class="p">,</span><span class="w"> </span><span class="n">allocationSize</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">50</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="kd">private</span><span class="w"> </span><span class="n">Long</span><span class="w"> </span><span class="n">id</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>Now Hibernate calls <code>nextval</code> once, gets a block of 50 ids, hands them out in memory, and can batch the inserts freely.</p>
<p>The important part: <strong>the database sequence has to use the same increment</strong>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">ALTER</span><span class="w"> </span><span class="n">SEQUENCE</span><span class="w"> </span><span class="n">order_id_seq</span><span class="w"> </span><span class="k">INCREMENT</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="mi">50</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>If they don&rsquo;t match, recent Hibernate versions refuse to start (which is good). Older ones would happily hand out overlapping ids across instances and you&rsquo;d find out from duplicate key errors in prod. Good news if your table uses <code>bigserial</code>: the sequence already exists (<code>&lt;table&gt;_&lt;column&gt;_seq</code>), you just point the generator at it and change the increment. No data migration needed.</p>
<p>Then turn batching on properly:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-properties" data-lang="properties"><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.jdbc.batch_size</span><span class="o">=</span><span class="s">50</span>
</span></span><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.order_inserts</span><span class="o">=</span><span class="s">true</span>
</span></span><span class="line"><span class="cl"><span class="na">spring.jpa.properties.hibernate.order_updates</span><span class="o">=</span><span class="s">true</span>
</span></span></code></pre></div><p>And add <code>reWriteBatchedInserts=true</code> to your JDBC URL. With it, the Postgres driver rewrites a batch into multi-row <code>INSERT ... VALUES (...), (...), (...)</code> statements, which is noticeably faster again.</p>
<pre tabindex="0"><code>jdbc:postgresql://db:5432/app?reWriteBatchedInserts=true
</code></pre><p>Yes, you&rsquo;ll get gaps in your ids when an instance restarts and throws away the rest of its block. That&rsquo;s fine. Ids are identifiers, not row counters. If someone needs them to have no gaps, that&rsquo;s a different column.</p>
<h3 id="mistake-5-migrations-that-lock-your-hottest-table">Mistake 5: Migrations that lock your hottest table</h3>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/5-postgresql-mistakes-i-see-in-every-spring-boot-app/image-06.jpg"></p>
<p>Flyway or Liquibase runs on startup, applies a migration, and the app starts. Easy. Until the migration is this:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="k">ADD</span><span class="w"> </span><span class="k">COLUMN</span><span class="w"> </span><span class="k">source</span><span class="w"> </span><span class="nb">VARCHAR</span><span class="p">(</span><span class="mi">50</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>That&rsquo;s harmless, right? On Postgres 11+ adding a nullable column is instant, it only touches metadata.</p>
<p>Except it still needs an <code>ACCESS EXCLUSIVE</code> lock on the table, even if just for a millisecond. And if a long-running query (say, a 3-minute analytics report) is reading from <code>order</code> at that moment, the <code>ALTER</code> has to wait. Here&rsquo;s the bad part: <strong>while it waits, every new query on <code>order</code> queues up behind it</strong>, even simple <code>SELECT</code>s. Lock requests in Postgres are first-come-first-served, so nothing can jump ahead of the waiting <code>ALTER</code>. Your one-millisecond migration just made the most important table in your system unavailable for three minutes.</p>
<p>In Kubernetes it gets worse. The new pod is stuck on the migration, the readiness probe fails, the liveness probe kills the pod, a new pod starts, tries the migration again, and the whole thing repeats.</p>
<p><strong>Always set a lock timeout in migrations:</strong></p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">SET</span><span class="w"> </span><span class="n">lock_timeout</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;5s&#39;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w"></span><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="k">ADD</span><span class="w"> </span><span class="k">COLUMN</span><span class="w"> </span><span class="k">source</span><span class="w"> </span><span class="nb">VARCHAR</span><span class="p">(</span><span class="mi">50</span><span class="p">);</span><span class="w">
</span></span></span></code></pre></div><p>If it can&rsquo;t get the lock within 5 seconds, it fails fast instead of taking production down with it. Retry the deploy when it&rsquo;s quieter.</p>
<p>Then there&rsquo;s the list of operations that are slow and locking on top of that:</p>
<p><strong><code>CREATE INDEX</code> without <code>CONCURRENTLY</code></strong> blocks all writes to the table for as long as the index takes to build. On a big table that can be many minutes. Use <code>CREATE INDEX CONCURRENTLY</code>. It&rsquo;s slower, but writes keep going. Catch: it can&rsquo;t run inside a transaction, and Flyway wraps every migration in one. Put it in its own migration file and Flyway will notice and run it outside a transaction (it refuses to mix it with other statements unless you set <code>mixed=true</code>). In Liquibase use <code>runInTransaction=&quot;false&quot;</code> on the changeset. If a concurrent build fails, it leaves an <code>INVALID</code> index behind, so drop it and try again.</p>
<p><strong>Adding <code>NOT NULL</code> to an existing column</strong> scans the whole table while holding <code>ACCESS EXCLUSIVE</code>. The safe way is in steps:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="k">ADD</span><span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">order_source_not_null</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="k">CHECK</span><span class="w"> </span><span class="p">(</span><span class="k">source</span><span class="w"> </span><span class="k">IS</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">)</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">VALID</span><span class="p">;</span><span class="w">           </span><span class="c1">-- instant
</span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="n">VALIDATE</span><span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">order_source_not_null</span><span class="p">;</span><span class="w">  </span><span class="c1">-- scans, but doesn&#39;t block writes
</span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="k">ALTER</span><span class="w"> </span><span class="k">COLUMN</span><span class="w"> </span><span class="k">source</span><span class="w"> </span><span class="k">SET</span><span class="w"> </span><span class="k">NOT</span><span class="w"> </span><span class="k">NULL</span><span class="p">;</span><span class="w">  </span><span class="c1">-- PG12+ uses the check, no scan
</span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="k">ALTER</span><span class="w"> </span><span class="k">TABLE</span><span class="w"> </span><span class="s2">&#34;order&#34;</span><span class="w"> </span><span class="k">DROP</span><span class="w"> </span><span class="k">CONSTRAINT</span><span class="w"> </span><span class="n">order_source_not_null</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></div><p>Same trick for new foreign keys: add with <code>NOT VALID</code>, then <code>VALIDATE CONSTRAINT</code> separately.</p>
<p><strong>Changing a column type</strong> (the classic <code>int</code> → <code>bigint</code> when you&rsquo;re about to run out of ids) rewrites the whole table under an exclusive lock. For a big table that means a new column, backfilling it in batches, and a swap. Not a one-line migration.</p>
<p><strong>Adding a column with a volatile default</strong> like <code>DEFAULT gen_random_uuid()</code> or <code>clock_timestamp()</code> also rewrites the table. Constant defaults are fine on Postgres 11+.</p>
<p>The general rule: before any migration touches a big table, ask two questions. &ldquo;What lock does this take?&rdquo; and &ldquo;Does this rewrite or scan the table?&rdquo; The <a href="https://www.postgresql.org/docs/current/sql-altertable.html">Postgres docs for ALTER TABLE</a> list the lock level for each operation, and it&rsquo;s worth five minutes of reading.</p>
<h3 id="a-quick-checklist">A quick checklist</h3>
<p><strong>Indexes</strong></p>
<ul>
<li>Did you run the missing FK index query on prod?</li>
<li>Are there <code>DELETE</code>s on parent tables that take way longer than they should?</li>
</ul>
<p><strong>Fetching</strong></p>
<ul>
<li>Any query with more than one <code>JOIN FETCH</code> on collections?</li>
<li>Did anyone &ldquo;fix&rdquo; <code>MultipleBagFetchException</code> by switching <code>List</code> to <code>Set</code>?</li>
<li>Is <code>default_batch_fetch_size</code> set?</li>
</ul>
<p><strong>Deletes</strong></p>
<ul>
<li>Are you calling <code>deleteAll()</code> or derived <code>deleteBy...</code> methods on big tables?</li>
<li>Do you <code>clear()</code> + <code>addAll()</code> collections with <code>orphanRemoval</code>?</li>
<li>Does your cleanup job delete everything in one statement?</li>
<li>What does <code>n_dead_tup</code> look like on your busiest tables?</li>
</ul>
<p><strong>Inserts</strong></p>
<ul>
<li>Are you using <code>GenerationType.IDENTITY</code> on entities you insert in bulk?</li>
<li>Does <code>allocationSize</code> match the sequence&rsquo;s <code>INCREMENT BY</code>?</li>
<li>Is <code>reWriteBatchedInserts=true</code> in your JDBC URL?</li>
</ul>
<p><strong>Migrations</strong></p>
<ul>
<li>Do your migrations set <code>lock_timeout</code>?</li>
<li>Does every <code>CREATE INDEX</code> on an existing table use <code>CONCURRENTLY</code>?</li>
<li>Does anyone review migrations for lock level before they merge?</li>
</ul>
<p>None of these mean your team did anything stupid. Spring Boot and Hibernate make the easy path really easy, and the easy path works great right up until you have real data. The good part is that every single fix here is small, can be done one table and one PR at a time, and you&rsquo;ll see the difference in your database CPU graph the same day.</p>
]]></content:encoded></item><item><title>Building an MCP Server in Java with Spring AI: Let Claude Code Use Your Database Without Seeing a Password</title><link>https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/</link><pubDate>Fri, 25 Sep 2026 14:46:28 +0000</pubDate><guid>https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/</guid><description>&lt;p>&lt;em>Four annotated methods, one security config, and no JSON-RPC code of your own.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-01.png">&lt;/p>
&lt;p>In my &lt;a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">previous article&lt;/a> I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.&lt;/p>
&lt;p>Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.&lt;/p></description><content:encoded><![CDATA[<p><em>Four annotated methods, one security config, and no JSON-RPC code of your own.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-01.png"></p>
<p>In my <a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">previous article</a> I built an MCP server from scratch in Python. I wrote the JSON-RPC 2.0 message handling, declared tool schemas by hand and wired up the STDIO transport myself. It’s a good way to learn how the protocol works on the wire.</p>
<p>Python isn’t the only option, though. Most of the systems I work on are Java and Spring, and that’s where the data lives. So this time I built the same kind of server in Java.</p>
<p>It turns out you don’t need to implement JSON-RPC yourself. Spring AI has a Boot starter for MCP servers. It handles the protocol, the transport, schema generation and tool registration. You write ordinary Spring beans and add a few annotations.</p>
<p>The full code is on GitHub: <a href="https://github.com/SukachVitally/mcp-demo">SukachVitally/mcp-demo</a>.</p>
<h3 id="why-bother-the-server-is-theboundary">Why bother: the server is the boundary</h3>
<p>The business logic here is deliberately boring. It’s a task list: you create tasks, move them through statuses, and finish or cancel them. Swap in your own domain; the MCP part stays the same.</p>
<p>The point is how Claude Code reaches the data:</p>
<pre tabindex="0"><code>Claude Code ──HTTP + API key──▶ MCP server (Spring) ──JDBC──▶ PostgreSQL
</code></pre><ul>
<li><strong>Claude never sees database credentials.</strong> The server holds the connection. Claude holds only an API key that works for the MCP endpoint and nothing else.</li>
<li><strong>Claude can only do what you expose.</strong> There’s no SQL console. If you don’t write a delete_task tool, tasks can&rsquo;t be deleted, however the prompt is phrased.</li>
<li><strong>Your validation and transactions still apply.</strong> Every call goes through the same service layer as the rest of your application.</li>
</ul>
<p>Giving an agent a database URL and a password is quick, but you can’t take it back. An MCP server gives the agent a small, typed and auditable API instead.</p>
<h3 id="what-werebuilding">What we’re building</h3>
<p>A PostgreSQL table of tasks. Each task has a name and one of four statuses: NEW, IN_PROGRESS, DONE or CANCELLED. The server exposes four tools:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-02.png"></p>
<p>Stack: Java 25, Spring Boot 4, Spring AI 2.0 MCP server, PostgreSQL 18 with Liquibase, and Spring Security.</p>
<h3 id="step-1-dependencies">Step 1: Dependencies</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/build.gradle"><em>build.gradle</em></a></p>
<pre tabindex="0"><code>dependencies {
    implementation &#39;org.springframework.boot:spring-boot-starter-data-jpa&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-liquibase&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-webmvc&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-security&#39;
    implementation &#39;org.springframework.boot:spring-boot-starter-validation&#39;
    implementation platform(&#39;org.springframework.ai:spring-ai-bom:2.0.1&#39;)
    implementation &#39;org.springframework.ai:spring-ai-starter-mcp-server-webmvc&#39;
    implementation &#39;org.springaicommunity:mcp-server-security-spring-boot:0.1.14&#39;
    runtimeOnly &#39;org.postgresql:postgresql&#39;
}
</code></pre><p>Two lines do the MCP work:</p>
<ul>
<li>spring-ai-starter-mcp-server-webmvc is the MCP server over HTTP on Spring MVC. There&rsquo;s a -webflux variant for reactive apps, and a plain spring-ai-starter-mcp-server for stdio.</li>
<li>mcp-server-security-spring-boot from the <a href="https://github.com/spring-ai-community/mcp-security">spring-ai-community/mcp-security</a> project adds API-key and OAuth2 support on top of Spring Security. We&rsquo;ll come back to it.</li>
</ul>
<h3 id="step-2-configure-theserver">Step 2: Configure the server</h3>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/resources/application.yaml"><em>application.yaml</em></a></p>
<pre tabindex="0"><code>spring:
  ai:
    mcp:
      server:
        protocol: STATELESS
        type: sync
        name: &#34;Task MCP demo&#34;
        instructions: &gt;-
          Manages a simple task list. Create tasks with add_task, look them up with get_task or
          get_task_list, and move them through the statuses NEW, IN_PROGRESS, DONE and CANCELLED
          with update_task_status.
        streamable-http:
          mcp-endpoint: /mcp
</code></pre><p>What these settings mean:</p>
<ul>
<li><strong>protocol: STATELESS</strong>: plain HTTP request and response, with no session kept between calls. Our tools never need to push anything back to the client, so we don&rsquo;t need sessions, and the server scales horizontally like any other REST service. Use STREAMABLE if you need server-to-client messages. The older SSE option is deprecated since Spring AI 2.0.</li>
<li><strong>type: sync</strong>: tools are ordinary blocking methods. With async, they return Reactor Mono/Flux types instead.</li>
<li><strong>instructions</strong>: sent to the client when it connects. It&rsquo;s the server&rsquo;s short explanation to the model of how the tools fit together. Treat it as part of the prompt.</li>
<li><strong>mcp-endpoint: /mcp</strong>: the URL that Claude Code will call.</li>
</ul>
<h3 id="step-3-business-logic-keep-itboring">Step 3: Business logic (keep it boring)</h3>
<p>Nothing here knows about MCP. It’s a normal JPA entity, repository and service:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/service/TaskService.java"><em>TaskService.java</em></a></p>
<pre tabindex="0"><code>@Service
@Validated
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class TaskService {
    public static final int NAME_MAX_LEN
GTH = 255;
    private final TaskRepository repository;
    private final TaskMapper mapper;
    @Transactional
    public TaskDto create(@NotBlank @Size(max = NAME_MAX_LENGTH) String name) {
        var entity = new TaskEntity();
        entity.setName(name);
        entity.setStatus(TaskStatus.NEW);
        return mapper.toDto(repository.save(entity));
    }
    @Transactional
    public TaskDto updateStatus(Long id, @NotNull TaskStatus status) {
        var entity = findEntity(id);
        entity.setStatus(status);
        return mapper.toDto(entity);
    }
    // get(id), getList(), findEntity(id) throws TaskNotFoundException ...
}
</code></pre><p>The service returns a small record, not the entity:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/dto/TaskDto.java"><em>TaskDto.java</em></a></p>
<pre tabindex="0"><code>public record TaskDto(Long id, String name, TaskStatus status) {}
</code></pre><p>That matters more than it looks. Whatever a tool returns is serialized and handed to the model, so the DTO decides exactly which fields leave your system.</p>
<h3 id="step-4-taskmcptool-the-actual-mcpserver">Step 4: TaskMcpTool, the actual MCP server</h3>
<p>This is the whole MCP layer:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/mcp/TaskMcpTool.java"><em>TaskMcpTool.java</em></a></p>
<pre tabindex="0"><code>@Component
@RequiredArgsConstructor
public class TaskMcpTool {
    private final TaskService service;
    @McpTool(name = &#34;add_task&#34;, description = &#34;Create a new task with status NEW and return it&#34;)
    public TaskDto add(@McpToolParam(description = &#34;Task name, 1-255 characters&#34;) String name) {
        return service.create(name);
    }
    @McpTool(name = &#34;get_task&#34;, description = &#34;Get a task by its id. Fails if the task does not exist&#34;)
    public TaskDto get(@McpToolParam(description = &#34;Task id&#34;) Long id) {
        return service.get(id);
    }
    @McpTool(name = &#34;update_task_status&#34;,
            description = &#34;Change the status of a task and return the updated task. Fails if the task does not exist&#34;)
    public TaskDto updateStatus(@McpToolParam(description = &#34;Task id&#34;) Long id,
                                @McpToolParam(description = &#34;New task status&#34;) TaskStatus status) {
        return service.updateStatus(id, status);
    }
    @McpTool(name = &#34;get_task_list&#34;, description = &#34;List all tasks&#34;)
    public List&lt;TaskDto&gt; getList() {
        return service.getList();
    }
}
</code></pre><p>Only a thin adapter: each method delegates to the service. Most of the work happens in the annotations.</p>
<h3 id="how-the-tools-get-registered">How the tools get registered</h3>
<p>The class is a plain @Component. When the application starts, Spring AI&rsquo;s annotation scanner finds every bean method annotated with @McpTool and registers it as an MCP tool. You don&rsquo;t need a registry, a ToolCallback list or any manual wiring. To add a tool, write another annotated method.</p>
<h3 id="mcptool-the-name-and-description-the-modelsees">@McpTool: the name and description the model sees</h3>
<ul>
<li><strong>name</strong> is the tool id the model calls. I use snake_case verbs (add_task, get_task_list) because that&rsquo;s the convention across MCP servers, and models pick such names up reliably. Without a name, the Java method name is used, and add on its own tells the model very little.</li>
<li><strong>description</strong> is the most important string in the class. It&rsquo;s the only thing the model reads when deciding which tool to call and what to expect back. Say what the tool does, what it returns and when it fails (&ldquo;Fails if the task does not exist&rdquo;). A vague description gives you a model that guesses.</li>
</ul>
<h3 id="mcptoolparam-the-schema-is-generated-foryou">@McpToolParam: the schema is generated for you</h3>
<p>Each parameter gets a description, and Spring AI builds a JSON Schema from the Java type. Here’s what the server actually returns for update_task_status when Claude Code asks for tools/list:</p>
<pre tabindex="0"><code>{
  &#34;name&#34;: &#34;update_task_status&#34;,
  &#34;description&#34;: &#34;Change the status of a task and return the updated task. Fails if the task does not exist&#34;,
  &#34;inputSchema&#34;: {
    &#34;type&#34;: &#34;object&#34;,
    &#34;properties&#34;: {
      &#34;id&#34;:     { &#34;type&#34;: &#34;integer&#34;, &#34;format&#34;: &#34;int64&#34;, &#34;description&#34;: &#34;Task id&#34; },
      &#34;status&#34;: { &#34;type&#34;: &#34;string&#34;,
                  &#34;enum&#34;: [&#34;NEW&#34;, &#34;IN_PROGRESS&#34;, &#34;DONE&#34;, &#34;CANCELLED&#34;],
                  &#34;description&#34;: &#34;New task status&#34; }
    },
    &#34;required&#34;: [&#34;id&#34;, &#34;status&#34;]
  }
}
</code></pre><p>Things to notice:</p>
<ul>
<li><strong>Long became</strong> <strong>integer with</strong> <strong>int64 format.</strong> You don&rsquo;t write any schema by hand.</li>
<li><strong>Parameters are required by default</strong> (required = true). Set @McpToolParam(required = false) for optional ones.</li>
<li><strong>The</strong> <strong>TaskStatus enum became a JSON</strong> <strong>enum.</strong> The model sees the four allowed values up front, so it can&rsquo;t invent a status like DELETED. If it tries, the call is rejected by schema validation before your method runs:</li>
</ul>
<pre tabindex="0"><code>Tool (update_task_status) input validation failed: ... /status: does not 
have a value in the enumeration [&#34;NEW&#34;, &#34;IN_PROGRESS&#34;, &#34;DONE&#34;, &#34;CANCELLED&#34;]
</code></pre><p>Use enums for anything with a fixed set of values. You get validation and documentation in one place.</p>
<h3 id="return-values-anderrors">Return values and errors</h3>
<p>You return a normal Java object, and Spring AI serializes it to JSON as the tool result. <code>TaskDto</code> and <code>List&lt;TaskDto&gt;</code> just work.</p>
<p>Exceptions work too. When TaskService throws TaskNotFoundException, the client doesn&rsquo;t get a stack trace or a broken JSON-RPC response. It gets a tool result with isError: true and the exception message as the text:</p>
<pre tabindex="0"><code>{ 
  &#34;content&#34;: [{ &#34;type&#34;: &#34;text&#34;, &#34;text&#34;: &#34;Task with id -1 is not found&#34; }], 
  &#34;isError&#34;: true 
}
</code></pre><p>That’s the behaviour you want: the model reads the message, understands what went wrong and can recover, for example by calling get_task_list to find the right id. Write exception messages for the model to read, not just for your logs.</p>
<p>The same applies to Bean Validation. A blank name fails @NotBlank in the service and comes back to the model as an error result, not a 500.</p>
<h3 id="a-tip-add-behaviour-hints">A tip: add behaviour hints</h3>
<p>If you look at the full tools/list response, every tool reports &ldquo;readOnlyHint&rdquo;: false, &ldquo;destructiveHint&rdquo;: true, including get_task_list. Those are the defaults. Clients such as Claude Code can use these hints to decide how cautious to be, so it&rsquo;s worth being honest about read-only tools:</p>
<pre tabindex="0"><code>@McpTool(name = &#34;get_task_list&#34;, description = &#34;List all tasks&#34;,
        annotations = @McpTool.McpAnnotations(readOnlyHint = true, 
                                              destructiveHint = false))
</code></pre><p>These are hints, not enforcement. What actually protects your data is the fact that the tool only reads.</p>
<h3 id="step-5-securityconfig-briefly">Step 5: SecurityConfig, briefly</h3>
<p>By default, an HTTP MCP endpoint is an unauthenticated JSON-RPC endpoint. Anyone who can reach /mcp can call your tools. The mcp-security library closes it with a few lines:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/main/java/org/example/mcpdemo/config/SecurityConfig.java"><em>SecurityConfig.java</em></a></p>
<pre tabindex="0"><code>@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http,
                                            ApiKeyEntityRepository&lt;ApiKeyEntityImpl&gt; apiKeyRepository) {
        return http
                .authorizeHttpRequests(auth -&gt; auth.anyRequest().authenticated())
                .with(mcpServerApiKey(), apiKey -&gt; apiKey.apiKeyRepository(apiKeyRepository))
                .build();
    }
    @Bean
    ApiKeyEntityRepository&lt;ApiKeyEntityImpl&gt; apiKeyRepository(@Value(&#34;${app.mcp.api-key.secret}&#34;) String secret) {
        var key = ApiKeyEntityImpl.builder()
                .name(&#34;demo key&#34;)
                .id(&#34;demo&#34;)
                .secret(secret)
                .build();
        return new InMemoryApiKeyEntityRepository&lt;&gt;(List.of(key));
    }
}
</code></pre><ul>
<li>mcpServerApiKey() plugs API-key authentication into the normal Spring Security filter chain.</li>
<li>The client sends an X-API-key header in the form <code>&lt;id&gt;.&lt;secret&gt;</code>, so <code>demo.&lt;your secret&gt;</code> here. Requests without it get 401.</li>
</ul>
<h3 id="step-6-run-it-and-connect-claudecode">Step 6: Run it and connect Claude Code</h3>
<p>Start PostgreSQL and the app:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/docker-compose.yaml"><em>docker-compose.yaml</em></a><em>,</em><a href="https://github.com/SukachVitally/mcp-demo/blob/main/.env.tpl"><em>.env.tpl</em></a><em>,</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/README.md"><em>README</em></a></p>
<pre tabindex="0"><code>cp .env.tpl .env          # sets MCP_API_KEY_SECRET
docker compose up -d
./gradlew bootRun
</code></pre><p>Register the server with Claude Code:</p>
<pre tabindex="0"><code>claude mcp add --transport http todos http://localhost:8080/mcp \
  --header &#34;X-API-key: demo.mcp-demo-test-secret&#34;
</code></pre><p>Then ask in plain language:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/building-an-mcp-server-in-java-with-spring-ai-let-claude-code-use-your-database-without-seeing-a/image-03.png"></p>
<p>“Add todo with name test” becomes an add_task call. &ldquo;Update task with id 1 to DONE&rdquo; becomes update_task_status with a valid enum value. Claude never saw a JDBC URL, a username or a password.</p>
<p>To inspect the server without Claude, use the MCP Inspector (npx @modelcontextprotocol/inspector). Choose the Streamable HTTP transport and add the same header.</p>
<h3 id="testing">Testing</h3>
<p>Because the server speaks standard MCP, the tests can use the official Java MCP client against a real server started by @SpringBootTest, with PostgreSQL in Testcontainers:</p>
<p><em>Source:</em> <a href="https://github.com/SukachVitally/mcp-demo/blob/main/src/test/java/org/example/mcpdemo/mcp/TaskMcpToolTest.java"><em>TaskMcpToolTest.java</em></a></p>
<pre tabindex="0"><code>var transport = HttpClientStreamableHttpTransport
        .builder(&#34;http://localhost:&#34; + port)
        .httpRequestCustomizer((builder, method, endpoint, body, context) -&gt;
                builder.header(&#34;X-API-key&#34;, &#34;demo.&#34; + API_KEY_SECRET))
        .build();
client = McpClient.sync(transport).build();
client.initialize();
var result = client.callTool(McpSchema.CallToolRequest.builder(&#34;get_task&#34;)
        .arguments(Map.of(&#34;id&#34;, -1L)).build());
assertThat(result.isError()).isTrue();
</code></pre><p>This covers the whole chain in one test: authentication, schema, serialization, error mapping and the database.</p>
<h3 id="takeaways">Takeaways</h3>
<ul>
<li><strong>You don’t write JSON-RPC in Java.</strong> spring-ai-starter-mcp-server-webmvc handles the protocol, the transport and tool discovery.</li>
<li><strong>An MCP tool is an annotated Spring bean method.</strong> @McpTool names and describes it, and @McpToolParam describes its inputs. The JSON Schema is generated from your Java types.</li>
<li><strong>Descriptions and error messages are prompts.</strong> The model reads them, so write them for the model.</li>
<li><strong>Use enums and DTOs</strong> to control what the model can send in and what it gets back.</li>
<li><strong>Secure the endpoint.</strong> API keys via mcp-security take ten lines, and OAuth2 is available when you need it.</li>
<li><strong>The MCP server is the security boundary.</strong> Claude Code works with your data through the operations you choose, never with your credentials.</li>
</ul>
<p>The Python version showed how MCP works on the wire. The Spring version shows how little code you need once a framework handles it. Take the repo, replace tasks with your own domain, and give your agent an API instead of a password.</p>
<p><strong>Links</strong></p>
<ul>
<li>Demo code: <a href="https://github.com/SukachVitally/mcp-demo">github.com/SukachVitally/mcp-demo</a></li>
<li>Spring AI MCP Server Boot Starter: <a href="https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html">docs.spring.io</a></li>
<li>MCP security for Spring: <a href="https://github.com/spring-ai-community/mcp-security/tree/main">github.com/spring-ai-community/mcp-security</a></li>
<li>Previous article, MCP in Python from scratch: <a href="https://medium.com/@sukach.v.v/mcp-the-protocol-that-finally-taught-ai-to-stop-being-useless-759de3745b79">MCP: The Protocol That Finally Taught AI to Stop Being Useless</a></li>
</ul>
]]></content:encoded></item></channel></rss>