fix: bind query parameters server-side instead of splicing them into SQL

[lukekim]

What

Parameterized queries on the Node gRPC path now run as Flight SQL prepared statements — CreatePreparedStatement → DoPut (bind a typed Arrow record batch) → GetFlightInfo → DoGet → ClosePreparedStatement — instead of substituting values into the SQL text client-side.

The HTTP/browser path already bound server-side and is unchanged. No public API change: .sql(query, { parameters }) works exactly as before, for both positional and named parameters.

Why

The client-side substitution was justified by this comment in src/grpc/client.node.ts:

Flight SQL prepared statements are not currently supported by the Spice server.

That is not true. The runtime implements CreatePreparedStatement in flight/actions.rs, spice-rs binds through it today, and I confirmed it directly against a live spice run — the server returns a handle and a typed parameter schema.

The consequence of splicing was that type information was discarded: every value was rendered to a SQL literal and re-parsed by the server. Escaping was applied, so this was not trivially injectable, but the semantics differed from the other five SDKs, which all bind server-side.

Notably, this PR does not so much add machinery as connect it: src/adbc/client.ts already contained a complete set of prepared-statement encoders and decoders, with no caller anywhere in the package. What was missing was the IPC-to-Flight framing — an Arrow IPC stream frames each message as [continuation][length][metadata][body], while Flight carries the metadata and the body as separate fields. Sending the undivided stream makes the server fail with Error decoding root message.

Two wire details worth recording

Both established empirically against a live runtime, and both are the kind of thing the next person will otherwise rediscover the hard way:

• Positional placeholders bind through columns named $1, $2, …
• Named placeholders bind through the bare name — column nm for placeholder $nm. Binding $nm fails with No value found for placeholder with name $nm, even though the parameter schema the server reports back from CreatePreparedStatement spells the field $nm.

The asymmetry is surprising enough that it's called out in a comment on buildNamedParameterColumns and pinned by a test.

Also worth flagging: GetFlightInfo accepts an unbound or wrongly-bound statement without complaint — the placeholder error only surfaces at DoGet. Any future work here should verify through DoGet, not GetFlightInfo.

Test changes

test/parameter-substitution.test.ts is removed. It defined a local ParameterSubstitutionHelper class that "mirrors the logic in GrpcFlightClient" and tested that copy, never importing from the SDK — so it would have gone on passing against substitution code that no longer exists. Its ~130 assertions are why the total test count drops.

Replaced by test/prepared-statement-binding.test.ts (18 tests) covering the column-naming rules for both placeholder styles, IPC stream framing and round-trip reassembly, and that values carrying SQL syntax stay data.

Verification

Run against a live spice run (Spice v2.1.1) with a local CSV dataset:

case	result
plain query, no parameters	✅
positional int / string / two params	✅
named parameters ({ nm: ... } and { $nm: ... })	✅
float parameter	✅
streaming callback with parameters	✅ (3 rows streamed, 3 final)
"CANADA' OR '1'='1" as a value	✅ returns [] — bound as data

• npm run build
• npm run typecheck — clean
• npm test — 19 failures, byte-identical to the failure set on unmodified trunk (all pre-existing, in nested-date-conversion, response-* and related suites)
• npm run test:browser — 61 passed, 0 failed
• Integration verified manually against a live runtime, as tabled above

Two notes for the reviewer:

• npm run lint reports 653 errors against 641 on trunk. The 12 added are no-unsafe-assignment / no-explicit-any in the new code, matching the pattern already used throughout src/adbc/client.ts. CI does not run npm run lint, and tightening the file's typing felt like a separate change.
• The README links to docs/PARAMETERIZED_QUERIES.md, which does not exist in the repo. Pre-existing and left alone here.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spice-js	Ready	Preview	Jul 29, 2026 11:14pm

[Copilot]

Pull request overview

This PR switches the Node.js gRPC (Arrow Flight SQL) execution path from client-side SQL parameter substitution to server-side binding via Flight SQL prepared statements, aligning the Node transport with the existing HTTP/browser behavior and preserving parameter typing over the wire.

Changes:

• Implement Flight SQL prepared statement flow on the Node gRPC path (CreatePreparedStatement → DoPut bind → GetFlightInfo → DoGet → ClosePreparedStatement).
• Add Arrow IPC stream splitting logic to correctly frame DoPut messages as Flight dataHeader/dataBody.
• Replace the old parameter-substitution unit test suite with focused tests for binding column naming and IPC framing; update README wording/examples accordingly.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/grpc/client.node.ts	Implements prepared-statement execution and DoPut binding, plus IPC stream splitting for Flight framing.
src/adbc/client.ts	Adds named-parameter column building and IPC serialization for server-side binding.
test/prepared-statement-binding.test.ts	Adds unit coverage for placeholder→column naming rules and IPC framing/splitting behavior.
test/parameter-substitution.test.ts	Removes tests for the now-deleted client-side substitution logic.
README.md	Updates documentation to describe server-side binding on the Flight SQL transport and adds a named-parameter example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[claudespice]

This PR is approved and its only red checks are stale — a maintainer re-run should clear it.

All six Cloud Tests legs come from one run (30498855850, 2026-07-29T23:15Z, never re-run). Every failure is in the same suite and has the same cause:

● cloud › Vercel Endpoint (via SDK) › simple query with constants
  HTTP query failed with status 500: {"success":false,"error":"undefined undefined: undefined"}

That is a server-side outage on the Vercel endpoint, not a defect here — this PR changes server-side parameter binding and never touches that endpoint. Evidence the endpoint has since recovered: the same six legs passed on run 30584139765 (2026-07-30, PR #316). #315 is red for the identical reason from an even older run.

One diagnostic note for the suite itself: the error handling works case passed in every failing leg, because a blanket 500 also satisfies an "it errors" assertion. That test can't distinguish an outage from healthy error handling.

gh run rerun returns 403 for this account, so the re-run needs someone with admin.