Files
JetCore/docs/design-sql-bound-parameters.md
T
brad ArantandClaude Opus 5.5 a18d1358b0 Add <bind> bound parameters for <sql> (phase 1)
Implements phase 1 of docs/design-sql-bound-parameters.md: <bind> supplies
the value for the next ? placeholder of the enclosing <sql>, with typed
validation (int, decimal, date, datetime, bool, ident with allow list),
null="empty", and refusal to change the connection character set.

- SqlBind.*: MySQL-free placeholder scanning and binding logic
- __bind.*, __sql, __mysql: runtime wiring
- Tag.cpp, jetc/JetParser.cpp: bind is a void tag in both
- jetc/JetCodegen: emit sized ZString literals for text holding a NUL,
  which previously truncated the compiled page
- tests: unit tests, end-to-end test against MySQL (interpreted and
  jetc-compiled), and the generator for the binary test page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 19:55:23 -08:00

9.8 KiB

Design: bound parameters for <sql>

Status: draft for review · Author: Brad Arant (drafted with Claude) · Date: 2026-10-23 Applies to: JetCore (__sql, __mysql, Tag.cpp tag dispatch, jetc parser/codegen)

1. The problem

<sql> builds its query by rendering its body as text, then sending the finished string to MySQL:

// __sql.cpp today
processContainer(container);                 // every $[...] substituted as plain text
global.getSession(sessionId)->query(out);    // mysql_real_query(the whole string)

So a request value lands inside the SQL text:

<sql>select id from users where email='$[email]' and secret='$[password]'</sql>

With email = x' or '1'='1' -- that becomes a different query. There is no escaping function in Jet, so this is the only way to write a query, and it's unsafe everywhere a value comes from a request. Numeric positions are worse: where id=$[id] has no quotes, so even escaping wouldn't help (id = 1 or 1=1).

Measured on 2026-10-23 (<sql> blocks whose body contains a request/session value other than $[.column], $[_login_id] or $[_session_id]):

Site <sql> blocks with values pasted in files
barant.com 152 117 64
ClockPlanet 94 83 35

Roughly 80% of all queries. Login, signup, cart, checkout and admin pages are all in that set.

2. Goals

  1. A way to pass values to <sql> that can never change the query's meaning, whatever they contain.
  2. No change to how results are read - <ifrow>, <whilerow>, $[.column], $[?N], $[#] keep working exactly as today.
  3. Easy, mechanical migration of existing pages; old pages keep running until migrated.
  4. A path to enforcing it, so new unsafe queries can't be written by accident.

Non-goals: an ORM, query builders, or changing <database>/<mysql> connection handling.

3. Proposed syntax

Placeholders are ? in the query; values come from <bind> tags inside the <sql>, in order:

<sql>
   select id, name from users where email=? and status=?
   <bind value="$[email]">
   <bind value="ACTIVE">
</sql>

<bind> attributes:

attribute meaning
value the value (any Jet expression - $[...] is fine here, that's the point)
type string (default), int, decimal, bool, date, datetime, ident
null empty = bind SQL NULL when the value is empty (default: bind '')
allow for type="ident" only: comma list of permitted identifiers

Type behaviour (a value that doesn't fit throws a catchable Jet exception - <try>/<catch> works, see §6):

  • string - quoted and escaped (§4).

  • int - must match ^-?[0-9]{1,19}$; emitted bare. This fixes the unquoted where id=$[id] case.

  • decimal - must match ^-?[0-9]{1,30}(\.[0-9]{1,30})?$; emitted bare.

  • bool - 1/0/true/false/yes/no → 1/0.

  • date / datetime - must parse as YYYY-MM-DD / YYYY-MM-DD HH:MM[:SS]; quoted.

  • ident - for the things SQL can't parameterise (column in ORDER BY, a sort direction, a table name). The value must be in allow or it throws; emitted backtick-quoted (ASC/DESC emitted bare). Example:

    <sql>select * from products order by ? ?
       <bind value="$[sort]" type="ident" allow="name,price,created">
       <bind value="$[dir]"  type="ident" allow="ASC,DESC">
    </sql>
    

Why <bind> and not <param>: param is an HTML element (inside <object>), and jetc's void-tag list treats it as HTML. A Jet-only name avoids any ambiguity.

Why positional ? and not named (:email): ? is what MySQL and every SQL library uses, it needs no new attribute-name syntax in the parser, and the <bind> lines sit right under the query so the order is easy to read. Named binds can be added later without breaking this (§9).

4. How it works

__sql collects the <bind> values while its body renders, then replaces each ? that is outside a string literal, backtick identifier or comment with the bound value, rendered safely - and only then calls query() as today.

  • Strings are escaped with mysql_real_escape_string_quote(mysql, to, from, len, '\'') and wrapped in single quotes. This uses the connection's character set and respects NO_BACKSLASH_ESCAPES, which plain mysql_real_escape_string doesn't.
  • The connection's character set is pinned at connect time (mysql_options(MYSQL_SET_CHARSET_NAME, "utf8mb4") in __mysql), so escaping and server parsing always agree. <sql> refuses a SET NAMES/SET CHARACTER SET statement (the classic way to make escaping and parsing disagree).
  • Number of ? must equal number of <bind>s, otherwise throw "sql: 3 placeholders but 2 bind values".

This is the same approach PHP's PDO uses by default. Its big advantage here: the result path doesn't change at all - query() still runs mysql_real_query and mysql_store_result, so MYSQL_ROW, getColumnValue(), <ifrow>, <whilerow> and the column-index map are untouched.

Why not real server-side prepared statements (yet)

mysql_stmt_* returns rows through typed bind buffers, not MYSQL_ROW, so getColumnValue(), $[?N], $[#] and the field-index map would all need a second implementation, and some statements (multi-statements, some DDL) can't be prepared. That's a bigger change for no extra safety over correct emulation. It stays open as a later option (§9), behind the same <bind> syntax, so pages written now won't need touching again.

Code shape

  • New __bind.h/.cpp: on construction, find the nearest enclosing __sql (walk parent with dynamic_cast<__sql*>; throw "bind must be inside sql" if none), resolve value/type/null/allow, validate per type, and call sql->addBind(...). Produces no output.
  • __sql: a std::vector<BoundValue> member and addBind(). After processContainer(container), run bindPlaceholders(out) - a small scanner that tracks '...' (with '' and \'), "...", `...`, -- , # and /* */ so ? inside them is left alone - then query(result).
  • __mysql: escapeString(const MString&) wrapper around mysql_real_escape_string_quote; pin utf8mb4 at connect.
  • Tag.cpp: add ifTagName(in, "bind") next to sql (line ~494).
  • jetc JetParser.cpp: add "bind" to the Jet void-tag list (it has no closing tag); JetCodegen.cpp: emit __bind like the other tags.

Estimated size: ~200 lines plus tests.

5. Existing pages: nothing breaks

A <sql> with no <bind> runs exactly as today - no ? replacement at all, so existing queries containing a literal ? are unaffected. Migration is page by page:

<!-- before -->
<sql>select * from users where email="$[email]" and status="CONFIRM"</sql>
<!-- after -->
<sql>select * from users where email=? and status="CONFIRM"
   <bind value="$[email]">
</sql>

<!-- before: unquoted number, injectable even with escaping -->
<sql>delete from cart_item where session_uuid='$[_session_id]' and sku='$[sku]'</sql>
<!-- after -->
<sql>delete from cart_item where session_uuid=? and sku=?
   <bind value="$[_session_id]">
   <bind value="$[sku]">
</sql>

6. Errors

  • Bad <bind> value (wrong type, ident not allowed), placeholder/bind count mismatch, <bind> outside <sql>: throw coreutils::Exception with a clear message, caught by <try>/<catch> like the MySQL errors fixed on 2026-09-13.
  • The exception text never includes the bound value itself (it may be a password).

7. Enforcement

Once pages are migrated, make the unsafe form an error instead of a habit:

  1. jetc --lint-sql - lists every <sql> whose body contains $[...] other than $[.column] (row values from an outer query), with file:line. This is the migration worklist (§8) and a CI check.
  2. Per-site strict mode - an APIServer site setting "sqlInterpolation": "warn" | "error". In error mode <sql> refuses to run if its body substituted any $[...] except $[.column]; warn logs it. Default warn for existing sites, error for new ones.
  3. Escape hatch - <sql raw="yes"> for the rare trusted dynamic SQL (generated by the site itself, never from input), so it's visible in review and greppable.

8. Migration plan

Phase What Notes
1 Implement <bind>, escaping, utf8mb4 pinning, tests JetCore only; no page changes
2 jetc --lint-sql; run on both sites produces the worklist (≈200 queries)
3 Convert the high-risk pages first login/signup/password reset, cart/checkout/payment (pp.jet), admin procs, ClockPlanet mobile_api.jet and auth
4 Convert the rest; turn on warn logs show anything missed
5 Switch both sites to error unsafe queries can no longer ship

Phase 3 is the one that matters most for security and is a few days' work; each conversion is mechanical and testable page by page.

9. Later

  • Named binds: where email=:email + <bind name="email" value="...">.
  • Real prepared statements (mysql_stmt_*) behind the same <bind> syntax.
  • The companion fix for output: HTML-escape $[...] by default with an explicit raw form - the same "safe unless you say otherwise" rule for the other half of the injection problem (cross-site scripting).

10. Tests

  • Every type: valid values bind correctly; invalid values throw.
  • Injection strings (' or '1'='1, \', multibyte sequences such as 0xbf27, --, ;, NUL bytes) are stored and read back byte-for-byte unchanged.
  • ? inside '...', "...", `...`, --, # and /* */ is never replaced.
  • Placeholder/bind count mismatch throws; <bind> outside <sql> throws.
  • A <sql> with no binds produces exactly the same query text as before.
  • <ifrow>/<whilerow>/$[.col]/$[?N]/$[#] behave identically on bound queries.
  • NO_BACKSLASH_ESCAPES on and off.