Skip to content

feat: support named :name query placeholders - #55

Merged
omer-cengel merged 2 commits into
masterfrom
feature/named-query-placeholders
Sep 30, 2026
Merged

omer-cengel merged 2 commits into
masterfrom
feature/named-query-placeholders

Conversation

@omer-cengel

Copy link
Copy Markdown
Member

Summary

Queries can now write :name placeholders instead of $N, so parameters read as their meaning and the generated method parameters carry the names the query author chose. Each named placeholder compiles to a JDBC ? and is analyzed wherever an indexed placeholder is.

Changes

  • Compile :name (a colon directly followed by an unquoted ASCII identifier, compared exactly as written) to ?; placeholder text in string literals, quoted identifiers, and comments is untouched, and : name is not a placeholder.
  • Treat each distinct name as one parameter numbered by its first textual occurrence; every occurrence binds at its own ? position in textual order.
  • Accept named placeholders in comparisons with a column on either side, IN lists, LIKE/ILIKE patterns, BETWEEN bounds, INSERT values, UPDATE assignments, LIMIT, and OFFSET; the method parameter is named after the placeholder, so LIMIT :pageSize generates pageSize.
  • Reject a query mixing $N and :name, a qualified (:a.b), quoted (:"x"), or &name placeholder anywhere in the statement, a named placeholder in an unanalyzed location, and one name used with conflicting types, with diagnostics that write the placeholder as the query spells it.
  • Document the named form, its ordering, and its rejections in the query reference.
  • Add parser, compiler, and analyzer tests, a generated-repository compilation and execution test, and a PostgreSQL execution test of a query that repeats a name.

Scope and non-goals

  • Queries written only with $N placeholders produce unchanged models, executable SQL, generated code, and diagnostics.
  • Cast-typed placeholders such as :name::text, non-placeholder INSERT/UPDATE expressions, = ANY, upsert, @name or macro syntax, and :1 are not supported by this change.
  • Code generation, the runtime, configuration, and the sample are unchanged.

A query may write :name placeholders instead of $N. Each distinct name is
one parameter numbered by first occurrence and names its method parameter;
every occurrence compiles to a JDBC ? bound in textual order. Mixed $N and
:name, qualified, quoted, and &name placeholders anywhere in the statement,
unanalyzed locations, and conflicting types are rejected with the
placeholder as written. Queries using only $N are unchanged.
@omer-cengel
omer-cengel merged commit 54bcb07 into master Sep 30, 2026
6 checks passed
@omer-cengel
omer-cengel deleted the feature/named-query-placeholders branch September 30, 2026 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant