Skip to content

fix(#8): dialect-neutral placeholders (S4.1) and parameter type mapping (S5) - #15

Merged
ssilvius merged 2 commits into
mainfrom
fix/8-dialect-neutrality
Aug 3, 2026
Merged

fix(#8): dialect-neutral placeholders (S4.1) and parameter type mapping (S5)#15
ssilvius merged 2 commits into
mainfrom
fix/8-dialect-neutrality

Conversation

@ssilvius

@ssilvius ssilvius commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Summary

http-sql is dialect-free by design, but two spots of SPEC.md prose were written in SQLite's voice. S4.1 named ? as the placeholder syntax when the actual normative content is the ordering rule, and S5 mapped JSON parameter values onto SQLite type affinities — including a boolean -> INTEGER (1 or 0) row that is a real conformance defect, since a PostgreSQL server following it literally would bind an integer into a boolean column and fail. This PR rewords S4.1 to state the ordering rule and hand placeholder syntax to the server's dialect, and rewrites the S5 mapping column in terms of the server's corresponding types (text, integer, real, boolean, null), demoting SQLite's 1/0 boolean representation to an implementation detail of SQLite-backed servers. Prose only; no reference-server behavior changes.

Acceptance criteria mapping

1. S4.1 states the ordering rule and leaves placeholder syntax to the dialect

The params bullet no longer says "in the order of ? placeholders"; it says "in the order of the positional placeholders in sql", which is the part that is actually normative. A following paragraph makes the delegation explicit — http-sql never parses or rewrites sql, so the client must write placeholders in whatever syntax its target server accepts.

Evidence: SPEC.md:49 (params bullet, ? removed) and SPEC.md:51 ("The placeholder syntax itself is the server's, not this spec's").

2. A non-normative note records the per-dialect placeholder syntaxes

The dialect examples are kept, but parenthesized and explicitly labelled non-normative so they read as orientation rather than as a requirement, and the note also states that this document's examples happen to use ? so readers do not mistake the example style for a rule.

Evidence: SPEC.md:51, "(Non-normative: ? in SQLite and MySQL, $1 in PostgreSQL. The examples in this document use ?.)".

3. S5 expresses the mapping as the server's corresponding types, fixing the boolean defect

The table's right-hand column changed from SQLite affinity names (TEXT / INTEGER / REAL / INTEGER (1 or 0) / NULL) to semantic descriptions of the server's own types. The defective boolean row is the substantive fix: a Postgres server now correctly binds a JSON true as a native boolean. A following sentence states that these names are semantic rather than literal SQL type names.

Evidence: SPEC.md:78 now reads | boolean | the server's boolean type |, and SPEC.md:81 states "The type names above are semantic, not literal SQL type names".

4. SQLite's 1/0 boolean storage becomes an implementation detail, noted as such

Rather than deleting the SQLite behavior (which would leave SQLite server authors guessing), it is retained as the worked example of the general rule that a server whose engine lacks one of these types natively chooses its own representation. The paragraph closes by forbidding servers from assuming any particular engine's type system on the client's behalf.

Evidence: SPEC.md:81, "SQLite has no boolean type, so SQLite-backed servers store booleans as 1 and 0", framed as "an implementation detail of that server".

5. No reference server code change needed — verified

Both reference servers pass decoded JSON parameter values straight to their driver and never coerce booleans, so they are already conformant under the new wording. Searching both files for boolean matches only TypeScript interface fields and function signatures (atomic?: boolean), never a binding-time conversion.

Evidence: examples/cloudflare-worker-to-d1/src/index.ts:18 and examples/cloudflare-durable-object/src/index.ts:63 are the only boolean occurrences in each file, both on the atomic request field; git diff --name-only main...HEAD lists SPEC.md alone.

Not done

I left conformance/README.md untouched even though rows P-1 through P-3 still describe roundtrips as "a TEXT param" / "an INTEGER param" / "a NULL param" (conformance/README.md:57-59). That is SQLite-affinity vocabulary of the same family, and there is no boolean roundtrip row at all — a gap now that boolean binding is normatively engine-specific. Both are out of this issue's stated scope, which names S4.1 and S5 only, and adding a conformance case is a suite change that deserves its own issue rather than riding along on a spec-wording fix. I also did not touch README.md or implementations.md: the issue cites them as context for why neutrality matters, not as text to change, and their existing vendor-neutral claims become more accurate rather than less once SPEC.md stops contradicting them. Finally, I did not renumber or restructure S5's tagged-value section — blob and bigint were already dialect-neutral encodings.

Closes #8

S4.1 named `?` as the placeholder syntax; the normative content is the
ordering rule, so state that and leave placeholder syntax to the server's
dialect with a non-normative note (`?` in SQLite/MySQL, `$1` in PostgreSQL).

S5 mapped JSON values onto SQLite type affinities, and the boolean ->
INTEGER (1 or 0) row was a conformance defect: a PostgreSQL server
following it literally binds an integer into a boolean column and fails.
Express the mapping as the server's corresponding types instead, and note
SQLite's 1/0 representation as an implementation detail of SQLite-backed
servers.

Closes #8

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ssilvius
ssilvius merged commit b32d6e9 into main Aug 3, 2026
1 check passed
@ssilvius
ssilvius deleted the fix/8-dialect-neutrality branch August 3, 2026 05:28
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.

fix S4.1 placeholders and S5 boolean mapping toward dialect-neutrality (Sean ruled dialect-free; SQLite-family recommendation withdrawn)

1 participant