Skip to content

Apply readOnly, fetchSize, timeout and flushMode to criteria queries and type the criteria closures - #16823

Closed
borinquenkid wants to merge 15 commits into
fix/h7-bulk-write-pagination-guard-8.0.xfrom
fix/h7-criteria-query-args-8.0.x
Closed

borinquenkid wants to merge 15 commits into
fix/h7-bulk-write-pagination-guard-8.0.xfrom
fix/h7-criteria-query-args-8.0.x

Conversation

@borinquenkid

Copy link
Copy Markdown
Member

Fixes #16808

Stacked on #16822 (chain: #16816, #16817, #16818, #16820, #16821, #16822). no ci until the chain reaches 8.0.x.

Problem

  • HibernateQuery never read the query arguments map. A criteria query dropped readOnly, fetchSize, timeout and flushMode, which the HQL path applied: Person.where { ... }.list(readOnly: true) loaded modifiable entities and flushMode: 'MANUAL' still flushed first. withCriteria(args) { } read only max, offset and sort.
  • The same map was read separately by HqlQueryMethods and by the criteria code, so a setting could be honoured by one path and dropped by the other.
  • The criteria closures of GormEntity.where, whereLazy, whereAny and findAll had no @DelegatesTo, so eq and gt did not type-check under @CompileStatic.

Changes

  • New HibernateQuerySettings record: reads fetchSize, timeout, readOnly and flushMode from an arguments map once. A value that is not a whole number throws IllegalArgumentException naming the argument and the value.
  • HqlQueryMethods.populateQuerySettings and the new HibernateQuery.setArguments (it now implements QueryArgumentsAware) both go through it. CriteriaMethodInvoker passes the whole map for withCriteria(args).
  • @DelegatesTo(DetachedCriteria) on the five GormEntity methods.
  • Upgrade guide section 26.15.

Tests

  • QueryArgumentsPropagationSpec (12): readOnly true/false through where().list, findAll(args) { } and withCriteria(args) { }, a single result, flushMode MANUAL vs ALWAYS with a pending change, parsing, a bad value, absent arguments, and a later call keeping earlier settings. Red before the fix (8 failures).
  • HibernateQuerySettingsSpec (18).
  • SingleResultFirstRowSpec (3): first row on ascending and descending order, and null when nothing matches.
  • GormEntityCriteriaTypingSpec: a @CompileStatic class calls all five methods. It fails to compile without the annotation.
  • Whole grails-data-hibernate7-core suite: 4444 tests, 0 failures. grails-datamapping-core: 1813, 0 failures. codeStyle, validateRepositoryConventions and rat pass.
  • PITest (from feat(build-logic): add opt-in PITest mutation testing support and skill #16819) on HibernateQuerySettings: 9 mutants, 9 killed.

Not in this PR

  • singleResult with several matching rows keeps returning the first row, which is the Grails convention (find documents it). SingleResultFirstRowSpec pins it for criteria get, and where get and find.
  • The duplicate argument constants in HibernateQueryConstants and GrailsHibernateUtil are already deprecated and are left for removal in the Java-to-Groovy chain.

…and type the criteria closures

The Hibernate 7 HibernateQuery never read the query arguments map, so a
criteria query dropped readOnly, fetchSize, timeout and flushMode that the HQL
path applied. Both paths now read them through one HibernateQuerySettings
record, which also rejects a value that is not a whole number by naming the
argument. withCriteria(args) and the list(args) builder route pass the whole
map to the query.

GormEntity.where, whereLazy, whereAny and findAll carry @DelegatesTo
(DetachedCriteria) so the criteria closures type-check under CompileStatic.

Fixes #16808

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

…nate 5 does

The criteria reference describes get as returning a unique result and says it is not to be
confused with a limit to just the first row. Hibernate 5 throws NonUniqueResultException
when several rows match; Hibernate 7 caught it and returned the first row, so a criteria
that matched more rows than intended went unnoticed after an upgrade.

Criteria get now takes its own strict path. find, findBy, findWhere and the get and find
of a where query keep returning the first row on both modules.

The behaviour is pinned by an integration spec that runs unchanged against the Hibernate 5
and Hibernate 7 grails-hibernate apps; the core SingleResultFirstRowSpec asserted the old
first-row result for criteria get and is removed.
…of HibernateQueryExecutor

uniqueResult returns the row when one matches, null when none do and fails with the
row count when several do; singleResult keeps returning the first row. Both run against
a real session.
@borinquenkid

borinquenkid commented Nov 2, 2026 •

Copy link
Copy Markdown
Member Author

For the team: criteria get with several matching rows

This PR now fails a criteria get when more than one row matches, as Hibernate 5 does. Before, Hibernate 7 caught the error and returned the first row.

The criteria reference describes get as returning "a unique result, i.e. just one row… not to be confused with a limit to just the first row". On H5, createCriteria().get { gt 'qty', 0 } over three rows throws NonUniqueResultException; on H7 it returned the first. An application that relied on H5's error to find a criteria matching too much would stop seeing it after an upgrade.

find, findBy*, findWhere and the get() and find() of a where query return the first row on both modules, and still do. One integration spec (CriteriaSingleResultScenarioSpec) runs unchanged on the H5 and H7 grails-hibernate apps: H5 7/7, H7 7/7.

Worth sharing with the team

  • The docs list singleResult as an alias for get, but H5 has no such method (MissingMethodException). H7 has it and returns the first row. I left it as it is; making it strict would turn an H5 error into a different H7 behavior.
  • On H7, a criteria that sets maxResults still returns a row and does not throw (covered by HibernateQueryExecutorSpec). I did not check that case on H5.

@borinquenkid borinquenkid added this to the grails:8.0.1 milestone Nov 4, 2026
…uery-args-8.0.x

Takes the merge of fix/h7-subquery-root-alias-nested-paths-8.0.x. The upgrade guide numbers its sections 26.14 (not-equal comparisons), 26.15 (bulk statements)
and 26.16 (query arguments), as the sections of the branches below it already took 26.14 and 26.15.

Claude-Session: https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not approving. A get that finds more than one row leaves the session it opened still bound.

}
} else {
result = hibernateQuery.singleResult();
result = hibernateQuery.uniqueResult();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

createCriteria().get { gt('age', 18) } with two matching rows, and no session already bound. The call throws, and the session it opened stays bound. Close that session even when the call throws.

…ened

createCriteria().get { gt('age', 18) } with two matching rows threw and left the session it had opened bound to
the thread, as did a list with a sort that names no property and a criteria closure that throws. The session the
builder opened is now closed when the call throws, as it is when the call returns. A session of the caller that
the builder only participates in is left as it is.

Claude-Session: https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL
@borinquenkid

Copy link
Copy Markdown
Member Author

Reproduced and fixed in 20510a5. createCriteria().get { gt('age', 18) } with two matching rows threw and left the session it had opened bound to the thread. So did two other calls that fail before the builder reaches its own cleanup: a list with a sort that names no property, and a criteria closure that throws.

CriteriaMethodInvoker now asks the builder to close its session when a criteria call throws (closeSessionAfterFailure), as it is closed when the call returns. The builder does nothing when it only participates in a session of the caller, and nothing when it has already closed the session for that failure, as throwRuntimeException does for the invalid projections. My first version closed twice and failed HibernateCriteriaBuilderSqlProjectionSpec; the check is in the builder now.

Cases in CriteriaSessionCleanupSpec, each run with no session bound: the get with two rows, the list with the bad sort, the closure that throws, a call that returns (still closes), and a get that throws inside a bound session of the caller, which stays bound and open. The first three fail without the commit. CriteriaMethodInvokerSpec checks that the invoker asks the builder to close on a failure and not on success. The 4637 tests of the Hibernate 7 module pass and codeStyle is clean.

Not covered: scroll() results, which the builder closes the session for as before whether the call returns or not. If another call leaves a session bound, the call would let me find which path it takes.

Branch policy: the new types and throws of this PR were already in it; this commit adds one public method of the builder and no throw. Where the PR belongs is still open; I have not moved it.

https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL

@matrei matrei left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 20510a5 (base fix/h7-bulk-write-pagination-guard-8.0.x, #16822's head branch). This PR's own change is the 18 files GitHub shows, measured from ff0c8c9, the #16822 commit it last merged; #16822's head is 65d597f now. The PR is labelled no ci, so CI has not run on it.

What I ran locally:

  • A throwaway spec with Hibernate 5 on 7.0.x (00f51d4), Hibernate 7 on 8.0.x (9fc7dd3), and Hibernate 5 and 7 at this head. Each call ran in a transaction of its own, except in the last two rows, which run with no session bound:

    Call Hibernate 5, 7.0.x Hibernate 7, 8.0.x Hibernate 7, this head
    where { }.list(readOnly: true) ignored ignored applied
    where { }.find(readOnly: true) ignored ignored applied
    findAll(readOnly: true) { } ignored ignored applied
    findAllBy…(…, [readOnly: true]) ignored ignored applied
    withCriteria(readOnly: true) { } ignored ignored applied
    createCriteria().list(readOnly: true) { } applied ignored applied
    list(readOnly: true) applied applied applied
    flushMode: 'ALWAYS' on where { }.list, withCriteria and a finder ignored ignored applied
    flushMode: 'ALWAYS' on createCriteria().list applied ignored applied
    where { }.list(fetchSize: 'abc') ignored ignored IllegalArgumentException
    criteria get with three matching rows NonUniqueResultException the first row NonUniqueResultException
    no session bound, a criteria closure that throws nothing left bound its session left bound nothing left bound
    no session bound, list(max: 10, sort: 'noSuchProperty') { } nothing left bound its session left bound nothing left bound

    The datastore of the spec does not flush before a query by default, so ALWAYS is the value that shows whether flushMode arrives. Hibernate 5 at this head gives the same results as on 7.0.x, except that withCriteria(args) applies readOnly and flushMode: on 8.0.x, withCriteria(Map, Closure) calls createCriteria().list(args) { }, and on 7.0.x it sets the map as builder properties.

  • The two example-app specs on Hibernate 5 at this head: the 13 features pass.

  • A @GrailsCompileStatic class in the Hibernate 7 example app, on 8.0.x and at this head: flat criteria, the where DSL, association blocks (pets { eq('name', 'rex') }, owner { eq('name', 'Ned') }), mixed criteria and an association path return the same rows on both. A plain @CompileStatic class at this head returns the same rows too.

  • This PR's diff applied to 8.0.x: the code applies without conflicts; only the upgrade guide conflicts. With it, the full suites of grails-datamapping-core and grails-data-hibernate7-core pass on 8.0.x (1816 and 4716 tests, no failures), the PR's new specs included.

Needs a fix

  1. Branch: this can go to 8.0.x on its own. For Hibernate 7, 8.0.x is the right branch: all rows of the table but list(readOnly: true) are wrong there, and Hibernate 7 starts at 8.0. But nothing in the change needs #16816 to #16822. Only the example-app specs use ScenarioItem and ScenarioStatus, which come from #16816. Please rebase onto 8.0.x and give the example apps a domain class of their own, as #17051 does with BulkWriteItem. Then this PR does not wait for the chain, and no ci can go: a pull request against 8.0.x runs the tests.

  2. Branch: Hibernate 5 drops the same arguments on 7.0.x, where they are documented. findAll.adoc lists readOnly, fetchSize, flushMode and timeout for findAll(Map queryParams, Closure whereCriteria), and findAllBy.adoc lists them as metaParams of the dynamic finders. On 7.0.x, Hibernate 5 ignores them for both, and for where queries. The cause is the one this PR fixes for Hibernate 7: DynamicFinder.populateArgumentsForCriteria and DetachedCriteria hand these arguments only to a query that implements QueryArgumentsAware, and the Hibernate 5 HibernateQuery does not. By the rule in the dev@ thread, that part goes to 7.0.x in a pull request of its own for Hibernate 5 and is merged up. QueryArgumentsAware is the hook both callers already use, so implementing it adds no extension point. The Hibernate 5 example-app spec of this PR belongs there too. It passes at this head, but it covers only withCriteria and createCriteria().list, which Hibernate 5 honours on 8.0.x. On 7.0.x its withCriteria(readOnly: true) feature would fail, since withCriteria there ignores readOnly, and where queries, findAll(args) { } and the finders need features of their own.

  3. The strict criteria get changes a result on 8.0.x. On 8.0.x, createCriteria().get { gt('amount', 0) } with three matching rows returns the first row; at this head it throws NonUniqueResultException, as Hibernate 5 does on 7.0.x. I agree with the change: the reference describes get as returning "a unique result", "not to be confused with a limit to just the first row", and Hibernate 7 starts at 8.0, so 8.0.x is the oldest branch with the bug. But a call that returned a row now throws, so the rule in the dev@ thread asks for a second reviewer, a description of the change, and an upgrade note that says how to keep the first row, for example maxResults(1) with an order in the closure, which you found still returns a row. The note does not mention the change yet, and the description mentions it only in your comment of 11-02.

  4. New public API on the patch line. The patch rule allows no new public classes or methods on 8.0.x. Here:

    • HibernateQuerySettings is a new public record (@since 8.0.1). HqlQueryMethods and HibernateQuery, which use it, are in its package, so it can be package-private.
    • HibernateCriteriaBuilder.closeSessionAfterFailure() is public. CriteriaMethodInvoker, its only caller, is in grails.orm too, so it can be package-private.
    • HibernateQuery.getFetchSize(), getTimeout(), getReadOnly() and getFlushMode() are read only by QueryArgumentsPropagationSpec. The spec already tests readOnly and flushMode by their effect, and HibernateQueryExecutorSpec covers what reaches the Hibernate query, so the getters can go.
    • HibernateQuery.uniqueResult() and HibernateQueryExecutor.uniqueResult() serve only the criteria get. The invoker could get the rows from the existing list() and check their number itself.

    HibernateQuery.setArguments implements the existing QueryArgumentsAware, so that one is fine.

  5. @DelegatesTo belongs in a pull request of its own, against 8.1.x. It does not fix the arguments: it lets the closures of where, whereLazy, whereAny and findAll type-check under plain @CompileStatic. It is in grails-datamapping-core, so every datastore and Hibernate 5 get it, and 7.0.x has the same signatures. Code that did not compile now compiles, and I found no result that changes (see above), so it is an improvement rather than a fix, and that goes to the next minor. GormEntityCriteriaTypingSpec covers flat criteria under plain @CompileStatic. @GrailsCompileStatic compiled where closures before, through WhereQueryTypeCheckingExtension, as dynamic calls; with the annotation they are compiled statically. Features for association blocks and for @GrailsCompileStatic would catch a later change that binds a call in a nested block to the outer criteria.

  6. The upgrade note.

    • 8.0.0 is released, and on 8.0.x the notes for later changes are in the Grails 8.0.1 section. 8.0.x moved "Custom User Types" and "Several Unidirectional hasMany Associations on One Owner" there, which are 26.11 and 26.12 on this branch. Please put this note there, as a ==== section, rather than as 26.16 of the 8.0.0 changes.
    • It should cover the strict get (item 3), and say that the dynamic finders now apply the arguments too. The @DelegatesTo paragraph goes with item 5.
  7. Description. Please update it to match this head:

    • "Stacked on #16822" and the no ci line change with item 1.
    • It leaves out the strict get, the session cleanup of 20510a5 and the dynamic finders.
    • The test counts (4444 Hibernate 7 tests) are older than your comment of 11-18, which says 4637.
    • "Fixes #16808" would close the issue, which also lists readOnly(true) and cache(true) on a DetachedCriteria, still "no-op for now" in AbstractDetachedCriteria, and the completeness tests of F6. "Part of #16808" fits, unless the issue says those are done or not needed.
    • What changes for applications, as the rule in the dev@ thread asks: arguments that criteria queries and finders ignored now apply, a criteria get that returned the first of several rows now throws, and a fetchSize or timeout that is not a whole number now throws instead of being ignored.

Suggestions

  1. CriteriaSessionCleanupSpec has @Issue('https://github.com/apache/grails-core/issues/16823'), which is this pull request. #16808, or James's review comment, fits.
  2. In CriteriaSingleResultScenarioSpec, "find with a closure returns the first row" and "dynamic finder and findWhere return the first row" query without an order, so the expected n1 is the row the database happens to return first. H2 returns the rows in insertion order; another database need not.
  3. The four example-app specs can use a bare @Integration: each app has one Application class, and the annotation finds it.

Verified as correct

  • At this head, every call in the table applies readOnly and flushMode on Hibernate 7, and a criteria get throws when several rows match and returns the row or null otherwise.
  • James's finding of 11-12 is fixed: a criteria get that throws, a closure that throws and a refused sort leave no session bound, and CriteriaSessionCleanupSpec checks that a session of the caller stays bound and open.
  • A setting absent from the map keeps its current value, so a later call does not reset an earlier one, and the HQL path reads the same settings through HibernateQuerySettings.

@borinquenkid

Copy link
Copy Markdown
Member Author

Items 1, 3, 4, 6 and 7 of your review: the Hibernate 7 part is rebased on 8.0.x as #17077, with a domain class of its own, no new public API (package-private settings record and cleanup hook, no getters, the criteria get reads list()), the strict get in the description and the 8.0.1 note, and the ordering assumptions removed. The Hibernate 5 part (item 2) goes to 7.0.x and @DelegatesTo (item 5) to 8.1.x as separate pull requests; this PR will be closed when they are open.

https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL

@borinquenkid

Copy link
Copy Markdown
Member Author

Item 2 of your review: the Hibernate 5 part is #17078 against 7.0.x (HibernateQuery implements QueryArgumentsAware, a spec with 6 of 10 features failing without it, a 7.0.19 upgrade note).

https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL

@borinquenkid

Copy link
Copy Markdown
Member Author

Item 5 of your review: @DelegatesTo is #17080 against 8.1.x, with the association-block and @GrailsCompileStatic features you suggested. Together with #17077 (Hibernate 7, 8.0.x) and #17078 (Hibernate 5, 7.0.x), this covers everything in this PR, so I am closing it.

https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

4 participants