Legend:
Library
Module
Module type
Parameter
Class
Class type
Intermediate query string representation.
This module provides a common representation of database query strings. This module can be used directly to construct queries dynamically, or indirectly via the parser, as may be more convenient when the query string is known at compile-time. In the latter case, the input string is typically very similar to the output string. In either case the intermediate representation serve to unify the syntax across database systems and to provide additional functionality.
When using this module directly, it provides:
flexible, pure, and efficient construction (S, L),
L frag translates to the literally inserted substring frag. The frag argument must be trusted or verified to be secure to avoid SQL injection attacks. Use V, Q, or P to safely insert strings or other values.
V (t, v) translates to a parameter of type t bound to the value v. That is, the query string will contain a parameter reference which does not conflict with any P nodes and bind v to the corresponding parameter each time the query is executed. This allows taking advantage of driver-dependent serialization and escaping mechanisms to safely send values to the database server.
*)
| Qof string
(*
Q s corresponds to a quoted string literal. This is passed as part of the query string if a suitable quoting function is available in the client library, otherwise it is equivalent to V(Caqti_type.Field.t.String, s).
*)
| Pof int
(*
P i refers to parameter number i, counting from 0, so that e.g. P 0 translates to "$1" for PostgreSQL and "?1" for SQLite3.
*)
| Eof string
(*
E name will be replaced by the fragment returned by an environment lookup function, as passed directly to expand or indirectly through the ?env argument found in higher-level functions. An error will be issued for any remaining E-nodes in the final translation to a query string.
S frags is the concatenation of frags. Apart from combining different kinds of nodes, this constructor can be nested according to the flow of the generating code.
*)
t is an intermediate representation of a query string to be send to a database, possibly combined with some hidden parameters used to safely embed values. Apart from embedding values, this representation provides indexed parameter references, independent of the target database system. For databases which use linear parameter references (like ? for MariaDB), the driver will reshuffle, elide, and duplicate parameters as needed.
Please note that additional constructors may be added to this type across minor releases.
const_fields t x returns a list of fragments corresponding to the single-field projections of the value x as described by the type descriptor t. Each element of the returned list will be either a V-fragment containing the projected value, or the L["NULL"] fragment if the projection is None.
The result can be turned into a comma-separated list with concat, except values of unitary types, i.e. types having no fields, may require special care.
normal q rewrites q to a normal form containing at most one top-level S constructor, containing no empty literals, and no consecutive literals. This function can be used to post-process queries before using equal and hash.
pp ppf q prints a human-readable representation of q on ppf. The printed string is not suitable for sending to an SQL database; doing so may lead to an SQL injection vulnerability.
show q is the same human-readable representation of q as printed by pp. The returned string is not suitable for sending to an SQL database; doing so may lead to an SQL injection vulnerability.
type expand_error
A description of the error caused during expand if the environment lookup function returns an invalid result or raises Not_found for a variable when the expansion is final.
val pp_expand_error : Stdlib.Format.formatter ->expand_error-> unit
expand f q replaces each occurrence of E v some some v with f v or leaves it unchanged where f v raises Not_found. The Not_found exception will not escape this call.
parameterfinal
If true, then an error is raised instead of leaving environment references unexpended if f raises Not_found. This is used by drivers for performing the final expansion. Defaults to false.
Matches a single expression terminated by the end of input or a semicolon lookahead. The accepted languages is described in The Syntax of Query Templates.
A variant of angstrom_parser which accepts unquoted semicolons as part of the single statement, as is valid in some cases like in SQLite3 trigger definitions. This is the parser used by Caqti_request, where it's assumed that the input is a single SQL statement.
Matches a sequence of statements while ignoring surrounding white space and end-of-line comments starting with "--". This parser can be used to load schema files with support for environment expansions, like substituting the name of the database schema.
val of_string : string ->(t, [ `Invalid of int * string ])Stdlib.result
Parses a single expression using angstrom_parser_with_semicolon. The error indicates the byte position of the input string where the parse failure occurred in addition to an error message. See The Syntax of Query Templates for how the input string is interpreted.