Skip to content

Support named parameters in prepared statements - #261

Merged
quinnj-bot[bot] merged 2 commits into
mainfrom
claude/named-parameters
Nov 11, 2026
Merged

quinnj-bot[bot] merged 2 commits into
mainfrom
claude/named-parameters

Conversation

@quinnj-bot

@quinnj-bot quinnj-bot Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Why

DBInterface.prepare(conn, "INSERT INTO t VALUES (:id, :name)") fails with a 1064 syntax error (#207): MySQL's prepared statements take positional ? markers only. Users want to bind by name and reuse one value in several places. MySQL.jl now rewrites :name to ? on the client and binds values by name.

What changed

  • DBInterface.prepare sends each :name outside string literals, quoted identifiers, and comments as ? and keeps the names. SQL without :name is prepared byte-for-byte as before.
  • DBInterface.execute takes a NamedTuple, or an AbstractDict keyed by Symbol or String, for a statement with names. DBInterface.executemany binds each row of a NamedTuple batch by name.
  • When the server does not read every :name as a parameter, the SQL is prepared as written. MariaDB prepares stored-program DDL, and a label such as lbl:LOOP looks like a name.

Fixes #207

Behavior

Statement Values Result
? markers tuple, vector, NamedTuple, row, scalar unchanged: iteration order
:name markers NamedTuple, AbstractDict (Symbol or String keys) bound by name
:name markers tuple, vector, scalar one value per marker, in marker order
:name markers Tables.AbstractRow MySQLInterfaceError: its column order need not match the markers; use NamedTuple(row)
:id used twice (id=1,) both markers get 1
:userId (userid=1,) MySQLInterfaceError: names are case-sensitive
missing name MySQLInterfaceError before anything is sent
extra key ignored, as in SQLite.jl and Python DB-API
? and :name in one statement MySQLInterfaceError at prepare
executemany, NamedTuple batch each row by name (DBInterface itself passes NamedTuple batches positionally)

Design

  • One scanner pass at prepare. SQL with no : costs one memchr and no allocation. The scanner skips '...' and "..." literals (backslash escapes follow the session's NO_BACKSLASH_ESCAPES status flag), backtick identifiers, and #, -- , and /* */ comments. I checked each rule against the parameter counts of mysql:8.4.13 and mariadb:11.4.13.
  • Executable comments (/*! */, /*M! */) stay untouched. The server runs or skips them by version (/*!99999 */ is skipped, and MySQL skips /*M! */), so a rewrite inside one could break a statement that works today.
  • After the rewrite, the server is the authority. A 1064 parse error or a parameter count different from the number of names means a :word was not a parameter. The client then prepares the SQL as written. If that also fails, it reports the rewrite's problem, such as the "cannot mix ? and :name" error. MariaDB prepares CREATE PROCEDURE ... lbl:LOOP (also lbl :LOOP and `lbl`:LOOP), so a lexical rule alone would break those statements.
  • Statement gains one field, named::Union{Nothing, NamedSQL} (the rewritten SQL plus the name of each ?). stmt.sql keeps the text as written. Execution of a named statement wraps the values in an allocation-free by-name view that the existing positional encoder iterates.

Scope

  • Covers prepare, execute, the one-shot execute(conn, sql, params), executemultiple, and executemany. A tuple or vector still binds to :name markers in marker order, so MariaDB sql_mode=ORACLE statements, where :x is a native positional marker, keep working.
  • Leaves out keyword-argument values (execute(stmt; id=1)), which MySQL.jl rejects for every statement today, and by-name binding of Tables.AbstractRow.
  • A :name inside an executable comment is not a parameter.

Tradeoffs

  • Reserving label keywords (:begin, :loop) was rejected: BETWEEN :begin AND :end is a plausible query.
  • A "colon must not follow a word character" rule (SQLAlchemy's) was rejected: MariaDB prepares lbl :LOOP.
  • Preparing the SQL as written first and rewriting on failure was rejected: it adds a round trip to every named prepare. The fallback costs one only when the rewrite fails.
  • Binding rows positionally was rejected: a row whose columns are in a different order would bind silently wrong.

Blast Radius

Every DBInterface.prepare now scans its SQL, and every prepared execute checks one field. Positional statements send identical bytes. On MariaDB with sql_mode=ORACLE, where :x is a native positional marker, positional values behave as before, but a NamedTuple now binds by name instead of in field order. A Tables.jl row passed as the parameters there now raises an error, where main bound it positionally; pass a tuple or vector to keep binding by position.

Verification

  • New tests fail on main and pass here: the rewrite table, fake-peer wire checks (rewritten SQL, values in marker order, NO_BACKSLASH_ESCAPES, re-prepare after 1615, the fallbacks, executemany), and a live workflow on the mysql:8.4 and mariadb:11.4 lanes (NamedTuple, Dict, reused and mixed-case names, missing and extra names, the MariaDB label). The trim workload now prepares and executes a named statement, and the scripted server rejects any :id that reaches it.
  • Perf, positional statements against mysql:8.4.13 (7 interleaved runs per side on a loaded machine): no measurable change. The execute medians were 324 µs on main and 291 µs on this branch, with overlapping ranges, bound by the Docker VM round trip. Allocations per call are identical (execute 46/46, prepare 57/57, prepare of SQL with a time literal 37/37). The new prepare-time scan costs 9 ns for SQL without a colon and about 2 ns per byte otherwise, with no allocation. A named execute allocates the same 46 times as a positional one.
  • I re-read the diff for callers, error paths, and concurrency (named state is set once at prepare; nothing new is shared). A randomized differential run against both servers compared the server's parameter count and echoed literal values with the scanner. It found 0 failures in 3000 statements per server, and a deliberately broken lexer fails it.

🤖 Generated with Claude Code

quinnj and others added 2 commits November 10, 2026 15:27
MySQL's prepared statements take positional ? markers only. DBInterface.prepare
now rewrites each :name outside string literals, quoted identifiers, and
comments to ? and keeps the names. DBInterface.execute binds a NamedTuple or
AbstractDict by name; a tuple or vector binds one value per marker in order.
executemany binds each row of a NamedTuple batch by name. SQL without :name is
prepared byte-for-byte as before. When the server does not read every :name
as a parameter (MariaDB stored-program labels such as lbl:LOOP), the SQL is
prepared as written.

Fixes #207

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@quinnj quinnj left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[review generated via AI]

Approving. An independent check ran the new tests against main, where they fail, and against this head, where the full suite passes 2411/2411 with the live MySQL 8.4 and MariaDB 11.4 lanes and the trimmed build. Positional statements behaved exactly as on main on both servers. The MariaDB sql_mode=ORACLE changes listed under Blast Radius are accepted.

@quinnj-bot
quinnj-bot Bot merged commit f62895e into main Nov 11, 2026
17 checks passed
@quinnj-bot
quinnj-bot Bot deleted the claude/named-parameters branch November 11, 2026 04:35
@quinnj-bot quinnj-bot Bot mentioned this pull request Nov 11, 2026
quinnj referenced this pull request Nov 11, 2026
Co-authored-by: Jacob Quinn <quinn.jacobd@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.

Named Parameters Does not Work for prepare() function

1 participant