diff --git a/docs/JetCore.pdf b/docs/JetCore.pdf index 3b53732..b7498ed 100644 Binary files a/docs/JetCore.pdf and b/docs/JetCore.pdf differ diff --git a/docs/JetCore.tex b/docs/JetCore.tex index ac5a4c1..54eb713 100644 --- a/docs/JetCore.tex +++ b/docs/JetCore.tex @@ -377,6 +377,72 @@ variable parsing. This sequence is |> this is not parsed or resolved and is different from the 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} +select id, name from users where email=? and status=? + + + +\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} +select * from products order by ? ? + + + +\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} +delete from cart_item where session_uuid=? and sku=? + + + +\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