Skip to content

Support upserts through Quick entity queries - #334

Open
elpete wants to merge 5 commits into
nextfrom
feat/63-upsert
Open

Support upserts through Quick entity queries#334
elpete wants to merge 5 commits into
nextfrom
feat/63-upsert

Conversation

@elpete

@elpete elpete commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

Closes #63

Issue review

Recommendation: 9/10 — implement. Upsert is a useful bulk persistence primitive and qb provides the database-specific SQL safely. Quick should expose it as an explicit entity-query operation so the mutation cannot bypass Quick's entity metadata.

Quick semantics

upsert() now behaves like updateAll():

  • it is implemented directly on QuickBuilder rather than relying on missing-method forwarding
  • it enforces read-only entities and read-only attributes
  • force = true provides the same explicit escape hatch as updateAll
  • literal insert rows and explicit update values are bound through Quick's attribute metadata, preserving aliases, configured SQL types, and null conversion
  • it returns qb's bulk execution result (or SQL for toSql = true)
  • it does not hydrate entities or fire per-entity insert/update/save lifecycle events, because one database statement may affect multiple existing and new rows

The QuickQB wrapper remains responsible for the qb 14 signature, including matchNulls, constrained deleteUnmatched, and QuickBuilder sources.

Test-first evidence

The public entity-query regression was added before the implementation. It failed because upserting through a read-only Quick entity did not throw QuickReadOnlyException. Coverage now verifies:

  • updating an existing row and inserting a new row in one call
  • Quick attribute-to-column mapping (firstName to first_name)
  • the bulk execution result contract
  • read-only entity protection
  • read-only attributes in both inserted values and explicit update values
  • the force escape hatch

Validation

  • Focused upsert, updateAll, and read-only suites: 26 passed, 0 failed, 0 errors
  • Full Lucee 6 suite: 570 passed, 0 failed, 0 errors, 3 skipped
  • Formatter completed
  • git diff --check passed

Uses the currently resolved qb 14 beta (14.0.0-beta.3).

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