Skip to content

refactor(query): adopt error-returning build and render contracts #447

Description

@scottescue

Outcome

All query and expression build paths can return stable validation and unsupported-feature errors without emitting semantically different fallback SQL.

Context

The normative query specifications require Build and expression rendering to report errors. Current two-result builders and string-only ToSQL methods cannot reliably propagate invalid identifier, invalid metadata, or dialect capability failures, which encourages FALSE, NULL, or omitted-clause fallbacks.

In scope

  • Ratify and implement the public error-returning Build shape governed by the API stability policy.
  • Introduce an error-returning expression/render contract used consistently by normal and prepared builds.
  • Preserve stable error codes, errors.Is behavior, deterministic argument cleanup, and redacted diagnostics.
  • Provide a deliberate compatibility or cutover path for existing two-result callers.
  • Migrate representative select, mutation, identifier, and dialect-gating paths to prove the contract.

Out of scope

  • Implementing every missing query feature in this issue.
  • Silently retaining false, null, or dropped-clause fallbacks after the new contract is available.
  • Driver execution behavior unrelated to build errors.

Acceptance criteria

  • Public and internal build/render signatures are documented and approved under the API stability policy.
  • Invalid metadata and unsafe identifiers return typed build errors without executable SQL.
  • Unsupported dialect features return unsupported_feature without binding orphaned arguments.
  • Normal and prepared builders preserve the same validation and error semantics.
  • Migration coverage demonstrates the compatibility/cutover path for existing callers.
  • Query, expression, generated-code, and driver-facing test suites pass with no silent fallback path remaining in migrated features.

Metadata

Metadata

Labels

area:queryQuery builder, expressions, relationspriority:criticalCritical: blocks other work or affects correctness/securitystatus:readyActionable now; scope and acceptance criteria are ready

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions