Document <bind> and bound parameters in the user manual

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
brad ArantandClaude Opus 5.5 committed 2026-11-20 20:22:50 -08:00
1 parent cfdb3cbf57
commit fd81bb877f
2 files changed
+81

No files matched your search

+81
View File
@@ -377,6 +377,72 @@ variable parsing. This sequence is |> this is not parsed or resolved
and is different from the <exclude /> tag as exclude may be further
parsed if output is again evaluated.
\section{bind}
Use the bind tag inside an sql tag to supply the value for a ?
placeholder in the statement. Each bind fills the next ? in order. The
value is escaped or checked before it reaches the server, so whatever
it contains can never change the meaning of the statement. Use bind for
every value that comes from a request, a cookie or a session instead of
writing \$[name] into the statement text.
The bind tag has no closing tag and produces no output. It must be
inside an sql tag, although it may be inside other tags (if, for and so
on) within that sql tag.
\begin{verbatim}
<sql>select id, name from users where email=? and status=?
<bind value="$[email]">
<bind value="ACTIVE">
</sql>
\end{verbatim}
The attributes are:
value - the value to bind. Required. Any expression or variable
reference may be used here.
type - how the value is checked and sent. The values are:
\begin{itemize}
\item string - the default. Quoted and escaped.
\item int - a whole number of up to 19 digits, optionally negative.
Sent without quotes.
\item decimal - a number with an optional fraction, for example
-12.50. Sent without quotes.
\item bool - 1, true, yes, 0, false or no (any case). Sent as 1 or 0.
\item date - YYYY-MM-DD.
\item datetime - YYYY-MM-DD HH:MM or YYYY-MM-DD HH:MM:SS.
\item ident - a column or table name, or a sort direction, for the
places SQL cannot take a value (ORDER BY and so on). Requires the allow
attribute. Names are sent in backticks; ASC and DESC are sent as they
are.
\end{itemize}
null - set to empty to send SQL NULL when the value is empty. Without
it an empty value is sent as an empty string (and is an error for int,
decimal, bool, date and datetime).
allow - for type="ident" only. A comma separated list of the values
that are permitted. Any other value is an error.
\begin{verbatim}
<sql>select * from products order by ? ?
<bind value="$[sort]" type="ident" allow="name,price,created">
<bind value="$[dir]" type="ident" allow="ASC,DESC">
</sql>
\end{verbatim}
A ? inside a quoted string, a backtick name or a comment in the
statement is not a placeholder. An sql tag that contains no bind tags
is run exactly as written, so a ? in it is left alone.
These are errors, and can be caught with try/catch: a value that does
not fit its type, an ident that is not in the allow list, a bind
outside an sql tag, a bind with no value, an unknown type, and a
statement whose number of ? placeholders differs from its number of
bind tags. The error text never contains the bound value itself.
\section{call}
Use the call tag to evoke an executable file from a jet script.
@@ -570,6 +636,21 @@ As long as sql statements are executed within the same mysql
containing tag then the same mysql session is used for each sql
statement.
Values that come from a request, a cookie or a session should be
passed with bind tags and ? placeholders rather than written into the
statement text. See the bind tag.
\begin{verbatim}
<sql>delete from cart_item where session_uuid=? and sku=?
<bind value="$[_session_id]">
<bind value="$[sku]">
</sql>
\end{verbatim}
A statement that changes the connection character set (SET NAMES, SET
CHARACTER SET and similar) is refused. The connection always uses
utf8mb4.
The attributes are:
sessionid