Route JPAInsertClause.execute() through native SQL when values contain function templates (#1757)

[zio0911]

Summary

JPAInsertClause.execute() and HibernateInsertClause.execute() now route through JpaNativeInsertSerializer (native SQL) when value expressions contain a TemplateExpression — typically a schema-qualified function call from SQLExpressions.function/stringFunction/numberFunction or a raw SQL fragment. Plain path/literal/parameter INSERTs continue to use the existing JPQLSerializer path so JPA semantics (cascade behaviour for paths, callbacks where applicable) are preserved.

Aligns execute() with the native routing that executeWithKey() / executeWithKeys() (#1693) already use, so callers no longer need to invoke a key-returning method purely to dodge the JPQL parser when their values contain function templates.

Fixes #1757.

Changes

• JPAInsertClause.execute() — detect template values via a new hasTemplateValue() helper and dispatch to native path when present, falling back to JPQL otherwise.
• HibernateInsertClause.execute() — same change applied with Session.doReturningWork(...) instead of EntityManager.unwrap.
• JpaInsertNativeHelper — added executeUpdate(Connection, String, Object[]) for the non-key-returning native path. Class javadoc generalized.
• Regression tests in JPAExecuteWithKeyTest and HibernateExecuteWithKeyTest:
  • execute_with_function_template_routes_through_native_sql — verifies that upper({0}) inside a value expression is preserved and the function is evaluated by the DB.
  • execute_without_template_uses_jpql_path — verifies plain INSERTs still go through JPQL.

Test plan

• ./mvnw -Pdev -pl querydsl-libraries/querydsl-jpa -am test — 3238 tests, 0 failures
• JPAExecuteWithKeyTest (13 tests, includes 2 new execute_* cases)
• HibernateExecuteWithKeyTest (includes 2 new execute_* cases)
• Verified end-to-end in a downstream Spring/JPA consumer doing INSERT with a schema-qualified external SQL function — pre-patch reproduced the SemanticException from JPAInsertClause.execute() does not route to native SQL when values contain function templates / SQL fragments #1757; post-patch the INSERT succeeds via the native path.

[velo]

Thanks for the fix and tests. I’m requesting changes due to a backwards-compatibility concern.

Gate results:

1. Test coverage: PASS (new tests added for template and non-template execute paths in both JPA and Hibernate variants).
2. Backwards compatibility: FAIL
3. Security: PASS (uses prepared statements with bound parameters; no obvious injection risk introduced).

Blocking issue (backwards compatibility):

• In querydsl-jpa JPAInsertClause.execute(), when hasTemplateValue() is true, the new implementation unconditionally unwraps org.hibernate.Session and calls doReturningWork(...).
  This hard-requires Hibernate at runtime for that code path. querydsl-jpa is used with non-Hibernate JPA providers (e.g., EclipseLink/OpenJPA), so this can fail at runtime (unwrap failure) where previously execute() stayed provider-neutral.

Please add provider-safe handling, e.g.:

• guard unwrap with capability checks and provide a provider-neutral fallback, or
• fail fast with a clear, documented exception only for unsupported providers and preserve previous behavior otherwise.

Once this is addressed, I’m happy to re-review.

[zio0911]

@velo
Addressed in fd7f8e9.

Instead of guarding the unwrap, I switched JPAInsertClause.execute() to use the JPA-standard EntityManager.createNativeQuery(...) for the native path. This removes the Hibernate dependency entirely from this code path — it now works under any JPA provider (EclipseLink, OpenJPA, etc.) without capability checks or fallback logic.

HibernateInsertClause.execute() is intentionally left unchanged: that class is Hibernate-specific by design and continues to use Session.doReturningWork(...), consistent with its existing executeWithKey path.

3238 tests pass locally on -Pdev. Ready for re-review.

[velo]

Thanks for the update and for addressing the provider-compatibility concern. This now includes focused regression tests for both routing paths, preserves existing behavior for non-template inserts, and checks are green.