fix(#8): dialect-neutral placeholders (S4.1) and parameter type mapping (S5) - #15
Merged
Conversation
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>
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 aboolean -> INTEGER (1 or 0)row that is a real conformance defect, since a PostgreSQL server following it literally would bind an integer into abooleancolumn 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
paramsbullet no longer says "in the order of?placeholders"; it says "in the order of the positional placeholders insql", which is the part that is actually normative. A following paragraph makes the delegation explicit — http-sql never parses or rewritessql, so the client must write placeholders in whatever syntax its target server accepts.Evidence: SPEC.md:49 (
paramsbullet,?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,$1in 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
trueas 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
1and0", 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
booleanmatches 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
booleanoccurrences in each file, both on theatomicrequest field;git diff --name-only main...HEADlists 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 —
blobandbigintwere already dialect-neutral encodings.Closes #8