<?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>Hibernate on Vitalii Sukach</title><link>https://vitaliisukach.dev/tags/hibernate/</link><description>Recent content in Hibernate on Vitalii Sukach</description><generator>Hugo</generator><language>en-us</language><lastBuildDate>Sat, 07 Nov 2026 10:00:00 +0000</lastBuildDate><atom:link href="https://vitaliisukach.dev/tags/hibernate/index.xml" rel="self" type="application/rss+xml"/><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>DateTime Handling in Java and PostgreSQL: A Practical Guide</title><link>https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/</link><pubDate>Sat, 15 Aug 2026 14:24:50 +0000</pubDate><guid>https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/</guid><description>&lt;p>&lt;em>Everything I wish someone had told me before I stored a meeting time in a&lt;/em> &lt;em>timestamp column.&lt;/em>&lt;/p>
&lt;p>&lt;img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-01.png">&lt;/p>
&lt;p>There is a specific kind of bug that only shows up in production, only in October, and only for users in one country. It gets closed as “not reproducible” twice before someone finally sits down with a coffee and reads the column definition.&lt;/p>
&lt;p>It is almost always a datetime bug.&lt;/p>
&lt;p>The frustrating part is that both Java and PostgreSQL have &lt;em>excellent&lt;/em> date/time support. java.time is one of the best-designed APIs in the JDK. PostgreSQL&amp;rsquo;s temporal types are precise and well documented. The bugs happen at the seam — in the assumptions each side makes about what the other means, and in the two or three words in the type names that mean the opposite of what you&amp;rsquo;d guess.&lt;/p></description><content:encoded><![CDATA[<p><em>Everything I wish someone had told me before I stored a meeting time in a</em> <em>timestamp column.</em></p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-01.png"></p>
<p>There is a specific kind of bug that only shows up in production, only in October, and only for users in one country. It gets closed as “not reproducible” twice before someone finally sits down with a coffee and reads the column definition.</p>
<p>It is almost always a datetime bug.</p>
<p>The frustrating part is that both Java and PostgreSQL have <em>excellent</em> date/time support. java.time is one of the best-designed APIs in the JDK. PostgreSQL&rsquo;s temporal types are precise and well documented. The bugs happen at the seam — in the assumptions each side makes about what the other means, and in the two or three words in the type names that mean the opposite of what you&rsquo;d guess.</p>
<p>This guide walks through both models, then spends real time on the part that actually causes outages: time zones.</p>
<p>Every code output and query result below was executed — Java 21 and PostgreSQL 16 — not written from memory.</p>
<h3 id="part-1-the-javaside">Part 1: The Java Side</h3>
<h4 id="ask-three-questions-get-onetype">Ask three questions, get one type</h4>
<p>Every java.time class is an answer to some combination of three questions:</p>
<ol>
<li>Do I know the <strong>date</strong>?</li>
<li>Do I know the <strong>time of day</strong>?</li>
<li>Do I know which <strong>point on the global timeline</strong> this is?</li>
</ol>
<p>That last one is the important one, and it’s the one people skip. Here’s the map:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-02.png"></p>
<p>The single most useful sentence in this article: <strong>LocalDateTime is not a point in time.</strong> 2026-08-15T12:00 is twelve o&rsquo;clock <em>somewhere</em>, and until you say where, it refers to a 26-hour-wide smear across the planet. If you have an Instant and you call .toLocalDateTime(), you have thrown away information and the compiler will not warn you.</p>
<h4 id="instant-is-the-boring-correctdefault">Instant is the boring, correct default</h4>
<pre tabindex="0"><code>Instant now = Instant.now();     // 2026-08-15T10:00:00.123456789Z
</code></pre><p>An Instant is nanoseconds since the epoch. No zone, no offset, no calendar. When it prints with a Z, that isn&rsquo;t a stored time zone — it&rsquo;s the ISO-8601 way of rendering an epoch value.</p>
<p>Anything that <em>happened</em> — a login, a payment, a row insert — is an Instant. Reach for something else only when you have a reason.</p>
<h4 id="zoneid-vs-zoneoffset-not-the-samething">ZoneId vs ZoneOffset: not the same thing</h4>
<p>This distinction matters more than any other in this article.</p>
<pre tabindex="0"><code>ZoneId.of(&#34;Europe/London&#34;)  // -&gt; java.time.ZoneRegion
ZoneId.of(&#34;+01:00&#34;)         // -&gt; java.time.ZoneOffset
</code></pre><p>A <strong>ZoneOffset</strong> is a fixed number of hours and minutes from UTC. +01:00. That&rsquo;s the whole thing. It&rsquo;s a fact about one moment.</p>
<p>A <strong>ZoneId</strong> (specifically a ZoneRegion, like Europe/London) is a <em>rulebook</em>. It knows that London was +00:00 in January, +01:00 in August, and it knows the exact instants at which it flips — going back decades and forward as far as legislators have declared.</p>
<p>ZoneOffset is a value. ZoneId is a function from instant to offset. Confusing them is the root cause of most scheduling bugs.</p>
<h4 id="offsetdatetime-vs-zoneddatetime">OffsetDateTime vs ZonedDateTime</h4>
<p>Both identify a real instant. The difference is what survives.</p>
<pre tabindex="0"><code>ZonedDateTime nyc = ZonedDateTime.of(2026, 7, 4, 12, 0, 0, 0,
                                     ZoneId.of(&#34;America/New_York&#34;));
nyc                    // 2026-07-04T12:00-04:00[America/New_York]
nyc.toOffsetDateTime() // 2026-07-04T12:00-04:00
nyc.toInstant()        // 2026-07-04T16:00:00Z
</code></pre><p>All three describe the same moment. But the ZonedDateTime still knows it&rsquo;s in New York, so if you add six months to it, it will correctly land on -05:00. The OffsetDateTime has been flattened — it remembers <em>that</em> the offset was -04:00, not <em>why</em>. Add six months and you get a wrong wall-clock time.</p>
<p>Rule of thumb: ZonedDateTime for calculating, OffsetDateTime for transporting, Instant for storing.</p>
<h4 id="duration-vsperiod">Duration vs Period</h4>
<pre tabindex="0"><code>LocalDate.of(2026, 1, 31).plusMonths(1)  // 2026-02-28
</code></pre><p>Duration is exact elapsed time — seconds and nanos. Period is calendar time — years, months, days. &ldquo;One month&rdquo; is not a fixed number of seconds, and plusMonths clamps rather than overflowing. Both behaviors are correct; mixing them up is not.</p>
<p>This distinction resurfaces the moment DST enters the picture, and we’ll come back to it.</p>
<h4 id="a-word-on-the-oldapi">A word on the old API</h4>
<p>java.util.Date is a mislabeled Instant (it has no time zone despite what toString() implies). Calendar is mutable and lenient. java.sql.Timestamp extends java.util.Date and adds nanoseconds while breaking the equals contract.</p>
<p>If you’re on a legacy codebase, convert at the boundary and never let them into your domain:</p>
<pre tabindex="0"><code>Instant i = oldDate.toInstant();
Date    d = Date.from(instant);
</code></pre><h3 id="part-2-the-postgresql-side">Part 2: The PostgreSQL Side</h3>
<h4 id="timestamptz-does-not-store-a-timezone">timestamptz does not store a time zone</h4>
<p>This is the single biggest source of confusion, and it comes straight from the type name. TIMESTAMP WITH TIME ZONE is an 8-byte value. So is TIMESTAMP WITHOUT TIME ZONE. There is no room in there for a zone, and PostgreSQL doesn&rsquo;t try:</p>
<pre tabindex="0"><code>SELECT pg_column_size(&#39;2026-08-15 12:00:00&#39;::timestamp)     AS ts_bytes,     
       --  8
       pg_column_size(&#39;2026-08-15 12:00:00+02&#39;::timestamptz) AS tstz_bytes,  
       --  8
       pg_column_size(&#39;12:00:00+02&#39;::timetz)                 AS timetz_bytes; 
       -- 12
</code></pre><p>What timestamptz actually does is <strong>convert to UTC on write and convert back on read</strong>. The offset you supplied on input is used and then discarded. From the <a href="https://www.postgresql.org/docs/current/datatype-datetime.html">official docs</a>:</p>
<blockquote>
<p><em>In either case, the value is stored internally as UTC, and the originally stated or assumed time zone is not retained.</em></p></blockquote>
<p>A better mental model: timestamptz is Instant. timestamp is LocalDateTime. The names lie; the semantics don&rsquo;t.</p>
<h4 id="the-demo-that-makes-itclick">The demo that makes it click</h4>
<p>Insert the same two literals into both column types, with the session zone set to London:</p>
<pre tabindex="0"><code>SET TimeZone = &#39;Europe/London&#39;;
CREATE TABLE t (id int, ts timestamp, tstz timestamptz);
INSERT INTO t VALUES (1, &#39;2026-08-15 12:00:00&#39;,    &#39;2026-08-15 12:00:00&#39;);
INSERT INTO t VALUES (2, &#39;2026-08-15 12:00:00+00&#39;, &#39;2026-08-15 12:00:00+00&#39;);
SELECT * FROM t;
</code></pre><pre tabindex="0"><code> id |         ts          |          tstz
----+---------------------+------------------------
  1 | 2026-08-15 12:00:00 | 2026-08-15 12:00:00+01
  2 | 2026-08-15 12:00:00 | 2026-08-15 13:00:00+01
</code></pre><p>Two things happened. Row 1’s tstz had no offset, so PostgreSQL <em>assumed</em> the session zone. Row 2&rsquo;s explicit +00 was honoured and re-rendered as 13:00+01. Meanwhile the ts column ignored the offset entirely and stored the digits.</p>
<p>Now reconnect from New York and run the identical SELECT:</p>
<pre tabindex="0"><code> id |         ts          |          tstz
----+---------------------+------------------------
  1 | 2026-08-15 12:00:00 | 2026-08-15 07:00:00-04
  2 | 2026-08-15 12:00:00 | 2026-08-15 08:00:00-04
</code></pre><p>The tstz column re-renders per client. The ts column is frozen. <strong>Neither row changed on disk.</strong></p>
<p>That last point deserves emphasis, because it’s where the panic starts: when a developer sees a different value than QA saw, the instinct is “the data is corrupted.” It isn’t. Two clients with different TimeZone settings are looking at the same UTC value through different windows.</p>
<h4 id="at-time-zone-runs-bothways">AT TIME ZONE runs both ways</h4>
<p>AT TIME ZONE is the one operator you need, and its behavior flips depending on the input type:</p>
<pre tabindex="0"><code>-- timestamptz -&gt; timestamp: &#34;what does the clock read there?&#34;
SELECT &#39;2026-08-15 12:00:00+00&#39;::timestamptz AT TIME ZONE &#39;Asia/Tokyo&#39;;
-- 2026-08-15 21:00:00   (type: timestamp without time zone)
</code></pre><pre tabindex="0"><code>-- timestamp -&gt; timestamptz: &#34;this wall clock reading WAS in Tokyo&#34;
SELECT &#39;2026-08-15 12:00:00&#39;::timestamp AT TIME ZONE &#39;Asia/Tokyo&#39;;
-- 2026-08-15 03:00:00+00   (type: timestamp with time zone)
</code></pre><p>One removes zone context, the other attaches it. Read it as “interpret this value in that zone.” The function form timezone(&lsquo;Asia/Tokyo&rsquo;, value) is identical.</p>
<h4 id="the-rest-of-thefamily">The rest of the family</h4>
<ul>
<li><strong>date</strong> — 4 bytes, no zone, no ambiguity. Great for things that are genuinely dates.</li>
<li><strong>time</strong> — time of day, no zone.</li>
<li><strong>timetz</strong> — 12 bytes, and <a href="https://www.postgresql.org/docs/current/datatype-datetime.html">PostgreSQL itself recommends against it</a>. A time of day with an offset but no date can&rsquo;t resolve DST, so it&rsquo;s not meaningfully anchored. It won&rsquo;t even accept a zone name:</li>
</ul>
<pre tabindex="0"><code>SELECT &#39;12:00:00 Europe/London&#39;::timetz; -- ERROR: invalid input syntax for type time with time zone
</code></pre><ul>
<li><strong>interval</strong> — 16 bytes storing months, days, and microseconds <em>separately</em>, which is exactly why it can be DST-aware.</li>
</ul>
<h4 id="now-vs-localtimestamp">now() vs localtimestamp</h4>
<pre tabindex="0"><code>SELECT pg_typeof(now()),            -- timestamp with time zone
       pg_typeof(current_timestamp), -- timestamp with time zone
       pg_typeof(localtimestamp),    -- timestamp without time zone
       pg_typeof(current_date);      -- date
</code></pre><p>now() and current_timestamp are timestamptz and are safe. localtimestamp and current_date are evaluated in the session zone, which means a DEFAULT current_date column produces different answers for different clients. Be deliberate.</p>
<h4 id="so-which-do-youpick">So which do you pick?</h4>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-03.png"></p>
<p>The short version: <strong>use</strong> <strong>timestamptz for essentially everything.</strong> Reach for timestamp only when you genuinely mean a floating wall-clock time that must not shift — &ldquo;the store opens at 09:00 local, whatever local means at that branch&rdquo; — and store the zone ID beside it.</p>
<h3 id="part-3-time-zonesproperly">Part 3: Time Zones, Properly</h3>
<p>This is where the real complexity lives, so let’s slow down.</p>
<h4 id="three-things-called-timezone">Three things called “time zone”</h4>
<ol>
<li><strong>An offset</strong> — +01:00. A number.</li>
<li><strong>An IANA zone ID</strong> — Europe/London. A named set of historical and future rules. PostgreSQL ships ~499 of these in pg_timezone_names; Java reads the same tzdata.</li>
<li><strong>An abbreviation</strong> — EST, BST, IST. Ambiguous, unversioned, and a trap.</li>
</ol>
<p>That third one is genuinely dangerous:</p>
<pre tabindex="0"><code>SELECT &#39;2026-08-15 12:00:00 EST&#39;::timestamptz,               -- 2026-08-15 17:00:00+00
       &#39;2026-08-15 12:00:00 America/New_York&#39;::timestamptz;  -- 2026-08-15 16:00:00+00
</code></pre><p>One hour apart. EST is a <em>fixed</em> -05:00 in PostgreSQL — it does not mean &ldquo;Eastern time,&rdquo; it means &ldquo;Eastern Standard Time, always.&rdquo; In August, New York is on -04:00. If you accept zone abbreviations from user input, you have already shipped a bug. (IST is worse — it can mean India, Ireland, or Israel depending on who you ask.)</p>
<p><strong>Always use full IANA names.</strong></p>
<p>Offsets aren’t zones either. Nepal is +05:45; the Chatham Islands are +12:45:</p>
<pre tabindex="0"><code>ZonedDateTime.of(2026,8,15,12,0,0,0, ZoneId.of(&#34;Asia/Kathmandu&#34;))
// 2026-08-15T12:00+05:45[Asia/Kathmandu]
</code></pre><p>If your API contract says “offset in whole hours,” it’s wrong.</p>
<h3 id="where-postgresqls-session-zone-comesfrom">Where PostgreSQL’s session zone comes from</h3>
<p>The TimeZone GUC is a <strong>per-connection setting</strong>. Its value is decided by, in order: an explicit SET TimeZone, the connection&rsquo;s startup parameters, the postgresql.conf value, and finally the server&rsquo;s OS zone.</p>
<p>That last fallback is why the same query returns different results on a developer laptop and in CI. And with connection pooling, SET TimeZone on a borrowed connection leaks to whoever gets it next.</p>
<p>Pin it. Set timezone = &lsquo;UTC&rsquo; in postgresql.conf, and add it to the JDBC URL so it survives pool reuse:</p>
<pre tabindex="0"><code>jdbc:postgresql://host:5432/db?options=-c%20TimeZone%3DUTC
</code></pre><p>Then make the client responsible for rendering. Formatting a timestamp for a human is a presentation concern, not a database one.</p>
<h4 id="the-spring-forward-gap">The spring-forward gap</h4>
<p>On 29 March 2026, London jumps from 01:00 to 02:00. The local times between them <strong>do not exist</strong>.</p>
<p>Ask Java for one anyway:</p>
<pre tabindex="0"><code>LocalDateTime gap = LocalDateTime.of(2026, 3, 29, 1, 30);
gap.atZone(ZoneId.of(&#34;Europe/London&#34;));
// 2026-03-29T02:30+01:00[Europe/London]
ZoneId.of(&#34;Europe/London&#34;).getRules().getTransition(gap);
// Transition[Gap at 2026-03-29T01:00Z to +01:00]
</code></pre><p>Java doesn’t throw. It silently pushes the value forward by the length of the gap. PostgreSQL does the same thing:</p>
<pre tabindex="0"><code>SET TimeZone=&#39;Europe/London&#39;;
SELECT &#39;2026-03-29 01:30:00&#39;::timestamptz;
-- 2026-03-29 02:30:00+01
</code></pre><p>Both are “correct” — but neither told you. If a user sets a 01:30 alarm on that date, you should be validating with getTransition() and telling them, not letting the platform quietly reschedule.</p>
<h4 id="the-fall-back-overlapwhere-java-and-postgresql-disagree">The fall-back overlap — where Java and PostgreSQL disagree</h4>
<p>On 25 October 2026, London goes from 02:00 back to 01:00. Local times between 01:00 and 02:00 happen <strong>twice</strong>, one hour apart.</p>
<p>Java’s rules expose both:</p>
<pre tabindex="0"><code>ZoneId london = ZoneId.of(&#34;Europe/London&#34;);
LocalDateTime overlap = LocalDateTime.of(2026, 10, 25, 1, 30);
london.getRules().getValidOffsets(overlap);
// [+01:00, Z]
ZonedDateTime earlier = overlap.atZone(london);
// 2026-10-25T01:30+01:00[Europe/London]  instant = 2026-10-25T00:30:00Z
ZonedDateTime later = earlier.withLaterOffsetAtOverlap();
// 2026-10-25T01:30Z[Europe/London]       instant = 2026-10-25T01:30:00Z
</code></pre><p>Java’s default for an ambiguous local time is the <strong>earlier</strong> offset — 00:30Z.</p>
<p>Now ask PostgreSQL the same question:</p>
<pre tabindex="0"><code>SELECT &#39;2026-10-25 01:30:00&#39;::timestamp AT TIME ZONE &#39;Europe/London&#39;;
-- 2026-10-25 01:30:00+00
</code></pre><p>PostgreSQL picked 01:30Z — the <strong>later</strong> one.</p>
<p>Same input, same tzdata, one hour apart. If your application resolves an ambiguous local time in Java and your reporting job resolves it in SQL, they will disagree for one hour, twice a year, in every DST zone.</p>
<p>There is no clever fix. The lesson is: <strong>never let a</strong> <strong>LocalDateTime cross the boundary and get resolved on the other side.</strong> Resolve to an Instant in exactly one place, with explicit overlap handling, and send the instant.</p>
<h4 id="dst-arithmetic-plusdays-is-not-plushours24">DST arithmetic: plusDays is not plusHours(24)</h4>
<pre tabindex="0"><code>ZonedDateTime start = ZonedDateTime.of(2026, 3, 28, 12, 0, 0, 0, london);
// 2026-03-28T12:00Z[Europe/London]
start.plusDays(1);                 // 2026-03-29T12:00+01:00  (23 real hours)
start.plus(Duration.ofDays(1));    // 2026-03-29T13:00+01:00  (24 real hours)
start.plusHours(24);               // 2026-03-29T13:00+01:00
</code></pre><p>plusDays preserves the wall clock. Duration preserves elapsed time. PostgreSQL draws the same line, using the same value:</p>
<pre tabindex="0"><code>SET TimeZone=&#39;Europe/London&#39;;
SELECT &#39;2026-03-28 12:00:00+00&#39;::timestamptz + interval &#39;1 day&#39;,   -- 2026-03-29 12:00:00+01
       &#39;2026-03-28 12:00:00+00&#39;::timestamptz + interval &#39;24 hours&#39;; -- 2026-03-29 13:00:00+01
</code></pre><p>This is one place the two platforms agree beautifully — interval &lsquo;1 day&rsquo; and plusDays(1) mean the same thing, and interval &lsquo;24 hours&rsquo; and Duration.ofDays(1) mean the same thing. &ldquo;Every day at 9am&rdquo; is plusDays / interval &lsquo;1 day&rsquo;. &ldquo;Every 24 hours&rdquo; is Duration / interval &lsquo;24 hours&rsquo;. Pick the one the product actually means.</p>
<h4 id="future-events-an-instant-is-notenough">Future events: an instant is not enough</h4>
<pre tabindex="0"><code>ZoneId ny = ZoneId.of(&#34;America/New_York&#34;);
ZonedDateTime.of(2027, 1, 15, 9, 0, 0, 0, ny).withZoneSameInstant(UTC); // 2027-01-15T14:00Z
ZonedDateTime.of(2027, 7, 15, 9, 0, 0, 0, ny).withZoneSameInstant(UTC); // 2027-07-15T13:00Z
</code></pre><p>“9am in New York” is a different UTC instant depending on the date. So if a user schedules a recurring 9am standup and a government later changes DST rules — which happens several times a year somewhere — the stored instant becomes wrong.</p>
<p>For <strong>past events</strong>, store the instant. That’s history; it can’t change.</p>
<p>For <strong>future user-scheduled events</strong>, store three things:</p>
<pre tabindex="0"><code>CREATE TABLE meetings (
  id            bigserial PRIMARY KEY,
  local_start   timestamp   NOT NULL,  -- 2027-01-15 09:00
  zone_id       text        NOT NULL,  -- &#39;America/New_York&#39;
  computed_utc  timestamptz NOT NULL   -- cache; recompute on tzdata update
);
</code></pre><p>The first two are the truth. The third is a derived index for querying, refreshed when tzdata changes.</p>
<h4 id="tzdata-is-a-movingtarget">tzdata is a moving target</h4>
<p>Java bundles a copy of the IANA database (2025b on the JDK I ran this on); PostgreSQL bundles its own; your OS has a third. They drift. When Java and PostgreSQL are on different tzdata versions, they will resolve recently-changed zones differently.</p>
<p>Check what you have:</p>
<pre tabindex="0"><code>ZoneRulesProvider.getVersions(&#34;Europe/London&#34;).lastKey();  // 2025b
</code></pre><pre tabindex="0"><code>SELECT name, utc_offset, is_dst FROM pg_timezone_names WHERE name = &#39;Europe/London&#39;;
</code></pre><p>Pin tzdata in your base images, and treat a tzdata bump as a deployment that requires recomputing cached future instants.</p>
<h3 id="part-4-wiring-java-to-postgresql">Part 4: Wiring Java to PostgreSQL</h3>
<h4 id="the-mappingtable">The mapping table</h4>
<p>Per the <a href="https://jdbc.postgresql.org/documentation/query/">pgJDBC documentation</a>:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-04.png"></p>
<p>Note the omission, in the driver’s own words:</p>
<blockquote>
<p><em>ZonedDateTime, Instant and OffsetTime / TIME WITH TIME ZONE are not supported.</em></p></blockquote>
<p>So don’t hand the driver an Instant and hope — depending on the driver version you&rsquo;ll either get a Can&rsquo;t infer the SQL type to use for an instance of java.time.Instant exception or undocumented behavior. Convert explicitly at the boundary instead:</p>
<pre tabindex="0"><code>// write
ps.setObject(1, instant.atOffset(ZoneOffset.UTC));
// read
Instant i = rs.getObject(&#34;occurred_at&#34;, OffsetDateTime.class).toInstant();
</code></pre><p>Note that reading a timestamptz gives you an OffsetDateTime normalized to UTC — the driver&rsquo;s offset is always Z, because that&rsquo;s what the backend holds. The offset carries no information. Convert straight to Instant and don&rsquo;t be tempted to read meaning into it.</p>
<h4 id="avoid-settimestamp--gettimestamp">Avoid setTimestamp / getTimestamp</h4>
<p>The java.sql.Timestamp overloads convert using the <strong>JVM default time zone</strong> unless you pass an explicit Calendar. That makes your persistence layer&rsquo;s correctness depend on the container&rsquo;s TZ environment variable. Use the java.time setObject/getObject methods instead — they&rsquo;re unambiguous.</p>
<p>If you must keep the JVM zone from mattering at all, set it explicitly at startup:</p>
<pre tabindex="0"><code>-Duser.timezone=UTC
</code></pre><p>Belt and braces, not a substitute for correct types.</p>
<h4 id="precision-java-has-nanos-postgresql-hasmicros">Precision: Java has nanos, PostgreSQL has micros</h4>
<pre tabindex="0"><code>Instant.parse(&#34;2026-08-15T10:00:00.123456789Z&#34;)           // .123456789
    .truncatedTo(ChronoUnit.MICROS)                        // .123456
</code></pre><p>PostgreSQL stores microseconds. Those last three digits are gone on the round trip, and PostgreSQL may <strong>round</strong> rather than truncate:</p>
<pre tabindex="0"><code>SELECT &#39;2026-08-15 10:00:00.123456789&#39;::timestamptz;  -- 10:00:00.123457
</code></pre><p>If you have an equality test or an optimistic-lock check comparing an in-memory Instant to one that&rsquo;s been through the database, truncate to micros <em>before</em> you persist so both sides agree.</p>
<h4 id="dont-wrap-the-column-in-afunction">Don’t wrap the column in a function</h4>
<p>Because timestamptz is stored as UTC, &ldquo;give me everything that happened on 1 Feb in New York&rdquo; tempts you into this:</p>
<pre tabindex="0"><code>EXPLAIN SELECT count(*) FROM events
WHERE (occurred_at AT TIME ZONE &#39;America/New_York&#39;)::date = DATE &#39;2026-02-01&#39;;
--  Seq Scan on events
</code></pre><p>Index gone. Compute the boundary instants instead and do a half-open range scan:</p>
<pre tabindex="0"><code>SELECT (DATE &#39;2026-02-01&#39; + time &#39;00:00&#39;) AT TIME ZONE &#39;America/New_York&#39;,  -- 2026-02-01 05:00+00
       (DATE &#39;2026-02-02&#39; + time &#39;00:00&#39;) AT TIME ZONE &#39;America/New_York&#39;;  -- 2026-02-02 05:00+00
EXPLAIN SELECT count(*) FROM events
WHERE occurred_at &gt;= &#39;2026-02-01 05:00:00+00&#39;
  AND occurred_at &lt;  &#39;2026-02-02 05:00:00+00&#39;;
--  Index Only Scan using events_occurred_at_idx
</code></pre><p>Note that this “day” is 24 hours only because February has no DST transition. On a transition day it’s 23 or 25 — which the boundary-instant approach handles correctly and a naive + interval &lsquo;24 hours&rsquo; does not. Half-open ranges (&gt;= and &lt;) also dodge the microsecond-boundary problem that BETWEEN creates.</p>
<h3 id="part-5-jpa-and-hibernate">Part 5: JPA and Hibernate</h3>
<p>Hibernate 6 made zoned types a first-class concern via TimeZoneStorageType:</p>
<p><img loading="lazy" src="https://vitaliisukach.dev/posts/datetime-handling-in-java-and-postgresql-a-practical-guide/image-05.png"></p>
<p>For PostgreSQL, the practical consequence is settled by the database, not the ORM: timestamptz discards the offset, so under DEFAULT your OffsetDateTime round-trips as UTC. Which is fine — as long as you expected it.</p>
<p>Sensible defaults:</p>
<pre tabindex="0"><code>spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          time_zone: UTC
        timezone:
          default_storage: NORMALIZE_UTC
</code></pre><p>And in the entity, be explicit about intent:</p>
<pre tabindex="0"><code>@Entity
public class Booking {
    
    // A moment. Maps to timestamptz.
    @Column(nullable = false)
    private Instant createdAt;
    
    // A date. Not a moment.
    @Column(nullable = false)
    private LocalDate serviceDate;
    
    // A wall-clock time that must not shift. Maps to timestamp.
    @Column(nullable = false)
    private LocalDateTime localStart;
    
    @Column(nullable = false)
    private String zoneId;   // &#39;Europe/London&#39;
    
    public ZonedDateTime start() {
        return localStart.atZone(ZoneId.of(zoneId));
    }
}
</code></pre><p>If you genuinely need the user’s original offset preserved, @TimeZoneStorage(TimeZoneStorageType.COLUMN) with @TimeZoneColumn writes it to a companion column. Use it when the offset is <em>data</em> — an audit trail of what the user&rsquo;s device claimed — not as a default.</p>
<h3 id="part-6-testing-thisstuff">Part 6: Testing This Stuff</h3>
<p>Datetime bugs are only cheap if you catch them before the clocks change. Three habits do most of the work.</p>
<h4 id="1-inject-aclock">1. Inject a Clock</h4>
<p>Instant.now() scattered through business logic is untestable. Inject java.time.Clock and you can move time at will:</p>
<pre tabindex="0"><code>@Bean Clock clock() { return Clock.systemUTC(); }
// in a test
Clock fixed = Clock.fixed(Instant.parse(&#34;2026-10-25T00:30:00Z&#34;), ZoneOffset.UTC);
</code></pre><h4 id="2-run-ci-in-a-hostile-timezone">2. Run CI in a hostile time zone</h4>
<p>If your JVM, your database, and your CI runner are all UTC, every zone bug hides until production. Force one of them somewhere awkward:</p>
<pre tabindex="0"><code>-Duser.timezone=Pacific/Chatham
</code></pre><p>+12:45 and it observes DST. If your test suite survives Chatham, it will survive most things. Do the same for the PostgreSQL container:</p>
<pre tabindex="0"><code>@Container
static PostgreSQLContainer&lt;?&gt; pg = new PostgreSQLContainer&lt;&gt;(&#34;postgres:16&#34;)
        .withEnv(&#34;TZ&#34;, &#34;Asia/Kathmandu&#34;)
        .withUrlParam(&#34;options&#34;, &#34;-c TimeZone=Asia/Kathmandu&#34;);
</code></pre><p>The point isn’t that production runs there — it’s that a test which only passes in UTC is a test that has proven nothing about zone handling.</p>
<h4 id="3-write-the-four-transition-tests">3. Write the four transition tests</h4>
<p>For any code that converts between local and instant, pin these explicitly:</p>
<pre tabindex="0"><code>static final ZoneId LONDON = ZoneId.of(&#34;Europe/London&#34;);
@Test void gapTimesAreRejectedNotSilentlyShifted() {
    LocalDateTime gap = LocalDateTime.of(2026, 3, 29, 1, 30);
    assertThat(LONDON.getRules().getValidOffsets(gap)).isEmpty();
    assertThatThrownBy(() -&gt; scheduler.schedule(gap, LONDON))
        .isInstanceOf(NonExistentLocalTimeException.class);
}
@Test void overlapTimesResolveToTheDocumentedChoice() {
    LocalDateTime overlap = LocalDateTime.of(2026, 10, 25, 1, 30);
    assertThat(LONDON.getRules().getValidOffsets(overlap)).hasSize(2);
    assertThat(scheduler.resolve(overlap, LONDON))
        .isEqualTo(Instant.parse(&#34;2026-10-25T00:30:00Z&#34;)); // earlier, by policy
}
@Test void dailyRecurrenceKeepsWallClockAcrossDst() {
    ZonedDateTime start = ZonedDateTime.of(2026, 3, 28, 9, 0, 0, 0, LONDON);
    assertThat(recurrence.next(start).toLocalTime()).isEqualTo(LocalTime.of(9, 0));
}
@Test void instantSurvivesTheDatabaseRoundTrip() {
    Instant original = Instant.now().truncatedTo(ChronoUnit.MICROS);
    repository.save(new Event(original));
    assertThat(repository.findLatest().occurredAt()).isEqualTo(original);
}
</code></pre><p>The fourth one catches more real bugs than you’d expect — it’s the one that fails when someone quietly changes a column from timestamptz to timestamp.</p>
<h3 id="the-shortversion">The Short Version</h3>
<p>If you skim one section, make it this one.</p>
<p><strong>Schema</strong></p>
<ul>
<li>timestamptz by default. It&rsquo;s the same 8 bytes and it&rsquo;s unambiguous.</li>
<li>timestamp only for wall-clock times that must not shift — and store the zone ID beside it.</li>
<li>date for dates. timetz for nothing.</li>
<li>Pin timezone = &lsquo;UTC&rsquo; in postgresql.conf and in the JDBC URL.</li>
</ul>
<p><strong>Java</strong></p>
<ul>
<li>Instant for things that happened. LocalDate for dates. ZonedDateTime for scheduling. OffsetDateTime at the JDBC boundary.</li>
<li>LocalDateTime is not a point in time. Treat every use as a question to answer, not an answer.</li>
<li>Never accept zone abbreviations. Full IANA names only.</li>
<li>plusDays ≠ plus(Duration.ofDays(1)). Know which one your product means.</li>
</ul>
<p><strong>The seam</strong></p>
<ul>
<li>pgJDBC speaks LocalDate/LocalTime/LocalDateTime/OffsetDateTime. Convert Instant explicitly.</li>
<li>Avoid setTimestamp/getTimestamp — they use the JVM default zone.</li>
<li>Truncate to microseconds before persisting.</li>
<li>Don’t wrap indexed timestamp columns in AT TIME ZONE; compute boundary instants instead.</li>
</ul>
<p><strong>And the one that bites hardest</strong></p>
<p>Java resolves an ambiguous local time to the <em>earlier</em> offset. PostgreSQL picks the <em>later</em> one. Resolve ambiguity in exactly one place, deliberately, and pass instants across the boundary — never local times.</p>
<p>Store the instant, render the local time, and keep the zone rules in exactly one layer. Most datetime bugs are just that rule, broken somewhere.</p>
<p><em>All examples verified on OpenJDK 21.0.10 (tzdata 2025b) and PostgreSQL 16.13.</em></p>
<p><strong>Sources</strong></p>
<ul>
<li><a href="https://www.postgresql.org/docs/current/datatype-datetime.html">PostgreSQL: Date/Time Types</a></li>
<li><a href="https://jdbc.postgresql.org/documentation/query/">pgJDBC: Using Java 8 Date and Time classes</a></li>
<li><a href="https://docs.hibernate.org/orm/6.4/javadocs/org/hibernate/annotations/TimeZoneStorageType.html">Hibernate</a> <a href="https://docs.hibernate.org/orm/6.4/javadocs/org/hibernate/annotations/TimeZoneStorageType.html">TimeZoneStorageType Javadoc</a></li>
<li><a href="https://docs.hibernate.org/orm/6.2/migration-guide/">Hibernate 6 migration guide</a></li>
<li><a href="https://thorben-janssen.com/hibernate-6-offsetdatetime-and-zoneddatetime/">Thorben Janssen: TimezoneStorageType</a></li>
</ul>
]]></content:encoded></item></channel></rss>