OXY-6: array input + = ANY(?)

[Kalin-Rudnicki]

OXY-6 — Add support for array input + unnest

Adds first-class support in oxygen-sql for binding a collection as a single parameter and expanding it as Postgres col = ANY(?), avoiding N-placeholder IN lists (JDBC ~32767-param limit / plan-cache blowup).

DSL

@compile
val selectByIdArray: QueryIO[ArraySeq[UUID], Person] =
  for {
    ids <- input.array[UUID]
    p   <- select[Person]
    _   <- where if ids.contains(p.id)   // -> WHERE p.id = ANY(?)
  } yield p

Q.input.array[A] binds an ArraySeq[A] as one java.sql.Array param; ids.contains(col) generates col = ANY(?). Encoding reuses the existing RowRepr.ArrayRepr / ArraySeqEncoder (no ::type[] cast — the JDBC typed array already carries the element type).

What changed

• DSL: T.ArrayInput, Q.input.array
• parsing/model: VariableReference.ArrayFromInput, InputPart, RawQueryExpr/QueryExpr ArrayContains, DecoderBuilder exhaustiveness
• generation: FragmentBuilder emits <col> = ANY(?); TypeclassExpr.RowRepr.arraySeq
• tests: 3 compile-checked queries + 1 Postgres integration test (empty / 1000+ large / composed-with-scalar) — passes against a real container
• docs: array-input section in docs/sql/queries.md

Scope / decisions

• Single-column element types only (per ticket "restrict to single-column A initially").
• = ANY(?) form only; UNNEST-as-a-table-source deferred (overlaps OXY-98 lateral join).
• Kept distinct from OXY-17 (IN with N placeholders).
• Full rationale + assumptions + confidence score (8.5/10) in report/OXY-6.md.

🤖 Generated with Claude Code

[Kalin-Rudnicki]

💬 Feedback from Kalin

The primary intended use case for the array/unnest input — in my head — is using UNNEST as an input JOIN table, e.g.:

SELECT *
  FROM UNNEST(?) a
  JOIN other b ON b.id = a

This PR implemented = ANY(?) and deferred the UNNEST-as-table-source case — but that table-source case is the main goal, not a nice-to-have. Please make that case work and give it solid tests (empty array, the join actually filtering correctly, composition with other inputs/joins, real-Postgres integration).

Spinning up an agent to build the FROM UNNEST(?) a JOIN ... support and test it thoroughly.

[Kalin-Rudnicki]

UNNEST(?) as an input join table source (the primary use case)

Following the feedback that the main goal was using UNNEST as an input join table (SELECT * FROM UNNEST(?) a JOIN other b ON b.id = a), this is now implemented (additive — the = ANY(?) contains support is unchanged and still passing).

DSL

select.unnest(ids) turns a previously-declared input.array[A] collection into a UNNEST(?) from-item that yields one row per element, aliased so it can be JOINed / filtered / selected like any other table:

@compile
val notesByPersonIdUnnest: QueryIO[ArraySeq[UUID], Note] =
  for {
    ids <- input.array[UUID]
    id  <- select.unnest(ids)          // FROM UNNEST(?::uuid[]) id(id)
    n   <- join[Note] if n.personId == id
  } yield n

generates:

SELECT n.id, n.person_id, n.note
    FROM UNNEST(?::uuid[]) id(id)
    JOIN note n ON n.person_id = id.id

The whole collection still binds as a single java.sql.Array param via the existing RowRepr.ArrayRepr / ArraySeqEncoder.

Notes / decisions

• Ambiguity fix: the unnested column is named = alias and referenced qualified as alias.alias (via UNNEST(?::type[]) alias(alias)), so it never collides with a same-named column of a joined table (e.g. note.id).
• Keeps the array declaration (input.array) separate from its table-source usage (select.unnest(ids)) — this reuses all the array-encoder wiring and composes cleanly with other inputs/joins/wheres.
• Single-column element types only (v1), same restriction as input.array.
• Supported as the root FROM source (the owner's example); JOIN UNNEST(?) (unnest as a non-root join item) is left as future work.

Test coverage

New integration test "UNNEST(?) as an input join table" in CustomQuerySpec, run against the real Postgres testcontainer:

• basic join filters correctly (only matching rows return)
• the unnested column decodes + is selectable (yield (id, n))
• empty array → zero rows
• larger array (all real ids + 1000 random misses), still one bound param
• composition with an extra scalar input[String] used in a WHERE

14/14 CustomQuerySpec tests pass (new UNNEST test + the pre-existing = ANY(?) test).