Statistics & SQL Logging

## Why you cannot just read the SQL in your code Hibernate does not execute SQL you wrote — it generates it. Entity state changes become INSERT/UPDATE/DELETE at flush time, and HQL/JPQL/Criteria queries become SELECTs whose joins, aliases and column lists come from the mapping. So the first diagnostic step for almost any ORM problem is: make the generated statements visible. ## Switch 1: hibernate.show_sql `hibernate.show_sql=true` is the oldest switch. It makes Hibernate print each statement directly to `System.out`, bypassing the logging framework entirely. Consequences: you cannot set a level, cannot filter it, cannot attach it to a file appender, cannot correlate it with the rest of your log because it has no timestamp, thread name or MDC context. In a container it goes to the console stream where it may be interleaved unpredictably with real log output. It is convenient in a scratch project and inappropriate anywhere else. ## Switch 2: the org.hibernate.SQL logger Hibernate logs every statement it prepares to a category named exactly `org.hibernate.SQL`, at DEBUG level. Setting that category to DEBUG in logback.xml/log4j2.xml produces the same content as `show_sql`, but as ordinary log events: timestamped, thread-labelled, filterable, and routable. This is the version you want, because you can enable it for one test class, one environment, or one short window in staging without redeploying a code change. ## Formatting helpers - `hibernate.format_sql=true` breaks the statement across lines with indentation. Very useful for wide multi-join selects, noisy for one-line inserts. - `hibernate.highlight_sql=true` (Hibernate 6) adds ANSI colour for a terminal. - `hibernate.use_sql_comments=true` emits a leading `/* ... */` comment identifying the source: the HQL string, or something like `load com.example.Order`. This is the cheapest way to answer 'which line of code produced this query?' and it also shows up in the database's own statement log, which makes it valuable well beyond development. ## Bind parameters Hibernate binds values through `PreparedStatement`, which is what keeps it safe from SQL injection and lets the database cache plans. That is why the statement text contains `?`. The values are logged separately, by the type descriptors, at TRACE: - Hibernate 6 and later: `org.hibernate.orm.jdbc.bind` (and `org.hibernate.orm.jdbc.extract` for values read back out of the result set). - Hibernate 5: `org.hibernate.type.descriptor.sql.BasicBinder` (or the broader `org.hibernate.type`). These produce one line per parameter, so a batch of a thousand inserts becomes thousands of lines. They also dump the raw values — emails, names, tokens — into your log files, which is a privacy and compliance problem. Enable them narrowly and never by default in production. ## When logging alone is not enough The SQL log tells you what was sent, not how long it took, how many times, or whether a cache satisfied the request instead. It also does not stitch statement and parameters back into one runnable line. Tools that sit between Hibernate and the driver solve that: - **p6spy** wraps the `DataSource`/driver and logs a single line per statement with values inlined and the elapsed time. - **datasource-proxy** does the same programmatically and additionally exposes query counts, which makes it the usual basis for automated 'this endpoint must issue at most N statements' assertions. Both see everything that reaches JDBC, including statements from code that does not go through Hibernate at all. ## Production posture Running `org.hibernate.SQL` at DEBUG in production is a real cost: one log event per statement, at hundreds or thousands of statements per second, with the serialization and I/O that implies, plus log-storage bills. The normal setup is: SQL logging off by default, `use_sql_comments` on (cheap, and it makes the database-side slow-query log self-explanatory), and slow statements captured either by the database or by Hibernate's own slow-query threshold. Turn DEBUG on deliberately, briefly, and preferably on one instance.