Document <bind> and bound parameters in the user manual
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
cfdb3cbf57
commit
fd81bb877f
2 files changed
+81
No files matched your search
Binary file not shown.
@@ -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
|
and is different from the <exclude /> tag as exclude may be further
|
||||||
parsed if output is again evaluated.
|
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}
|
\section{call}
|
||||||
|
|
||||||
Use the call tag to evoke an executable file from a jet script.
|
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
|
containing tag then the same mysql session is used for each sql
|
||||||
statement.
|
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:
|
The attributes are:
|
||||||
|
|
||||||
sessionid
|
sessionid
|
||||||
|
|||||||
Reference in new issue
Block a user